ffi_tpm2.cpp File Reference

#include <botan/ffi.h>
#include <botan/assert.h>
#include <botan/internal/ffi_pkey.h>
#include <botan/internal/ffi_rng.h>
#include <botan/internal/ffi_util.h>

Go to the source code of this file.

Functions
int	botan_tpm2_crypto_backend_state_destroy (botan_tpm2_crypto_backend_state_t cbs)
int	botan_tpm2_ctx_destroy (botan_tpm2_ctx_t ctx)
int	botan_tpm2_ctx_enable_crypto_backend (botan_tpm2_ctx_t ctx, botan_rng_t rng)
int	botan_tpm2_ctx_from_esys (botan_tpm2_ctx_t *ctx_out, ESYS_CONTEXT *esys_ctx)
int	botan_tpm2_ctx_init (botan_tpm2_ctx_t *ctx_out, const char *tcti_nameconf)
int	botan_tpm2_ctx_init_ex (botan_tpm2_ctx_t *ctx_out, const char *tcti_name, const char *tcti_conf)
int	botan_tpm2_enable_crypto_backend (botan_tpm2_crypto_backend_state_t *cbs_out, ESYS_CONTEXT *esys_ctx, botan_rng_t rng)
int	botan_tpm2_rng_init (botan_rng_t *rng_out, botan_tpm2_ctx_t ctx, botan_tpm2_session_t s1, botan_tpm2_session_t s2, botan_tpm2_session_t s3)
int	botan_tpm2_session_destroy (botan_tpm2_session_t session)
int	botan_tpm2_supports_crypto_backend ()
int	botan_tpm2_unauthenticated_session_init (botan_tpm2_session_t *session_out, botan_tpm2_ctx_t ctx)

Function Documentation

botan_tpm2_crypto_backend_state_destroy()

int botan_tpm2_crypto_backend_state_destroy

(

botan_tpm2_crypto_backend_state_t

cbs

)

Frees all resources of a TPM2 Crypto Callback State Note that this does not attempt to de-register the crypto backend, it just frees the resource pointed to by cbs. Use the ESAPI function Esys_SetCryptoCallbacks(ctx, nullptr) to deregister manually.

Parameters

cbs	TPM2 Crypto Callback State

Returns

0 on success

Definition at line 203 of file ffi_tpm2.cpp.

                                                                                   {
#if defined(BOTAN_HAS_TPM2_CRYPTO_BACKEND)
   return BOTAN_FFI_CHECKED_DELETE(cbs);
#else
   BOTAN_UNUSED(cbs);
   return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
#endif
}

References BOTAN_FFI_CHECKED_DELETE, BOTAN_FFI_ERROR_NOT_IMPLEMENTED, and BOTAN_UNUSED.

botan_tpm2_ctx_destroy()

int botan_tpm2_ctx_destroy

(

botan_tpm2_ctx_t

ctx

)

Frees all resources of a TPM2 context

Parameters

ctx	TPM2 context

Returns

0 on success

Definition at line 172 of file ffi_tpm2.cpp.

                                                 {
#if defined(BOTAN_HAS_TPM2)
   return BOTAN_FFI_CHECKED_DELETE(ctx);
#else
   BOTAN_UNUSED(ctx);
   return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
#endif
}

References BOTAN_FFI_CHECKED_DELETE, BOTAN_FFI_ERROR_NOT_IMPLEMENTED, and BOTAN_UNUSED.

botan_tpm2_ctx_enable_crypto_backend()

int botan_tpm2_ctx_enable_crypto_backend	(	botan_tpm2_ctx_t	ctx,
		botan_rng_t	rng )

Enable Botan's TSS2 crypto backend that replaces the cryptographic functions required for the communication with the TPM with implementations provided by Botan instead of using TSS' defaults OpenSSL or mbedTLS. Note that the provided rng should not be dependent on the TPM and the caller must ensure that it remains usable for the lifetime of the ctx.

Parameters

ctx	TPM2 context
rng	random number generator to be used by the crypto backend

Definition at line 150 of file ffi_tpm2.cpp.

                                                                                {
#if defined(BOTAN_HAS_TPM2)
   return BOTAN_FFI_VISIT(ctx, [=](botan_tpm2_ctx_wrapper& ctx_wrapper) -> int {
      Botan::RandomNumberGenerator& rng_ref = safe_get(rng);
 
      // The lifetime of the RNG used for the crypto backend should be managed
      // by the TPM2::Context. Here, we just need to trust the user that they
      // keep the passed-in RNG instance intact for the lifetime of the context.
      ctx_wrapper.ctx->use_botan_crypto_backend(std::shared_ptr<Botan::RandomNumberGenerator>(&rng_ref, [](auto*) {}));
      return BOTAN_FFI_SUCCESS;
   });
#else
   BOTAN_UNUSED(ctx, rng);
   return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
#endif
}

References BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_SUCCESS, BOTAN_FFI_VISIT, BOTAN_UNUSED, and Botan_FFI::safe_get().

