Botan::TPM2::Context Class Reference

#include <tpm2_context.h>

Inheritance diagram for Botan::TPM2::Context:

Public Member Functions
	Context (const Context &)=delete
	Context (Context &&ctx) noexcept=default
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 &&ctx) noexcept=default
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 (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

Referenced by create(), and create().

Context() [2/2]

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

defaultnoexcept

~Context()

Botan::TPM2::Context::~Context

(

)

Definition at line 399 of file tpm2_context.cpp.

                  {
   if(m_impl) {
      Esys_Finalize(&m_impl->m_ctx);
      Tss2_TctiLdr_Finalize(&m_impl->m_tcti_ctx);
   }
}

Member Function Documentation

create() [1/2]

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 53 of file tpm2_context.cpp.

                                                                     {
   // We cannot std::make_shared as the constructor is private
   return std::shared_ptr<Context>(new Context(tcti_nameconf.c_str()));
}

References Context().

Referenced by botan_tpm2_ctx_init(), and botan_tpm2_ctx_init_ex().

create() [2/2]

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 58 of file tpm2_context.cpp.

                                                                                               {
   const auto tcti_ptr = tcti.has_value() ? tcti->c_str() : nullptr;
   const auto conf_ptr = conf.has_value() ? conf->c_str() : nullptr;
 
   // We cannot std::make_shared as the constructor is private
   return std::shared_ptr<Context>(new Context(tcti_ptr, conf_ptr));
}

References Context().

esys_context()

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

noexcept

Returns

an ESYS_CONTEXT* for use in other TPM2 functions.

Definition at line 106 of file tpm2_context.cpp.

                                             {
   return m_impl->m_ctx;
}

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 373 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 288 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 207 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 275 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 91 of file tpm2_context.h.

{ return esys_context(); }

operator=() [1/2]

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

delete

operator=() [2/2]

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

defaultnoexcept

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 317 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 TPMI_DH_PERSISTENT new_persistent_handle = [&] {
      if(persistent_handle.has_value()) {
         return persistent_handle.value();
      } else {
         const auto free_persistent_handle = find_free_persistent_handle();
         BOTAN_STATE_CHECK(free_persistent_handle.has_value());
         return free_persistent_handle.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 312 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 279 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 213 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 45 of file tpm2_context.cpp.

                                                     {
#if defined(BOTAN_TSS2_SUPPORTS_CRYPTO_CALLBACKS) and defined(BOTAN_HAS_TPM2_CRYPTO_BACKEND)
   return true;
#else
   return false;
#endif
}

Referenced by botan_tpm2_supports_crypto_backend().

transient_handles()

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

(

)

const

Definition at line 284 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 80 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 = std::make_unique<CryptoCallbackState>(rng);
   enable_crypto_callbacks(shared_from_this());
#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, Botan::TPM2::enable_crypto_callbacks(), and uses_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 91 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 use_botan_crypto_backend().

vendor()

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

(

)

const

Returns

the Vendor of the TPM2

Definition at line 190 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