Botan 3.14.1
Crypto and TLS for C&
xmss_hash.h
Go to the documentation of this file.
1/*
2 * XMSS Hash
3 * (C) 2016,2017 Matthias Gierlings
4 *
5 * Botan is released under the Simplified BSD License (see license.txt)
6 **/
7
8#ifndef BOTAN_XMSS_HASH_H_
9#define BOTAN_XMSS_HASH_H_
10
11#include <botan/hash.h>
12#include <botan/internal/hash_engine.h>
13
14#include <algorithm>
15#include <span>
16
17namespace Botan {
18
19class XMSS_Parameters;
20
21/**
22 * A collection of pseudorandom hash functions required for XMSS and WOTS
23 * computations.
24 **/
25class XMSS_Hash final {
26 public:
27 explicit XMSS_Hash(const XMSS_Parameters& params);
28 XMSS_Hash(std::string_view hash_function_name, size_t hash_id_size);
29
30 XMSS_Hash(const XMSS_Hash& hash);
31 XMSS_Hash(XMSS_Hash&& hash) = default;
32 ~XMSS_Hash() = default;
33
34 XMSS_Hash& operator=(const XMSS_Hash&) = delete;
36
37 std::string hash_function() const { return m_hash->name(); }
38
39 private:
40 inline void calculate_hash(const uint8_t hash_id,
42 std::span<const uint8_t> key,
43 std::span<const uint8_t> data) {
44 m_hash->update(m_zero_padding);
45 m_hash->update(hash_id);
46 m_hash->update(key.data(), key.size());
47 m_hash->update(data.data(), data.size());
48 m_hash->final(result);
49 }
50
51 public:
52 /**
53 * Pseudorandom function creating a hash out of a key and data using
54 * a cryptographic hash function.
55 *
56 * @param[out] result The hash calculated using key and data.
57 * @param[in] key An n-byte key value.
58 * @param[in] data A 32-byte XMSS_Address data value
59 **/
60 inline void prf(secure_vector<uint8_t>& result, std::span<const uint8_t> key, std::span<const uint8_t> data) {
61 calculate_hash(0x03, result, key, data);
62 }
63
64 /**
65 * Pseudoranom function creating a hash out of a key and data using
66 * a cryptographic hash function for key derivation.
67 *
68 * This function is described in NIST SP.800-208 Section 5 as a
69 * separate PRF to avoid a multi-target attack vector.
70 *
71 * @param[out] result The hash calculated using key and data.
72 * @param[in] key An n-byte key value.
73 * @param[in] data A 32-byte XMSS_Address data value
74 **/
76 std::span<const uint8_t> key,
77 std::span<const uint8_t> data) {
78 calculate_hash(0x04, result, key, data);
79 }
80
81 /**
82 * F is a keyed cryptographic hash function used by the WOTS+ algorithm.
83 *
84 * @param[out] result The hash calculated using key and data.
85 * @param[in] key key of length n bytes.
86 * @param[in] data string of arbitrary length.
87 **/
88 void f(secure_vector<uint8_t>& result, std::span<const uint8_t> key, std::span<const uint8_t> data) {
89 calculate_hash(0x00, result, key, data);
90 }
91
92 /**
93 * Cryptographic hash function h accepting n byte keys and 2n byte
94 * strings of data.
95 *
96 * @param[out] result The hash calculated using key and data.
97 * @param[in] key key of length n bytes.
98 * @param[in] data string of 2n bytes length.
99 **/
100 void h(secure_vector<uint8_t>& result, std::span<const uint8_t> key, std::span<const uint8_t> data) {
101 calculate_hash(0x01, result, key, data);
102 }
103
104 /**
105 * Cryptographic hash function h accepting 3n byte keys and data
106 * strings of arbitrary length.
107 *
108 * @param randomness n-byte value.
109 * @param root n-byte root node.
110 * @param index_bytes Index value padded with leading zeros.
111 * @param data string of arbitrary length.
112 *
113 * @return hash value of n-bytes length.
114 **/
115 secure_vector<uint8_t> h_msg(std::span<const uint8_t> randomness,
116 std::span<const uint8_t> root,
117 std::span<const uint8_t> index_bytes,
118 std::span<const uint8_t> data) {
119 h_msg_init(randomness, root, index_bytes);
120 h_msg_update(data);
121 return m_msg_hash->final();
122 }
123
124 /**
125 * Initializes buffered h_msg computation with prefix data.
126 *
127 * @param randomness random n-byte value.
128 * @param root n-byte root node.
129 * @param index_bytes Index value padded with leading zeros.
130 **/
131 void h_msg_init(std::span<const uint8_t> randomness,
132 std::span<const uint8_t> root,
133 std::span<const uint8_t> index_bytes);
134
135 /**
136 * Adds a message block to buffered h_msg computation.
137 *
138 * @param data A message block
139 **/
140 void h_msg_update(std::span<const uint8_t> data);
141
142 /**
143 * Finalizes buffered h_msg computation and retrieves the result.
144 *
145 * @return Hash calculated using the prefix set by h_msg_init() and
146 * message blocks provided through calls to h_msg_update().
147 **/
149
150 /**
151 * Batched variant of prf with a shared key: outputs[i] = prf(key, data[i])
152 **/
153 void prf_batch(std::span<std::span<uint8_t>> outputs,
154 std::span<const uint8_t> key,
155 std::span<std::span<const uint8_t>> data) {
156 keyed_engine(0x03, key, m_prf_engine).batch_hash(outputs, data);
157 }
158
159 /**
160 * Batched variant of prf_keygen with a shared key: outputs[i] = prf_keygen(key, data[i])
161 **/
162 void prf_keygen_batch(std::span<std::span<uint8_t>> outputs,
163 std::span<const uint8_t> key,
164 std::span<std::span<const uint8_t>> data) {
165 keyed_engine(0x04, key, m_prf_keygen_engine).batch_hash(outputs, data);
166 }
167
168 /**
169 * Batched variant of f: outputs[i] = f(keys[i], data[i])
170 **/
171 void f_batch(std::span<std::span<uint8_t>> outputs,
172 std::span<std::span<const uint8_t>> keys,
173 std::span<std::span<const uint8_t>> data) {
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 }
181
182 /**
183 * Batched variant of h: outputs[i] = h(keys[i], data[i])
184 **/
185 void h_batch(std::span<std::span<uint8_t>> outputs,
186 std::span<std::span<const uint8_t>> keys,
187 std::span<std::span<const uint8_t>> data) {
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 }
195
196 size_t output_length() const { return m_hash->output_length(); }
197
198 private:
199 /// A batch engine whose prefix bakes in the (usually fixed) key,
200 /// making the prefix exactly one hash block for the n=32 parameter
201 /// sets, which allows a precomputed midstate
202 struct Keyed_Engine {
204 std::unique_ptr<Hash_Engine> engine;
205 };
206
207 Hash_Engine& keyed_engine(uint8_t hash_id, std::span<const uint8_t> key, Keyed_Engine& slot) {
208 if(!slot.engine || slot.key.size() != key.size() || !std::equal(key.begin(), key.end(), slot.key.begin())) {
209 secure_vector<uint8_t> prefix(m_zero_padding.begin(), m_zero_padding.end());
210 prefix.push_back(hash_id);
211 prefix.insert(prefix.end(), key.begin(), key.end());
212 slot.key.assign(key.begin(), key.end());
213 slot.engine = Hash_Engine::create_or_throw(m_hash->name(), prefix);
214 }
215 return *slot.engine;
216 }
217
218 std::unique_ptr<HashFunction> m_hash;
219 std::unique_ptr<HashFunction> m_msg_hash;
220
221 /// Batch engines for prf, prf_keygen, f and h, created on first use.
222 /// Note that these are not copied by the copy constructor.
223 Keyed_Engine m_prf_engine;
224 Keyed_Engine m_prf_keygen_engine;
225 std::unique_ptr<Hash_Engine> m_f_engine;
226 std::unique_ptr<Hash_Engine> m_h_engine;
227
228 /// Hash id prefixes (for domain separation) prepended to the hash input
229 /// are big-endian representations with `hash_id_length` bytes. See the
230 /// definition of the `toByte` function in RFC 8391 and truncated hash
231 /// parameter sets in NIST SP-800-208.
232 std::vector<uint8_t> m_zero_padding;
233};
234
235} // namespace Botan
236
237#endif
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="")
~XMSS_Hash()=default
std::string hash_function() const
Definition xmss_hash.h:37
size_t output_length() const
Definition xmss_hash.h:196
XMSS_Hash & operator=(XMSS_Hash &&)=default
XMSS_Hash(XMSS_Hash &&hash)=default
secure_vector< uint8_t > h_msg_final()
Definition xmss_hash.cpp:52
void prf(secure_vector< uint8_t > &result, std::span< const uint8_t > key, std::span< const uint8_t > data)
Definition xmss_hash.h:60
void prf_batch(std::span< std::span< uint8_t > > outputs, std::span< const uint8_t > key, std::span< std::span< const uint8_t > > data)
Definition xmss_hash.h:153
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)
Definition xmss_hash.h:162
void h_msg_update(std::span< const uint8_t > data)
Definition xmss_hash.cpp:48
void prf_keygen(secure_vector< uint8_t > &result, std::span< const uint8_t > key, std::span< const uint8_t > data)
Definition xmss_hash.h:75
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)
Definition xmss_hash.h:115
XMSS_Hash(const XMSS_Parameters &params)
Definition xmss_hash.cpp:24
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)
Definition xmss_hash.h:185
void f(secure_vector< uint8_t > &result, std::span< const uint8_t > key, std::span< const uint8_t > data)
Definition xmss_hash.h:88
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)
Definition xmss_hash.h:171
void h(secure_vector< uint8_t > &result, std::span< const uint8_t > key, std::span< const uint8_t > data)
Definition xmss_hash.h:100
XMSS_Hash & operator=(const XMSS_Hash &)=delete
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.
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128