botan_tpm2_ctx_from_esys()

int botan_tpm2_ctx_from_esys	(	botan_tpm2_ctx_t *	ctx_out,
		struct ESYS_CONTEXT *	esys_ctx )

Wrap an existing ESYS_CONTEXT for use in Botan. Note that destroying the created botan_tpm2_ctx_t won't finalize esys_ctx

Parameters

ctx_out	output TPM2 context
esys_ctx	ESYS_CONTEXT to wrap

Returns

0 on success

Definition at line 133 of file ffi_tpm2.cpp.

                                                                                {
#if defined(BOTAN_HAS_TPM2)
   return ffi_guard_thunk(__func__, [=]() -> int {
      if(ctx_out == nullptr || esys_ctx == nullptr) {
         return BOTAN_FFI_ERROR_NULL_POINTER;
      }
 
      auto ctx = std::make_unique<botan_tpm2_ctx_wrapper>();
      ctx->ctx = Botan::TPM2::Context::create(esys_ctx);
      return ffi_new_object(ctx_out, std::move(ctx));
   });
#else
   BOTAN_UNUSED(ctx_out, esys_ctx);
   return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
#endif
}

References BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_UNUSED, Botan::TPM2::Context::create(), Botan_FFI::ffi_guard_thunk(), and Botan_FFI::ffi_new_object().

botan_tpm2_ctx_init()

int botan_tpm2_ctx_init	(	botan_tpm2_ctx_t *	ctx_out,
		const char *	tcti_nameconf )

Initialize a TPM2 context

Parameters

ctx_out	output TPM2 context
tcti_nameconf	TCTI config (may be nullptr)

Returns

0 on success

Definition at line 75 of file ffi_tpm2.cpp.

                                                                              {
#if defined(BOTAN_HAS_TPM2)
   return ffi_guard_thunk(__func__, [=]() -> int {
      if(ctx_out == nullptr) {
         return BOTAN_FFI_ERROR_NULL_POINTER;
      }
      auto ctx = std::make_unique<botan_tpm2_ctx_wrapper>();
 
      auto tcti = [=]() -> std::optional<std::string> {
         if(tcti_nameconf == nullptr) {
            return {};
         } else {
            return std::string(tcti_nameconf);
         }
      }();
 
      ctx->ctx = Botan::TPM2::Context::create(std::move(tcti));
      return ffi_new_object(ctx_out, std::move(ctx));
   });
#else
   BOTAN_UNUSED(ctx_out, tcti_nameconf);
   return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
#endif
}

References BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_UNUSED, Botan::TPM2::Context::create(), Botan_FFI::ffi_guard_thunk(), and Botan_FFI::ffi_new_object().

botan_tpm2_ctx_init_ex()

int botan_tpm2_ctx_init_ex	(	botan_tpm2_ctx_t *	ctx_out,
		const char *	tcti_name,
		const char *	tcti_conf )

Initialize a TPM2 context

Parameters

ctx_out	output TPM2 context
tcti_name	TCTI name (may be nullptr)
tcti_conf	TCTI config (may be nullptr)

Returns

0 on success

Definition at line 100 of file ffi_tpm2.cpp.

                                                                                                    {
#if defined(BOTAN_HAS_TPM2)
   return ffi_guard_thunk(__func__, [=]() -> int {
      if(ctx_out == nullptr) {
         return BOTAN_FFI_ERROR_NULL_POINTER;
      }
      auto ctx = std::make_unique<botan_tpm2_ctx_wrapper>();
 
      auto tcti_name_str = [=]() -> std::optional<std::string> {
         if(tcti_name == nullptr) {
            return {};
         } else {
            return std::string(tcti_name);
         }
      }();
 
      auto tcti_conf_str = [=]() -> std::optional<std::string> {
         if(tcti_conf == nullptr) {
            return {};
         } else {
            return std::string(tcti_conf);
         }
      }();
 
      ctx->ctx = Botan::TPM2::Context::create(std::move(tcti_name_str), std::move(tcti_conf_str));
      return ffi_new_object(ctx_out, std::move(ctx));
   });
#else
   BOTAN_UNUSED(ctx_out, tcti_name, tcti_conf);
   return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
#endif
}

References BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_UNUSED, Botan::TPM2::Context::create(), Botan_FFI::ffi_guard_thunk(), and Botan_FFI::ffi_new_object().

botan_tpm2_enable_crypto_backend()

int botan_tpm2_enable_crypto_backend	(	botan_tpm2_crypto_backend_state_t *	cbs_out,
		struct ESYS_CONTEXT *	esys_ctx,
		botan_rng_t	rng )

Use this if you just need Botan's crypto backend but do not want to wrap any other ESYS functionality using Botan's TPM2 wrapper. A Crypto Backend State is created that the user needs to keep alive for as long as the crypto backend is used and needs to be destroyed after. Note that the provided rng should not be dependent on the TPM and the caller must ensure that it remains usable for the lifetime of the esys_ctx.

Parameters

