Namespaces
namespace	detail

Classes
class	AttributeWrapper

class	Context

struct	CryptoCallbackState

class	EC_PrivateKey

class	EC_PublicKey

class	Error

struct	esys_liberator

class	HashFunction

class	Object

struct	ObjectAttributes

struct	ObjectHandles

class	ObjectSetter

class	PrivateKey

struct	PropMap

struct	PublicInfo

class	PublicKey

class	RandomNumberGenerator

class	RSA_PrivateKey

class	RSA_PublicKey

class	Session

struct	SessionAttributes

class	SessionBundle

class	Signature_Operation

class	Signature_Operation_Base

struct	SignatureAlgorithmSelection

class	Verification_Operation

Concepts
concept	tpm2_buffer

Typedefs
using	TPMA_SESSION = uint8_t

template<typename T >
using	unique_esys_ptr = std::unique_ptr<T, esys_liberator>
	A unique pointer type for ESYS handles that automatically frees the handle.

Functions
constexpr auto	as_span (tpm2_buffer auto &data)
	Construct a std::span as a view into a TPM2 buffer.

constexpr auto	as_span (tpm2_buffer auto &data, size_t length)

std::optional< TPM2_ALG_ID >	asymmetric_algorithm_botan_to_tss2 (std::string_view algo_name) noexcept

std::optional< std::pair< TPMI_ALG_SYM, TPM2_KEY_BITS > >	block_cipher_botan_to_tss2 (std::string_view cipher_name) noexcept

std::optional< std::string >	block_cipher_tss2_to_botan (TPMI_ALG_SYM cipher_id, TPM2_KEY_BITS key_bits) noexcept

constexpr void	check_rc (std::string_view location, TSS2_RC rc)

template<TSS2_RC... expected_errors> requires (sizeof...(expected_errors) > 0)
constexpr TSS2_RC	check_rc_expecting (std::string_view location, TSS2_RC rc)

std::optional< TPMT_SYM_DEF >	cipher_botan_to_tss2 (std::string_view algo_name)

std::optional< TPMI_ALG_SYM_MODE >	cipher_mode_botan_to_tss2 (std::string_view mode_name) noexcept

std::optional< std::string >	cipher_mode_tss2_to_botan (TPMI_ALG_SYM_MODE mode_id)

std::optional< std::string >	cipher_tss2_to_botan (TPMT_SYM_DEF cipher_def) noexcept

template<concepts::resizable_byte_buffer OutT>
constexpr OutT	copy_into (const tpm2_buffer auto &data)

template<tpm2_buffer T>
constexpr T	copy_into (std::span< const uint8_t > data)

template<tpm2_buffer T>
constexpr void	copy_into (T &dest, std::span< const uint8_t > data)

std::optional< size_t >	curve_id_order_byte_size (TPMI_ECC_CURVE curve_id)

std::optional< std::string >	curve_id_tss2_to_botan (TPMI_ECC_CURVE mode_id)

std::string	get_botan_hash_name (TPM2_ALG_ID hash_id)

TSS2_RC	get_raw_rc (TSS2_RC rc)

std::optional< TPM2_ECC_CURVE >	get_tpm2_curve_id (const OID &curve_oid)

TPMI_ALG_HASH	get_tpm2_hash_type (std::string_view hash_name)

TPMT_SYM_DEF	get_tpm2_sym_cipher_spec (std::string_view algo_name)

std::optional< TPMI_ALG_HASH >	hash_algo_botan_to_tss2 (std::string_view hash_name) noexcept

std::optional< std::string >	hash_algo_tss2_to_botan (TPMI_ALG_HASH hash_id) noexcept

template<tpm2_buffer T>
constexpr T	init_empty ()
	Create an empty TPM2 buffer of the given type.

template<tpm2_buffer T>
constexpr T	init_with_size (size_t length)
	Create a TPM2 buffer of a given type and `length`.

constexpr auto	out_persistent_handle (Object &object)

constexpr auto	out_transient_handle (Object &object)

template<typename MaskT , typename FieldPointerT >
	PropMap (MaskT, FieldPointerT) -> PropMap< MaskT, FieldPointerT >
	Deduction guide to simplify the creation of PropMap instances.

std::optional< TPMI_ALG_ASYM_SCHEME >	rsa_encryption_padding_botan_to_tss2 (std::string_view name) noexcept

std::optional< TPMT_RSA_DECRYPT >	rsa_encryption_scheme_botan_to_tss2 (std::string_view padding)

std::pair< BigInt, BigInt >	rsa_pubkey_components_from_tss2_public (const TPM2B_PUBLIC *public_area)

std::optional< TPMI_ALG_SIG_SCHEME >	rsa_signature_padding_botan_to_tss2 (std::string_view padding_name) noexcept

std::optional< TPMT_SIG_SCHEME >	rsa_signature_scheme_botan_to_tss2 (std::string_view name)

void	set_crypto_callbacks (ESYS_CONTEXT ctx, void callback_state)

bool	supports_botan_crypto_backend () noexcept

std::unique_ptr< CryptoCallbackState >	use_botan_crypto_backend (ESYS_CONTEXT *context, const std::shared_ptr< Botan::RandomNumberGenerator > &rng)

Typedef Documentation

◆ TPMA_SESSION

