Botan 3.14.1
Crypto and TLS for C&
Botan::XMSS_Hash Class Referencefinal

#include <xmss_hash.h>

Public Member Functions

void f (secure_vector< uint8_t > &result, std::span< const uint8_t > key, std::span< const uint8_t > data)
void f_batch (std::span< std::span< uint8_t > > outputs, std::span< std::span< const uint8_t > > keys, std::span< std::span< const uint8_t > > data)
void h (secure_vector< uint8_t > &result, std::span< const uint8_t > key, std::span< const uint8_t > data)
void h_batch (std::span< std::span< uint8_t > > outputs, std::span< std::span< const uint8_t > > keys, std::span< std::span< const uint8_t > > data)
secure_vector< uint8_t > h_msg (std::span< const uint8_t > randomness, std::span< const uint8_t > root, std::span< const uint8_t > index_bytes, std::span< const uint8_t > data)
secure_vector< uint8_t > h_msg_final ()
void h_msg_init (std::span< const uint8_t > randomness, std::span< const uint8_t > root, std::span< const uint8_t > index_bytes)
void h_msg_update (std::span< const uint8_t > data)
std::string hash_function () const
XMSS_Hash & operator= (const XMSS_Hash &)=delete
XMSS_Hash & operator= (XMSS_Hash &&)=default
size_t output_length () const
void prf (secure_vector< uint8_t > &result, std::span< const uint8_t > key, std::span< const uint8_t > data)
void prf_batch (std::span< std::span< uint8_t > > outputs, std::span< const uint8_t > key, std::span< std::span< const uint8_t > > data)
void prf_keygen (secure_vector< uint8_t > &result, std::span< const uint8_t > key, std::span< const uint8_t > data)
void prf_keygen_batch (std::span< std::span< uint8_t > > outputs, std::span< const uint8_t > key, std::span< std::span< const uint8_t > > data)
 XMSS_Hash (const XMSS_Hash &hash)
 XMSS_Hash (const XMSS_Parameters &params)
 XMSS_Hash (std::string_view hash_function_name, size_t hash_id_size)
 XMSS_Hash (XMSS_Hash &&hash)=default
 ~XMSS_Hash ()=default

Detailed Description

A collection of pseudorandom hash functions required for XMSS and WOTS computations.

Definition at line 25 of file xmss_hash.h.

Constructor & Destructor Documentation

◆ XMSS_Hash() [1/4]

Botan::XMSS_Hash::XMSS_Hash ( const XMSS_Parameters & params)
explicit

Definition at line 24 of file xmss_hash.cpp.

24: XMSS_Hash(params.hash_function_name(), params.hash_id_size()) {}
XMSS_Hash(const XMSS_Parameters &params)
Definition xmss_hash.cpp:24

References XMSS_Hash().

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

◆ XMSS_Hash() [2/4]

Botan::XMSS_Hash::XMSS_Hash ( std::string_view hash_function_name,
size_t hash_id_size )

Definition at line 26 of file xmss_hash.cpp.