cbs_out	To be created Crypto Backend State
esys_ctx	TPM2 context
rng	random number generator to be used by the crypto backend

Definition at line 181 of file ffi_tpm2.cpp.

                                                      {
#if defined(BOTAN_HAS_TPM2_CRYPTO_BACKEND)
   return ffi_guard_thunk(__func__, [=]() -> int {
      if(cbs_out == nullptr || esys_ctx == nullptr) {
         return BOTAN_FFI_ERROR_NULL_POINTER;
      }
 
      Botan::RandomNumberGenerator& rng_ref = safe_get(rng);
 
      // Here, we just need to trust the user that they keep the passed-in RNG
      // instance intact for the lifetime of the context.
      const std::shared_ptr<Botan::RandomNumberGenerator> rng_ptr(&rng_ref, [](auto*) {});
      return ffi_new_object(cbs_out, Botan::TPM2::use_botan_crypto_backend(esys_ctx, rng_ptr));
   });
#else
   BOTAN_UNUSED(cbs_out, esys_ctx, rng);
   return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
#endif
}

References BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_UNUSED, Botan_FFI::ffi_guard_thunk(), Botan_FFI::ffi_new_object(), Botan_FFI::safe_get(), and Botan::TPM2::use_botan_crypto_backend().

botan_tpm2_rng_init()

int botan_tpm2_rng_init	(	botan_rng_t *	rng_out,
		botan_tpm2_ctx_t	ctx,
		botan_tpm2_session_t	s1,
		botan_tpm2_session_t	s2,
		botan_tpm2_session_t	s3 )

Initialize a random number generator object via TPM2

Parameters

rng_out	rng object to create
ctx	TPM2 context
s1	the first session to use (optional, may be nullptr)
s2	the second session to use (optional, may be nullptr)
s3	the third session to use (optional, may be nullptr)

Definition at line 212 of file ffi_tpm2.cpp.

                                                 {
#if defined(BOTAN_HAS_TPM2)
   return BOTAN_FFI_VISIT(ctx, [=](botan_tpm2_ctx_wrapper& ctx_wrapper) -> int {
      if(rng_out == nullptr) {
         return BOTAN_FFI_ERROR_NULL_POINTER;
      }
 
      return ffi_new_object(
         rng_out, std::make_unique<Botan::TPM2::RandomNumberGenerator>(ctx_wrapper.ctx, sessions(s1, s2, s3)));
   });
#else
   BOTAN_UNUSED(rng_out, ctx, s1, s2, s3);
   return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
#endif
}

References BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_FFI_VISIT, BOTAN_UNUSED, and Botan_FFI::ffi_new_object().

botan_tpm2_session_destroy()

int botan_tpm2_session_destroy

(

botan_tpm2_session_t

session

)

Create an unauthenticated session for use with TPM2

Parameters

session

the session object to destroy

Definition at line 249 of file ffi_tpm2.cpp.

                                                             {
#if defined(BOTAN_HAS_TPM2)
   return BOTAN_FFI_CHECKED_DELETE(session);
#else
   BOTAN_UNUSED(session);
   return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
#endif
}

References BOTAN_FFI_CHECKED_DELETE, BOTAN_FFI_ERROR_NOT_IMPLEMENTED, and BOTAN_UNUSED.

botan_tpm2_supports_crypto_backend()

int botan_tpm2_supports_crypto_backend

(

void

)

Checks if Botan's TSS2 crypto backend can be used in this build

Returns

1 if the crypto backend can be enabled

Definition at line 67 of file ffi_tpm2.cpp.

                                         {
#if defined(BOTAN_HAS_TPM2)
   return Botan::TPM2::Context::supports_botan_crypto_backend() ? 1 : 0;
#else
   return 0;
#endif
}

References Botan::TPM2::Context::supports_botan_crypto_backend().

botan_tpm2_unauthenticated_session_init()

int botan_tpm2_unauthenticated_session_init	(	botan_tpm2_session_t *	session_out,
		botan_tpm2_ctx_t	ctx )

Create an unauthenticated session for use with TPM2

Parameters

session_out	the session object to create
ctx	TPM2 context

Definition at line 232 of file ffi_tpm2.cpp.

                                                                                                     {
#if defined(BOTAN_HAS_TPM2)
   return BOTAN_FFI_VISIT(ctx, [=](botan_tpm2_ctx_wrapper& ctx_wrapper) -> int {
      if(session_out == nullptr) {
         return BOTAN_FFI_ERROR_NULL_POINTER;
      }
 
      auto session = std::make_unique<botan_tpm2_session_wrapper>();
      session->session = Botan::TPM2::Session::unauthenticated_session(ctx_wrapper.ctx);
      return ffi_new_object(session_out, std::move(session));
   });
#else
   BOTAN_UNUSED(session_out, ctx);
   return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
#endif
}

References BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_FFI_VISIT, BOTAN_UNUSED, Botan_FFI::ffi_new_object(), and Botan::TPM2::Session::unauthenticated_session().