Botan::TPM2::Context Class Reference

#include <tpm2_context.h>

Inheritance diagram for Botan::TPM2::Context:

Public Member Functions
	Context (const Context &)=delete
	Context (Context &&) noexcept
ESYS_CONTEXT *	esys_context () noexcept
void	evict (std::unique_ptr< TPM2::PrivateKey > key, const SessionBundle &sessions)
	Evicts a persistent key from the TPM. The key cannot be used after.
std::optional< TPM2_HANDLE >	find_free_persistent_handle () const
std::string	manufacturer () const
size_t	max_random_bytes_per_request () const
	operator ESYS_CONTEXT * () noexcept
Context &	operator= (const Context &)=delete
Context &	operator= (Context &&) noexcept
TPM2_HANDLE	persist (TPM2::PrivateKey &key, const SessionBundle &sessions, std::span< const uint8_t > auth_value={}, std::optional< TPM2_HANDLE > persistent_handle=std::nullopt)
	Makes key persistent at location persistent_handle or any free.
std::vector< TPM2_HANDLE >	persistent_handles () const
std::unique_ptr< TPM2::PrivateKey >	storage_root_key (std::span< const uint8_t > auth_value, const SessionBundle &sessions)
bool	supports_algorithm (std::string_view algo_name) const
std::vector< ESYS_TR >	transient_handles () const
void	use_botan_crypto_backend (const std::shared_ptr< Botan::RandomNumberGenerator > &rng)
bool	uses_botan_crypto_backend () const noexcept
std::string	vendor () const
	~Context ()

Static Public Member Functions
static std::shared_ptr< Context >	create (const std::string &tcti_nameconf)
static std::shared_ptr< Context >	create (ESYS_CONTEXT *ctx)
static std::shared_ptr< Context >	create (std::optional< std::string > tcti={}, std::optional< std::string > conf={})
static bool	supports_botan_crypto_backend () noexcept

Detailed Description

Central class for interacting with a TPM2. Additional to managing the connection to the TPM, this provides authorative information about the TPM's capabilities. Also, it allows to persist and evict keys generated by the TPM.

Definition at line 39 of file tpm2_context.h.

Constructor & Destructor Documentation

Context() [1/2]

Botan::TPM2::Context::Context ( const Context & )

delete

References Context().

Referenced by Context(), Context(), create(), create(), create(), operator=(), operator=(), and use_botan_crypto_backend().

Context() [2/2]

Botan::TPM2::Context::Context ( Context && )

defaultnoexcept

References Context().

~Context()

Botan::TPM2::Context::~Context

(

)

Definition at line 411 of file tpm2_context.cpp.

                  {
   if(!m_impl) {
      return;
   }
 
#if defined(BOTAN_HAS_TPM2_CRYPTO_BACKEND)
   // If this object manages a crypto backend state object and the ESYS context
   // will live on, because it was externally provided, we have to de-register
   // this state object from the crypto callbacks.
   //
   // This will prevent the crypto backend callbacks from using a dangling
   // pointer and cause graceful errors if the externally provided ESYS context
   // is used for any action that would still need the crypto backend state.
   //
   // We deliberately do not just disable the crypto backend silently, as that
   // might give users the false impression that they continue to benefit from
   // the crypto backend while in fact they're back to the TSS' default.
   if(m_impl->m_external && uses_botan_crypto_backend()) {
      try {
         set_crypto_callbacks(esys_context(), nullptr /* reset callback state */);
      } catch(...) {
         // ignore errors in destructor
      }
      m_impl->m_crypto_callback_state.reset();
   }
#endif
 
   // We don't finalize contexts that were provided externally. Those are
   // expected to be handled by the library users' applications.
   if(!m_impl->m_external) {
      // If the TCTI context was initialized explicitly, Esys_GetTcti() will
      // return a pointer to the TCTI context that then has to be finalized
      // explicitly. See ESAPI Specification Section 6.3 "Esys_GetTcti".
      TSS2_TCTI_CONTEXT* tcti_ctx = nullptr;
      Esys_GetTcti(m_impl->m_ctx, &tcti_ctx);  // ignore error in destructor
      if(tcti_ctx != nullptr) {
         Tss2_TctiLdr_Finalize(&tcti_ctx);
      }
 
      Esys_Finalize(&m_impl->m_ctx);
   }
}