using Botan::TPM2::TPMA_SESSION = uint8_t

Definition at line 20 of file tpm2_session.h.

◆ unique_esys_ptr

template<typename T >

using Botan::TPM2::unique_esys_ptr = std::unique_ptr<T, esys_liberator>

A unique pointer type for ESYS handles that automatically frees the handle.

Definition at line 162 of file tpm2_util.h.

Function Documentation

◆ as_span() [1/2]

auto Botan::TPM2::as_span ( tpm2_buffer auto & data )

constexpr

Construct a std::span as a view into a TPM2 buffer.

Definition at line 102 of file tpm2_util.h.

102 {

103 return std::span{data.buffer, data.size};

104}

Referenced by as_span(), copy_into(), copy_into(), Botan::TPM2::PrivateKey::create_transient_from_template(), Botan::TPM2::Verification_Operation::is_valid_signature(), rsa_pubkey_components_from_tss2_public(), and Botan::TPM2::Signature_Operation::sign().

◆ as_span() [2/2]

auto Botan::TPM2::as_span	(	tpm2_buffer auto &	data,
		size_t	length )

constexpr

Set the size of data to length and construct a std::span as a view into data

Definition at line 108 of file tpm2_util.h.

                                                              {
   BOTAN_ASSERT_NOMSG(length <= sizeof(data.buffer));
   data.size = static_cast<decltype(data.size)>(length);
   return as_span(data);
}

References as_span(), and BOTAN_ASSERT_NOMSG.

◆ asymmetric_algorithm_botan_to_tss2()

std::optional< TPM2_ALG_ID > Botan::TPM2::asymmetric_algorithm_botan_to_tss2 ( std::string_view algo_name )

inlinenodiscardnoexcept

Definition at line 26 of file tpm2_algo_mappings.h.

                                      {
   if(algo_name == "RSA") {
      return TPM2_ALG_RSA;
   } else if(algo_name == "ECC") {
      return TPM2_ALG_ECC;
   } else if(algo_name == "ECDSA") {
      return TPM2_ALG_ECDSA;
   } else if(algo_name == "ECDH") {
      return TPM2_ALG_ECDH;
   } else if(algo_name == "ECDAA") {
      return TPM2_ALG_ECDAA;
   } else {
      return std::nullopt;
   }
}

Referenced by Botan::TPM2::Context::supports_algorithm().

◆ block_cipher_botan_to_tss2()

std::optional< std::pair< TPMI_ALG_SYM, TPM2_KEY_BITS > > Botan::TPM2::block_cipher_botan_to_tss2 ( std::string_view cipher_name )

inlinenodiscardnoexcept

Definition at line 159 of file tpm2_algo_mappings.h.

                                        {
   if(cipher_name == "AES-128") {
      return std::pair{TPM2_ALG_AES, 128};
   } else if(cipher_name == "AES-192") {
      return std::pair{TPM2_ALG_AES, 192};
   } else if(cipher_name == "AES-256") {
      return std::pair{TPM2_ALG_AES, 256};
   } else if(cipher_name == "SM4") {
      return std::pair{TPM2_ALG_SM4, 128};
   } else if(cipher_name == "Camellia-128") {
      return std::pair{TPM2_ALG_CAMELLIA, 128};
   } else if(cipher_name == "Camellia-192") {
      return std::pair{TPM2_ALG_CAMELLIA, 192};
   } else if(cipher_name == "Camellia-256") {
      return std::pair{TPM2_ALG_CAMELLIA, 256};
   } else if(cipher_name == "3DES") {
      return std::pair{TPM2_ALG_TDES, 168};
   } else {
      return {};
   }
}

Referenced by cipher_botan_to_tss2(), and Botan::TPM2::Context::supports_algorithm().

◆ block_cipher_tss2_to_botan()

std::optional< std::string > Botan::TPM2::block_cipher_tss2_to_botan	(	TPMI_ALG_SYM	cipher_id,
		TPM2_KEY_BITS	key_bits )

inlinenodiscardnoexcept

Definition at line 120 of file tpm2_algo_mappings.h.

                                                                                                            {
   switch(cipher_id) {
      case TPM2_ALG_AES:
         if(key_bits == 128) {
            return "AES-128";
         } else if(key_bits == 192) {
            return "AES-192";
         } else if(key_bits == 256) {
            return "AES-256";
         }
         break;
 
      case TPM2_ALG_SM4:
         if(key_bits == 128) {
            return "SM4";
         }
         break;
 
      case TPM2_ALG_CAMELLIA:
         if(key_bits == 128) {
            return "Camellia-128";
         } else if(key_bits == 192) {
            return "Camellia-192";
         } else if(key_bits == 256) {
            return "Camellia-256";
         }
         break;
 
      case TPM2_ALG_TDES:
         return "3DES";
 
      default:
         break;
   }
 
   return std::nullopt;
}

Referenced by cipher_tss2_to_botan().

◆ check_rc()

void Botan::TPM2::check_rc	(	std::string_view	location,
		TSS2_RC	rc )

constexpr

Check the return code and throw an exception if some error occured.

Exceptions

TPM2::Error if an error occured.

Definition at line 54 of file tpm2_util.h.

                                                             {
   if(rc != TSS2_RC_SUCCESS) {
      throw Error(location, rc);
   }
}

