Botan 3.6.0
Crypto and TLS for C&
Botan::TPM2::HashFunction Class Referencefinal

#include <tpm2_hash.h>

Inheritance diagram for Botan::TPM2::HashFunction:
Botan::HashFunction Botan::Buffered_Computation

Public Member Functions

void clear () override
 
HashFunctionclone () const
 
std::unique_ptr< Botan::HashFunctioncopy_state () const override
 
template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T final ()
 
void final (std::span< uint8_t > out)
 
template<concepts::resizable_byte_buffer T>
void final (T &out)
 
void final (uint8_t out[])
 
std::vector< uint8_t > final_stdvec ()
 
std::pair< unique_esys_ptr< TPM2B_DIGEST >, unique_esys_ptr< TPMT_TK_HASHCHECK > > final_with_ticket ()
 
virtual size_t hash_block_size () const
 
 HashFunction (std::shared_ptr< Context > ctx, std::string_view algorithm, TPMI_RH_HIERARCHY hierarchy=ESYS_TR_RH_NULL, SessionBundle sessions={})
 
std::string name () const override
 
std::unique_ptr< Botan::HashFunctionnew_object () const override
 
size_t output_length () const override
 
template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T process (const uint8_t in[], size_t length)
 
template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T process (std::span< const uint8_t > in)
 
template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T process (std::string_view in)
 
virtual std::string provider () const
 
TPMI_ALG_HASH type () const
 
void update (const uint8_t in[], size_t length)
 
void update (std::span< const uint8_t > in)
 
void update (std::string_view str)
 
void update (uint8_t in)
 
void update_be (uint16_t val)
 
void update_be (uint32_t val)
 
void update_be (uint64_t val)
 
void update_le (uint16_t val)
 
void update_le (uint32_t val)
 
void update_le (uint64_t val)
 

Static Public Member Functions

static std::unique_ptr< HashFunctioncreate (std::string_view algo_spec, std::string_view provider="")
 
static std::unique_ptr< HashFunctioncreate_or_throw (std::string_view algo_spec, std::string_view provider="")
 
static std::vector< std::string > providers (std::string_view algo_spec)
 

Detailed Description

Exposes the hashing capability of a TPM 2.0 device as a Botan::HashFunction. Typically this is used to obtain a TPMT_TK_HASHCHECK ticket after the hash operation has been completed. Otherwise, the HashFunction behaves like any other Botan::HashFunction.

Definition at line 29 of file tpm2_hash.h.

Constructor & Destructor Documentation

◆ HashFunction()

Botan::TPM2::HashFunction::HashFunction ( std::shared_ptr< Context > ctx,
std::string_view algorithm,
TPMI_RH_HIERARCHY hierarchy = ESYS_TR_RH_NULL,
SessionBundle sessions = {} )

Definition at line 19 of file tpm2_hash.cpp.

22 :
23 m_hash_type(get_tpm2_hash_type(algorithm)),
24 m_hierarchy(hierarchy),
25 m_handle(std::move(ctx)),
26 m_sessions(std::move(sessions)) {
27 // When creating a new hash object we assume that the call will use it to
28 // hash data and therefore setup the hash object immediately.
29 lazy_setup();
30}
TPMI_ALG_HASH get_tpm2_hash_type(std::string_view hash_name)

Member Function Documentation

◆ clear()

void Botan::TPM2::HashFunction::clear ( )
overridevirtual

Reset the state.

Implements Botan::HashFunction.

Definition at line 56 of file tpm2_hash.cpp.

56 {
57 m_handle._reset();
58}
void _reset() noexcept
Flush the object's TPM handles and reset its internal state.

References Botan::TPM2::Object::_reset().

◆ clone()

HashFunction * Botan::HashFunction::clone ( ) const
inlineinherited
Returns
new object representing the same algorithm as *this

Definition at line 87 of file hash.h.

87{ return this->new_object().release(); }
virtual std::unique_ptr< HashFunction > new_object() const =0

◆ copy_state()