References esys_context(), Botan::TPM2::set_crypto_callbacks(), and uses_botan_crypto_backend().

Member Function Documentation

create() [1/3]

std::shared_ptr< Context > Botan::TPM2::Context::create ( const std::string & tcti_nameconf )

static

Parameters

tcti_nameconf

this is passed to Tss2_TctiLdr_Initialize verbatim

Definition at line 55 of file tpm2_context.cpp.

                                                                     {
   TSS2_TCTI_CONTEXT* tcti_ctx = nullptr;
   ESYS_CONTEXT* esys_ctx = nullptr;
   check_rc("TCTI Initialization", Tss2_TctiLdr_Initialize(tcti_nameconf.c_str(), &tcti_ctx));
   BOTAN_ASSERT_NONNULL(tcti_ctx);
   check_rc("TPM2 Initialization", Esys_Initialize(&esys_ctx, tcti_ctx, nullptr /* ABI version */));
   BOTAN_ASSERT_NONNULL(esys_ctx);
 
   // We cannot std::make_shared as the constructor is private
   return std::shared_ptr<Context>(new Context(esys_ctx, false /* context is managed by us */));
}

References BOTAN_ASSERT_NONNULL, Botan::TPM2::check_rc(), and Context().

Referenced by botan_tpm2_ctx_from_esys(), botan_tpm2_ctx_init(), and botan_tpm2_ctx_init_ex().

create() [2/3]

std::shared_ptr< Context > Botan::TPM2::Context::create ( ESYS_CONTEXT * ctx )

static

Create a TPM2::Context from an externally sourced TPM2-TSS ESYS Context. Note that the input contexts need to remain alive for the lifetime of the entire TPM2::Context! This allows to use Botan's TPM2 functionality within an exising ESAPI application.

Note that Botan won't finalize an externally provided ESYS context, this responsibility remains with the caller in this case.

Parameters

ctx	the already set up ESYS_CONTEXT*

Definition at line 82 of file tpm2_context.cpp.

                                                             {
   BOTAN_ARG_CHECK(esys_ctx != nullptr, "provided esys_ctx must not be null");
 
   // We cannot std::make_shared as the constructor is private
   return std::shared_ptr<Context>(new Context(esys_ctx, true /* context is managed externally */));
}

References BOTAN_ARG_CHECK, and Context().

create() [3/3]

std::shared_ptr< Context > Botan::TPM2::Context::create ( std::optional< std::string > tcti = {}, std::optional< std::string > conf = {} )

static

Parameters

tcti	if set this is passed to Tss2_TctiLdr_Initialize_Ex verbatim otherwise a nullptr is passed.
conf	if set this is passed to Tss2_TctiLdr_Initialize_Ex verbatim otherwise a nullptr is passed.

Definition at line 67 of file tpm2_context.cpp.

                                                                                               {
   const char* const tcti_ptr = tcti.has_value() ? tcti->c_str() : nullptr;
   const char* const conf_ptr = conf.has_value() ? conf->c_str() : nullptr;
 
   TSS2_TCTI_CONTEXT* tcti_ctx = nullptr;
   ESYS_CONTEXT* esys_ctx = nullptr;
   check_rc("TCTI Initialization", Tss2_TctiLdr_Initialize_Ex(tcti_ptr, conf_ptr, &tcti_ctx));
   BOTAN_ASSERT_NONNULL(tcti_ctx);
   check_rc("TPM2 Initialization", Esys_Initialize(&esys_ctx, tcti_ctx, nullptr /* ABI version */));
   BOTAN_ASSERT_NONNULL(esys_ctx);
 
   // We cannot std::make_shared as the constructor is private
   return std::shared_ptr<Context>(new Context(esys_ctx, false /* context is managed by us */));
}

References BOTAN_ASSERT_NONNULL, Botan::TPM2::check_rc(), and Context().

esys_context()

ESYS_CONTEXT * Botan::TPM2::Context::esys_context ( )

noexcept

Returns

an ESYS_CONTEXT* for use in other TPM2 functions.