Referenced by Botan::TPM2::Object::_public_info(), Botan::TPM2::Session::attributes(), Botan::TPM2::Session::authenticated_session(), check_rc_expecting(), Botan::TPM2::Context::create(), Botan::TPM2::Context::create(), Botan::TPM2::PrivateKey::create_transient_from_template(), Botan::TPM2::Context::evict(), Botan::TPM2::HashFunction::final_with_ticket(), Botan::TPM2::PrivateKey::load_transient(), Botan::TPM2::PublicKey::load_transient(), Botan::TPM2::Context::persist(), Botan::TPM2::Session::set_attributes(), set_crypto_callbacks(), Botan::TPM2::Signature_Operation::sign(), Botan::TPM2::Session::tpm_nonce(), and Botan::TPM2::Session::unauthenticated_session().

◆ check_rc_expecting()

template<TSS2_RC... expected_errors>
requires (sizeof...(expected_errors) > 0)

TSS2_RC Botan::TPM2::check_rc_expecting	(	std::string_view	location,
		TSS2_RC	rc )

nodiscardconstexpr

Check the return code and throw an exception if an unexpected error occured.

Errors that are listed in the expected_errors parameter are considered expected and will not cause an exception to be thrown. Instead the error code is decoded and returned to the caller for further processing.

Exceptions

TPM2::Error if an unexpected error occured.

Returns: TSS2_RC_SUCCESS or one of the expected error codes.

Definition at line 72 of file tpm2_util.h.

                                                                                        {
   // If the RC is success, we can return early and avoid the decoding.
   if(rc == TSS2_RC_SUCCESS) {
      return rc;
   }
 
   // An error occured, we need to decode it to check if it was expected.
   const TSS2_RC decoded_rc = get_raw_rc(rc);
 
   // Check if the error is one of the expected and return those to the caller.
   const bool is_expected_by_caller = ((decoded_rc == expected_errors) || ...);
   if(is_expected_by_caller) {
      return decoded_rc;
   }
 
   // The error was not expected, so call the normal error handling which
   // will throw an exception.
   check_rc(location, rc);
 
   // We know, rc is not 'success', so this won't ever be reached.
   return rc;
}

References check_rc(), and get_raw_rc().

Referenced by Botan::TPM2::Verification_Operation::is_valid_signature().

◆ cipher_botan_to_tss2()

std::optional< TPMT_SYM_DEF > Botan::TPM2::cipher_botan_to_tss2 ( std::string_view algo_name )

inlinenodiscard

Definition at line 296 of file tpm2_algo_mappings.h.

                                                                                              {
   SCAN_Name spec(algo_name);
   if(spec.arg_count() == 0) {
      return std::nullopt;
   }
 
   const auto cipher = block_cipher_botan_to_tss2(spec.arg(0));
   const auto mode = cipher_mode_botan_to_tss2(spec.algo_name());
 
   if(!cipher || !mode) {
      return std::nullopt;
   }
 
   return TPMT_SYM_DEF{
      .algorithm = cipher->first,
      .keyBits = {.sym = cipher->second},
      .mode = {.sym = mode.value()},
   };
}

References Botan::SCAN_Name::algo_name(), Botan::SCAN_Name::arg(), Botan::SCAN_Name::arg_count(), block_cipher_botan_to_tss2(), and cipher_mode_botan_to_tss2().

Referenced by get_tpm2_sym_cipher_spec(), and Botan::TPM2::Context::supports_algorithm().

◆ cipher_mode_botan_to_tss2()

std::optional< TPMI_ALG_SYM_MODE > Botan::TPM2::cipher_mode_botan_to_tss2 ( std::string_view mode_name )

inlinenodiscardnoexcept

Definition at line 262 of file tpm2_algo_mappings.h.

                                                                                                                 {
   if(mode_name == "CFB") {
      return TPM2_ALG_CFB;
   } else if(mode_name == "CBC") {
      return TPM2_ALG_CBC;
   } else if(mode_name == "ECB") {
      return TPM2_ALG_ECB;
   } else if(mode_name == "OFB") {
      return TPM2_ALG_OFB;
   } else if(mode_name == "CTR" || mode_name == "CTR-BE") {
      return TPM2_ALG_CTR;
   } else {
      return std::nullopt;
   }
}

Referenced by cipher_botan_to_tss2(), and Botan::TPM2::Context::supports_algorithm().

◆ cipher_mode_tss2_to_botan()

std::optional< std::string > Botan::TPM2::cipher_mode_tss2_to_botan ( TPMI_ALG_SYM_MODE mode_id )

inlinenodiscard

Definition at line 182 of file tpm2_algo_mappings.h.

                                                                                                 {
   switch(mode_id) {
      case TPM2_ALG_CFB:
         return "CFB";
      case TPM2_ALG_CBC:
         return "CBC";
      case TPM2_ALG_ECB:
         return "ECB";
      case TPM2_ALG_OFB:
         return "OFB";
      case TPM2_ALG_CTR:
         return "CTR";
      default:  // TPMI_ALG_SYM_MODE is not an enum
         return std::nullopt;
   }
}

Referenced by cipher_tss2_to_botan().

◆ cipher_tss2_to_botan()

std::optional< std::string > Botan::TPM2::cipher_tss2_to_botan ( TPMT_SYM_DEF cipher_def )

