Botan 3.14.1
Crypto and TLS for C&
Botan::TPM2 Namespace Reference

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)
constexpr void check_rc (std::string_view location, TSS2_RC rc)
template<TSS2_RC... expected_errors>
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)
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)
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::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 161 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 101 of file tpm2_util.h.

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

Referenced by as_span(), copy_into(), copy_into(), Botan::TPM2::PrivateKey::create_transient_from_template(), Botan::TPM2::Verification_Operation::is_valid_signature(), 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 107 of file tpm2_util.h.

107 {
108 BOTAN_ASSERT_NOMSG(length <= sizeof(data.buffer));
109 data.size = static_cast<decltype(data.size)>(length);
110 return as_span(data);
111}
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
constexpr auto as_span(tpm2_buffer auto &data)
Construct a std::span as a view into a TPM2 buffer.
Definition tpm2_util.h:101

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

Definition at line 18 of file tpm2_algo_mappings.cpp.

18 {
19 if(algo_name == "RSA") {
20 return TPM2_ALG_RSA;
21 } else if(algo_name == "ECC") {
22 return TPM2_ALG_ECC;
23 } else if(algo_name == "ECDSA") {
24 return TPM2_ALG_ECDSA;
25 } else if(algo_name == "ECDH") {
26 return TPM2_ALG_ECDH;
27 } else if(algo_name == "ECDAA") {
28 return TPM2_ALG_ECDAA;
29 } else {
30 return std::nullopt;
31 }
32}

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

Definition at line 133 of file tpm2_algo_mappings.cpp.

134 {
135 if(cipher_name == "AES-128") {
136 return std::pair{TPM2_ALG_AES, 128};
137 } else if(cipher_name == "AES-192") {
138 return std::pair{TPM2_ALG_AES, 192};
139 } else if(cipher_name == "AES-256") {
140 return std::pair{TPM2_ALG_AES, 256};
141 } else if(cipher_name == "SM4") {
142 return std::pair{TPM2_ALG_SM4, 128};
143 } else if(cipher_name == "Camellia-128") {
144 return std::pair{TPM2_ALG_CAMELLIA, 128};
145 } else if(cipher_name == "Camellia-192") {
146 return std::pair{TPM2_ALG_CAMELLIA, 192};
147 } else if(cipher_name == "Camellia-256") {
148 return std::pair{TPM2_ALG_CAMELLIA, 256};
149 } else if(cipher_name == "3DES") {
150 return std::pair{TPM2_ALG_TDES, 168};
151 } else {
152 return {};
153 }
154}

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

Definition at line 95 of file tpm2_algo_mappings.cpp.

95 {
96 switch(cipher_id) {
97 case TPM2_ALG_AES:
98 if(key_bits == 128) {
99 return "AES-128";
100 } else if(key_bits == 192) {
101 return "AES-192";
102 } else if(key_bits == 256) {
103 return "AES-256";
104 }
105 break;
106
107 case TPM2_ALG_SM4:
108 if(key_bits == 128) {
109 return "SM4";
110 }
111 break;
112
113 case TPM2_ALG_CAMELLIA:
114 if(key_bits == 128) {
115 return "Camellia-128";
116 } else if(key_bits == 192) {
117 return "Camellia-192";
118 } else if(key_bits == 256) {
119 return "Camellia-256";
120 }
121 break;
122
123 case TPM2_ALG_TDES:
124 return "3DES";
125
126 default:
127 break;
128 }
129
130 return std::nullopt;
131}

Referenced by cipher_tss2_to_botan().

◆ check_rc()

◆ check_rc_expecting()

template<TSS2_RC... expected_errors>
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 occurred.

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::Errorif an unexpected error occurred.
Returns
TSS2_RC_SUCCESS or one of the expected error codes.

Definition at line 71 of file tpm2_util.h.

71 {
72 // If the RC is success, we can return early and avoid the decoding.
73 if(rc == TSS2_RC_SUCCESS) {
74 return rc;
75 }
76
77 // An error occurred, we need to decode it to check if it was expected.
78 const TSS2_RC decoded_rc = get_raw_rc(rc);
79
80 // Check if the error is one of the expected and return those to the caller.
81 const bool is_expected_by_caller = ((decoded_rc == expected_errors) || ...);
82 if(is_expected_by_caller) {
83 return decoded_rc;
84 }
85
86 // The error was not expected, so call the normal error handling which
87 // will throw an exception.
88 check_rc(location, rc);
89
90 // We know, rc is not 'success', so this won't ever be reached.
91 return rc;
92}
constexpr void check_rc(std::string_view location, TSS2_RC rc)
Definition tpm2_util.h:53
TSS2_RC get_raw_rc(TSS2_RC rc)
uint32_t TSS2_RC
Forward declaration of TSS2 type for convenience.
Definition tpm2_error.h:15

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