Definition at line 123 of file tpm2_context.cpp.

                                             {
   return m_impl->m_ctx;
}

Referenced by operator ESYS_CONTEXT *(), operator=(), use_botan_crypto_backend(), and ~Context().

evict()

void Botan::TPM2::Context::evict	(	std::unique_ptr< TPM2::PrivateKey >	key,
		const SessionBundle &	sessions )

Evicts a persistent key from the TPM. The key cannot be used after.

Definition at line 385 of file tpm2_context.cpp.

                                                                                    {
   BOTAN_ASSERT_NONNULL(key);
 
   auto& handles = key->handles();
   BOTAN_ARG_CHECK(handles.has_persistent_handle(), "Key does not have a persistent handle assigned");
 
   // 1. Evict the key from the TPM's NV storage
   //    This will free the persistent handle, but the transient handle will
   //    still be valid.
   ESYS_TR no_new_handle = ESYS_TR_NONE;
   check_rc("Esys_EvictControl",
            Esys_EvictControl(m_impl->m_ctx,
                              ESYS_TR_RH_OWNER /*TODO: hierarchy*/,
                              handles.transient_handle(),
                              sessions[0],
                              sessions[1],
                              sessions[2],
                              0,
                              &no_new_handle));
   BOTAN_ASSERT(no_new_handle == ESYS_TR_NONE, "When deleting a key, no new handle is returned");
 
   // 2. The persistent key was deleted and the transient key was flushed by
   //    Esys_EvictControl().
   handles._disengage();
}

References BOTAN_ARG_CHECK, BOTAN_ASSERT, BOTAN_ASSERT_NONNULL, and Botan::TPM2::check_rc().

find_free_persistent_handle()

std::optional< TPM2_HANDLE > Botan::TPM2::Context::find_free_persistent_handle

(

)

const

Returns

a persistent handle that is currently not in use or std::nullopt if no such handle is available

Definition at line 305 of file tpm2_context.cpp.

                                                                    {
   const auto occupied_handles = persistent_handles();
 
   // This is modeled after the implementation in tpm2-tools, which also takes
   // "platform persistent" handles into account. We don't do that here, but
   // we might need to in the future.
   //
   // See: https://github.com/tpm2-software/tpm2-tools/blob/bd832d3f79/lib/tpm2_capability.c#L143-L196
 
   // all persistent handles are occupied
   if(occupied_handles.size() >= TPM2_MAX_CAP_HANDLES) {
      return std::nullopt;
   }
 
   // find the lowest handle that is not occupied
   for(TPM2_HANDLE i = TPM2_PERSISTENT_FIRST; i < TPM2_PERSISTENT_LAST; ++i) {
      if(!value_exists(occupied_handles, i)) {
         return i;
      }
   }
 
   BOTAN_ASSERT_UNREACHABLE();
}

References BOTAN_ASSERT_UNREACHABLE, persistent_handles(), and Botan::value_exists().

Referenced by persist().

manufacturer()

std::string Botan::TPM2::Context::manufacturer

(

)

const

Returns

the Manufacturer of the TPM2

Definition at line 224 of file tpm2_context.cpp.

                                      {
   std::array<uint8_t, 4 + 1 /* ensure zero termination */> manufacturer_data{};
   store_be(std::span{manufacturer_data}.first<4>(), get_tpm_property(m_impl->m_ctx, TPM2_PT_MANUFACTURER));
   return std::string(cast_uint8_ptr_to_char(manufacturer_data.data()));
}

References Botan::cast_uint8_ptr_to_char(), and Botan::store_be().

max_random_bytes_per_request()

size_t Botan::TPM2::Context::max_random_bytes_per_request

(

)

const

Returns

the maximum number of random bytes to be requested at once

Definition at line 292 of file tpm2_context.cpp.

                                                   {
   return get_tpm_property(m_impl->m_ctx, TPM2_PT_MAX_DIGEST);
}

operator ESYS_CONTEXT *()

Botan::TPM2::Context::operator ESYS_CONTEXT * ( )

inlinenoexcept

Definition at line 105 of file tpm2_context.h.

{ return esys_context(); }

References esys_context().