inlinenodiscardnoexcept

Returns: a Botan cipher mode name string if the cipher_id, key_bits and mode_name are known, otherwise std::nullopt

Definition at line 282 of file tpm2_algo_mappings.h.

                                                                                                   {
   const auto cipher_name = block_cipher_tss2_to_botan(cipher_def.algorithm, cipher_def.keyBits.sym);
   if(!cipher_name) {
      return std::nullopt;
   }
 
   const auto mode_name = cipher_mode_tss2_to_botan(cipher_def.mode.sym);
   if(!mode_name) {
      return std::nullopt;
   }
 
   return Botan::fmt("{}({})", mode_name.value(), cipher_name.value());
}

References block_cipher_tss2_to_botan(), cipher_mode_tss2_to_botan(), and Botan::fmt().

◆ copy_into() [1/3]

template<concepts::resizable_byte_buffer OutT>

OutT Botan::TPM2::copy_into ( const tpm2_buffer auto & data )

constexpr

Copy the content of the TPM2 buffer data into a new resizable byte buffer of the user's choosing.

Definition at line 133 of file tpm2_util.h.

                                                       {
   OutT result;
   result.resize(data.size);
   copy_mem(result, as_span(data));
   return result;
}

References as_span(), and Botan::copy_mem().

◆ copy_into() [2/3]

template<tpm2_buffer T>

T Botan::TPM2::copy_into ( std::span< const uint8_t > data )

constexpr

Create a TPM2 buffer from the provided data, assuming that the provided data is not larger than the capacity of the buffer type.

Definition at line 124 of file tpm2_util.h.

                                                   {
   T result;
   copy_into(result, data);
   return result;
}

References copy_into(), and T.

◆ copy_into() [3/3]

template<tpm2_buffer T>

void Botan::TPM2::copy_into	(	T &	dest,
		std::span< const uint8_t >	data )

constexpr

Copy the data into the TPM2 buffer dest, assuming that the provided data is not larger than the capacity of the buffer.

Definition at line 117 of file tpm2_util.h.

117 {

118 copy_mem(as_span(dest, data.size()), data);

119}

References as_span(), and Botan::copy_mem().

Referenced by copy_into(), Botan::TPM2::EC_PrivateKey::create_unrestricted_transient(), Botan::TPM2::RSA_PrivateKey::create_unrestricted_transient(), Botan::TPM2::PrivateKey::load_transient(), Botan::TPM2::Context::persist(), and Botan::TPM2::Session::tpm_nonce().

◆ curve_id_order_byte_size()

std::optional< size_t > Botan::TPM2::curve_id_order_byte_size ( TPMI_ECC_CURVE curve_id )

inlinenodiscard

Definition at line 221 of file tpm2_algo_mappings.h.

                                                                                           {
   switch(curve_id) {
      case TPM2_ECC_NIST_P192:
         return 24;
      case TPM2_ECC_NIST_P224:
         return 28;
      case TPM2_ECC_NIST_P256:
         return 32;
      case TPM2_ECC_NIST_P384:
         return 48;
      case TPM2_ECC_NIST_P521:
         return 66;  // Rounded up to the next full byte
      case TPM2_ECC_SM2_P256:
         return 32;
      default:
         return std::nullopt;
   }
}

◆ curve_id_tss2_to_botan()

std::optional< std::string > Botan::TPM2::curve_id_tss2_to_botan ( TPMI_ECC_CURVE mode_id )

inlinenodiscard

Definition at line 199 of file tpm2_algo_mappings.h.

                                                                                           {
   // Currently, tpm2-tss does not include support for Brainpool curves or 25519/448.
   // Once the corresponding PR (https://github.com/tpm2-software/tpm2-tss/pull/2897) is merged and released,
   // this function should be updated.
   switch(mode_id) {
      case TPM2_ECC_NIST_P192:
         return "secp192r1";
      case TPM2_ECC_NIST_P224:
         return "secp224r1";
      case TPM2_ECC_NIST_P256:
         return "secp256r1";
      case TPM2_ECC_NIST_P384:
         return "secp384r1";
      case TPM2_ECC_NIST_P521:
         return "secp521r1";
      case TPM2_ECC_SM2_P256:
         return "sm2p256v1";
      default:
         return std::nullopt;
   }
}

◆ get_botan_hash_name()

std::string Botan::TPM2::get_botan_hash_name ( TPM2_ALG_ID hash_id )

inlinenodiscard

Returns: a Botan hash name string if the hash_id value is known, otherwise throws Invalid_State

Definition at line 112 of file tpm2_algo_mappings.h.

                                                                        {
   if(auto hash_name = hash_algo_tss2_to_botan(hash_id)) {
      return hash_name.value();
   }
 
   throw Invalid_State("TPM 2.0 hash object with unexpected hash type");
}

References hash_algo_tss2_to_botan().

Referenced by Botan::TPM2::HashFunction::name().

◆ get_raw_rc()

TSS2_RC Botan::TPM2::get_raw_rc ( TSS2_RC rc )