Definition at line 263 of file tpm2_algo_mappings.cpp.

263 {
264 const AlgorithmSpec spec(algo_name);
265 const auto m = spec.match("*({cipher})");
266 if(!m) {
267 return std::nullopt;
268 }
269
270 const auto cipher = block_cipher_botan_to_tss2(m->str("cipher"));
271 const auto mode = cipher_mode_botan_to_tss2(m->head());
272
273 if(!cipher || !mode) {
274 return std::nullopt;
275 }
276
277 return TPMT_SYM_DEF{
278 .algorithm = cipher->first,
279 .keyBits = {.sym = cipher->second},
280 .mode = {.sym = mode.value()},
281 };
282}
std::optional< std::pair< TPMI_ALG_SYM, TPM2_KEY_BITS > > block_cipher_botan_to_tss2(std::string_view cipher_name) noexcept
std::optional< TPMI_ALG_SYM_MODE > cipher_mode_botan_to_tss2(std::string_view mode_name) noexcept

References block_cipher_botan_to_tss2(), cipher_mode_botan_to_tss2(), and Botan::AlgorithmSpec::match().

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

Definition at line 236 of file tpm2_algo_mappings.cpp.

236 {
237 if(mode_name == "CFB") {
238 return TPM2_ALG_CFB;
239 } else if(mode_name == "CBC") {
240 return TPM2_ALG_CBC;
241 } else if(mode_name == "ECB") {
242 return TPM2_ALG_ECB;
243 } else if(mode_name == "OFB") {
244 return TPM2_ALG_OFB;
245 } else if(mode_name == "CTR" || mode_name == "CTR-BE") {
246 return TPM2_ALG_CTR;
247 } else {
248 return std::nullopt;
249 }
250}

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

Definition at line 156 of file tpm2_algo_mappings.cpp.

156 {
157 switch(mode_id) {
158 case TPM2_ALG_CFB:
159 return "CFB";
160 case TPM2_ALG_CBC:
161 return "CBC";
162 case TPM2_ALG_ECB:
163 return "ECB";
164 case TPM2_ALG_OFB:
165 return "OFB";
166 case TPM2_ALG_CTR:
167 return "CTR";
168 default: // TPMI_ALG_SYM_MODE is not an enum
169 return std::nullopt;
170 }
171}

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)
nodiscard
Returns
a Botan cipher mode name string if the cipher_id, key_bits and mode_name are known, otherwise std::nullopt

Definition at line 252 of file tpm2_algo_mappings.cpp.

252 {
253 const auto cipher_name = block_cipher_tss2_to_botan(cipher_def.algorithm, cipher_def.keyBits.sym);
254 const auto mode_name = cipher_mode_tss2_to_botan(cipher_def.mode.sym);
255
256 if(mode_name && cipher_name) {
257 return Botan::fmt("{}({})", *mode_name, *cipher_name);
258 } else {
259 return std::nullopt;
260 }
261}
std::optional< std::string > cipher_mode_tss2_to_botan(TPMI_ALG_SYM_MODE mode_id)
std::optional< std::string > block_cipher_tss2_to_botan(TPMI_ALG_SYM cipher_id, TPM2_KEY_BITS key_bits)
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

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 132 of file tpm2_util.h.

132 {
133 OutT result;
134 result.resize(data.size);
135 copy_mem(result, as_span(data));
136 return result;
137}
constexpr void copy_mem(T *out, const T *in, size_t n)
Definition mem_ops.h:144

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 123 of file tpm2_util.h.

123 {
124 T result{};
125 copy_into(result, data);
126 return result;
127}
constexpr void copy_into(T &dest, std::span< const uint8_t > data)
Definition tpm2_util.h:116

References copy_into().

◆ 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 116 of file tpm2_util.h.

116 {
117 copy_mem(as_span(dest, data.size()), data);
118}

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

Definition at line 195 of file tpm2_algo_mappings.cpp.

195 {
196 switch(curve_id) {
197 case TPM2_ECC_NIST_P192:
198 return 24;
199 case TPM2_ECC_NIST_P224:
200 return 28;
201 case TPM2_ECC_NIST_P256:
202 return 32;
203 case TPM2_ECC_NIST_P384:
204 return 48;
205 case TPM2_ECC_NIST_P521:
206 return 66; // Rounded up to the next full byte
207 case TPM2_ECC_SM2_P256:
208 return 32;
209 default:
210 return std::nullopt;
211 }
212}

