Botan 3.5.0
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 case Group_Params::HYBRID_X25519_KYBER_512_R3_OQS:
29 case Group_Params::HYBRID_X25519_KYBER_512_R3_CLOUDFLARE:
30 return {{"X25519", "X25519"}, {"Kyber", "Kyber-512-r3"}};
31 case Group_Params::HYBRID_X25519_KYBER_768_R3_OQS:
32 return {{"X25519", "X25519"}, {"Kyber", "Kyber-768-r3"}};
33 case Group_Params::HYBRID_X448_KYBER_768_R3_OQS:
34 return {{"X448", "X448"}, {"Kyber", "Kyber-768-r3"}};
35 case Group_Params::HYBRID_X25519_eFRODOKEM_640_SHAKE_OQS:
36 return {{"X25519", "X25519"}, {"FrodoKEM", "eFrodoKEM-640-SHAKE"}};
37 case Group_Params::HYBRID_X25519_eFRODOKEM_640_AES_OQS:
38 return {{"X25519", "X25519"}, {"FrodoKEM", "eFrodoKEM-640-AES"}};
39 case Group_Params::HYBRID_X448_eFRODOKEM_976_SHAKE_OQS:
40 return {{"X448", "X448"}, {"FrodoKEM", "eFrodoKEM-976-SHAKE"}};
41 case Group_Params::HYBRID_X448_eFRODOKEM_976_AES_OQS:
42 return {{"X448", "X448"}, {"FrodoKEM", "eFrodoKEM-976-AES"}};
43
44 case Group_Params::HYBRID_SECP256R1_KYBER_512_R3_OQS:
45 return {{"ECDH", "secp256r1"}, {"Kyber", "Kyber-512-r3"}};
46 case Group_Params::HYBRID_SECP256R1_KYBER_768_R3_OQS:
47 return {{"ECDH", "secp256r1"}, {"Kyber", "Kyber-768-r3"}};
48 case Group_Params::HYBRID_SECP256R1_eFRODOKEM_640_SHAKE_OQS:
49 return {{"ECDH", "secp256r1"}, {"FrodoKEM", "eFrodoKEM-640-SHAKE"}};
50 case Group_Params::HYBRID_SECP256R1_eFRODOKEM_640_AES_OQS:
51 return {{"ECDH", "secp256r1"}, {"FrodoKEM", "eFrodoKEM-640-AES"}};
52
53 case Group_Params::HYBRID_SECP384R1_KYBER_768_R3_OQS:
54 return {{"ECDH", "secp384r1"}, {"Kyber", "Kyber-768-r3"}};
55 case Group_Params::HYBRID_SECP384R1_eFRODOKEM_976_SHAKE_OQS:
56 return {{"ECDH", "secp384r1"}, {"FrodoKEM", "eFrodoKEM-976-SHAKE"}};
57 case Group_Params::HYBRID_SECP384R1_eFRODOKEM_976_AES_OQS:
58 return {{"ECDH", "secp384r1"}, {"FrodoKEM", "eFrodoKEM-976-AES"}};
59
60 case Group_Params::HYBRID_SECP521R1_KYBER_1024_R3_OQS:
61 return {{"ECDH", "secp521r1"}, {"Kyber", "Kyber-1024-r3"}};
62 case Group_Params::HYBRID_SECP521R1_eFRODOKEM_1344_SHAKE_OQS:
63 return {{"ECDH", "secp521r1"}, {"FrodoKEM", "eFrodoKEM-1344-SHAKE"}};
64 case Group_Params::HYBRID_SECP521R1_eFRODOKEM_1344_AES_OQS:
65 return {{"ECDH", "secp521r1"}, {"FrodoKEM", "eFrodoKEM-1344-AES"}};
66
67 default:
68 return {};
69 }
70}
71
72std::vector<AlgorithmIdentifier> algorithm_identifiers_for_group(Group_Params group) {
73 BOTAN_ASSERT_NOMSG(group.is_pqc_hybrid());
74
75 const auto specs = algorithm_specs_for_group(group);
76 std::vector<AlgorithmIdentifier> result;
77 result.reserve(specs.size());
78
79 // This maps the string-based algorithm specs hard-coded above to OID-based
80 // AlgorithmIdentifier objects. The mapping is needed because
81 // load_public_key() depends on those while create_private_key() requires the
82 // strong-based spec.
83 //
84 // TODO: This is inconvenient, confusing and error-prone. Find a better way
85 // to load arbitrary public keys.
86 for(const auto& spec : specs) {
87 result.push_back(AlgorithmIdentifier(spec.second, AlgorithmIdentifier::USE_EMPTY_PARAM));
88 }
89
90 return result;
91}
92
93std::vector<size_t> public_value_lengths_for_group(Group_Params group) {
94 BOTAN_ASSERT_NOMSG(group.is_pqc_hybrid());
95
96 // This duplicates information of the algorithm internals.
97 //
98 // TODO: Find a way to expose important algorithm constants globally
99 // in the library, to avoid violating the DRY principle.
100 switch(group.code()) {
101 case Group_Params::HYBRID_X25519_KYBER_512_R3_CLOUDFLARE:
102 case Group_Params::HYBRID_X25519_KYBER_512_R3_OQS:
103 return {32, 800};
104 case Group_Params::HYBRID_X25519_KYBER_768_R3_OQS:
105 return {32, 1184};
106 case Group_Params::HYBRID_X448_KYBER_768_R3_OQS:
107 return {56, 1184};
108 case Group_Params::HYBRID_X25519_eFRODOKEM_640_SHAKE_OQS:
109 return {32, 9616};
110 case Group_Params::HYBRID_X25519_eFRODOKEM_640_AES_OQS:
111 return {32, 9616};
112 case Group_Params::HYBRID_X448_eFRODOKEM_976_SHAKE_OQS:
113 return {56, 15632};
114 case Group_Params::HYBRID_X448_eFRODOKEM_976_AES_OQS:
115 return {56, 15632};
116
117 case Group_Params::HYBRID_SECP256R1_KYBER_512_R3_OQS:
118 return {32, 800};
119 case Group_Params::HYBRID_SECP256R1_KYBER_768_R3_OQS:
120 return {32, 1184};
121 case Group_Params::HYBRID_SECP256R1_eFRODOKEM_640_SHAKE_OQS:
122 return {32, 9616};
123 case Group_Params::HYBRID_SECP256R1_eFRODOKEM_640_AES_OQS:
124 return {32, 9616};
125
126 case Group_Params::HYBRID_SECP384R1_KYBER_768_R3_OQS:
127 return {48, 1184};
128 case Group_Params::HYBRID_SECP384R1_eFRODOKEM_976_SHAKE_OQS:
129 return {48, 15632};
130 case Group_Params::HYBRID_SECP384R1_eFRODOKEM_976_AES_OQS:
131 return {48, 15632};
132
133 case Group_Params::HYBRID_SECP521R1_eFRODOKEM_1344_SHAKE_OQS:
134 return {66, 21520};
135 case Group_Params::HYBRID_SECP521R1_eFRODOKEM_1344_AES_OQS:
136 return {66, 21520};
137 case Group_Params::HYBRID_SECP521R1_KYBER_1024_R3_OQS:
138 return {66, 1568};
139
140 default:
141 return {};
142 }
143}
144
145} // namespace
146
147std::unique_ptr<Hybrid_KEM_PublicKey> Hybrid_KEM_PublicKey::load_for_group(
148 Group_Params group, std::span<const uint8_t> concatenated_public_values) {
149 const auto public_value_lengths = public_value_lengths_for_group(group);
150 auto alg_ids = algorithm_identifiers_for_group(group);
151 BOTAN_ASSERT_NOMSG(public_value_lengths.size() == alg_ids.size());
152
153 const auto expected_public_values_length =
154 reduce(public_value_lengths, size_t(0), [](size_t acc, size_t len) { return acc + len; });
155 BOTAN_ARG_CHECK(expected_public_values_length == concatenated_public_values.size(),
156 "Concatenated public values have an unexpected length");
157
158 BufferSlicer public_value_slicer(concatenated_public_values);
159 std::vector<std::unique_ptr<Public_Key>> pks;
160 for(size_t idx = 0; idx < alg_ids.size(); ++idx) {
161 pks.emplace_back(load_public_key(alg_ids[idx], public_value_slicer.take(public_value_lengths[idx])));
162 }
163 BOTAN_ASSERT_NOMSG(public_value_slicer.empty());
164 return std::make_unique<Hybrid_KEM_PublicKey>(std::move(pks));
165}
166
167Hybrid_KEM_PublicKey::Hybrid_KEM_PublicKey(std::vector<std::unique_ptr<Public_Key>> pks) {
168 BOTAN_ARG_CHECK(pks.size() >= 2, "List of public keys must include at least two keys");
169 BOTAN_ARG_CHECK(std::all_of(pks.begin(), pks.end(), [](const auto& pk) { return pk != nullptr; }),
170 "List of public keys contains a nullptr");
171 BOTAN_ARG_CHECK(std::all_of(pks.begin(),
172 pks.end(),
173 [](const auto& pk) {
174 return pk->supports_operation(PublicKeyOperation::KeyEncapsulation) ||
175 pk->supports_operation(PublicKeyOperation::KeyAgreement);
176 }),
177 "Some provided public key is not compatible with this hybrid wrapper");
178
179 std::transform(
180 pks.begin(), pks.end(), std::back_inserter(m_public_keys), [](auto& key) -> std::unique_ptr<Public_Key> {
181 if(key->supports_operation(PublicKeyOperation::KeyAgreement) &&
182 !key->supports_operation(PublicKeyOperation::KeyEncapsulation)) {
183 return std::make_unique<KEX_to_KEM_Adapter_PublicKey>(std::move(key));
184 } else {
185 return std::move(key);
186 }
187 });
188
189 m_key_length =
190 reduce(m_public_keys, size_t(0), [](size_t kl, const auto& key) { return std::max(kl, key->key_length()); });
191 m_estimated_strength = reduce(
192 m_public_keys, size_t(0), [](size_t es, const auto& key) { return std::max(es, key->estimated_strength()); });
193}
194
195std::string Hybrid_KEM_PublicKey::algo_name() const {
196 std::ostringstream algo_name("Hybrid(");
197 for(size_t i = 0; i < m_public_keys.size(); ++i) {
198 if(i > 0) {
199 algo_name << ",";
200 }
201 algo_name << m_public_keys[i]->algo_name();
202 }
203 algo_name << ")";
204 return algo_name.str();
205}
206
207size_t Hybrid_KEM_PublicKey::estimated_strength() const {
208 return m_estimated_strength;
209}
210
211size_t Hybrid_KEM_PublicKey::key_length() const {
212 return m_key_length;
213}
214
215bool Hybrid_KEM_PublicKey::check_key(RandomNumberGenerator& rng, bool strong) const {
216 return reduce(m_public_keys, true, [&](bool ckr, const auto& key) { return ckr && key->check_key(rng, strong); });
217}
218
219AlgorithmIdentifier Hybrid_KEM_PublicKey::algorithm_identifier() const {
220 throw Botan::Not_Implemented("Hybrid keys don't have an algorithm identifier");
221}
222
223std::vector<uint8_t> Hybrid_KEM_PublicKey::public_key_bits() const {
224 return raw_public_key_bits();
225}
226
227std::vector<uint8_t> Hybrid_KEM_PublicKey::raw_public_key_bits() const {
228 // draft-ietf-tls-hybrid-design-06 3.2
229 // The values are directly concatenated, without any additional encoding
230 // or length fields; this assumes that the representation and length of
231 // elements is fixed once the algorithm is fixed. If concatenation were
232 // to be used with values that are not fixed-length, a length prefix or
233 // other unambiguous encoding must be used to ensure that the composition
234 // of the two values is injective.
235 return reduce(m_public_keys, std::vector<uint8_t>(), [](auto pkb, const auto& key) {
236 return concat(pkb, key->raw_public_key_bits());
237 });
238}
239
240std::unique_ptr<Private_Key> Hybrid_KEM_PublicKey::generate_another(RandomNumberGenerator& rng) const {
241 std::vector<std::unique_ptr<Private_Key>> new_private_keys;
242 std::transform(
243 m_public_keys.begin(), m_public_keys.end(), std::back_inserter(new_private_keys), [&](const auto& public_key) {
244 return public_key->generate_another(rng);
245 });
246 return std::make_unique<Hybrid_KEM_PrivateKey>(std::move(new_private_keys));
247}
248
249bool Hybrid_KEM_PublicKey::supports_operation(PublicKeyOperation op) const {
251}
252
253namespace {
254
255class Hybrid_KEM_Encryption_Operation final : public PK_Ops::KEM_Encryption_with_KDF {
256 public:
257 Hybrid_KEM_Encryption_Operation(const Hybrid_KEM_PublicKey& key,
258 std::string_view kdf,
259 std::string_view provider) :
260 PK_Ops::KEM_Encryption_with_KDF(kdf), m_raw_kem_shared_key_length(0), m_encapsulated_key_length(0) {
261 m_kem_encryptors.reserve(key.public_keys().size());
262 for(const auto& k : key.public_keys()) {
263 const auto& newenc = m_kem_encryptors.emplace_back(*k, "Raw", provider);
264 m_raw_kem_shared_key_length += newenc.shared_key_length(0 /* no KDF */);
265 m_encapsulated_key_length += newenc.encapsulated_key_length();
266 }
267 }
268
269 size_t raw_kem_shared_key_length() const override { return m_raw_kem_shared_key_length; }
270
271 size_t encapsulated_key_length() const override { return m_encapsulated_key_length; }
272
273 void raw_kem_encrypt(std::span<uint8_t> out_encapsulated_key,
274 std::span<uint8_t> raw_shared_key,
275 Botan::RandomNumberGenerator& rng) override {
276 BOTAN_ASSERT_NOMSG(out_encapsulated_key.size() == encapsulated_key_length());
277 BOTAN_ASSERT_NOMSG(raw_shared_key.size() == raw_kem_shared_key_length());
278
279 BufferStuffer encaps_key_stuffer(out_encapsulated_key);
280 BufferStuffer shared_key_stuffer(raw_shared_key);
281
282 for(auto& kem_enc : m_kem_encryptors) {
283 kem_enc.encrypt(encaps_key_stuffer.next(kem_enc.encapsulated_key_length()),
284 shared_key_stuffer.next(kem_enc.shared_key_length(0 /* no KDF */)),
285 rng);
286 }
287 }
288
289 private:
290 std::vector<PK_KEM_Encryptor> m_kem_encryptors;
291 size_t m_raw_kem_shared_key_length;
292 size_t m_encapsulated_key_length;
293};
294
295} // namespace
296
297std::unique_ptr<Botan::PK_Ops::KEM_Encryption> Hybrid_KEM_PublicKey::create_kem_encryption_op(
298 std::string_view kdf, std::string_view provider) const {
299 return std::make_unique<Hybrid_KEM_Encryption_Operation>(*this, kdf, provider);
300}
301
302namespace {
303
304auto extract_public_keys(const std::vector<std::unique_ptr<Private_Key>>& private_keys) {
305 std::vector<std::unique_ptr<Public_Key>> public_keys;
306 public_keys.reserve(private_keys.size());
307 for(const auto& private_key : private_keys) {
308 BOTAN_ARG_CHECK(private_key != nullptr, "List of private keys contains a nullptr");
309 public_keys.push_back(private_key->public_key());
310 }
311 return public_keys;
312}
313
314} // namespace
315
316std::unique_ptr<Hybrid_KEM_PrivateKey> Hybrid_KEM_PrivateKey::generate_from_group(Group_Params group,
318 const auto algo_spec = algorithm_specs_for_group(group);
319 std::vector<std::unique_ptr<Private_Key>> private_keys;
320 private_keys.reserve(algo_spec.size());
321 for(const auto& spec : algo_spec) {
322 private_keys.push_back(create_private_key(spec.first, rng, spec.second));
323 }
324 return std::make_unique<Hybrid_KEM_PrivateKey>(std::move(private_keys));
325}
326
327Hybrid_KEM_PrivateKey::Hybrid_KEM_PrivateKey(std::vector<std::unique_ptr<Private_Key>> sks) :
328 Hybrid_KEM_PublicKey(extract_public_keys(sks)) {
329 BOTAN_ARG_CHECK(sks.size() >= 2, "List of private keys must include at least two keys");
330 BOTAN_ARG_CHECK(std::all_of(sks.begin(),
331 sks.end(),
332 [](const auto& sk) {
333 return sk->supports_operation(PublicKeyOperation::KeyEncapsulation) ||
334 sk->supports_operation(PublicKeyOperation::KeyAgreement);
335 }),
336 "Some provided private key is not compatible with this hybrid wrapper");
337
338 std::transform(
339 sks.begin(), sks.end(), std::back_inserter(m_private_keys), [](auto& key) -> std::unique_ptr<Private_Key> {
340 if(key->supports_operation(PublicKeyOperation::KeyAgreement) &&
341 !key->supports_operation(PublicKeyOperation::KeyEncapsulation)) {
342 auto ka_key = dynamic_cast<PK_Key_Agreement_Key*>(key.get());
343 BOTAN_ASSERT_NONNULL(ka_key);
344 (void)key.release();
345 return std::make_unique<KEX_to_KEM_Adapter_PrivateKey>(std::unique_ptr<PK_Key_Agreement_Key>(ka_key));
346 } else {
347 return std::move(key);
348 }
349 });
350}
351
353 throw Not_Implemented("Hybrid private keys cannot be serialized");
354}
355
356std::unique_ptr<Public_Key> Hybrid_KEM_PrivateKey::public_key() const {
357 return std::make_unique<Hybrid_KEM_PublicKey>(extract_public_keys(m_private_keys));
358}
359
361 return reduce(m_public_keys, true, [&](bool ckr, const auto& key) { return ckr && key->check_key(rng, strong); });
362}
363
364namespace {
365
366class Hybrid_KEM_Decryption final : public PK_Ops::KEM_Decryption_with_KDF {
367 public:
368 Hybrid_KEM_Decryption(const Hybrid_KEM_PrivateKey& key,
370 const std::string_view kdf,
371 const std::string_view provider) :
372 PK_Ops::KEM_Decryption_with_KDF(kdf), m_encapsulated_key_length(0), m_raw_kem_shared_key_length(0) {
373 m_decryptors.reserve(key.private_keys().size());
374 for(const auto& private_key : key.private_keys()) {
375 const auto& newdec = m_decryptors.emplace_back(*private_key, rng, "Raw", provider);
376 m_encapsulated_key_length += newdec.encapsulated_key_length();
377 m_raw_kem_shared_key_length += newdec.shared_key_length(0 /* no KDF */);
378 }
379 }
380
381 void raw_kem_decrypt(std::span<uint8_t> out_shared_key, std::span<const uint8_t> encap_key) override {
382 BOTAN_ASSERT_NOMSG(out_shared_key.size() == raw_kem_shared_key_length());
383 BOTAN_ASSERT_NOMSG(encap_key.size() == encapsulated_key_length());
384
385 BufferSlicer encap_key_slicer(encap_key);
386 BufferStuffer shared_secret_stuffer(out_shared_key);
387
388 for(auto& decryptor : m_decryptors) {
389 decryptor.decrypt(shared_secret_stuffer.next(decryptor.shared_key_length(0 /* no KDF */)),
390 encap_key_slicer.take(decryptor.encapsulated_key_length()));
391 }
392 }
393
394 size_t encapsulated_key_length() const override { return m_encapsulated_key_length; }
395
396 size_t raw_kem_shared_key_length() const override { return m_raw_kem_shared_key_length; }
397
398 private:
399 std::vector<PK_KEM_Decryptor> m_decryptors;
400 size_t m_encapsulated_key_length;
401 size_t m_raw_kem_shared_key_length;
402};
403
404} // namespace
405
406std::unique_ptr<Botan::PK_Ops::KEM_Decryption> Hybrid_KEM_PrivateKey::create_kem_decryption_op(
407 RandomNumberGenerator& rng, std::string_view kdf, std::string_view provider) const {
408 return std::make_unique<Hybrid_KEM_Decryption>(*this, rng, kdf, provider);
409}
410
411} // 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
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:422
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:262
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:107