Definition at line 18 of file tpm2_error.cpp.

                               {
#if defined(BOTAN_TSS2_SUPPORTS_ERROR_DECODING)
   TSS2_RC_INFO info;
   const TSS2_RC decoding_rc = Tss2_RC_DecodeInfo(rc, &info);
   if(decoding_rc != TSS2_RC_SUCCESS) [[unlikely]] {
      throw Error(fmt("Decoding RC failed (was: {})", rc), decoding_rc);
   }
   return info.error;
#else
   // This fallback implementation is derived from the implementation of
   // Tss2_RC_DecodeInfo in tpm2-tss 4.0.0.
   const bool formatted = (rc & (1 << 7)) != 0;
   if(formatted) {
      return (rc & 0x3F) | TPM2_RC_FMT1;
   } else {
      return rc & 0xFFFF;
   }
#endif
}

References Botan::fmt().

Referenced by check_rc_expecting().

◆ get_tpm2_curve_id()

std::optional< TPM2_ECC_CURVE > Botan::TPM2::get_tpm2_curve_id ( const OID & curve_oid )

inlinenodiscard

Definition at line 240 of file tpm2_algo_mappings.h.

                                                                                         {
   // Currently, tpm2-tss does not include support for Brainpool curves or 25519/448.
   // Once the corresponding PR (https://github.com/tpm2-software/tpm2-tss/pull/2897) is merged and released,
   // this function should be updated.
   const std::string curve_name = curve_oid.to_formatted_string();
   if(curve_name == "secp192r1") {
      return TPM2_ECC_NIST_P192;
   } else if(curve_name == "secp224r1") {
      return TPM2_ECC_NIST_P224;
   } else if(curve_name == "secp256r1") {
      return TPM2_ECC_NIST_P256;
   } else if(curve_name == "secp384r1") {
      return TPM2_ECC_NIST_P384;
   } else if(curve_name == "secp521r1") {
      return TPM2_ECC_NIST_P521;
   } else if(curve_name == "sm2p256v1") {
      return TPM2_ECC_SM2_P256;
   } else {
      return std::nullopt;
   }
}

References Botan::OID::to_formatted_string().

Referenced by Botan::TPM2::EC_PrivateKey::create_unrestricted_transient().

◆ get_tpm2_hash_type()

TPMI_ALG_HASH Botan::TPM2::get_tpm2_hash_type ( std::string_view hash_name )

inlinenodiscard

Returns: a TPMI_ALG_HASH value if the hash_name is known, otherwise throws Lookup_Error

Definition at line 73 of file tpm2_algo_mappings.h.

                                                                                {
   if(auto hash_id = hash_algo_botan_to_tss2(hash_name)) {
      return hash_id.value();
   }
 
   throw Lookup_Error("TPM 2.0 Hash", hash_name);
}

References hash_algo_botan_to_tss2().

Referenced by Botan::TPM2::Session::authenticated_session(), and Botan::TPM2::Session::unauthenticated_session().

◆ get_tpm2_sym_cipher_spec()

TPMT_SYM_DEF Botan::TPM2::get_tpm2_sym_cipher_spec ( std::string_view algo_name )

inlinenodiscard

Definition at line 316 of file tpm2_algo_mappings.h.

                                                                                     {
   if(auto cipher = cipher_botan_to_tss2(algo_name)) {
      return cipher.value();
   }
 
   throw Lookup_Error("TPM 2.0 Symmetric Cipher Spec", algo_name);
}

References cipher_botan_to_tss2().

Referenced by Botan::TPM2::Session::authenticated_session(), and Botan::TPM2::Session::unauthenticated_session().

◆ hash_algo_botan_to_tss2()

std::optional< TPMI_ALG_HASH > Botan::TPM2::hash_algo_botan_to_tss2 ( std::string_view hash_name )

inlinenodiscardnoexcept

Returns: a TPMI_ALG_HASH value if the hash_name is known, otherwise std::nullopt

Definition at line 47 of file tpm2_algo_mappings.h.

                                                                                                           {
   if(hash_name == "SHA-1") {
      return TPM2_ALG_SHA1;
   } else if(hash_name == "SHA-256") {
      return TPM2_ALG_SHA256;
   } else if(hash_name == "SHA-384") {
      return TPM2_ALG_SHA384;
   } else if(hash_name == "SHA-512") {
      return TPM2_ALG_SHA512;
   } else if(hash_name == "SHA-3(256)") {
      return TPM2_ALG_SHA3_256;
   } else if(hash_name == "SHA-3(384)") {
      return TPM2_ALG_SHA3_384;
   } else if(hash_name == "SHA-3(512)") {
      return TPM2_ALG_SHA3_512;
   } else if(hash_name == "SM3") {
      return TPM2_ALG_SM3_256;
   } else {
      return std::nullopt;
   }
}

Referenced by get_tpm2_hash_type(), rsa_encryption_scheme_botan_to_tss2(), rsa_signature_scheme_botan_to_tss2(), and Botan::TPM2::Context::supports_algorithm().

◆ hash_algo_tss2_to_botan()

std::optional< std::string > Botan::TPM2::hash_algo_tss2_to_botan ( TPMI_ALG_HASH hash_id )

inlinenodiscardnoexcept

Returns: a Botan hash name string if the hash_id value is known, otherwise std::nullopt