◆ curve_id_tss2_to_botan()

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

Definition at line 173 of file tpm2_algo_mappings.cpp.

173 {
174 // Currently, tpm2-tss does not include support for Brainpool curves or 25519/448.
175 // Once the corresponding PR (https://github.com/tpm2-software/tpm2-tss/pull/2897) is merged and released,
176 // this function should be updated.
177 switch(mode_id) {
178 case TPM2_ECC_NIST_P192:
179 return "secp192r1";
180 case TPM2_ECC_NIST_P224:
181 return "secp224r1";
182 case TPM2_ECC_NIST_P256:
183 return "secp256r1";
184 case TPM2_ECC_NIST_P384:
185 return "secp384r1";
186 case TPM2_ECC_NIST_P521:
187 return "secp521r1";
188 case TPM2_ECC_SM2_P256:
189 return "sm2p256v1";
190 default:
191 return std::nullopt;
192 }
193}

◆ get_botan_hash_name()

std::string Botan::TPM2::get_botan_hash_name ( TPM2_ALG_ID hash_id)
nodiscard
Returns
a Botan hash name string if the hash_id value is known, otherwise throws Invalid_State

Definition at line 87 of file tpm2_algo_mappings.cpp.

87 {
88 if(auto hash_name = hash_algo_tss2_to_botan(hash_id)) {
89 return hash_name.value();
90 }
91
92 throw Invalid_State("TPM 2.0 hash object with unexpected hash type");
93}
std::optional< std::string > hash_algo_tss2_to_botan(TPMI_ALG_HASH hash_id)

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.

18 {
19#if defined(BOTAN_TSS2_SUPPORTS_ERROR_DECODING)
20 TSS2_RC_INFO info;
21 const TSS2_RC decoding_rc = Tss2_RC_DecodeInfo(rc, &info);
22 if(decoding_rc != TSS2_RC_SUCCESS) [[unlikely]] {
23 throw Error(fmt("Decoding RC failed (was: {})", rc), decoding_rc);
24 }
25 return info.error;
26#else
27 // This fallback implementation is derived from the implementation of
28 // Tss2_RC_DecodeInfo in tpm2-tss 4.0.0.
29 const bool formatted = (rc & (1 << 7)) != 0;
30 if(formatted) {
31 return (rc & 0x3F) | TPM2_RC_FMT1;
32 } else {
33 return rc & 0xFFFF;
34 }
35#endif
36}

References Botan::fmt().

Referenced by check_rc_expecting(), and Botan::TPM2::Error::Error().

◆ get_tpm2_curve_id()

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

Definition at line 214 of file tpm2_algo_mappings.cpp.

214 {
215 // Currently, tpm2-tss does not include support for Brainpool curves or 25519/448.
216 // Once the corresponding PR (https://github.com/tpm2-software/tpm2-tss/pull/2897) is merged and released,
217 // this function should be updated.
218 const auto curve_name = curve_oid.registered_name();
219 if(curve_name == "secp192r1") {
220 return TPM2_ECC_NIST_P192;
221 } else if(curve_name == "secp224r1") {
222 return TPM2_ECC_NIST_P224;
223 } else if(curve_name == "secp256r1") {
224 return TPM2_ECC_NIST_P256;
225 } else if(curve_name == "secp384r1") {
226 return TPM2_ECC_NIST_P384;
227 } else if(curve_name == "secp521r1") {
228 return TPM2_ECC_NIST_P521;
229 } else if(curve_name == "sm2p256v1") {
230 return TPM2_ECC_SM2_P256;
231 } else {
232 return std::nullopt;
233 }
234}
std::optional< std::string > registered_name() const
Definition asn1_oid.cpp:149

References Botan::OID::registered_name().

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)
nodiscard
Returns
a TPMI_ALG_HASH value if the hash_name is known, otherwise throws Lookup_Error

Definition at line 56 of file tpm2_algo_mappings.cpp.

56 {
57 if(auto hash_id = hash_algo_botan_to_tss2(hash_name)) {
58 return hash_id.value();
59 }
60
61 throw Lookup_Error("TPM 2.0 Hash", hash_name);
62}
std::optional< TPMI_ALG_HASH > hash_algo_botan_to_tss2(std::string_view hash_name) noexcept

References hash_algo_botan_to_tss2().

Referenced by Botan::TPM2::Session::authenticated_session(), Botan::TPM2::HashFunction::HashFunction(), 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)
nodiscard

Definition at line 284 of file tpm2_algo_mappings.cpp.

