Botan 3.5.0
Crypto and TLS for C&
xmss.h
Go to the documentation of this file.
1/*
2 * XMSS Keys
3 * (C) 2016,2017 Matthias Gierlings
4 * (C) 2019 René Korthaus, Rohde & Schwarz Cybersecurity
5 *
6 * Botan is released under the Simplified BSD License (see license.txt)
7 **/
8
9#ifndef BOTAN_XMSS_H_
10#define BOTAN_XMSS_H_
11
12#include <memory>
13#include <span>
14
15#include <botan/exceptn.h>
16#include <botan/pk_keys.h>
17#include <botan/xmss_parameters.h>
18
19namespace Botan {
20
21class RandomNumberGenerator;
22class XMSS_Address;
23class XMSS_Hash;
24class XMSS_PrivateKey_Internal;
25class XMSS_Verification_Operation;
26class XMSS_WOTS_PublicKey;
27class XMSS_WOTS_PrivateKey;
28
29/**
30 * An XMSS: Extended Hash-Based Signature public key.
31 *
32 * [1] XMSS: Extended Hash-Based Signatures,
33 * Request for Comments: 8391
34 * Release: May 2018.
35 * https://datatracker.ietf.org/doc/rfc8391/
36 **/
37class BOTAN_PUBLIC_API(2, 0) XMSS_PublicKey : public virtual Public_Key {
38 public:
39 /**
40 * Creates a new XMSS public key for the chosen XMSS signature method.
41 * New public and prf seeds are generated using rng. The appropriate WOTS
42 * signature method will be automatically set based on the chosen XMSS
43 * signature method.
44 *
45 * @param xmss_oid Identifier for the selected XMSS signature method.
46 * @param rng A random number generator to use for key generation.
47 **/
49
50 /**
51 * Loads a public key.
52 *
53 * Public key must be encoded as in RFC
54 * draft-vangeest-x509-hash-sigs-03.
55 *
56 * @param key_bits DER encoded public key bits
57 */
58 XMSS_PublicKey(std::span<const uint8_t> key_bits);
59
60 /**
61 * Creates a new XMSS public key for a chosen XMSS signature method as
62 * well as pre-computed root node and public_seed values.
63 *
64 * @param xmss_oid Identifier for the selected XMSS signature method.
65 * @param root Root node value.
66 * @param public_seed Public seed value.
67 **/
70 secure_vector<uint8_t> public_seed);
71
72 std::string algo_name() const override { return "XMSS"; }
73
75 return AlgorithmIdentifier(object_identifier(), AlgorithmIdentifier::USE_EMPTY_PARAM);
76 }
77
78 bool check_key(RandomNumberGenerator&, bool) const override { return true; }
79
80 size_t estimated_strength() const override { return m_xmss_params.estimated_strength(); }
81
82 size_t key_length() const override { return m_xmss_params.estimated_strength(); }
83
84 /**
85 * Generates a byte sequence representing the XMSS
86 * public key, as defined in [1] (p. 23, "XMSS Public Key")
87 *
88 * @return 4-byte OID, followed by n-byte root node, followed by
89 * public seed.
90 **/
91 std::vector<uint8_t> raw_public_key_bits() const override;
92
93 /**
94 * Returns the encoded public key as defined in RFC
95 * draft-vangeest-x509-hash-sigs-03.
96 *
97 * @return encoded public key bits
98 **/
99 std::vector<uint8_t> public_key_bits() const override;
100
101 BOTAN_DEPRECATED("Use raw_public_key_bits()") std::vector<uint8_t> raw_public_key() const;
102
103 std::unique_ptr<Private_Key> generate_another(RandomNumberGenerator& rng) const final;
104
105 bool supports_operation(PublicKeyOperation op) const override { return (op == PublicKeyOperation::Signature); }
106
107 std::unique_ptr<PK_Ops::Verification> create_verification_op(std::string_view params,
108 std::string_view provider) const override;
109
110 std::unique_ptr<PK_Ops::Verification> create_x509_verification_op(const AlgorithmIdentifier& alg_id,
111 std::string_view provider) const override;
112
113 protected:
115
116 const secure_vector<uint8_t>& public_seed() const { return m_public_seed; }
117
118 const secure_vector<uint8_t>& root() const { return m_root; }
119
120 const XMSS_Parameters& xmss_parameters() const { return m_xmss_params; }
121
122 protected:
123 std::vector<uint8_t> m_raw_key;
128};
129
130template <typename>
131class Atomic;
132
134
135/**
136 * Determines how WOTS+ private keys are derived from the XMSS private key
137 */
139 /// This roughly followed the suggestions in RFC 8391 but is vulnerable
140 /// to a multi-target attack. For new private keys, we recommend using
141 /// the derivation as suggested in NIST SP.800-208.
142 /// Private keys generated with Botan 2.x will need to stay with this mode,
143 /// otherwise they won't be able to generate valid signatures any longer.
144 Botan2x = 1,
145
146 /// Derivation as specified in NIST SP.800-208 to avoid a multi-target attack
147 /// on the WOTS+ key derivation suggested in RFC 8391. New private keys
148 /// should use this mode.
149 NIST_SP800_208 = 2,
150};
151
152/**
153 * An XMSS: Extended Hash-Based Signature private key.
154 * The XMSS private key does not support the X509 and PKCS7 standard. Instead
155 * the raw format described in [1] is used.
156 *
157 * [1] XMSS: Extended Hash-Based Signatures,
158 * Request for Comments: 8391
159 * Release: May 2018.
160 * https://datatracker.ietf.org/doc/rfc8391/
161 **/
162
165
167 public virtual Private_Key {
168 public:
169 /**
170 * Creates a new XMSS private key for the chosen XMSS signature method.
171 * New seeds for public/private key and pseudo random function input are
172 * generated using the provided RNG. The appropriate WOTS signature method
173 * will be automatically set based on the chosen XMSS signature method.
174 *
175 * @param xmss_algo_id Identifier for the selected XMSS signature method.
176 * @param rng A random number generator to use for key generation.
177 * @param wots_derivation_method The method used to derive WOTS+ private keys
178 **/
181 WOTS_Derivation_Method wots_derivation_method = WOTS_Derivation_Method::NIST_SP800_208);
182
183 /**
184 * Creates an XMSS_PrivateKey from a byte sequence produced by
185 * raw_private_key().
186 *
187 * @param raw_key An XMSS private key serialized using raw_private_key().
188 **/
189 XMSS_PrivateKey(std::span<const uint8_t> raw_key);
190
191 /**
192 * Creates a new XMSS private key for the chosen XMSS signature method
193 * using precomputed seeds for public/private keys and pseudo random
194 * function input. The appropriate WOTS signature method will be
195 * automatically set, based on the chosen XMSS signature method.
196 *
197 * @param xmss_algo_id Identifier for the selected XMSS signature method.
198 * @param idx_leaf Index of the next unused leaf.
199 * @param wots_priv_seed A seed to generate a Winternitz-One-Time-
200 * Signature private key from.
201 * @param prf a secret n-byte key sourced from a secure source
202 * of uniformly random data.
203 * @param root Root node of the binary hash tree.
204 * @param public_seed The public seed.
205 * @param wots_derivation_method The method used to derive WOTS+ private keys
206 **/
208 size_t idx_leaf,
209 secure_vector<uint8_t> wots_priv_seed,
212 secure_vector<uint8_t> public_seed,
213 WOTS_Derivation_Method wots_derivation_method = WOTS_Derivation_Method::NIST_SP800_208);
214
215 bool stateful_operation() const override { return true; }
216
217 std::unique_ptr<Public_Key> public_key() const override;
218
219 /**
220 * Retrieves the last unused leaf index of the private key. Reusing a leaf
221 * by utilizing leaf indices lower than the last unused leaf index will
222 * compromise security.
223 *
224 * @return Index of the last unused leaf.
225 **/
226 BOTAN_DEPRECATED("Use remaining_operations()") size_t unused_leaf_index() const;
227
228 /**
229 * Retrieves the number of remaining signatures for this private key.
230 */
231 BOTAN_DEPRECATED("Use remaining_operations()") size_t remaining_signatures() const;
232
233 std::optional<uint64_t> remaining_operations() const override;
234
235 std::unique_ptr<PK_Ops::Signature> create_signature_op(RandomNumberGenerator&,
236 std::string_view,
237 std::string_view provider) const override;
238
239 secure_vector<uint8_t> private_key_bits() const override;
240
241 /**
242 * Generates a non standartized byte sequence representing the XMSS
243 * private key.
244 *
245 * @return byte sequence consisting of the following elements in order:
246 * 4-byte OID, n-byte root node, n-byte public seed,
247 * 8-byte unused leaf index, n-byte prf seed, n-byte private seed.
248 **/
249 secure_vector<uint8_t> raw_private_key() const;
250
251 WOTS_Derivation_Method wots_derivation_method() const;
252
253 private:
255
256 size_t reserve_unused_leaf_index();
257
258 const secure_vector<uint8_t>& prf_value() const;
259
260 XMSS_WOTS_PublicKey wots_public_key_for(XMSS_Address& adrs, XMSS_Hash& hash) const;
261 XMSS_WOTS_PrivateKey wots_private_key_for(XMSS_Address& adrs, XMSS_Hash& hash) const;
262
263 /**
264 * Algorithm 9: "treeHash"
265 * Computes the internal n-byte nodes of a Merkle tree.
266 *
267 * @param start_idx The start index.
268 * @param target_node_height Height of the target node.
269 * @param adrs Address of the tree containing the target node.
270 *
271 * @return The root node of a tree of height target_node height with the
272 * leftmost leaf being the hash of the WOTS+ pk with index
273 * start_idx.
274 **/
275 secure_vector<uint8_t> tree_hash(size_t start_idx, size_t target_node_height, XMSS_Address& adrs);
276
277 void tree_hash_subtree(secure_vector<uint8_t>& result,
278 size_t start_idx,
279 size_t target_node_height,
280 XMSS_Address& adrs);
281
282 /**
283 * Helper for multithreaded tree hashing.
284 */
285 void tree_hash_subtree(secure_vector<uint8_t>& result,
286 size_t start_idx,
287 size_t target_node_height,
288 XMSS_Address& adrs,
289 XMSS_Hash& hash);
290
291 std::shared_ptr<XMSS_PrivateKey_Internal> m_private;
292};
293
295
296} // namespace Botan
297
298#endif
bool stateful_operation() const override
Definition xmss.h:215
const secure_vector< uint8_t > & root() const
Definition xmss.h:118
secure_vector< uint8_t > m_root
Definition xmss.h:126
const secure_vector< uint8_t > & public_seed() const
Definition xmss.h:116
secure_vector< uint8_t > m_public_seed
Definition xmss.h:127
const XMSS_Parameters & xmss_parameters() const
Definition xmss.h:120
XMSS_Parameters m_xmss_params
Definition xmss.h:124
std::vector< uint8_t > m_raw_key
Definition xmss.h:123
size_t estimated_strength() const override
Definition xmss.h:80
size_t key_length() const override
Definition xmss.h:82
XMSS_WOTS_Parameters m_wots_params
Definition xmss.h:125
std::string algo_name() const override
Definition xmss.h:72
AlgorithmIdentifier algorithm_identifier() const override
Definition xmss.h:74
bool check_key(RandomNumberGenerator &, bool) const override
Definition xmss.h:78
int(* final)(unsigned char *, CTX *)
#define BOTAN_DIAGNOSTIC_POP
Definition compiler.h:191
#define BOTAN_DIAGNOSTIC_PUSH
Definition compiler.h:188
#define BOTAN_DIAGNOSTIC_IGNORE_INHERITED_VIA_DOMINANCE
Definition compiler.h:190
#define BOTAN_PUBLIC_API(maj, min)
Definition compiler.h:31
#define BOTAN_DEPRECATED(msg)
Definition compiler.h:125
PublicKeyOperation
Definition pk_keys.h:45
Gf448Elem root(const Gf448Elem &elem)
Compute the root of elem in the field.
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:61
WOTS_Derivation_Method
Definition xmss.h:138