Definition at line 85 of file tpm2_algo_mappings.h.

                                                                                                    {
   switch(hash_id) {
      case TPM2_ALG_SHA1:
         return "SHA-1";
      case TPM2_ALG_SHA256:
         return "SHA-256";
      case TPM2_ALG_SHA384:
         return "SHA-384";
      case TPM2_ALG_SHA512:
         return "SHA-512";
      case TPM2_ALG_SHA3_256:
         return "SHA-3(256)";
      case TPM2_ALG_SHA3_384:
         return "SHA-3(384)";
      case TPM2_ALG_SHA3_512:
         return "SHA-3(512)";
      case TPM2_ALG_SM3_256:
         return "SM3";
      default:  // TPMI_ALG_HASH is not an enum
         return std::nullopt;
   }
}

Referenced by get_botan_hash_name().

◆ init_empty()

template<tpm2_buffer T>

T Botan::TPM2::init_empty ( )

constexpr

Create an empty TPM2 buffer of the given type.

Definition at line 152 of file tpm2_util.h.

152 {

153 return init_with_size<T>(0);

154}

References init_with_size().

Referenced by Botan::TPM2::EC_PrivateKey::create_unrestricted_transient(), Botan::TPM2::RSA_PrivateKey::create_unrestricted_transient(), Botan::TPM2::HashFunction::final_with_ticket(), and Botan::TPM2::Signature_Operation::sign().

◆ init_with_size()

template<tpm2_buffer T>

T Botan::TPM2::init_with_size ( size_t length )

constexpr

Create a TPM2 buffer of a given type and length.

Definition at line 142 of file tpm2_util.h.

                                          {
   T result;
   BOTAN_ASSERT_NOMSG(length <= sizeof(result.buffer));
   result.size = static_cast<decltype(result.size)>(length);
   clear_bytes(result.buffer, length);
   return result;
}

References BOTAN_ASSERT_NOMSG, Botan::clear_bytes(), and T.

Referenced by init_empty().

◆ out_persistent_handle()

auto Botan::TPM2::out_persistent_handle ( Object & object )

constexpr

Helper to set the persistent handle of an object from a TSS2 library function's out parameter.

Definition at line 223 of file tpm2_util.h.

223 {

224 return ObjectSetter{object, true};

225}

Botan::TPM2::ObjectSetter

Definition tpm2_util.h:182

Referenced by Botan::TPM2::Context::persist().

◆ out_transient_handle()

auto Botan::TPM2::out_transient_handle ( Object & object )

constexpr

Helper to set the transient handle of an object from a TSS2 library function's out parameter.

Definition at line 217 of file tpm2_util.h.

217 {

218 return ObjectSetter{object, false};

219}

Referenced by Botan::TPM2::Session::authenticated_session(), Botan::TPM2::PrivateKey::create_transient_from_template(), Botan::TPM2::PrivateKey::load_transient(), Botan::TPM2::PublicKey::load_transient(), Botan::TPM2::Context::persist(), and Botan::TPM2::Session::unauthenticated_session().

◆ PropMap()

template<typename MaskT , typename FieldPointerT >

Botan::TPM2::PropMap	(	MaskT	,
		FieldPointerT	) -> PropMap< MaskT, FieldPointerT >

Deduction guide to simplify the creation of PropMap instances.

◆ rsa_encryption_padding_botan_to_tss2()

std::optional< TPMI_ALG_ASYM_SCHEME > Botan::TPM2::rsa_encryption_padding_botan_to_tss2 ( std::string_view name )

inlinenodiscardnoexcept

Definition at line 361 of file tpm2_algo_mappings.h.

                                 {
   if(name == "OAEP" || name == "EME-OAEP" || name == "EME1") {
      return TPM2_ALG_OAEP;
   } else if(name == "PKCS1v15" || name == "EME-PKCS1-v1_5") {
      return TPM2_ALG_RSAES;
   } else if(name == "Raw") {
      return TPM2_ALG_NULL;
   } else {
      return std::nullopt;
   }
}

References name.

Referenced by rsa_encryption_scheme_botan_to_tss2(), and Botan::TPM2::Context::supports_algorithm().

◆ rsa_encryption_scheme_botan_to_tss2()

std::optional< TPMT_RSA_DECRYPT > Botan::TPM2::rsa_encryption_scheme_botan_to_tss2 ( std::string_view padding )

inlinenodiscard

Definition at line 374 of file tpm2_algo_mappings.h.

                                                                                                               {
   const SCAN_Name req(padding);
   const auto scheme = rsa_encryption_padding_botan_to_tss2(req.algo_name());
   if(!scheme) {
      return std::nullopt;
   }
 
   if(scheme.value() == TPM2_ALG_OAEP) {
      if(req.arg_count() < 1) {
         return std::nullopt;
      }
 
      const auto hash = hash_algo_botan_to_tss2(req.arg(0));
      if(!hash) {
         return std::nullopt;
      }
 
      return TPMT_RSA_DECRYPT{
         .scheme = scheme.value(),
         .details = {.oaep = {.hashAlg = hash.value()}},
      };
   } else if(scheme.value() == TPM2_ALG_RSAES) {
      return TPMT_RSA_DECRYPT{
         .scheme = scheme.value(),
         .details = {.rsaes = {}},
      };
   } else {
      return std::nullopt;
   }
}

References Botan::SCAN_Name::algo_name(), Botan::SCAN_Name::arg(), Botan::SCAN_Name::arg_count(), hash_algo_botan_to_tss2(), and rsa_encryption_padding_botan_to_tss2().