operator=() [1/2]

Context & Botan::TPM2::Context::operator= ( const Context & )

delete

References Context().

operator=() [2/2]

Context & Botan::TPM2::Context::operator= ( Context && )

defaultnoexcept

References Context(), esys_context(), supports_botan_crypto_backend(), use_botan_crypto_backend(), and uses_botan_crypto_backend().

persist()

TPM2_HANDLE Botan::TPM2::Context::persist	(	TPM2::PrivateKey &	key,
		const SessionBundle &	sessions,
		std::span< const uint8_t >	auth_value = {},
		std::optional< TPM2_HANDLE >	persistent_handle = std::nullopt )

Makes key persistent at location persistent_handle or any free.

Definition at line 334 of file tpm2_context.cpp.

                                                                         {
   auto& handles = key.handles();
 
   BOTAN_ARG_CHECK(!persistent_handle || !value_exists(persistent_handles(), persistent_handle.value()),
                   "Persistent handle already in use");
   BOTAN_ARG_CHECK(!handles.has_persistent_handle(), "Key already has a persistent handle assigned");
 
   // 1. Decide on the location to persist the key to.
   //    This uses either the handle provided by the caller or a free handle.
   const std::optional<TPMI_DH_PERSISTENT> new_persistent_handle =
      persistent_handle.has_value() ? persistent_handle : find_free_persistent_handle();
 
   BOTAN_STATE_CHECK(new_persistent_handle.has_value());
 
   // 2. Persist the transient key in the TPM's NV storage
   //    This will flush the transient key handle and replace it with a new
   //    transient handle that references the persisted key.
   check_rc("Esys_EvictControl",
            Esys_EvictControl(m_impl->m_ctx,
                              ESYS_TR_RH_OWNER /*TODO: hierarchy*/,
                              handles.transient_handle(),
                              sessions[0],
                              sessions[1],
                              sessions[2],
                              *new_persistent_handle,
                              out_transient_handle(handles)));
   BOTAN_ASSERT_NOMSG(handles.has_transient_handle());
 
   // 3. Reset the auth value of the key object
   //    This is necessary to ensure that the key object remains usable after
   //    the transient handle was recreated inside Esys_EvictControl().
   if(!auth_value.empty()) {
      const auto user_auth = copy_into<TPM2B_AUTH>(auth_value);
      check_rc("Esys_TR_SetAuth", Esys_TR_SetAuth(m_impl->m_ctx, handles.transient_handle(), &user_auth));
   }
 
   // 4. Update the key object with the new persistent handle
   //    This double-checks that the key was persisted at the correct location,
   //    but also brings the key object into a consistent state.
   check_rc("Esys_TR_GetTpmHandle",
            Esys_TR_GetTpmHandle(m_impl->m_ctx, handles.transient_handle(), out_persistent_handle(handles)));
 
   BOTAN_ASSERT_NOMSG(handles.has_persistent_handle());
   BOTAN_ASSERT_EQUAL(*new_persistent_handle, handles.persistent_handle(), "key was persisted at the correct location");
 
   return *new_persistent_handle;
}

References BOTAN_ARG_CHECK, BOTAN_ASSERT_EQUAL, BOTAN_ASSERT_NOMSG, BOTAN_STATE_CHECK, Botan::TPM2::check_rc(), Botan::TPM2::copy_into(), find_free_persistent_handle(), Botan::TPM2::PrivateKey::handles(), Botan::TPM2::out_persistent_handle(), Botan::TPM2::out_transient_handle(), persistent_handles(), and Botan::value_exists().

persistent_handles()

std::vector< TPM2_HANDLE > Botan::TPM2::Context::persistent_handles

(

)

const

Definition at line 329 of file tpm2_context.cpp.

                                                         {
   return get_tpm_property_list<TPM2_CAP_HANDLES, TPM2_HANDLE>(
      m_impl->m_ctx, TPM2_PERSISTENT_FIRST, TPM2_MAX_CAP_HANDLES);
}

Referenced by find_free_persistent_handle(), and persist().

storage_root_key()

std::unique_ptr< TPM2::PrivateKey > Botan::TPM2::Context::storage_root_key	(	std::span< const uint8_t >	auth_value,
		const SessionBundle &	sessions )