284 {
285 if(auto cipher = cipher_botan_to_tss2(algo_name)) {
286 return cipher.value();
287 }
288
289 throw Lookup_Error("TPM 2.0 Symmetric Cipher Spec", algo_name);
290}
std::optional< TPMT_SYM_DEF > cipher_botan_to_tss2(std::string_view 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)
nodiscardnoexcept
Returns
a TPMI_ALG_HASH value if the hash_name is known, otherwise std::nullopt

Definition at line 34 of file tpm2_algo_mappings.cpp.

34 {
35 if(hash_name == "SHA-1") {
36 return TPM2_ALG_SHA1;
37 } else if(hash_name == "SHA-256") {
38 return TPM2_ALG_SHA256;
39 } else if(hash_name == "SHA-384") {
40 return TPM2_ALG_SHA384;
41 } else if(hash_name == "SHA-512") {
42 return TPM2_ALG_SHA512;
43 } else if(hash_name == "SHA-3(256)") {
44 return TPM2_ALG_SHA3_256;
45 } else if(hash_name == "SHA-3(384)") {
46 return TPM2_ALG_SHA3_384;
47 } else if(hash_name == "SHA-3(512)") {
48 return TPM2_ALG_SHA3_512;
49 } else if(hash_name == "SM3") {
50 return TPM2_ALG_SM3_256;
51 } else {
52 return std::nullopt;
53 }
54}

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)
nodiscard
Returns
a Botan hash name string if the hash_id value is known, otherwise std::nullopt

Definition at line 64 of file tpm2_algo_mappings.cpp.

64 {
65 switch(hash_id) {
66 case TPM2_ALG_SHA1:
67 return "SHA-1";
68 case TPM2_ALG_SHA256:
69 return "SHA-256";
70 case TPM2_ALG_SHA384:
71 return "SHA-384";
72 case TPM2_ALG_SHA512:
73 return "SHA-512";
74 case TPM2_ALG_SHA3_256:
75 return "SHA-3(256)";
76 case TPM2_ALG_SHA3_384:
77 return "SHA-3(384)";
78 case TPM2_ALG_SHA3_512:
79 return "SHA-3(512)";
80 case TPM2_ALG_SM3_256:
81 return "SM3";
82 default: // TPMI_ALG_HASH is not an enum
83 return std::nullopt;
84 }
85}

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 151 of file tpm2_util.h.

151 {
152 return init_with_size<T>(0);
153}
constexpr T init_with_size(size_t length)
Create a TPM2 buffer of a given type and length.
Definition tpm2_util.h:141

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 141 of file tpm2_util.h.

141 {
142 T result{};
143 BOTAN_ASSERT_NOMSG(length <= sizeof(result.buffer));
144 result.size = static_cast<decltype(result.size)>(length);
145 clear_bytes(result.buffer, length);
146 return result;
147}
constexpr void clear_bytes(void *ptr, size_t bytes)
Definition mem_ops.h:101

References BOTAN_ASSERT_NOMSG, and Botan::clear_bytes().

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}

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

Definition at line 326 of file tpm2_algo_mappings.cpp.

326 {
327 if(name == "OAEP" || name == "EME-OAEP" || name == "EME1") {
328 return TPM2_ALG_OAEP;
329 } else if(name == "PKCS1v15" || name == "EME-PKCS1-v1_5") {
330 return TPM2_ALG_RSAES;
331 } else if(name == "Raw") {
332 return TPM2_ALG_NULL;
333 } else {
334 return std::nullopt;
335 }
336}
const char * name
Definition ffi_tls.h:59

References name.

Referenced by 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)
nodiscard

Definition at line 338 of file tpm2_algo_mappings.cpp.

338 {
339 const AlgorithmSpec req(padding);
340
341 if(const auto m = req.match("OAEP|EME-OAEP|EME1({hash})")) {
342 const auto hash = hash_algo_botan_to_tss2(m->str("hash"));
343 if(!hash) {
344 return std::nullopt;
345 }
346
347 return TPMT_RSA_DECRYPT{
348 .scheme = TPM2_ALG_OAEP,
349 .details = {.oaep = {.hashAlg = hash.value()}},
350 };
351 }
352
353 if(req.matches("PKCS1v15|EME-PKCS1-v1_5")) {
354 return TPMT_RSA_DECRYPT{
355 .scheme = TPM2_ALG_RSAES,
356 .details = {.rsaes = {}},
357 };
358 }
359
360 return std::nullopt;
361}

References hash_algo_botan_to_tss2(), Botan::AlgorithmSpec::match(), and Botan::AlgorithmSpec::matches().

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