Referenced by Botan::TPM2::Context::supports_algorithm().

◆ rsa_pubkey_components_from_tss2_public()

std::pair< BigInt, BigInt > Botan::TPM2::rsa_pubkey_components_from_tss2_public ( const TPM2B_PUBLIC * public_blob )

This helper function transforms a public_blob in a TPM2B_PUBLIC* format into the functional components of an RSA public key. Namely, a pair of modulus and exponent as big integers.

Parameters

public_blob The public blob to decompose into RSA pubkey components

Definition at line 29 of file tpm2_rsa.cpp.

                                                                                                {
   BOTAN_ASSERT_NONNULL(public_area);
   const auto& pub = public_area->publicArea;
   BOTAN_ARG_CHECK(pub.type == TPM2_ALG_RSA, "Public key is not an RSA key");
 
   // TPM2 may report 0 when the exponent is 'the default' (2^16 + 1)
   const auto exponent = (pub.parameters.rsaDetail.exponent == 0) ? 65537 : pub.parameters.rsaDetail.exponent;
 
   return {BigInt(as_span(pub.unique.rsa)), exponent};
}

References as_span(), BOTAN_ARG_CHECK, and BOTAN_ASSERT_NONNULL.

◆ rsa_signature_padding_botan_to_tss2()

std::optional< TPMI_ALG_SIG_SCHEME > Botan::TPM2::rsa_signature_padding_botan_to_tss2 ( std::string_view padding_name )

inlinenodiscardnoexcept

Definition at line 324 of file tpm2_algo_mappings.h.

                                         {
   // TODO(Botan4) remove the deprecated aliases
   if(padding_name == "EMSA_PKCS1" || padding_name == "PKCS1v15" || padding_name == "EMSA-PKCS1-v1_5" ||
      padding_name == "EMSA3") {
      return TPM2_ALG_RSASSA;
   } else if(padding_name == "PSS" || padding_name == "PSSR" || padding_name == "EMSA-PSS" ||
             padding_name == "PSS-MGF1" || padding_name == "EMSA4") {
      return TPM2_ALG_RSAPSS;
   } else {
      return std::nullopt;
   }
}

Referenced by rsa_signature_scheme_botan_to_tss2(), and Botan::TPM2::Context::supports_algorithm().

◆ rsa_signature_scheme_botan_to_tss2()

std::optional< TPMT_SIG_SCHEME > Botan::TPM2::rsa_signature_scheme_botan_to_tss2 ( std::string_view name )

inlinenodiscard

Definition at line 338 of file tpm2_algo_mappings.h.

                                                                                                          {
   const SCAN_Name req(name);
   if(req.arg_count() == 0) {
      return std::nullopt;
   }
 
   const auto scheme = rsa_signature_padding_botan_to_tss2(req.algo_name());
   const auto hash = hash_algo_botan_to_tss2(req.arg(0));
   if(!scheme || !hash) {
      return std::nullopt;
   }
 
   if(scheme.value() == TPM2_ALG_RSAPSS && req.arg_count() != 1) {
      // RSA signing using PSS with MGF1
      return std::nullopt;
   }
 
   return TPMT_SIG_SCHEME{
      .scheme = scheme.value(),
      .details = {.any = {.hashAlg = hash.value()}},
   };
}

References Botan::SCAN_Name::algo_name(), Botan::SCAN_Name::arg(), Botan::SCAN_Name::arg_count(), hash_algo_botan_to_tss2(), name, and rsa_signature_padding_botan_to_tss2().

Referenced by Botan::TPM2::Context::supports_algorithm().

◆ set_crypto_callbacks()

void Botan::TPM2::set_crypto_callbacks	(	ESYS_CONTEXT *	ctx,
		void *	callback_state )

Enable the Botan crypto callbacks for the given ESYS context.

The callbacks may maintain two types of state:

'userdata' is a pointer to a CryptoCallbackState object that is passed to all callback functions. This provides access to a random number generator specified by the user. The lifetime of this object is bound to the TPM2::Context.
'context' is a pointer to a DigestCallbackState object that contains either a HashFunction or a MessageAuthenticationCode object. This holds the hash state between update callback invocations. The lifetime of this object is bound to the digest callbacks, hence *_finish() and *_abort() will delete the object.

The runtime crypto backend is available since TSS2 4.0.0 and later. Explicit support for SM4 was added in TSS2 4.1.0.

Note that the callback implementations should be defensive in regard to the input parameters. All pointers should be checked for nullptr before being dereferenced. Some output parameters (e.g. out-buffer lengths) may be regarded as optional, and should be checked for nullptr before being written to.

Error code conventions:

TSS2_ESYS_RC_BAD_REFERENCE: reference (typically userdata) invalid
TSS2_ESYS_RC_BAD_VALUE: invalid input (e.g. size != 0 w/ nullptr buffer)
TSS2_ESYS_RC_NOT_SUPPORTED: algorithm identifier not mapped to Botan
TSS2_ESYS_RC_NOT_IMPLEMENTED: algorithm not available (e.g. disabled)

Enable Botan's crypto callbacks in the TPM2-TSS for the given context.

Exceptions

Not_Implemented if the TPM2-TSS does not support crypto callbacks.