Definition at line 296 of file tpm2_context.cpp.

                                                                                           {
   return TPM2::PrivateKey::load_persistent(shared_from_this(), storage_root_key_handle, auth_value, sessions);
}

References Botan::TPM2::PrivateKey::load_persistent().

supports_algorithm()

bool Botan::TPM2::Context::supports_algorithm

(

std::string_view

algo_name

)

const

The algo_name can be any of the string algorithm specifiers used elsewhere. For example, "RSA", "AES-128", "SHA-1", "CTR(3DES)", etc.

Returns

true if the specified algorithm is supported by the TPM

Definition at line 230 of file tpm2_context.cpp.

                                                               {
   // Go through all the string mappings we have available and check if we
   // can find the algorithm name in any of them. If we do, we can check if
   // the TPM supports the required algorithms.
   const auto required_alg_ids = [&]() -> std::vector<TPM2_ALG_ID> {
      std::vector<TPM2_ALG_ID> result;
      if(auto algo_id = asymmetric_algorithm_botan_to_tss2(algo_name)) {
         result.push_back(algo_id.value());
      }
 
      if(auto hash_id = hash_algo_botan_to_tss2(algo_name)) {
         result.push_back(hash_id.value());
      }
 
      if(auto block_id = block_cipher_botan_to_tss2(algo_name)) {
         result.push_back(block_id->first);
      }
 
      if(auto cipher_mode_id = cipher_mode_botan_to_tss2(algo_name)) {
         result.push_back(cipher_mode_id.value());
      }
 
      if(auto cipher_spec = cipher_botan_to_tss2(algo_name)) {
         result.push_back(cipher_spec->algorithm);
         result.push_back(cipher_spec->mode.sym);
      }
 
      if(auto sig_padding = rsa_signature_padding_botan_to_tss2(algo_name)) {
         result.push_back(sig_padding.value());
      }
 
      if(auto sig = rsa_signature_scheme_botan_to_tss2(algo_name)) {
         result.push_back(sig->scheme);
         result.push_back(sig->details.any.hashAlg);
      }
 
      if(auto enc_scheme = rsa_encryption_scheme_botan_to_tss2(algo_name)) {
         result.push_back(enc_scheme->scheme);
         if(enc_scheme->scheme == TPM2_ALG_OAEP) {
            result.push_back(enc_scheme->details.oaep.hashAlg);
         }
      }
 
      if(auto enc_id = rsa_encryption_padding_botan_to_tss2(algo_name)) {
         result.push_back(enc_id.value());
      }
 
      return result;
   }();
 
   if(required_alg_ids.empty()) {
      // The algorithm name is not known to us, so we cannot check for support.
      return false;
   }
 
   const auto algo_caps =
      get_tpm_property_list<TPM2_CAP_ALGS, TPM2_ALG_ID>(m_impl->m_ctx, TPM2_ALG_FIRST, TPM2_MAX_CAP_ALGS);
 
   return std::all_of(
      required_alg_ids.begin(), required_alg_ids.end(), [&](TPM2_ALG_ID id) { return value_exists(algo_caps, id); });
}

References Botan::TPM2::asymmetric_algorithm_botan_to_tss2(), Botan::TPM2::block_cipher_botan_to_tss2(), Botan::TPM2::cipher_botan_to_tss2(), Botan::TPM2::cipher_mode_botan_to_tss2(), Botan::TPM2::hash_algo_botan_to_tss2(), Botan::TPM2::rsa_encryption_padding_botan_to_tss2(), Botan::TPM2::rsa_encryption_scheme_botan_to_tss2(), Botan::TPM2::rsa_signature_padding_botan_to_tss2(), and Botan::TPM2::rsa_signature_scheme_botan_to_tss2().

supports_botan_crypto_backend()

bool Botan::TPM2::Context::supports_botan_crypto_backend ( )

staticnoexcept

Checks if the TSS2 supports registering Botan's crypto backend at runtime. Older versions of the TSS2 do not support this feature ( 4.0.0), also Botan may be compiled without support for TSS' crypto backend.

Returns

true if the TSS2 supports Botan's crypto backend

