Botan 3.5.0
Crypto and TLS for C&
hss.h
Go to the documentation of this file.
1/**
2 * HSS - Hierarchical Signatures System (RFC 8554)
3 * (C) 2023 Jack Lloyd
4 * 2023 Fabian Albert, Philippe Lieser - Rohde & Schwarz Cybersecurity GmbH
5 *
6 * Botan is released under the Simplified BSD License (see license.txt)
7 */
8
9#ifndef BOTAN_HSS_H_
10#define BOTAN_HSS_H_
11
12#include <botan/asn1_obj.h>
13#include <botan/rng.h>
14#include <botan/internal/int_utils.h>
15#include <botan/internal/lms.h>
16
17#include <memory>
18#include <span>
19#include <string_view>
20#include <utility>
21#include <vector>
22
23namespace Botan {
24
25/**
26 * @brief The index of a node within a specific LMS tree layer
27 */
29
30/**
31 * @brief The HSS layer in the HSS multi tree starting at 0 from the root
32 */
34
35/**
36 * @brief The HSS-LMS parameters.
37 *
38 * See RFC 8554 Section 6.
39 */
41 public:
42 /**
43 * @brief Represents a pair of LMS and LMOTS parameters associated with one LMS tree layer.
44 */
46 public:
47 /**
48 * @brief The LMS parameters.
49 */
50 const LMS_Params& lms_params() const { return m_lms_params; }
51
52 /**
53 * @brief The LMOTS parameters.
54 */
55 const LMOTS_Params& lmots_params() const { return m_lmots_params; }
56
57 /**
58 * @brief Construct a new params pair
59 */
60 LMS_LMOTS_Params_Pair(LMS_Params p_lms_params, LMOTS_Params p_lmots_params) :
61 m_lms_params(std::move(p_lms_params)), m_lmots_params(std::move(p_lmots_params)) {}
62
63 private:
64 LMS_Params m_lms_params;
65 LMOTS_Params m_lmots_params;
66 };
67
68 /**
69 * @brief Construct the HSS-LMS parameters from a vector LMS and LM-OTS parameters.
70 */
71 explicit HSS_LMS_Params(std::vector<LMS_LMOTS_Params_Pair> lm_lmots_params);
72
73 /**
74 * @brief Construct the HSS-LMS parameters form an algorithm parameter string.
75 *
76 * The HSS/LMS instance to use for creating new keys is defined using an algorithm parameter string,
77 * i.e. to define which hash function (hash), LMS tree hights (h)
78 * and OTS Winternitz coefficient widths (w) to use. The syntax is the following:
79 *
80 * HSS-LMS(<hash>,HW(<h>,<w>),HW(<h>,<w>),...)
81 *
82 * e.g. 'HSS-LMS(SHA-256,HW(5,1),HW(5,1))' to use SHA-256 in a two-layer HSS instance
83 * with a LMS tree height 5 and w=1. The following parameters are allowed (which are
84 * specified in RFC 8554 and draft-fluhrer-lms-more-parm-sets-11):
85 *
86 * hash: 'SHA-256', 'Truncated(SHA-256,192)', 'SHAKE-256(256)', SHAKE-256(192)
87 * h: '5', '10', '15', '20', '25'
88 * w: '1', '2', '4', '8'
89 *
90 * Note: The selected hash function is also used for seed derivation.
91 */
92 explicit HSS_LMS_Params(std::string_view algo_params);
93
94 /**
95 * @brief Returns the LMS an LM-OTS parameters at the specified @p level of the HSS tree.
96 */
97 const LMS_LMOTS_Params_Pair& params_at_level(HSS_Level level) const { return m_lms_lmots_params.at(level.get()); }
98
99 /**
100 * @brief Returns the number of layers the HSS tree has.
101 */
102 HSS_Level L() const { return checked_cast_to<HSS_Level>(m_lms_lmots_params.size()); }
103
104 /**
105 * @brief The maximal number of signatures allowed for these HSS parameters
106 */
107 HSS_Sig_Idx max_sig_count() const { return m_max_sig_count; }
108
109 private:
110 /**
111 * @brief Compute the maximal number of signatures
112 */
113 HSS_Sig_Idx calc_max_sig_count() const;
114
115 std::vector<LMS_LMOTS_Params_Pair> m_lms_lmots_params;
116 HSS_Sig_Idx m_max_sig_count;
117};
118
119/**
120 * @brief The internal HSS-LMS private key.
121 *
122 * Note that the format is not specified in the RFC 8554,
123 * and is Botan specific.
124 */
126 public:
127 /**
128 * @brief Create an internal HSS-LMS private key.
129 *
130 * @param hss_params The HSS-LMS parameters for the key.
131 * @param rng The rng to use.
132 */
134
135 /**
136 * @brief Parse a private HSS-LMS key.
137 *
138 * @param key_bytes The private key bytes to parse.
139 * @return The internal HSS-LMS private key.
140 * @throws Decoding_Error If parsing the private key fails.
141 */
142 static std::shared_ptr<HSS_LMS_PrivateKeyInternal> from_bytes_or_throw(std::span<const uint8_t> key_bytes);
143
144 /**
145 * @brief Returns the used HSS-LMS parameters.
146 */
147 const HSS_LMS_Params& hss_params() const { return m_hss_params; }
148
149 /**
150 * @brief Returns the key in its encoded format.
151 */
152 secure_vector<uint8_t> to_bytes() const;
153
154 /**
155 * @brief Get the idx of the next signature to generate.
156 */
157 HSS_Sig_Idx get_idx() const { return m_current_idx; }
158
159 /**
160 * @brief Set the idx of the next signature to generate.
161 *
162 * Note that creating two signatures with the same index is insecure.
163 * The index must be lower than hss_params().max_sig_count().
164 */
165 void set_idx(HSS_Sig_Idx idx);
166
167 /**
168 * @brief Create a HSS-LMS signature.
169 *
170 * See RFC 8554 6.2 - Algorithm 8.
171 *
172 * For each signature creation the hypertree is computed once
173 * again, so no data is stored between multiple signatures. However,
174 * storing data between multiple signatures could be an optimization
175 * if applications create multiple signatures in one go.
176 *
177 * @param msg The message to sign.
178 */
179 secure_vector<uint8_t> sign(std::span<const uint8_t> msg);
180
181 /**
182 * @brief Create the HSS root LMS tree's LMS_PrivateKey using the HSS-LMS private key.
183 *
184 * We use the same generation as the reference implementation (https://github.com/cisco/hash-sigs)
185 * with SECRET_METHOD==2.
186 *
187 * @return The LMS private key
188 */
189 LMS_PrivateKey hss_derive_root_lms_private_key() const;
190
191 /**
192 * @brief Returns the size in bytes of a signature created by this key.
193 */
194 size_t signature_size() const { return m_sig_size; }
195
196 private:
197 HSS_LMS_PrivateKeyInternal(HSS_LMS_Params hss_params, LMS_Seed hss_seed, LMS_Identifier identifier);
198
199 /**
200 * @brief Get the index of the next signature to generate and
201 * increase the counter by one.
202 */
203 HSS_Sig_Idx reserve_next_idx();
204
205 /**
206 * @brief Returns the size in bytes the key would have in its encoded format.
207 */
208 size_t size() const;
209
210 /**
211 * @brief Derive the seed and identifier of an LMS tree from its parent LMS tree.
212 *
213 * We use the same generation as the reference implementation (https://github.com/cisco/hash-sigs).
214 *
215 * @param child_lms_lmots_params The LMS-LMOTS parameter pair of the child tree.
216 * @param parent_sk The parent's LMS private key
217 * @param parent_q The LMS leaf number the child tree has in its parent tree.
218 * @return LMS private key
219 */
220 static LMS_PrivateKey hss_derive_child_lms_private_key(
221 const HSS_LMS_Params::LMS_LMOTS_Params_Pair& child_lms_lmots_params,
222 const LMS_PrivateKey& parent_sk,
223 LMS_Tree_Node_Idx parent_q);
224
225 HSS_LMS_Params m_hss_params;
226 LMS_Seed m_hss_seed;
227 LMS_Identifier m_identifier;
228 HSS_Sig_Idx m_current_idx;
229 const size_t m_sig_size;
230};
231
232class HSS_Signature;
233
234/**
235 * @brief The internal HSS-LMS public key.
236 *
237 * Format according to RFC 8554:
238 * u32str(L) || pub[0]
239 */
241 public:
242 /**
243 * @brief Create the public HSS-LMS key from its private key.
244 *
245 * @param hss_sk The private HSS-LMS key.
246 * @return The internal HSS-LMS public key.
247 */
248 static HSS_LMS_PublicKeyInternal create(const HSS_LMS_PrivateKeyInternal& hss_sk);
249
250 /**
251 * @brief Parse a public HSS-LMS key.
252 *
253 * @param key_bytes The public key bytes to parse.
254 * @return The internal HSS-LMS public key.
255 * @throws Decoding_Error If parsing the public key fails.
256 */
257 static std::shared_ptr<HSS_LMS_PublicKeyInternal> from_bytes_or_throw(std::span<const uint8_t> key_bytes);
258
260 m_L(L), m_top_lms_pub_key(std::move(top_lms_pub_key)) {}
261
262 /**
263 * @brief Returns the key in its encoded format.
264 */
265 std::vector<uint8_t> to_bytes() const;
266
267 /**
268 * @brief Returns the public LMS key of the top LMS tree.
269 */
270 const LMS_PublicKey& lms_pub_key() const { return m_top_lms_pub_key; }
271
272 /**
273 * @brief Returns the size in bytes the key would have in its encoded format.
274 */
275 size_t size() const;
276
277 /**
278 * @brief The algorithm identifier for HSS-LMS
279 */
280 AlgorithmIdentifier algorithm_identifier() const;
281
282 /**
283 * @brief The object identifier for HSS-LMS
284 */
285 OID object_identifier() const;
286
287 /**
288 * @brief The algorithm name for HSS-LMS
289 */
290 std::string algo_name() const { return "HSS-LMS"; }
291
292 /**
293 * @brief Verify a HSS-LMS signature.
294 *
295 * See RFC 8554 6.3.
296 *
297 * @param msg The signed message.
298 * @param sig The already parsed HSS-LMS signature.
299 * @return True iff the signature is valid.
300 */
301 bool verify_signature(std::span<const uint8_t> msg, const HSS_Signature& sig) const;
302
303 private:
304 HSS_Level m_L;
305 LMS_PublicKey m_top_lms_pub_key;
306};
307
308/**
309 * @brief A HSS-LMS signature.
310 *
311 * Format according to RFC 8554:
312 * u32str(Nspk) || sig[0] || pub[1] || ... || sig[Nspk-1] || pub[Nspk] || sig[Nspk]
313 */
315 public:
316 /**
317 * @brief A LMS public key signed by the HSS layer above it.
318 *
319 * signed_pub_key[i] = sig[i] || pub[i+1],
320 * for i between 0 and Nspk-1, inclusive.
321 */
323 public:
324 /**
325 * @brief Constructor for a new sig-pubkey-pair
326 */
328
329 /**
330 * @brief The signature of the public key
331 */
332 const LMS_Signature& signature() const { return m_sig; }
333
334 /**
335 * @brief The signed public key
336 */
337 const LMS_PublicKey& public_key() const { return m_pub; }
338
339 private:
340 LMS_Signature m_sig;
341 LMS_PublicKey m_pub;
342 };
343
344 /**
345 * @brief Parse a HSS-LMS signature.
346 *
347 * @param sig_bytes The signature bytes to parse.
348 * @return The parsed HSS-LMS signature.
349 * @throws Decoding_Error If parsing the signature fails.
350 */
351 static HSS_Signature from_bytes_or_throw(std::span<const uint8_t> sig_bytes);
352
353 /**
354 * @brief Returns the size a signature would have in its encoded format.
355 *
356 * @param params The HSS-LMS parameters.
357 * @return size_t The expected size in bytes.
358 */
359 static size_t size(const HSS_LMS_Params& params);
360
361 /**
362 * @brief Returns the number of signed public keys (Nspk = L-1).
363 */
364 HSS_Level Nspk() const { return HSS_Level(static_cast<uint32_t>(m_signed_pub_keys.size())); }
365
366 /**
367 * @brief Returns the signed LMS key signed by a specific layer.
368 *
369 * @param layer The layer by which the LMS key is signed.
370 * @return The LMS key and the signature by its parent layer.
371 */
372 const Signed_Pub_Key& signed_pub_key(HSS_Level layer) const { return m_signed_pub_keys.at(layer.get()); }
373
374 /**
375 * @brief Returns the LMS signature by the bottom layer of the signed message.
376 */
377 const LMS_Signature& bottom_sig() const { return m_sig; }
378
379 private:
380 /**
381 * @brief Private constructor using the individual signature fields.
382 */
383 HSS_Signature(std::vector<Signed_Pub_Key> signed_pub_keys, LMS_Signature sig) :
384 m_signed_pub_keys(std::move(signed_pub_keys)), m_sig(std::move(sig)) {}
385
386 std::vector<Signed_Pub_Key> m_signed_pub_keys;
387 LMS_Signature m_sig;
388};
389
390} // namespace Botan
391
392#endif
Represents a pair of LMS and LMOTS parameters associated with one LMS tree layer.
Definition hss.h:45
const LMS_Params & lms_params() const
The LMS parameters.
Definition hss.h:50
const LMOTS_Params & lmots_params() const
The LMOTS parameters.
Definition hss.h:55
LMS_LMOTS_Params_Pair(LMS_Params p_lms_params, LMOTS_Params p_lmots_params)
Construct a new params pair.
Definition hss.h:60
The HSS-LMS parameters.
Definition hss.h:40
const LMS_LMOTS_Params_Pair & params_at_level(HSS_Level level) const
Returns the LMS an LM-OTS parameters at the specified level of the HSS tree.
Definition hss.h:97
HSS_Level L() const
Returns the number of layers the HSS tree has.
Definition hss.h:102
HSS_Sig_Idx max_sig_count() const
The maximal number of signatures allowed for these HSS parameters.
Definition hss.h:107
The internal HSS-LMS private key.
Definition hss.h:125
HSS_Sig_Idx get_idx() const
Get the idx of the next signature to generate.
Definition hss.h:157
const HSS_LMS_Params & hss_params() const
Returns the used HSS-LMS parameters.
Definition hss.h:147
size_t signature_size() const
Returns the size in bytes of a signature created by this key.
Definition hss.h:194
The internal HSS-LMS public key.
Definition hss.h:240
std::string algo_name() const
The algorithm name for HSS-LMS.
Definition hss.h:290
HSS_LMS_PublicKeyInternal(HSS_Level L, LMS_PublicKey top_lms_pub_key)
Definition hss.h:259
const LMS_PublicKey & lms_pub_key() const
Returns the public LMS key of the top LMS tree.
Definition hss.h:270
A LMS public key signed by the HSS layer above it.
Definition hss.h:322
const LMS_Signature & signature() const
The signature of the public key.
Definition hss.h:332
const LMS_PublicKey & public_key() const
The signed public key.
Definition hss.h:337
A HSS-LMS signature.
Definition hss.h:314
const LMS_Signature & bottom_sig() const
Returns the LMS signature by the bottom layer of the signed message.
Definition hss.h:377
HSS_Level Nspk() const
Returns the number of signed public keys (Nspk = L-1).
Definition hss.h:364
const Signed_Pub_Key & signed_pub_key(HSS_Level layer) const
Returns the signed LMS key signed by a specific layer.
Definition hss.h:372
The LM-OTS parameters.
Definition lm_ots.h:100
The LMS parameters.
Definition lms.h:88
Representation of an LMS Private key.
Definition lms.h:189
The LMS public key.
Definition lms.h:224
Container for LMS Signature data.
Definition lms.h:290
int(* final)(unsigned char *, CTX *)
#define BOTAN_TEST_API
Definition compiler.h:51
bool verify_signature(std::span< const uint8_t, ED448_LEN > pk, bool phflag, std::span< const uint8_t > context, std::span< const uint8_t > sig, std::span< const uint8_t > msg)
Verify a signature(RFC 8032 5.2.7)
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:61