Definition at line 861 of file tpm2_crypto_backend_impl.cpp.

                                                                   {
#if defined(BOTAN_TSS2_SUPPORTS_CRYPTO_CALLBACKS)
   BOTAN_ASSERT_NONNULL(ctx);
 
   // clang-format off
   ESYS_CRYPTO_CALLBACKS callbacks{
      .rsa_pk_encrypt = &rsa_pk_encrypt,
      .hash_start     = &hash_start,
      .hash_update    = &hash_update,
      .hash_finish    = &hash_finish,
      .hash_abort     = &hash_abort,
      .hmac_start     = &hmac_start,
      .hmac_update    = &hmac_update,
      .hmac_finish    = &hmac_finish,
      .hmac_abort     = &hmac_abort,
      .get_random2b   = &get_random2b,
      .get_ecdh_point = &get_ecdh_point,
      .aes_encrypt    = &aes_encrypt,
      .aes_decrypt    = &aes_decrypt,
#if defined(BOTAN_TSS2_SUPPORTS_SM4_IN_CRYPTO_CALLBACKS)
      .sm4_encrypt    = &sm4_encrypt,
      .sm4_decrypt    = &sm4_decrypt,
#endif
      .init           = &init,
      .userdata       = callback_state,
   };
   // clang-format on
 
   check_rc("Esys_SetCryptoCallbacks", Esys_SetCryptoCallbacks(ctx, &callbacks));
#else
   BOTAN_UNUSED(ctx, callback_state);
   throw Not_Implemented(
      "This build of botan was compiled with a TSS2 version lower than 4.0.0, "
      "which does not support custom runtime crypto backends");
#endif
}

References BOTAN_ASSERT_NONNULL, BOTAN_UNUSED, check_rc(), and init.

Referenced by use_botan_crypto_backend(), and Botan::TPM2::Context::~Context().

◆ supports_botan_crypto_backend()

bool Botan::TPM2::supports_botan_crypto_backend ( )

nodiscardnoexcept

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).

Returns: true if the TSS2 supports Botan's crypto backend

Definition at line 23 of file tpm2_crypto_backend.cpp.

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

Referenced by Botan::TPM2::Context::supports_botan_crypto_backend().

◆ use_botan_crypto_backend()

std::unique_ptr< CryptoCallbackState > Botan::TPM2::use_botan_crypto_backend	(	ESYS_CONTEXT *	context,
		const std::shared_ptr< Botan::RandomNumberGenerator > &	rng )

nodiscard

Enable Botan's crypto callbacks in the TPM2-TSS for the given ESYS_CONTEXT context. Use this if you do not plan to use Botan's TPM wrapper (rooted in TPM2::Context) but still want to benefit from Botan's TPM crypto backend. Otherwise, use TPM2::Context::use_botan_crypto_backend().

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 and that the returned pointer to the CryptoCallbackState must be kept alive as long as the associated ESYS_CONTEXT is valid and used.

Parameters

context	the ESYS_CONTEXT pointer to register the crypto backend on
rng	the (independent) random number generator to be used

Returns: a state object that must be kept alive by the caller for as long as the associated ESYS_CONTEXT is valid.

Exceptions

Not_Implemented if the TPM2-TSS does not support crypto callbacks.

Definition at line 16 of file tpm2_crypto_backend.cpp.

                                                                                {
   auto crypto_callback_state = std::make_unique<CryptoCallbackState>(CryptoCallbackState{.rng = rng});
   set_crypto_callbacks(context, crypto_callback_state.get());
   return crypto_callback_state;
}

References set_crypto_callbacks().

Referenced by botan_tpm2_enable_crypto_backend(), and Botan::TPM2::Context::use_botan_crypto_backend().

Namespaces

Classes

Concepts

Typedefs

Functions

Typedef Documentation

◆ TPMA_SESSION

◆ unique_esys_ptr

Function Documentation

◆ as_span() [1/2]

◆ as_span() [2/2]

◆ asymmetric_algorithm_botan_to_tss2()

◆ block_cipher_botan_to_tss2()

◆ block_cipher_tss2_to_botan()

◆ check_rc()

◆ check_rc_expecting()

◆ cipher_botan_to_tss2()

◆ cipher_mode_botan_to_tss2()

◆ cipher_mode_tss2_to_botan()

◆ cipher_tss2_to_botan()

◆ copy_into() [1/3]

◆ copy_into() [2/3]

◆ copy_into() [3/3]

◆ curve_id_order_byte_size()

◆ curve_id_tss2_to_botan()

◆ get_botan_hash_name()

◆ get_raw_rc()

◆ get_tpm2_curve_id()

◆ get_tpm2_hash_type()

◆ get_tpm2_sym_cipher_spec()

◆ hash_algo_botan_to_tss2()

◆ hash_algo_tss2_to_botan()

◆ init_empty()

◆ init_with_size()

◆ out_persistent_handle()

◆ out_transient_handle()

◆ PropMap()

◆ rsa_encryption_padding_botan_to_tss2()

◆ rsa_encryption_scheme_botan_to_tss2()

◆ rsa_pubkey_components_from_tss2_public()

◆ rsa_signature_padding_botan_to_tss2()

◆ rsa_signature_scheme_botan_to_tss2()

◆ set_crypto_callbacks()

◆ supports_botan_crypto_backend()

◆ use_botan_crypto_backend()