Botan 3.7.1
Crypto and TLS for C&
hybrid_public_key.cpp
Go to the documentation of this file.
1/**
2* Composite key pair that exposes the Public/Private key API but combines
3* multiple key agreement schemes into a hybrid algorithm.
4*
5* (C) 2023 Jack Lloyd
6* 2023 Fabian Albert, René Meusel - Rohde & Schwarz Cybersecurity
7*
8* Botan is released under the Simplified BSD License (see license.txt)
9*/
10
11#include <botan/internal/hybrid_public_key.h>
12
13#include <botan/pk_algs.h>
14
15#include <botan/internal/fmt.h>
16#include <botan/internal/kex_to_kem_adapter.h>
17#include <botan/internal/pk_ops_impl.h>
18#include <botan/internal/stl_util.h>
19
20namespace Botan::TLS {
21
22namespace {
23
24std::vector<std::pair<std::string, std::string>> algorithm_specs_for_group(Group_Params group) {
25 BOTAN_ARG_CHECK(group.is_pqc_hybrid(), "Group is not hybrid");
26
27 switch(group.code()) {
28 // draft-kwiatkowski-tls-ecdhe-mlkem-02 Section 3
29 //
30 // NIST's special publication 800-56Cr2 approves the usage of HKDF with
31 // two distinct shared secrets, with the condition that the first one
32 // is computed by a FIPS-approved key-establishment scheme. FIPS also
33 // requires a certified implementation of the scheme, which will remain
34 // more ubiqutous for secp256r1 in the coming years.
35 //
36 // For this reason we put the ML-KEM-768 shared secret first in
37 // X25519MLKEM768, and the secp256r1 shared secret first in
38 // SecP256r1MLKEM768.
39 case Group_Params::HYBRID_X25519_ML_KEM_768:
40 return {{"ML-KEM", "ML-KEM-768"}, {"X25519", "X25519"}};
41 case Group_Params::HYBRID_SECP256R1_ML_KEM_768:
42 return {{"ECDH", "secp256r1"}, {"ML-KEM", "ML-KEM-768"}};
43
44 case Group_Params::HYBRID_X25519_eFRODOKEM_640_SHAKE_OQS:
45 return {{"X25519", "X25519"}, {"FrodoKEM", "eFrodoKEM-640-SHAKE"}};
46 case Group_Params::HYBRID_X25519_eFRODOKEM_640_AES_OQS:
47 return {{"X25519", "X25519"}, {"FrodoKEM", "eFrodoKEM-640-AES"}};
48 case Group_Params::HYBRID_X448_eFRODOKEM_976_SHAKE_OQS:
49 return {{"X448", "X448"}, {"FrodoKEM", "eFrodoKEM-976-SHAKE"}};
50 case Group_Params::HYBRID_X448_eFRODOKEM_976_AES_OQS:
51 return {{"X448", "X448"}, {"FrodoKEM", "eFrodoKEM-976-AES"}};
52
53 case Group_Params::HYBRID_SECP256R1_eFRODOKEM_640_SHAKE_OQS:
54 return {{"ECDH", "secp256r1"}, {"FrodoKEM", "eFrodoKEM-640-SHAKE"}};
55 case Group_Params::HYBRID_SECP256R1_eFRODOKEM_640_AES_OQS:
56 return {{"ECDH", "secp256r1"}, {"FrodoKEM", "eFrodoKEM-640-AES"}};
57
58 case Group_Params::HYBRID_SECP384R1_eFRODOKEM_976_SHAKE_OQS:
59 return {{"ECDH", "secp384r1"}, {"FrodoKEM", "eFrodoKEM-976-SHAKE"}};
60 case Group_Params::HYBRID_SECP384R1_eFRODOKEM_976_AES_OQS:
61 return {{"ECDH", "secp384r1"}, {"FrodoKEM", "eFrodoKEM-976-AES"}};
62
63 case Group_Params::HYBRID_SECP521R1_eFRODOKEM_1344_SHAKE_OQS:
64 return {{"ECDH", "secp521r1"}, {"FrodoKEM", "eFrodoKEM-1344-SHAKE"}};
65 case Group_Params::HYBRID_SECP521R1_eFRODOKEM_1344_AES_OQS:
66 return {{"ECDH", "secp521r1"}, {"FrodoKEM", "eFrodoKEM-1344-AES"}};
67
68 default:
69 return {};
70 }
71}
72
73std::vector<AlgorithmIdentifier> algorithm_identifiers_for_group(Group_Params group) {
74 BOTAN_ASSERT_NOMSG(group.is_pqc_hybrid());
75
76 const auto specs = algorithm_specs_for_group(group);
77 std::vector<AlgorithmIdentifier> result;
78 result.reserve(specs.size());
79
80 // This maps the string-based algorithm specs hard-coded above to OID-based
81 // AlgorithmIdentifier objects. The mapping is needed because
82 // load_public_key() depends on those while create_private_key() requires the
83 // strong-based spec.
84 //
85 // TODO: This is inconvenient, confusing and error-prone. Find a better way
86 // to load arbitrary public keys.
87 for(const auto& spec : specs) {
88 result.push_back(AlgorithmIdentifier(spec.second, AlgorithmIdentifier::USE_EMPTY_PARAM));
89 }
90
91 return result;
92}
93
94std::vector<size_t> public_value_lengths_for_group(Group_Params group) {
95 BOTAN_ASSERT_NOMSG(group.is_pqc_hybrid());
96
97 // This duplicates information of the algorithm internals.
98 //
99 // TODO: Find a way to expose important algorithm constants globally
100 // in the library, to avoid violating the DRY principle.
101 switch(group.code()) {
102 case Group_Params::HYBRID_X25519_ML_KEM_768:
103 return {1184, 32};
104 case Group_Params::HYBRID_SECP256R1_ML_KEM_768:
105 return {32, 1184};
106
107 case Group_Params::HYBRID_X25519_eFRODOKEM_640_SHAKE_OQS:
108 return {32, 9616};
109 case Group_Params::HYBRID_X25519_eFRODOKEM_640_AES_OQS:
110 return {32, 9616};
111 case Group_Params::HYBRID_X448_eFRODOKEM_976_SHAKE_OQS:
112 return {56, 15632};
113 case Group_Params::HYBRID_X448_eFRODOKEM_976_AES_OQS:
114 return {56, 15632};
115
116 case Group_Params::HYBRID_SECP256R1_eFRODOKEM_640_SHAKE_OQS:
117 return {32, 9616};
118 case Group_Params::HYBRID_SECP256R1_eFRODOKEM_640_AES_OQS:
119 return {32, 9616};
120
121 case Group_Params::HYBRID_SECP384R1_eFRODOKEM_976_SHAKE_OQS:
122 return {48, 15632};
123 case Group_Params::HYBRID_SECP384R1_eFRODOKEM_976_AES_OQS:
124 return {48, 15632};
125
126 case Group_Params::HYBRID_SECP521R1_eFRODOKEM_1344_SHAKE_OQS:
127 return {66, 21520};
128 case Group_Params::HYBRID_SECP521R1_eFRODOKEM_1344_AES_OQS:
129 return {66, 21520};
130
131 default:
132 return {};
133 }
134}
135
136} // namespace
137
138std::unique_ptr<Hybrid_KEM_PublicKey> Hybrid_KEM_PublicKey::load_for_group(
139 Group_Params group, std::span<const uint8_t> concatenated_public_values) {
140 const auto public_value_lengths = public_value_lengths_for_group(group);
141 auto alg_ids = algorithm_identifiers_for_group(group);
142 BOTAN_ASSERT_NOMSG(public_value_lengths.size() == alg_ids.size());
143
144 const auto expected_public_values_length =
145 reduce(public_value_lengths, size_t(0), [](size_t acc, size_t len) { return acc + len; });
146 if(expected_public_values_length != concatenated_public_values.size()) {
147 throw Decoding_Error("Concatenated public values have an unexpected length");
148 }
149
150 BufferSlicer public_value_slicer(concatenated_public_values);
151 std::vector<std::unique_ptr<Public_Key>> pks;
152 pks.reserve(alg_ids.size());
153 for(size_t idx = 0; idx < alg_ids.size(); ++idx) {
154 pks.emplace_back(load_public_key(alg_ids[idx], public_value_slicer.take(public_value_lengths[idx])));
155 }
156 BOTAN_ASSERT_NOMSG(public_value_slicer.empty());
157 return std::make_unique<Hybrid_KEM_PublicKey>(std::move(pks));
158}
159
160Hybrid_KEM_PublicKey::Hybrid_KEM_PublicKey(std::vector<std::unique_ptr<Public_Key>> pks) {
161 BOTAN_ARG_CHECK(pks.size() >= 2, "List of public keys must include at least two keys");
162 BOTAN_ARG_CHECK(std::all_of(pks.begin(), pks.end(), [](const auto& pk) { return pk != nullptr; }),
163 "List of public keys contains a nullptr");
164 BOTAN_ARG_CHECK(std::all_of(pks.begin(),
165 pks.end(),
166 [](const auto& pk) {
167 return pk->supports_operation(PublicKeyOperation::KeyEncapsulation) ||
168 pk->supports_operation(PublicKeyOperation::KeyAgreement);
169 }),
170 "Some provided public key is not compatible with this hybrid wrapper");
171
172 std::transform(
173 pks.begin(), pks.end(), std::back_inserter(m_public_keys), [](auto& key) -> std::unique_ptr<Public_Key> {
174 if(key->supports_operation(PublicKeyOperation::KeyAgreement) &&
175 !key->supports_operation(PublicKeyOperation::KeyEncapsulation)) {
176 return std::make_unique<KEX_to_KEM_Adapter_PublicKey>(std::move(key));
177 } else {
178 return std::move(key);
179 }
180 });
181
182 m_key_length =
183 reduce(m_public_keys, size_t(0), [](size_t kl, const auto& key) { return std::max(kl, key->key_length()); });
184 m_estimated_strength = reduce(
185 m_public_keys, size_t(0), [](size_t es, const auto& key) { return std::max(es, key->estimated_strength()); });
186}
187
188std::string Hybrid_KEM_PublicKey::algo_name() const {
189 std::ostringstream algo_name("Hybrid(");
190 for(size_t i = 0; i < m_public_keys.size(); ++i) {
191 if(i > 0) {
192 algo_name << ",";
193 }
194 algo_name << m_public_keys[i]->algo_name();
195 }
196 algo_name << ")";
197 return algo_name.str();
198}
199
200size_t Hybrid_KEM_PublicKey::estimated_strength() const {
201 return m_estimated_strength;
202}
203
204size_t Hybrid_KEM_PublicKey::key_length() const {
205 return m_key_length;
206}
207
208bool Hybrid_KEM_PublicKey::check_key(RandomNumberGenerator& rng, bool strong) const {
209 return reduce(m_public_keys, true, [&](bool ckr, const auto& key) { return ckr && key->check_key(rng, strong); });
210}
211
212AlgorithmIdentifier Hybrid_KEM_PublicKey::algorithm_identifier() const {
213 throw Botan::Not_Implemented("Hybrid keys don't have an algorithm identifier");
214}
215
216std::vector<uint8_t> Hybrid_KEM_PublicKey::public_key_bits() const {
217 return raw_public_key_bits();
218}
219
220std::vector<uint8_t> Hybrid_KEM_PublicKey::raw_public_key_bits() const {
221 // draft-ietf-tls-hybrid-design-06 3.2
222 // The values are directly concatenated, without any additional encoding
223 // or length fields; this assumes that the representation and length of
224 // elements is fixed once the algorithm is fixed. If concatenation were
225 // to be used with values that are not fixed-length, a length prefix or
226 // other unambiguous encoding must be used to ensure that the composition
227 // of the two values is injective.
228 return reduce(m_public_keys, std::vector<uint8_t>(), [](auto pkb, const auto& key) {
229 return concat(pkb, key->raw_public_key_bits());
230 });
231}
232
233std::unique_ptr<Private_Key> Hybrid_KEM_PublicKey::generate_another(RandomNumberGenerator& rng) const {
234 std::vector<std::unique_ptr<Private_Key>> new_private_keys;
235 std::transform(
236 m_public_keys.begin(), m_public_keys.end(), std::back_inserter(new_private_keys), [&](const auto& public_key) {
237 return public_key->generate_another(rng);
238 });
239 return std::make_unique<Hybrid_KEM_PrivateKey>(std::move(new_private_keys));
240}
241
242bool Hybrid_KEM_PublicKey::supports_operation(PublicKeyOperation op) const {
244}
245
246namespace {
247
248class Hybrid_KEM_Encryption_Operation final : public PK_Ops::KEM_Encryption_with_KDF {
249 public:
250 Hybrid_KEM_Encryption_Operation(const Hybrid_KEM_PublicKey& key,
251 std::string_view kdf,
252 std::string_view provider) :
253 PK_Ops::KEM_Encryption_with_KDF(kdf), m_raw_kem_shared_key_length(0), m_encapsulated_key_length(0) {
254 m_kem_encryptors.reserve(key.public_keys().size());
255 for(const auto& k : key.public_keys()) {
256 const auto& newenc = m_kem_encryptors.emplace_back(*k, "Raw", provider);
257 m_raw_kem_shared_key_length += newenc.shared_key_length(0 /* no KDF */);
258 m_encapsulated_key_length += newenc.encapsulated_key_length();
259 }
260 }
261
262 size_t raw_kem_shared_key_length() const override { return m_raw_kem_shared_key_length; }
263
264 size_t encapsulated_key_length() const override { return m_encapsulated_key_length; }
265
266 void raw_kem_encrypt(std::span<uint8_t> out_encapsulated_key,
267 std::span<uint8_t> raw_shared_key,
268 Botan::RandomNumberGenerator& rng) override {
269 BOTAN_ASSERT_NOMSG(out_encapsulated_key.size() == encapsulated_key_length());
270 BOTAN_ASSERT_NOMSG(raw_shared_key.size() == raw_kem_shared_key_length());
271
272 BufferStuffer encaps_key_stuffer(out_encapsulated_key);
273 BufferStuffer shared_key_stuffer(raw_shared_key);
274
275 for(auto& kem_enc : m_kem_encryptors) {
276 kem_enc.encrypt(encaps_key_stuffer.next(kem_enc.encapsulated_key_length()),
277 shared_key_stuffer.next(kem_enc.shared_key_length(0 /* no KDF */)),
278 rng);
279 }
280 }
281
282 private:
283 std::vector<PK_KEM_Encryptor> m_kem_encryptors;
284 size_t m_raw_kem_shared_key_length;
285 size_t m_encapsulated_key_length;
286};
287
288} // namespace
289
290std::unique_ptr<Botan::PK_Ops::KEM_Encryption> Hybrid_KEM_PublicKey::create_kem_encryption_op(
291 std::string_view kdf, std::string_view provider) const {
292 return std::make_unique<Hybrid_KEM_Encryption_Operation>(*this, kdf, provider);
293}
294
295namespace {
296
297auto extract_public_keys(const std::vector<std::unique_ptr<Private_Key>>& private_keys) {
298 std::vector<std::unique_ptr<Public_Key>> public_keys;
299 public_keys.reserve(private_keys.size());
300 for(const auto& private_key : private_keys) {
301 BOTAN_ARG_CHECK(private_key != nullptr, "List of private keys contains a nullptr");
302 public_keys.push_back(private_key->public_key());
303 }
304 return public_keys;
305}
306
307} // namespace
308
309std::unique_ptr<Hybrid_KEM_PrivateKey> Hybrid_KEM_PrivateKey::generate_from_group(Group_Params group,
311 const auto algo_spec = algorithm_specs_for_group(group);
312 std::vector<std::unique_ptr<Private_Key>> private_keys;
313 private_keys.reserve(algo_spec.size());
314 for(const auto& spec : algo_spec) {
315 private_keys.push_back(create_private_key(spec.first, rng, spec.second));
316 }
317 return std::make_unique<Hybrid_KEM_PrivateKey>(std::move(private_keys));
318}
319
320Hybrid_KEM_PrivateKey::Hybrid_KEM_PrivateKey(std::vector<std::unique_ptr<Private_Key>> sks) :
321 Hybrid_KEM_PublicKey(extract_public_keys(sks)) {
322 BOTAN_ARG_CHECK(sks.size() >= 2, "List of private keys must include at least two keys");
323 BOTAN_ARG_CHECK(std::all_of(sks.begin(),
324 sks.end(),
325 [](const auto& sk) {
326 return sk->supports_operation(PublicKeyOperation::KeyEncapsulation) ||
327 sk->supports_operation(PublicKeyOperation::KeyAgreement);
328 }),
329 "Some provided private key is not compatible with this hybrid wrapper");
330
331 std::transform(
332 sks.begin(), sks.end(), std::back_inserter(m_private_keys), [](auto& key) -> std::unique_ptr<Private_Key> {
333 if(key->supports_operation(PublicKeyOperation::KeyAgreement) &&
334 !key->supports_operation(PublicKeyOperation::KeyEncapsulation)) {
335 auto ka_key = dynamic_cast<PK_Key_Agreement_Key*>(key.get());
336 BOTAN_ASSERT_NONNULL(ka_key);
337 (void)key.release();
338 return std::make_unique<KEX_to_KEM_Adapter_PrivateKey>(std::unique_ptr<PK_Key_Agreement_Key>(ka_key));
339 } else {
340 return std::move(key);
341 }
342 });
343}
344
346 throw Not_Implemented("Hybrid private keys cannot be serialized");
347}
348
349std::unique_ptr<Public_Key> Hybrid_KEM_PrivateKey::public_key() const {
350 return std::make_unique<Hybrid_KEM_PublicKey>(extract_public_keys(m_private_keys));
351}
352
354 return reduce(m_public_keys, true, [&](bool ckr, const auto& key) { return ckr && key->check_key(rng, strong); });
355}
356
357namespace {
358
359class Hybrid_KEM_Decryption final : public PK_Ops::KEM_Decryption_with_KDF {
360 public:
361 Hybrid_KEM_Decryption(const Hybrid_KEM_PrivateKey& key,
363 const std::string_view kdf,
364 const std::string_view provider) :
365 PK_Ops::KEM_Decryption_with_KDF(kdf), m_encapsulated_key_length(0), m_raw_kem_shared_key_length(0) {
366 m_decryptors.reserve(key.private_keys().size());
367 for(const auto& private_key : key.private_keys()) {
368 const auto& newdec = m_decryptors.emplace_back(*private_key, rng, "Raw", provider);
369 m_encapsulated_key_length += newdec.encapsulated_key_length();
370 m_raw_kem_shared_key_length += newdec.shared_key_length(0 /* no KDF */);
371 }
372 }
373
374 void raw_kem_decrypt(std::span<uint8_t> out_shared_key, std::span<const uint8_t> encap_key) override {
375 BOTAN_ASSERT_NOMSG(out_shared_key.size() == raw_kem_shared_key_length());
376 BOTAN_ASSERT_NOMSG(encap_key.size() == encapsulated_key_length());
377
378 BufferSlicer encap_key_slicer(encap_key);
379 BufferStuffer shared_secret_stuffer(out_shared_key);
380
381 for(auto& decryptor : m_decryptors) {
382 decryptor.decrypt(shared_secret_stuffer.next(decryptor.shared_key_length(0 /* no KDF */)),
383 encap_key_slicer.take(decryptor.encapsulated_key_length()));
384 }
385 }
386
387 size_t encapsulated_key_length() const override { return m_encapsulated_key_length; }
388
389 size_t raw_kem_shared_key_length() const override { return m_raw_kem_shared_key_length; }
390
391 private:
392 std::vector<PK_KEM_Decryptor> m_decryptors;
393 size_t m_encapsulated_key_length;
394 size_t m_raw_kem_shared_key_length;
395};
396
397} // namespace
398
399std::unique_ptr<Botan::PK_Ops::KEM_Decryption> Hybrid_KEM_PrivateKey::create_kem_decryption_op(
400 RandomNumberGenerator& rng, std::string_view kdf, std::string_view provider) const {
401 return std::make_unique<Hybrid_KEM_Decryption>(*this, rng, kdf, provider);
402}
403
404} // namespace Botan::TLS
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:59
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:29
bool empty() const
Definition stl_util.h:129
std::span< const uint8_t > take(const size_t count)
Definition stl_util.h:98
Helper class to ease in-place marshalling of concatenated fixed-length values.
Definition stl_util.h:142
bool check_key(RandomNumberGenerator &rng, bool strong) const override
std::unique_ptr< Public_Key > public_key() const override
std::unique_ptr< PK_Ops::KEM_Decryption > create_kem_decryption_op(RandomNumberGenerator &rng, std::string_view kdf, std::string_view provider="base") const override
secure_vector< uint8_t > private_key_bits() const override
std::vector< std::unique_ptr< Public_Key > > m_public_keys
Hybrid_KEM_PublicKey(std::vector< std::unique_ptr< Public_Key > > pks)
bool check_key(RandomNumberGenerator &rng, bool strong) const override
static std::unique_ptr< Hybrid_KEM_PublicKey > load_for_group(Group_Params group, std::span< const uint8_t > concatenated_public_values)
int(* final)(unsigned char *, CTX *)
std::unique_ptr< Private_Key > create_private_key(std::string_view alg_name, RandomNumberGenerator &rng, std::string_view params, std::string_view provider)
Definition pk_algs.cpp:487
PublicKeyOperation
Definition pk_keys.h:45
RetT reduce(const std::vector< KeyT > &keys, RetT acc, ReducerT reducer)
Definition stl_util.h:47
constexpr auto concat(Rs &&... ranges)
Definition stl_util.h:263
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:61
std::unique_ptr< Public_Key > load_public_key(const AlgorithmIdentifier &alg_id, std::span< const uint8_t > key_bits)
Definition pk_algs.cpp:124