◆ 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)
nodiscardnoexcept

Definition at line 292 of file tpm2_algo_mappings.cpp.

292 {
293 // TODO(Botan4) remove the deprecated aliases
294 if(padding_name == "EMSA_PKCS1" || padding_name == "PKCS1v15" || padding_name == "EMSA-PKCS1-v1_5" ||
295 padding_name == "EMSA3") {
296 return TPM2_ALG_RSASSA;
297 } else if(padding_name == "PSS" || padding_name == "PSSR" || padding_name == "EMSA-PSS" ||
298 padding_name == "PSS-MGF1" || padding_name == "EMSA4") {
299 return TPM2_ALG_RSAPSS;
300 } else {
301 return std::nullopt;
302 }
303}

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

Definition at line 305 of file tpm2_algo_mappings.cpp.

305 {
306 const AlgorithmSpec req(name);
307
308 // PSS with an explicit MGF1 or salt size is not expressible
309 const auto m = req.match("*({hash})");
310 if(!m) {
311 return std::nullopt;
312 }
313
314 const auto scheme = rsa_signature_padding_botan_to_tss2(m->head());
315 const auto hash = hash_algo_botan_to_tss2(m->str("hash"));
316 if(!scheme || !hash) {
317 return std::nullopt;
318 }
319
320 return TPMT_SIG_SCHEME{
321 .scheme = scheme.value(),
322 .details = {.any = {.hashAlg = hash.value()}},
323 };
324}
std::optional< TPMI_ALG_SIG_SCHEME > rsa_signature_padding_botan_to_tss2(std::string_view padding_name) noexcept

References hash_algo_botan_to_tss2(), Botan::AlgorithmSpec::match(), 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_Implementedif the TPM2-TSS does not support crypto callbacks.

Definition at line 874 of file tpm2_crypto_backend_impl.cpp.

874 {
875#if defined(BOTAN_TSS2_SUPPORTS_CRYPTO_CALLBACKS)
877
878 // clang-format off
879 ESYS_CRYPTO_CALLBACKS callbacks{
880 .rsa_pk_encrypt = &rsa_pk_encrypt,
881 .hash_start = &hash_start,
882 .hash_update = &hash_update,
883 .hash_finish = &hash_finish,
884 .hash_abort = &hash_abort,
885 .hmac_start = &hmac_start,
886 .hmac_update = &hmac_update,
887 .hmac_finish = &hmac_finish,
888 .hmac_abort = &hmac_abort,
889 .get_random2b = &get_random2b,
890 .get_ecdh_point = &get_ecdh_point,
891 .aes_encrypt = &aes_encrypt,
892 .aes_decrypt = &aes_decrypt,
893#if defined(BOTAN_TSS2_SUPPORTS_SM4_IN_CRYPTO_CALLBACKS)
894 .sm4_encrypt = &sm4_encrypt,
895 .sm4_decrypt = &sm4_decrypt,
896#endif
897 .init = &init,
898 .userdata = callback_state,
899 };
900 // clang-format on
901
902 check_rc("Esys_SetCryptoCallbacks", Esys_SetCryptoCallbacks(ctx, &callbacks));
903#else
904 BOTAN_UNUSED(ctx, callback_state);
905 throw Not_Implemented(
906 "This build of botan was compiled with a TSS2 version lower than 4.0.0, "
907 "which does not support custom runtime crypto backends");
908#endif
909}
#define BOTAN_UNUSED
Definition assert.h:151
#define BOTAN_ASSERT_NONNULL(ptr)
Definition assert.h:121

References BOTAN_ASSERT_NONNULL, BOTAN_UNUSED, and check_rc().

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.

23 {
24#if defined(BOTAN_TSS2_SUPPORTS_CRYPTO_CALLBACKS)
25 return true;
26#else
27 return false;
28#endif
29}

References supports_botan_crypto_backend().

Referenced by Botan::TPM2::Context::supports_botan_crypto_backend(), and 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
contextthe ESYS_CONTEXT pointer to register the crypto backend on
Random Number Generatorsthe (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_Implementedif the TPM2-TSS does not support crypto callbacks.

Definition at line 16 of file tpm2_crypto_backend.cpp.

17 {
18 auto crypto_callback_state = std::make_unique<CryptoCallbackState>(CryptoCallbackState{.rng = rng});
19 set_crypto_callbacks(context, crypto_callback_state.get());
20 return crypto_callback_state;
21}
void set_crypto_callbacks(ESYS_CONTEXT *ctx, void *callback_state)

References set_crypto_callbacks().

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