Definition at line 47 of file tpm2_context.cpp.

                                                     {
#if defined(BOTAN_HAS_TPM2_CRYPTO_BACKEND)
   return Botan::TPM2::supports_botan_crypto_backend();
#else
   return false;
#endif
}

References Botan::TPM2::supports_botan_crypto_backend().

Referenced by botan_tpm2_supports_crypto_backend(), and operator=().

transient_handles()

std::vector< ESYS_TR > Botan::TPM2::Context::transient_handles

(

)

const

Definition at line 301 of file tpm2_context.cpp.

                                                    {
   return get_tpm_property_list<TPM2_CAP_HANDLES, ESYS_TR>(m_impl->m_ctx, TPM2_TRANSIENT_FIRST, TPM2_MAX_CAP_HANDLES);
}

use_botan_crypto_backend()

void Botan::TPM2::Context::use_botan_crypto_backend

(

const std::shared_ptr< Botan::RandomNumberGenerator > &

rng

)

Overrides the TSS2's crypto callbacks with Botan's functionality.

This replaces all cryptographic functionality required for the communication with the TPM by botan's implementations. The TSS2 would otherwise use OpenSSL or mbedTLS.

Note that the provided rng should not be dependent on the TPM.

Parameters

rng	the RNG to use for the crypto operations

Exceptions

Not_Implemented

if the TPM2-TSS does not support crypto callbacks

See also

supports_botan_crypto_backend()

Definition at line 98 of file tpm2_context.cpp.

                                                                                           {
#if defined(BOTAN_HAS_TPM2_CRYPTO_BACKEND)
   BOTAN_STATE_CHECK(!uses_botan_crypto_backend());
   m_impl->m_crypto_callback_state = Botan::TPM2::use_botan_crypto_backend(esys_context(), rng);
#else
   BOTAN_UNUSED(rng);
   throw Not_Implemented("This build of botan does not provide the TPM2 crypto backend");
#endif
}

References BOTAN_STATE_CHECK, BOTAN_UNUSED, Context(), esys_context(), use_botan_crypto_backend(), Botan::TPM2::use_botan_crypto_backend(), and uses_botan_crypto_backend().

Referenced by operator=(), and use_botan_crypto_backend().

uses_botan_crypto_backend()

bool Botan::TPM2::Context::uses_botan_crypto_backend ( ) const

noexcept

Returns

true if botan is used for the TSS' crypto functions

Definition at line 108 of file tpm2_context.cpp.

                                                       {
#if defined(BOTAN_HAS_TPM2_CRYPTO_BACKEND)
   return m_impl->m_crypto_callback_state != nullptr;
#else
   return false;
#endif
}

Referenced by operator=(), use_botan_crypto_backend(), and ~Context().

vendor()

std::string Botan::TPM2::Context::vendor

(

)

const

Returns

the Vendor of the TPM2

Definition at line 207 of file tpm2_context.cpp.

                                {
   constexpr std::array properties = {
      TPM2_PT_VENDOR_STRING_1, TPM2_PT_VENDOR_STRING_2, TPM2_PT_VENDOR_STRING_3, TPM2_PT_VENDOR_STRING_4};
   std::array<uint8_t, properties.size() * 4 + 1 /* ensure zero-termination */> vendor_string{};
 
   BufferStuffer bs(vendor_string);
 
   // The vendor name is transported in several uint32_t fields that are
   // loaded as big-endian bytes and concatenated to form the vendor string.
   for(auto prop : properties) {
      bs.append(store_be(get_tpm_property(m_impl->m_ctx, prop)));
   }
 
   BOTAN_ASSERT_NOMSG(bs.remaining_capacity() == 1);  // the ensured zero-termination
   return std::string(cast_uint8_ptr_to_char(vendor_string.data()));
}

References Botan::BufferStuffer::append(), BOTAN_ASSERT_NOMSG, Botan::cast_uint8_ptr_to_char(), Botan::BufferStuffer::remaining_capacity(), and Botan::store_be().

---

The documentation for this class was generated from the following files:

• src/lib/prov/tpm2/tpm2_context.h
• src/lib/prov/tpm2/tpm2_context.cpp