Botan 3.14.1
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 <botan/pk_keys.h>
13#include <botan/xmss_parameters.h>
14#include <memory>
15#include <span>
16
17namespace Botan {
18
20class XMSS_Address;
21class XMSS_Hash;
22class XMSS_PublicKey_Internal;
23class XMSS_PrivateKey_Internal;
27
28/**
29 * An XMSS: Extended Hash-Based Signature public key.
30 *
31 * [1] XMSS: Extended Hash-Based Signatures,
32 * Request for Comments: 8391
33 * Release: May 2018.
34 * https://datatracker.ietf.org/doc/rfc8391/
35 **/
36class BOTAN_PUBLIC_API(2, 0) XMSS_PublicKey : public virtual Public_Key {
37 public:
38 /**
39 * Creates an XMSS public key with a random public seed and an all-zero
40 * root. No private key corresponds to this public key, so it cannot be
41 * used to verify signatures. To generate a new key use XMSS_PrivateKey.
42 *
43 * @param xmss_oid Identifier for the selected XMSS signature method.
44 * @param rng A random number generator used to create the public seed.
45 **/
46 BOTAN_DEPRECATED("Use XMSS_PrivateKey to generate a new key")
48
49 /**
50 * Loads a public key from an X.509 SubjectPublicKeyInfo.
51 *
52 * Public key must be encoded as in draft-vangeest-x509-hash-sigs-03.
53 *
54 * @param alg_id the X.509 AlgorithmIdentifier
55 * @param key_bits DER encoded public key bits
56 */
57 XMSS_PublicKey(const AlgorithmIdentifier& alg_id, std::span<const uint8_t> key_bits);
58
59 /**
60 * Loads a public key.
61 *
62 * Public key must be encoded as in draft-vangeest-x509-hash-sigs-03.
63 *
64 * @param key_bits DER encoded public key bits
65 */
66 BOTAN_DEPRECATED("Use the constructor taking an AlgorithmIdentifier")
67 BOTAN_FUTURE_EXPLICIT XMSS_PublicKey(std::span<const uint8_t> key_bits);
68
69 /**
70 * Creates a new XMSS public key for a chosen XMSS signature method as
71 * well as pre-computed root node and public_seed values.
72 *
73 * @param xmss_oid Identifier for the selected XMSS signature method.
74 * @param root Root node value.
75 * @param public_seed Public seed value.
76 **/
80
81 std::string algo_name() const override { return "XMSS"; }
82
86
87 bool check_key(RandomNumberGenerator& rng, bool strong) const override;
88
89 size_t estimated_strength() const override;
90
91 size_t key_length() const override;
92
93 /**
94 * Generates a byte sequence representing the XMSS
95 * public key, as defined in [1] (p. 23, "XMSS Public Key")
96 *
97 * @return 4-byte OID, followed by n-byte root node, followed by
98 * public seed.
99 **/
100 std::vector<uint8_t> raw_public_key_bits() const override;
101
102 /**
103 * Returns the encoded public key as defined in RFC
104 * draft-vangeest-x509-hash-sigs-03.
105 *
106 * @return encoded public key bits
107 **/
108 std::vector<uint8_t> public_key_bits() const override;
109
110 BOTAN_DEPRECATED("Use raw_public_key_bits()") std::vector<uint8_t> raw_public_key() const;
111
112 std::unique_ptr<Private_Key> generate_another(RandomNumberGenerator& rng) const final;
113
114 bool supports_operation(PublicKeyOperation op) const override { return (op == PublicKeyOperation::Signature); }
115
116 std::unique_ptr<PK_Ops::Verification> _create_verification_op(
117 const PK_Signature_Options_Reader& options) const override;
118
119 std::unique_ptr<PK_Ops::Verification> create_x509_verification_op(const AlgorithmIdentifier& alg_id,
120 std::string_view provider) const override;
121
122 protected:
124
125 /**
126 * Which key the serialization in key_bits holds. A private key
127 * encoding carries the public key followed by the private key body.
128 */
129 enum class Key_Encoding : uint8_t { PublicKey, PrivateKey };
130
131 XMSS_PublicKey(const AlgorithmIdentifier& alg_id, std::span<const uint8_t> key_bits, Key_Encoding encoding);
132
133 const secure_vector<uint8_t>& public_seed() const;
134
135 const secure_vector<uint8_t>& root() const;
136
137 const XMSS_Parameters& xmss_parameters() const;
138
139 private:
140 std::shared_ptr<const XMSS_PublicKey_Internal> m_public_key;
141};
142
143template <typename>
144class Atomic;
145
146class XMSS_Index_Registry;
147
148/**
149 * Determines how WOTS+ private keys are derived from the XMSS private key
150 */
151enum class WOTS_Derivation_Method : uint8_t {
152 /// This roughly followed the suggestions in RFC 8391 but is vulnerable
153 /// to a multi-target attack. For new private keys, we recommend using
154 /// the derivation as suggested in NIST SP.800-208.
155 /// Private keys generated with Botan 2.x will need to stay with this mode,
156 /// otherwise they won't be able to generate valid signatures any longer.
158
159 /// Derivation as specified in NIST SP.800-208 to avoid a multi-target attack
160 /// on the WOTS+ key derivation suggested in RFC 8391. New private keys
161 /// should use this mode.
163};
164
165/**
166 * An XMSS: Extended Hash-Based Signature private key.
167 * The XMSS private key does not support the X509 and PKCS7 standard. Instead
168 * the raw format described in [1] is used.
169 *
170 * [1] XMSS: Extended Hash-Based Signatures,
171 * Request for Comments: 8391
172 * Release: May 2018.
173 * https://datatracker.ietf.org/doc/rfc8391/
174 **/
175
178
179class BOTAN_PUBLIC_API(2, 0) XMSS_PrivateKey final : public virtual XMSS_PublicKey,
180 public virtual Private_Key {
181 public:
182 /**
183 * Creates a new XMSS private key for the chosen XMSS signature method.
184 * New seeds for public/private key and pseudo random function input are
185 * generated using the provided RNG. The appropriate WOTS signature method
186 * will be automatically set based on the chosen XMSS signature method.
187 *
188 * @param xmss_algo_id Identifier for the selected XMSS signature method.
189 * @param rng A random number generator to use for key generation.
190 * @param wots_derivation_method The method used to derive WOTS+ private keys
191 **/
195
196 /**
197 * Loads a private key from a PKCS #8 PrivateKeyInfo.
198 *
199 * @param alg_id the PKCS #8 AlgorithmIdentifier
200 * @param key_bits An XMSS private key serialized using raw_private_key().
201 **/
202 XMSS_PrivateKey(const AlgorithmIdentifier& alg_id, std::span<const uint8_t> key_bits);
203
204 /**
205 * Creates an XMSS_PrivateKey from a byte sequence produced by
206 * raw_private_key().
207 *
208 * @param raw_key An XMSS private key serialized using raw_private_key().
209 **/
210 BOTAN_DEPRECATED("Use the constructor taking an AlgorithmIdentifier")
211 BOTAN_FUTURE_EXPLICIT XMSS_PrivateKey(std::span<const uint8_t> raw_key);
212
213 /**
214 * Creates a new XMSS private key for the chosen XMSS signature method
215 * using precomputed seeds for public/private keys and pseudo random
216 * function input. The appropriate WOTS signature method will be
217 * automatically set, based on the chosen XMSS signature method.
218 *
219 * @param xmss_algo_id Identifier for the selected XMSS signature method.
220 * @param idx_leaf Index of the next unused leaf.
221 * @param wots_priv_seed A seed to generate a Winternitz-One-Time-
222 * Signature private key from.
223 * @param prf a secret n-byte key sourced from a secure source
224 * of uniformly random data.
225 * @param root Root node of the binary hash tree.
226 * @param public_seed The public seed.
227 * @param wots_derivation_method The method used to derive WOTS+ private keys
228 **/
230 size_t idx_leaf,
231 secure_vector<uint8_t> wots_priv_seed,
236
237 bool stateful_operation() const override { return true; }
238
239 bool check_key(RandomNumberGenerator& rng, bool strong) const override;
240
241 std::unique_ptr<Public_Key> public_key() const override;
242
243 /**
244 * Retrieves the last unused leaf index of the private key. Reusing a leaf
245 * by utilizing leaf indices lower than the last unused leaf index will
246 * compromise security.
247 *
248 * @return Index of the last unused leaf.
249 **/
250 BOTAN_DEPRECATED("Use remaining_operations()") size_t unused_leaf_index() const;
251
252 /**
253 * Retrieves the number of remaining signatures for this private key.
254 */
255 BOTAN_DEPRECATED("Use remaining_operations()") size_t remaining_signatures() const;
256
257 std::optional<uint64_t> remaining_operations() const override;
258
259 std::unique_ptr<PK_Ops::Signature> _create_signature_op(
260 RandomNumberGenerator& rng, const PK_Signature_Options_Reader& options) const override;
261
262 secure_vector<uint8_t> private_key_bits() const override;
263
264 /**
265 * Generates a non standardized byte sequence representing the XMSS
266 * private key.
267 *
268 * @return byte sequence consisting of the following elements in order:
269 * 4-byte OID, n-byte root node, n-byte public seed,
270 * 4-byte unused leaf index, n-byte prf seed, n-byte private seed.
271 * At last 1-byte that encodes the WOTS+ key derivation method.
272 **/
273 secure_vector<uint8_t> raw_private_key() const;
274
275 WOTS_Derivation_Method wots_derivation_method() const;
276
277 private:
279
280 // The seeds and the precomputed Merkle root produced during key
281 // generation, used to construct the (immutable) public key before the
282 // derived private key body runs.
283 struct Keygen_Material;
284
285 XMSS_PrivateKey(XMSS_Parameters::xmss_algorithm_t xmss_algo_id,
287 Keygen_Material material);
288
289 static Keygen_Material generate_keygen_material(XMSS_Parameters::xmss_algorithm_t xmss_algo_id,
292
293 size_t reserve_unused_leaf_index();
294
295 const secure_vector<uint8_t>& prf_value() const;
296
297 XMSS_WOTS_PrivateKey wots_private_key_for(const XMSS_Address& adrs, XMSS_Hash& hash) const;
298
299 /**
300 * Algorithm 9: "treeHash"
301 * Computes the internal n-byte nodes of a Merkle tree.
302 *
303 * @param start_idx The start index.
304 * @param target_node_height Height of the target node.
305 * @param adrs Address of the tree containing the target node.
306 * @param hash The hash function to use
307 *
308 * @return The root node of a tree of height target_node height with the
309 * leftmost leaf being the hash of the WOTS+ pk with index
310 * start_idx.
311 **/
312 secure_vector<uint8_t> tree_hash(size_t start_idx,
313 size_t target_node_height,
314 const XMSS_Address& adrs,
315 XMSS_Hash& hash) const;
316
317 std::shared_ptr<const XMSS_PrivateKey_Internal> m_private;
318};
319
321
322} // namespace Botan
323
324#endif
#define BOTAN_DIAGNOSTIC_POP
Definition api.h:128
#define BOTAN_DIAGNOSTIC_PUSH
Definition api.h:125
#define BOTAN_DIAGNOSTIC_IGNORE_INHERITED_VIA_DOMINANCE
Definition api.h:127
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_DEPRECATED(msg)
Definition api.h:73
#define BOTAN_FUTURE_EXPLICIT
Definition api.h:52
virtual OID object_identifier() const
Definition pk_keys.cpp:24
bool stateful_operation() const override
Definition xmss.h:237
friend class XMSS_Signature_Operation
Definition xmss.h:278
WOTS_Derivation_Method wots_derivation_method() const
XMSS_PrivateKey(XMSS_Parameters::xmss_algorithm_t xmss_algo_id, RandomNumberGenerator &rng, WOTS_Derivation_Method wots_derivation_method=WOTS_Derivation_Method::NIST_SP800_208)
const secure_vector< uint8_t > & root() const
const secure_vector< uint8_t > & public_seed() const
bool supports_operation(PublicKeyOperation op) const override
Definition xmss.h:114
friend class XMSS_Verification_Operation
Definition xmss.h:123
std::string algo_name() const override
Definition xmss.h:81
AlgorithmIdentifier algorithm_identifier() const override
Definition xmss.h:83
XMSS_PublicKey(XMSS_Parameters::xmss_algorithm_t xmss_oid, RandomNumberGenerator &rng)
Gf448Elem root(const Gf448Elem &elem)
Compute the root of elem in the field.
PublicKeyOperation
Definition pk_keys.h:50
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
WOTS_Derivation_Method
Definition xmss.h:151