Botan 3.14.1
Crypto and TLS for C&
xmss_publickey.cpp
Go to the documentation of this file.
1/*
2 * XMSS Public Key
3 * An XMSS: Extended Hash-Based Signature public key.
4 * The XMSS public key does not support the X509 standard. Instead the
5 * raw format described in [1] is used.
6 *
7 * [1] XMSS: Extended Hash-Based Signatures,
8 * Request for Comments: 8391
9 * Release: May 2018.
10 * https://datatracker.ietf.org/doc/rfc8391/
11 *
12 * (C) 2016,2017 Matthias Gierlings
13 *
14 * Botan is released under the Simplified BSD License (see license.txt)
15 **/
16
17#include <botan/xmss.h>
18
19#include <botan/ber_dec.h>
20#include <botan/der_enc.h>
21#include <botan/pk_options.h>
22#include <botan/rng.h>
23#include <botan/internal/buffer_slicer.h>
24#include <botan/internal/concat_util.h>
25#include <botan/internal/loadstor.h>
26#include <botan/internal/pk_options_impl.h>
27#include <botan/internal/xmss_verification_operation.h>
28
29namespace Botan {
30
31namespace {
32
33XMSS_Parameters::xmss_algorithm_t deserialize_xmss_oid(std::span<const uint8_t> raw_key) {
34 if(raw_key.size() < 4) {
35 throw Decoding_Error("XMSS signature OID missing.");
36 }
37
38 // extract and convert algorithm id to enum type
39 uint32_t raw_id = 0;
40 for(size_t i = 0; i < 4; i++) {
41 raw_id = ((raw_id << 8) | raw_key[i]);
42 }
43
44 return static_cast<XMSS_Parameters::xmss_algorithm_t>(raw_id);
45}
46
47// fall back to raw decoding for previous versions, which did not encode an OCTET STRING
48std::vector<uint8_t> extract_raw_public_key(std::span<const uint8_t> key_bits) {
49 std::vector<uint8_t> raw_key;
50 try {
52
53 // Smoke check the decoded key. Valid raw keys might be decodable as BER
54 // and they might be either a sole public key or a concatenation of public
55 // and private key (with the optional WOTS+ derivation identifier).
56 const XMSS_Parameters params = XMSS_Parameters::from_id(deserialize_xmss_oid(raw_key));
57 if(raw_key.size() != params.raw_public_key_size() && raw_key.size() != params.raw_private_key_size() &&
58 raw_key.size() != params.raw_legacy_private_key_size()) {
59 throw Decoding_Error("unpacked XMSS key does not have the correct length");
60 }
61 } catch(Decoding_Error&) {
62 raw_key.assign(key_bits.begin(), key_bits.end());
63 } catch(Not_Implemented&) {
64 raw_key.assign(key_bits.begin(), key_bits.end());
65 }
66
67 return raw_key;
68}
69
70} // namespace
71
72class XMSS_PublicKey_Internal final {
73 public:
74 XMSS_PublicKey_Internal(const XMSS_Parameters& params,
76 secure_vector<uint8_t> public_seed) :
77 m_xmss_params(params),
78 m_wots_params(m_xmss_params.wots_parameters()),
79 m_root(std::move(root)),
80 m_public_seed(std::move(public_seed)) {}
81
82 const XMSS_Parameters& xmss_parameters() const { return m_xmss_params; }
83
84 const XMSS_WOTS_Parameters& wots_parameters() const { return m_wots_params; }
85
86 const secure_vector<uint8_t>& root() const { return m_root; }
87
88 const secure_vector<uint8_t>& public_seed() const { return m_public_seed; }
89
90 std::vector<uint8_t> raw_public_key_bits() const {
92 store_be(static_cast<uint32_t>(m_xmss_params.oid())), m_root, m_public_seed);
93 }
94
95 private:
96 XMSS_Parameters m_xmss_params;
97 XMSS_WOTS_Parameters m_wots_params;
99 secure_vector<uint8_t> m_public_seed;
100};
101
103 const auto params = XMSS_Parameters::from_id(xmss_oid);
104 m_public_key = std::make_shared<XMSS_PublicKey_Internal>(
105 params, secure_vector<uint8_t>(params.element_size()), rng.random_vec(params.element_size()));
106}
107
108XMSS_PublicKey::XMSS_PublicKey(std::span<const uint8_t> key_bits) : XMSS_PublicKey(AlgorithmIdentifier(), key_bits) {}
109
110XMSS_PublicKey::XMSS_PublicKey(const AlgorithmIdentifier& alg_id, std::span<const uint8_t> key_bits) :
111 XMSS_PublicKey(alg_id, key_bits, Key_Encoding::PublicKey) {}
112
114 std::span<const uint8_t> key_bits,
115 Key_Encoding encoding) {
116 // The XMSS parameter set is carried in the key bits; no AlgorithmIdentifier parameters are defined
117 if(!alg_id.parameters_are_empty()) {
118 throw Decoding_Error("Unexpected parameters for XMSS public key");
119 }
120
121 const auto raw_key = extract_raw_public_key(key_bits);
122 const auto xmss_oid = deserialize_xmss_oid(raw_key);
123 const auto params = XMSS_Parameters::from_id(xmss_oid);
124
125 if(encoding == Key_Encoding::PublicKey) {
126 if(raw_key.size() != params.raw_public_key_size()) {
127 throw Decoding_Error("Invalid XMSS public key size detected");
128 }
129 } else if(raw_key.size() != params.raw_private_key_size() &&
130 raw_key.size() != params.raw_legacy_private_key_size()) {
131 throw Decoding_Error("Invalid XMSS private key size");
132 }
133
134 BufferSlicer s(raw_key);
135 s.skip(4 /* algorithm ID -- already consumed by `deserialize_xmss_oid()` */);
136
137 auto root = s.copy_as_secure_vector(params.element_size());
138 auto public_seed = s.copy_as_secure_vector(params.element_size());
139
140 m_public_key = std::make_shared<XMSS_PublicKey_Internal>(params, std::move(root), std::move(public_seed));
141}
142
146 const auto params = XMSS_Parameters::from_id(xmss_oid);
147 BOTAN_ARG_CHECK(root.size() == params.element_size(), "XMSS: unexpected byte length of root hash");
148 BOTAN_ARG_CHECK(public_seed.size() == params.element_size(), "XMSS: unexpected byte length of public seed");
149 m_public_key = std::make_shared<XMSS_PublicKey_Internal>(params, std::move(root), std::move(public_seed));
150}
151
153 return m_public_key->public_seed();
154}
155
157 return m_public_key->root();
158}
159
161 return m_public_key->xmss_parameters();
162}
163
167
171
172bool XMSS_PublicKey::check_key(RandomNumberGenerator& /*rng*/, bool /*strong*/) const {
173 // The public key consists of (OID, root hash, public seed). The OID is
174 // validated and the byte lengths of root and public_seed are verified
175 // against the parameter set during deserialization. These are opaque
176 // hash outputs with no further structural invariants to check.
177 return true;
178}
179
180std::unique_ptr<PK_Ops::Verification> XMSS_PublicKey::_create_verification_op(
181 const PK_Signature_Options_Reader& options) const {
182 validate_for_hash_based_signature(options, "XMSS", xmss_parameters().hash_function_name());
183
185
186 return std::make_unique<XMSS_Verification_Operation>(*this);
187}
188
189std::unique_ptr<PK_Ops::Verification> XMSS_PublicKey::create_x509_verification_op(const AlgorithmIdentifier& alg_id,
190 std::string_view provider) const {
191 if(provider == "base" || provider.empty()) {
192 if(alg_id != this->algorithm_identifier()) {
193 throw Decoding_Error("Unexpected AlgorithmIdentifier for XMSS X509 signature");
194 }
195 return std::make_unique<XMSS_Verification_Operation>(*this);
196 }
197 throw Provider_Not_Found(algo_name(), provider);
198}
199
200std::vector<uint8_t> XMSS_PublicKey::raw_public_key_bits() const {
201 return m_public_key->raw_public_key_bits();
202}
203
204std::vector<uint8_t> XMSS_PublicKey::public_key_bits() const {
205 std::vector<uint8_t> output;
207 return output;
208}
209
210std::vector<uint8_t> XMSS_PublicKey::raw_public_key() const {
211 return raw_public_key_bits();
212}
213
214std::unique_ptr<Private_Key> XMSS_PublicKey::generate_another(RandomNumberGenerator& rng) const {
215 // Note: Given only an XMSS public key we cannot know which WOTS key
216 // derivation method was used to build the XMSS tree. Hence, we have to
217 // use the default here.
218 return std::make_unique<XMSS_PrivateKey>(xmss_parameters().oid(), rng);
219}
220
221} // namespace Botan
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
bool parameters_are_empty() const
Definition asn1_obj.h:715
static Limits DER()
Definition ber_dec.h:44
BER_Decoder & decode(bool &out)
Definition ber_dec.h:361
BER_Decoder & verify_end()
Definition ber_dec.cpp:471
void skip(const size_t count)
auto copy_as_secure_vector(const size_t count)
DER_Encoder & encode(bool b)
Definition der_enc.cpp:313
void random_vec(std::span< uint8_t > v)
Definition rng.h:254
size_t estimated_strength() const
static XMSS_Parameters from_id(xmss_algorithm_t id)
std::unique_ptr< PK_Ops::Verification > create_x509_verification_op(const AlgorithmIdentifier &alg_id, std::string_view provider) const override
const secure_vector< uint8_t > & root() const
bool check_key(RandomNumberGenerator &rng, bool strong) const override
std::vector< uint8_t > public_key_bits() const override
std::vector< uint8_t > raw_public_key_bits() const override
const secure_vector< uint8_t > & public_seed() const
const XMSS_Parameters & xmss_parameters() const
std::vector< uint8_t > raw_public_key() const
size_t estimated_strength() const override
size_t key_length() const override
std::unique_ptr< Private_Key > generate_another(RandomNumberGenerator &rng) const final
std::unique_ptr< PK_Ops::Verification > _create_verification_op(const PK_Signature_Options_Reader &options) const override
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)
void require_software_provider(const OptionsT &options, std::string_view algo_name)
void validate_for_hash_based_signature(const PK_Signature_Options_Reader &options, std::string_view algo_name, std::string_view hash_fn)
constexpr auto concat(Rs &&... ranges)
Definition concat_util.h:95
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
constexpr auto store_be(ParamTs &&... params)
Definition loadstor.h:745