26 :
27 m_hash(HashFunction::create(hash_function_name)),
28 m_msg_hash(HashFunction::create(hash_function_name)),
29 m_zero_padding(hash_id_size - 1 /* hash IDs are a single uint8_t */) {
30 if(!m_hash || !m_msg_hash) {
31 throw Lookup_Error(fmt("XMSS cannot use hash {} because it is unavailable", hash_function_name));
32 }
33
34 BOTAN_ASSERT(m_hash->output_length() > 0, "Hash output length of zero is invalid.");
35}
#define BOTAN_ASSERT(expr, assertion_made)
Definition assert.h:69
static std::unique_ptr< HashFunction > create(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:112
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

References BOTAN_ASSERT, and Botan::fmt().

◆ XMSS_Hash() [3/4]

Botan::XMSS_Hash::XMSS_Hash ( const XMSS_Hash & hash)

Definition at line 19 of file xmss_hash.cpp.

19 :
20 m_hash(hash.m_hash->new_object()),
21 m_msg_hash(hash.m_msg_hash->new_object()),
22 m_zero_padding(hash.m_zero_padding) {}

References XMSS_Hash().

◆ XMSS_Hash() [4/4]

Botan::XMSS_Hash::XMSS_Hash ( XMSS_Hash && hash)
default

References XMSS_Hash().

◆ ~XMSS_Hash()

Botan::XMSS_Hash::~XMSS_Hash ( )
default

Member Function Documentation

◆ f()

void Botan::XMSS_Hash::f ( secure_vector< uint8_t > & result,
std::span< const uint8_t > key,
std::span< const uint8_t > data )
inline

F is a keyed cryptographic hash function used by the WOTS+ algorithm.

Parameters
[out]resultThe hash calculated using key and data.
[in]keykey of length n bytes.
[in]datastring of arbitrary length.

Definition at line 88 of file xmss_hash.h.

88 {
89 calculate_hash(0x00, result, key, data);
90 }

◆ f_batch()

void Botan::XMSS_Hash::f_batch ( std::span< std::span< uint8_t > > outputs,
std::span< std::span< const uint8_t > > keys,
std::span< std::span< const uint8_t > > data )
inline

Batched variant of f: outputs[i] = f(keys[i], data[i])

Definition at line 171 of file xmss_hash.h.

173 {
174 if(!m_f_engine) {
175 std::vector<uint8_t> prefix(m_zero_padding);
176 prefix.push_back(0x00);
177 m_f_engine = Hash_Engine::create_or_throw(m_hash->name(), prefix);
178 }
179 m_f_engine->batch_hash(outputs, keys, data);
180 }
static std::unique_ptr< Hash_Engine > create_or_throw(std::string_view hash_fn, std::span< const uint8_t > common_prefix={}, std::string_view provider="")

References Botan::Hash_Engine::create_or_throw().

Referenced by Botan::xmss_wots_chains().

◆ h()

void Botan::XMSS_Hash::h ( secure_vector< uint8_t > & result,
std::span< const uint8_t > key,
std::span< const uint8_t > data )
inline

Cryptographic hash function h accepting n byte keys and 2n byte strings of data.

Parameters
[out]resultThe hash calculated using key and data.
[in]keykey of length n bytes.
[in]datastring of 2n bytes length.

Definition at line 100 of file xmss_hash.h.

100 {
101 calculate_hash(0x01, result, key, data);
102 }

Referenced by Botan::XMSS_Common_Ops::randomize_tree_hash().

◆ h_batch()

void Botan::XMSS_Hash::h_batch ( std::span< std::span< uint8_t > > outputs,
std::span< std::span< const uint8_t > > keys,
std::span< std::span< const uint8_t > > data )
inline

Batched variant of h: outputs[i] = h(keys[i], data[i])

Definition at line 185 of file xmss_hash.h.

187 {
188 if(!m_h_engine) {
189 std::vector<uint8_t> prefix(m_zero_padding);
190 prefix.push_back(0x01);
191 m_h_engine = Hash_Engine::create_or_throw(m_hash->name(), prefix);
192 }
193 m_h_engine->batch_hash(outputs, keys, data);
194 }

References Botan::Hash_Engine::create_or_throw().

Referenced by Botan::XMSS_Common_Ops::create_l_trees().

◆ h_msg()

secure_vector< uint8_t > Botan::XMSS_Hash::h_msg ( std::span< const uint8_t > randomness,
std::span< const uint8_t > root,
std::span< const uint8_t > index_bytes,
std::span< const uint8_t > data )
inline

Cryptographic hash function h accepting 3n byte keys and data strings of arbitrary length.

Parameters
randomnessn-byte value.
rootn-byte root node.
index_bytesIndex value padded with leading zeros.
datastring of arbitrary length.
Returns
hash value of n-bytes length.

Definition at line 115 of file xmss_hash.h.

118 {
119 h_msg_init(randomness, root, index_bytes);
120 h_msg_update(data);
121 return m_msg_hash->final();
122 }
void h_msg_update(std::span< const uint8_t > data)
Definition xmss_hash.cpp:48
void h_msg_init(std::span< const uint8_t > randomness, std::span< const uint8_t > root, std::span< const uint8_t > index_bytes)
Definition xmss_hash.cpp:37
Gf448Elem root(const Gf448Elem &elem)
Compute the root of elem in the field.

References h_msg_init(), h_msg_update(), and Botan::root().

◆ h_msg_final()

secure_vector< uint8_t > Botan::XMSS_Hash::h_msg_final ( )

Finalizes buffered h_msg computation and retrieves the result.

Returns
Hash calculated using the prefix set by h_msg_init() and message blocks provided through calls to h_msg_update().

Definition at line 52 of file xmss_hash.cpp.

52 {
53 return m_msg_hash->final();
54}

◆ h_msg_init()

void Botan::XMSS_Hash::h_msg_init ( std::span< const uint8_t > randomness,
std::span< const uint8_t > root,
std::span< const uint8_t > index_bytes )

Initializes buffered h_msg computation with prefix data.

Parameters
randomnessrandom n-byte value.
rootn-byte root node.
index_bytesIndex value padded with leading zeros.

Definition at line 37 of file xmss_hash.cpp.

39 {
40 m_msg_hash->clear();
41 m_msg_hash->update(m_zero_padding);
42 m_msg_hash->update(0x02);
43 m_msg_hash->update(randomness.data(), randomness.size());
44 m_msg_hash->update(root.data(), root.size());
45 m_msg_hash->update(index_bytes.data(), index_bytes.size());
46}

References Botan::root().

Referenced by h_msg().

◆ h_msg_update()

void Botan::XMSS_Hash::h_msg_update ( std::span< const uint8_t > data)

Adds a message block to buffered h_msg computation.

Parameters
dataA message block

Definition at line 48 of file xmss_hash.cpp.

48 {
49 m_msg_hash->update(data.data(), data.size());
50}

Referenced by h_msg().

◆ hash_function()

std::string Botan::XMSS_Hash::hash_function ( ) const
inline

Definition at line 37 of file xmss_hash.h.

37{ return m_hash->name(); }

◆ operator=() [1/2]

XMSS_Hash & Botan::XMSS_Hash::operator= ( const XMSS_Hash & )
delete

References XMSS_Hash().

◆ operator=() [2/2]

XMSS_Hash & Botan::XMSS_Hash::operator= ( XMSS_Hash && )
default

References XMSS_Hash().

◆ output_length()

size_t Botan::XMSS_Hash::output_length ( ) const
inline

Definition at line 196 of file xmss_hash.h.

196{ return m_hash->output_length(); }

Referenced by Botan::xmss_wots_chains(), and Botan::XMSS_WOTS_PrivateKey::XMSS_WOTS_PrivateKey().

◆ prf()

void Botan::XMSS_Hash::prf ( secure_vector< uint8_t > & result,
std::span< const uint8_t > key,
std::span< const uint8_t > data )
inline

Pseudorandom function creating a hash out of a key and data using a cryptographic hash function.

Parameters
[out]resultThe hash calculated using key and data.
[in]keyAn n-byte key value.
[in]dataA 32-byte XMSS_Address data value

Definition at line 60 of file xmss_hash.h.

60 {
61 calculate_hash(0x03, result, key, data);
62 }

Referenced by Botan::XMSS_Common_Ops::randomize_tree_hash(), and Botan::XMSS_WOTS_PrivateKey::XMSS_WOTS_PrivateKey().

◆ prf_batch()

void Botan::XMSS_Hash::prf_batch ( std::span< std::span< uint8_t > > outputs,
std::span< const uint8_t > key,
std::span< std::span< const uint8_t > > data )
inline

Batched variant of prf with a shared key: outputs[i] = prf(key, data[i])

Definition at line 153 of file xmss_hash.h.

155 {
156 keyed_engine(0x03, key, m_prf_engine).batch_hash(outputs, data);
157 }

Referenced by Botan::XMSS_Common_Ops::create_l_trees(), and Botan::xmss_wots_chains().

◆ prf_keygen()

void Botan::XMSS_Hash::prf_keygen ( secure_vector< uint8_t > & result,
std::span< const uint8_t > key,
std::span< const uint8_t > data )
inline

Pseudoranom function creating a hash out of a key and data using a cryptographic hash function for key derivation.

This function is described in NIST SP.800-208 Section 5 as a separate PRF to avoid a multi-target attack vector.

Parameters
[out]resultThe hash calculated using key and data.
[in]keyAn n-byte key value.
[in]dataA 32-byte XMSS_Address data value

Definition at line 75 of file xmss_hash.h.

77 {
78 calculate_hash(0x04, result, key, data);
79 }

◆ prf_keygen_batch()

void Botan::XMSS_Hash::prf_keygen_batch ( std::span< std::span< uint8_t > > outputs,
std::span< const uint8_t > key,
std::span< std::span< const uint8_t > > data )
inline

Batched variant of prf_keygen with a shared key: outputs[i] = prf_keygen(key, data[i])

Definition at line 162 of file xmss_hash.h.

164 {
165 keyed_engine(0x04, key, m_prf_keygen_engine).batch_hash(outputs, data);
166 }

Referenced by Botan::XMSS_WOTS_PrivateKey::XMSS_WOTS_PrivateKey().


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