std::unique_ptr< Botan::HashFunction > Botan::TPM2::HashFunction::copy_state ( ) const
overridevirtual
Exceptions
Not_Implementedas copying state is not supported within the TPM

Implements Botan::HashFunction.

Definition at line 60 of file tpm2_hash.cpp.

60 {
61 throw Not_Implemented("TPM 2.0 hash functions do not support copy_state");
62}

◆ create()

std::unique_ptr< HashFunction > Botan::HashFunction::create ( std::string_view algo_spec,
std::string_view provider = "" )
staticinherited

Create an instance based on a name, or return null if the algo/provider combination cannot be found. If provider is empty then best available is chosen.

Definition at line 107 of file hash.cpp.

107 {
108#if defined(BOTAN_HAS_COMMONCRYPTO)
109 if(provider.empty() || provider == "commoncrypto") {
110 if(auto hash = make_commoncrypto_hash(algo_spec))
111 return hash;
112
113 if(!provider.empty())
114 return nullptr;
115 }
116#endif
117
118 if(provider.empty() == false && provider != "base") {
119 return nullptr; // unknown provider
120 }
121
122#if defined(BOTAN_HAS_SHA1)
123 if(algo_spec == "SHA-1") {
124 return std::make_unique<SHA_1>();
125 }
126#endif
127
128#if defined(BOTAN_HAS_SHA2_32)
129 if(algo_spec == "SHA-224") {
130 return std::make_unique<SHA_224>();
131 }
132
133 if(algo_spec == "SHA-256") {
134 return std::make_unique<SHA_256>();
135 }
136#endif
137
138#if defined(BOTAN_HAS_SHA2_64)
139 if(algo_spec == "SHA-384") {
140 return std::make_unique<SHA_384>();
141 }
142
143 if(algo_spec == "SHA-512") {
144 return std::make_unique<SHA_512>();
145 }
146
147 if(algo_spec == "SHA-512-256") {
148 return std::make_unique<SHA_512_256>();
149 }
150#endif
151
152#if defined(BOTAN_HAS_RIPEMD_160)
153 if(algo_spec == "RIPEMD-160") {
154 return std::make_unique<RIPEMD_160>();
155 }
156#endif
157
158#if defined(BOTAN_HAS_WHIRLPOOL)
159 if(algo_spec == "Whirlpool") {
160 return std::make_unique<Whirlpool>();
161 }
162#endif
163
164#if defined(BOTAN_HAS_MD5)
165 if(algo_spec == "MD5") {
166 return std::make_unique<MD5>();
167 }
168#endif
169
170#if defined(BOTAN_HAS_MD4)
171 if(algo_spec == "MD4") {
172 return std::make_unique<MD4>();
173 }
174#endif
175
176#if defined(BOTAN_HAS_GOST_34_11)
177 if(algo_spec == "GOST-R-34.11-94" || algo_spec == "GOST-34.11") {
178 return std::make_unique<GOST_34_11>();
179 }
180#endif
181
182#if defined(BOTAN_HAS_ADLER32)
183 if(algo_spec == "Adler32") {
184 return std::make_unique<Adler32>();
185 }
186#endif
187
188#if defined(BOTAN_HAS_CRC24)
189 if(algo_spec == "CRC24") {
190 return std::make_unique<CRC24>();
191 }
192#endif
193
194#if defined(BOTAN_HAS_CRC32)
195 if(algo_spec == "CRC32") {
196 return std::make_unique<CRC32>();
197 }
198#endif
199
200#if defined(BOTAN_HAS_STREEBOG)
201 if(algo_spec == "Streebog-256") {
202 return std::make_unique<Streebog>(256);
203 }
204 if(algo_spec == "Streebog-512") {
205 return std::make_unique<Streebog>(512);
206 }
207#endif
208
209#if defined(BOTAN_HAS_SM3)
210 if(algo_spec == "SM3") {
211 return std::make_unique<SM3>();
212 }
213#endif
214
215 const SCAN_Name req(algo_spec);
216
217#if defined(BOTAN_HAS_SKEIN_512)
218 if(req.algo_name() == "Skein-512") {
219 return std::make_unique<Skein_512>(req.arg_as_integer(0, 512), req.arg(1, ""));
220 }
221#endif
222
223#if defined(BOTAN_HAS_BLAKE2B)
224 if(req.algo_name() == "Blake2b" || req.algo_name() == "BLAKE2b") {
225 return std::make_unique<BLAKE2b>(req.arg_as_integer(0, 512));
226 }
227#endif
228
229#if defined(BOTAN_HAS_BLAKE2S)
230 if(req.algo_name() == "Blake2s" || req.algo_name() == "BLAKE2s") {
231 return std::make_unique<BLAKE2s>(req.arg_as_integer(0, 256));
232 }
233#endif
234
235#if defined(BOTAN_HAS_KECCAK)
236 if(req.algo_name() == "Keccak-1600") {
237 return std::make_unique<Keccak_1600>(req.arg_as_integer(0, 512));
238 }
239#endif
240
241#if defined(BOTAN_HAS_SHA3)
242 if(req.algo_name() == "SHA-3") {
243 return std::make_unique<SHA_3>(req.arg_as_integer(0, 512));
244 }
245#endif
246
247#if defined(BOTAN_HAS_SHAKE)
248 if(req.algo_name() == "SHAKE-128" && req.arg_count() == 1) {
249 return std::make_unique<SHAKE_128>(req.arg_as_integer(0));
250 }
251 if(req.algo_name() == "SHAKE-256" && req.arg_count() == 1) {
252 return std::make_unique<SHAKE_256>(req.arg_as_integer(0));
253 }
254#endif
255
256#if defined(BOTAN_HAS_PARALLEL_HASH)
257 if(req.algo_name() == "Parallel") {
258 std::vector<std::unique_ptr<HashFunction>> hashes;
259
260 for(size_t i = 0; i != req.arg_count(); ++i) {
261 auto h = HashFunction::create(req.arg(i));
262 if(!h) {
263 return nullptr;
264 }
265 hashes.push_back(std::move(h));
266 }
267
268 return std::make_unique<Parallel>(hashes);
269 }
270#endif
271
272#if defined(BOTAN_HAS_TRUNCATED_HASH)
273 if(req.algo_name() == "Truncated" && req.arg_count() == 2) {
274 auto hash = HashFunction::create(req.arg(0));
275 if(!hash) {
276 return nullptr;
277 }
278
279 return std::make_unique<Truncated_Hash>(std::move(hash), req.arg_as_integer(1));
280 }
281#endif
282
283#if defined(BOTAN_HAS_COMB4P)
284 if(req.algo_name() == "Comb4P" && req.arg_count() == 2) {
285 auto h1 = HashFunction::create(req.arg(0));
286 auto h2 = HashFunction::create(req.arg(1));
287
288 if(h1 && h2) {
289 return std::make_unique<Comb4P>(std::move(h1), std::move(h2));
290 }
291 }
292#endif
293
294 return nullptr;
295}
virtual std::string provider() const
Definition hash.h:49
static std::unique_ptr< HashFunction > create(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:107
std::unique_ptr< HashFunction > make_commoncrypto_hash(std::string_view name)

References Botan::SCAN_Name::algo_name(), Botan::SCAN_Name::arg(), Botan::SCAN_Name::arg_as_integer(), Botan::SCAN_Name::arg_count(), Botan::HashFunction::create(), Botan::make_commoncrypto_hash(), and Botan::HashFunction::provider().

Referenced by botan_hash_init(), Botan::BlockCipher::create(), Botan::EME::create(), Botan::EMSA::create(), Botan::HashFunction::create(), Botan::KDF::create(), Botan::MessageAuthenticationCode::create(), Botan::PasswordHashFamily::create(), Botan::PBKDF::create(), Botan::HashFunction::create_or_throw(), Botan::Certificate_Store_In_Memory::find_cert_by_pubkey_sha1(), Botan::Certificate_Store_In_Memory::find_cert_by_raw_subject_dn_sha256(), and Botan::X942_PRF::kdf().

◆ create_or_throw()

◆ final() [1/4]

template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T Botan::Buffered_Computation::final ( )
inlineinherited

Complete the computation and retrieve the final result as a container of your choice.

Returns
a contiguous container holding the result

Definition at line 78 of file buf_comp.h.

78 {
79 T output(output_length());
80 final_result(output);
81 return output;
82 }
virtual size_t output_length() const =0
FE_25519 T
Definition ge.cpp:34

References T.

◆ final() [2/4]

void Botan::Buffered_Computation::final ( std::span< uint8_t > out)
inlineinherited

Definition at line 86 of file buf_comp.h.

86 {
87 BOTAN_ARG_CHECK(out.size() >= output_length(), "provided output buffer has insufficient capacity");
88 final_result(out);
89 }
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:29

References BOTAN_ARG_CHECK.

◆ final() [3/4]

template<concepts::resizable_byte_buffer T>
void Botan::Buffered_Computation::final ( T & out)
inlineinherited

Definition at line 92 of file buf_comp.h.

92 {
93 out.resize(output_length());
94 final_result(out);
95 }

◆ final() [4/4]

void Botan::Buffered_Computation::final ( uint8_t out[])
inlineinherited

◆ final_stdvec()

std::vector< uint8_t > Botan::Buffered_Computation::final_stdvec ( )
inlineinherited

Definition at line 84 of file buf_comp.h.

References final.

◆ final_with_ticket()

std::pair< unique_esys_ptr< TPM2B_DIGEST >, unique_esys_ptr< TPMT_TK_HASHCHECK > > Botan::TPM2::HashFunction::final_with_ticket ( )

Finalize the hash operation and return the digest and the ticket as TSS2 structures.

Returns
A pair of TPM2B_DIGEST and TPMT_TK_HASHCHECK

Definition at line 103 of file tpm2_hash.cpp.

103 {
105
106 std::pair<unique_esys_ptr<TPM2B_DIGEST>, unique_esys_ptr<TPMT_TK_HASHCHECK>> result;
107
108 const auto nodata = init_empty<TPM2B_MAX_BUFFER>();
109 check_rc("Esys_SequenceComplete",
110 Esys_SequenceComplete(*m_handle.context(),
111 m_handle.transient_handle(),
112 m_sessions[0],
113 m_sessions[1],
114 m_sessions[2],
115 &nodata,
116 m_hierarchy,
117 out_ptr(result.first),
118 out_ptr(result.second)));
119 BOTAN_ASSERT_NONNULL(result.first);
120
121 // Esys_SequenceComplete() destroys the underlying transient object
122 // so we need to disengage it's RAII wrapper.
123 m_handle._disengage();
124
125 return result;
126}
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:41
#define BOTAN_ASSERT_NONNULL(ptr)
Definition assert.h:86
bool has_transient_handle() const
const std::shared_ptr< Context > & context() const
ESYS_TR transient_handle() const noexcept
void _disengage() noexcept
Reset the object's internal state without flushing its TPM handles.
constexpr T init_empty()
Create an empty TPM2 buffer of the given type.
Definition tpm2_util.h:142
constexpr void check_rc(std::string_view location, TSS2_RC rc)
Definition tpm2_util.h:54
std::unique_ptr< T, esys_liberator > unique_esys_ptr
A unique pointer type for ESYS handles that automatically frees the handle.
Definition tpm2_util.h:154
constexpr auto out_ptr(T &outptr) noexcept
Definition stl_util.h:420

References Botan::TPM2::Object::_disengage(), BOTAN_ASSERT_NONNULL, BOTAN_STATE_CHECK, Botan::TPM2::check_rc(), Botan::TPM2::Object::context(), Botan::TPM2::Object::has_transient_handle(), Botan::TPM2::init_empty(), Botan::out_ptr(), and Botan::TPM2::Object::transient_handle().

◆ hash_block_size()

virtual size_t Botan::HashFunction::hash_block_size ( ) const
inlinevirtualinherited

◆ name()

std::string Botan::TPM2::HashFunction::name ( ) const
overridevirtual
Returns
the hash function name

Implements Botan::HashFunction.

Definition at line 32 of file tpm2_hash.cpp.

32 {
33 return get_botan_hash_name(m_hash_type);
34}
std::string get_botan_hash_name(TPM2_ALG_ID hash_id)

References Botan::TPM2::get_botan_hash_name().

Referenced by new_object().

◆ new_object()

std::unique_ptr< Botan::HashFunction > Botan::TPM2::HashFunction::new_object ( ) const
overridevirtual
Returns
new object representing the same algorithm as *this

Implements Botan::HashFunction.

Definition at line 64 of file tpm2_hash.cpp.

64 {
65 return std::make_unique<HashFunction>(m_handle.context(), name(), m_hierarchy, m_sessions);
66}
std::string name() const override
Definition tpm2_hash.cpp:32

References Botan::TPM2::Object::context(), and name().

◆ output_length()

size_t Botan::TPM2::HashFunction::output_length ( ) const
overridevirtual
Returns
length of the output of this function in bytes

Implements Botan::Buffered_Computation.

Definition at line 36 of file tpm2_hash.cpp.

36 {
37 switch(m_hash_type) {
38 case TPM2_ALG_SHA1:
39 return 20;
40 case TPM2_ALG_SHA256:
41 case TPM2_ALG_SHA3_256:
42 case TPM2_ALG_SM3_256:
43 return 32;
44 case TPM2_ALG_SHA384:
45 case TPM2_ALG_SHA3_384:
46 return 48;
47 case TPM2_ALG_SHA512:
48 case TPM2_ALG_SHA3_512:
49 return 64;
50 return 64;
51 default:
52 throw Invalid_State("TPM 2.0 hash object with unexpected hash type");
53 }
54}

◆ process() [1/3]

template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T Botan::Buffered_Computation::process ( const uint8_t in[],
size_t length )
inlineinherited

Update and finalize computation. Does the same as calling update() and final() consecutively.

Parameters
inthe input to process as a byte array
lengththe length of the byte array
Returns
the result of the call to final()

Definition at line 105 of file buf_comp.h.

105 {
106 update(in, length);
107 return final<T>();
108 }
int(* update)(CTX *, const void *, CC_LONG len)

References final, and update.

Referenced by Botan::Kyber_Symmetric_Primitives::H(), Botan::Kyber_Symmetric_Primitives::H(), and Botan::Kyber_Symmetric_Primitives::H().

◆ process() [2/3]

template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T Botan::Buffered_Computation::process ( std::span< const uint8_t > in)
inlineinherited

Update and finalize computation. Does the same as calling update() and final() consecutively.

Parameters
inthe input to process as a contiguous container
Returns
the result of the call to final()

Definition at line 129 of file buf_comp.h.

129 {
130 update(in);
131 return final<T>();
132 }

References final, and update.

◆ process() [3/3]

template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T Botan::Buffered_Computation::process ( std::string_view in)
inlineinherited

Update and finalize computation. Does the same as calling update() and final() consecutively.

Parameters
inthe input to process as a string
Returns
the result of the call to final()

Definition at line 117 of file buf_comp.h.

117 {
118 update(in);
119 return final<T>();
120 }

References final, and update.

◆ provider()

virtual std::string Botan::HashFunction::provider ( ) const
inlinevirtualinherited
Returns
provider information about this implementation. Default is "base", might also return "sse2", "avx2", "openssl", or some other arbitrary string.

Reimplemented in Botan::Keccak_1600, Botan::SHA_1, Botan::SHA_224, Botan::SHA_256, Botan::SHA_384, Botan::SHA_3, Botan::SHA_512, Botan::SHA_512_256, Botan::SHAKE_128, and Botan::SHAKE_256.

Definition at line 49 of file hash.h.

49{ return "base"; }

Referenced by Botan::HashFunction::create(), and Botan::HashFunction::create_or_throw().

◆ providers()

std::vector< std::string > Botan::HashFunction::providers ( std::string_view algo_spec)
staticinherited
Returns
list of available providers for this algorithm, empty if not available
Parameters
algo_specalgorithm name

Definition at line 305 of file hash.cpp.

305 {
306 return probe_providers_of<HashFunction>(algo_spec, {"base", "commoncrypto"});
307}
std::vector< std::string > probe_providers_of(std::string_view algo_spec, const std::vector< std::string > &possible={"base"})
Definition scan_name.h:105

References Botan::probe_providers_of().

◆ type()

TPMI_ALG_HASH Botan::TPM2::HashFunction::type ( ) const
inline
Returns
The hash algorithm identifier as TSS2's TPMI_ALG_HASH

Definition at line 45 of file tpm2_hash.h.

45{ return m_hash_type; }

◆ update() [1/4]

void Botan::Buffered_Computation::update ( const uint8_t in[],
size_t length )
inlineinherited

◆ update() [2/4]

void Botan::Buffered_Computation::update ( std::span< const uint8_t > in)
inlineinherited

Add new input to process.

Parameters
inthe input to process as a contiguous data range

Definition at line 41 of file buf_comp.h.

41{ add_data(in); }

◆ update() [3/4]

void Botan::Buffered_Computation::update ( std::string_view str)
inlineinherited

Add new input to process.

Parameters
strthe input to process as a std::string_view. Will be interpreted as a byte array based on the strings encoding.

Definition at line 56 of file buf_comp.h.

56{ add_data({cast_char_ptr_to_uint8(str.data()), str.size()}); }
const uint8_t * cast_char_ptr_to_uint8(const char *s)
Definition mem_ops.h:273

References Botan::cast_char_ptr_to_uint8().

◆ update() [4/4]

void Botan::Buffered_Computation::update ( uint8_t in)
inlineinherited

Process a single byte.

Parameters
inthe byte to process

Definition at line 62 of file buf_comp.h.

62{ add_data({&in, 1}); }

◆ update_be() [1/3]

void Botan::Buffered_Computation::update_be ( uint16_t val)
inherited

Definition at line 13 of file buf_comp.cpp.

13 {
14 uint8_t inb[sizeof(val)];
15 store_be(val, inb);
16 add_data({inb, sizeof(inb)});
17}
constexpr auto store_be(ParamTs &&... params)
Definition loadstor.h:773

References Botan::store_be().

Referenced by Botan::mgf1_mask(), and Botan::pbkdf2().

◆ update_be() [2/3]

void Botan::Buffered_Computation::update_be ( uint32_t val)
inherited

Definition at line 19 of file buf_comp.cpp.

19 {
20 uint8_t inb[sizeof(val)];
21 store_be(val, inb);
22 add_data({inb, sizeof(inb)});
23}

References Botan::store_be().

◆ update_be() [3/3]

void Botan::Buffered_Computation::update_be ( uint64_t val)
inherited

Definition at line 25 of file buf_comp.cpp.

25 {
26 uint8_t inb[sizeof(val)];
27 store_be(val, inb);
28 add_data({inb, sizeof(inb)});
29}

References Botan::store_be().

◆ update_le() [1/3]

void Botan::Buffered_Computation::update_le ( uint16_t val)
inherited

Definition at line 31 of file buf_comp.cpp.

31 {
32 uint8_t inb[sizeof(val)];
33 store_le(val, inb);
34 add_data({inb, sizeof(inb)});
35}
constexpr auto store_le(ParamTs &&... params)
Definition loadstor.h:764

References Botan::store_le().

◆ update_le() [2/3]

void Botan::Buffered_Computation::update_le ( uint32_t val)
inherited

Definition at line 37 of file buf_comp.cpp.

37 {
38 uint8_t inb[sizeof(val)];
39 store_le(val, inb);
40 add_data({inb, sizeof(inb)});
41}

References Botan::store_le().

◆ update_le() [3/3]

void Botan::Buffered_Computation::update_le ( uint64_t val)
inherited

Definition at line 43 of file buf_comp.cpp.

43 {
44 uint8_t inb[sizeof(val)];
45 store_le(val, inb);
46 add_data({inb, sizeof(inb)});
47}

References Botan::store_le().


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