Botan 3.14.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/assert.h>
14#include <botan/ec_group.h>
15#include <botan/pk_algs.h>
16#include <botan/pk_options_readers.h>
17#include <botan/internal/buffer_slicer.h>
18#include <botan/internal/buffer_stuffer.h>
19#include <botan/internal/concat_util.h>
20#include <botan/internal/hybrid_kem_ops.h>
21#include <botan/internal/kex_to_kem_adapter.h>
22#include <botan/internal/stl_util.h>
23#include <algorithm>
24#include <sstream>
25
26namespace Botan::TLS {
27
28namespace {
29
30std::vector<std::pair<std::string, std::string>> algorithm_specs_for_group(Group_Params group) {
31 BOTAN_ARG_CHECK(group.is_pqc_hybrid(), "Group is not hybrid");
32
33 switch(group.code()) {
34 // draft-kwiatkowski-tls-ecdhe-mlkem-02 Section 3
35 //
36 // NIST's special publication 800-56Cr2 approves the usage of HKDF with
37 // two distinct shared secrets, with the condition that the first one
38 // is computed by a FIPS-approved key-establishment scheme. FIPS also
39 // requires a certified implementation of the scheme, which will remain
40 // more ubiqutous for secp256r1 in the coming years.
41 //
42 // For this reason we put the ML-KEM-768 shared secret first in
43 // X25519MLKEM768, and the secp256r1 shared secret first in
44 // SecP256r1MLKEM768.
45 case Group_Params::HYBRID_X25519_ML_KEM_768:
46 return {{"ML-KEM", "ML-KEM-768"}, {"X25519", "X25519"}};
47 case Group_Params::HYBRID_SECP256R1_ML_KEM_768:
48 return {{"ECDH", "secp256r1"}, {"ML-KEM", "ML-KEM-768"}};
49 case Group_Params::HYBRID_SECP384R1_ML_KEM_1024:
50 return {{"ECDH", "secp384r1"}, {"ML-KEM", "ML-KEM-1024"}};
51
52 case Group_Params::HYBRID_X25519_eFRODOKEM_640_SHAKE_OQS:
53 return {{"X25519", "X25519"}, {"FrodoKEM", "eFrodoKEM-640-SHAKE"}};
54 case Group_Params::HYBRID_X25519_eFRODOKEM_640_AES_OQS:
55 return {{"X25519", "X25519"}, {"FrodoKEM", "eFrodoKEM-640-AES"}};
56 case Group_Params::HYBRID_X448_eFRODOKEM_976_SHAKE_OQS:
57 return {{"X448", "X448"}, {"FrodoKEM", "eFrodoKEM-976-SHAKE"}};
58 case Group_Params::HYBRID_X448_eFRODOKEM_976_AES_OQS:
59 return {{"X448", "X448"}, {"FrodoKEM", "eFrodoKEM-976-AES"}};
60
61 case Group_Params::HYBRID_SECP256R1_eFRODOKEM_640_SHAKE_OQS:
62 return {{"ECDH", "secp256r1"}, {"FrodoKEM", "eFrodoKEM-640-SHAKE"}};
63 case Group_Params::HYBRID_SECP256R1_eFRODOKEM_640_AES_OQS:
64 return {{"ECDH", "secp256r1"}, {"FrodoKEM", "eFrodoKEM-640-AES"}};
65
66 case Group_Params::HYBRID_SECP384R1_eFRODOKEM_976_SHAKE_OQS:
67 return {{"ECDH", "secp384r1"}, {"FrodoKEM", "eFrodoKEM-976-SHAKE"}};
68 case Group_Params::HYBRID_SECP384R1_eFRODOKEM_976_AES_OQS:
69 return {{"ECDH", "secp384r1"}, {"FrodoKEM", "eFrodoKEM-976-AES"}};
70
71 case Group_Params::HYBRID_SECP521R1_eFRODOKEM_1344_SHAKE_OQS:
72 return {{"ECDH", "secp521r1"}, {"FrodoKEM", "eFrodoKEM-1344-SHAKE"}};
73 case Group_Params::HYBRID_SECP521R1_eFRODOKEM_1344_AES_OQS:
74 return {{"ECDH", "secp521r1"}, {"FrodoKEM", "eFrodoKEM-1344-AES"}};
75
76 default:
77 return {};
78 }
79}
80
81std::vector<AlgorithmIdentifier> algorithm_identifiers_for_group(Group_Params group) {
82 BOTAN_ASSERT_NOMSG(group.is_pqc_hybrid());
83
84 const auto specs = algorithm_specs_for_group(group);
85 std::vector<AlgorithmIdentifier> result;
86 result.reserve(specs.size());
87
88 // This maps the string-based algorithm specs hard-coded above to OID-based
89 // AlgorithmIdentifier objects. The mapping is needed because
90 // load_public_key() depends on those while create_private_key() requires the
91 // strong-based spec.
92 //
93 // TODO: This is inconvenient, confusing and error-prone. Find a better way
94 // to load arbitrary public keys.
95 for(const auto& spec : specs) {
96 if(spec.first == "ECDH") {
97 result.push_back(AlgorithmIdentifier("ECDH", EC_Group::from_name(spec.second).DER_encode()));
98 } else {
99 result.push_back(AlgorithmIdentifier(spec.second, AlgorithmIdentifier::USE_EMPTY_PARAM));
100 }
101 }
102
103 return result;
104}
105
106std::vector<size_t> public_key_lengths_for_group(Group_Params group) {
107 BOTAN_ASSERT_NOMSG(group.is_pqc_hybrid());
108
109 // This duplicates information of the algorithm internals.
110 //
111 // TODO: Find a way to expose important algorithm constants globally
112 // in the library, to avoid violating the DRY principle.
113 switch(group.code()) {
114 case Group_Params::HYBRID_X25519_ML_KEM_768:
115 return {1184, 32};
116 case Group_Params::HYBRID_SECP256R1_ML_KEM_768:
117 return {65, 1184};
118 case Group_Params::HYBRID_SECP384R1_ML_KEM_1024:
119 return {97, 1568};
120
121 case Group_Params::HYBRID_X25519_eFRODOKEM_640_SHAKE_OQS:
122 case Group_Params::HYBRID_X25519_eFRODOKEM_640_AES_OQS:
123 return {32, 9616};
124
125 case Group_Params::HYBRID_X448_eFRODOKEM_976_SHAKE_OQS:
126 case Group_Params::HYBRID_X448_eFRODOKEM_976_AES_OQS:
127 return {56, 15632};
128
129 case Group_Params::HYBRID_SECP256R1_eFRODOKEM_640_SHAKE_OQS:
130 case Group_Params::HYBRID_SECP256R1_eFRODOKEM_640_AES_OQS:
131 return {65, 9616};
132
133 case Group_Params::HYBRID_SECP384R1_eFRODOKEM_976_SHAKE_OQS:
134 case Group_Params::HYBRID_SECP384R1_eFRODOKEM_976_AES_OQS:
135 return {97, 15632};
136
137 case Group_Params::HYBRID_SECP521R1_eFRODOKEM_1344_SHAKE_OQS:
138 case Group_Params::HYBRID_SECP521R1_eFRODOKEM_1344_AES_OQS:
139 return {133, 21520};
140
141 default:
142 return {};
143 }
144}
145
146std::vector<std::unique_ptr<Public_Key>> convert_kex_to_kem_pks(std::vector<std::unique_ptr<Public_Key>> pks) {
147 std::vector<std::unique_ptr<Public_Key>> result;
148 std::transform(pks.begin(), pks.end(), std::back_inserter(result), [](auto& key) -> std::unique_ptr<Public_Key> {
149 BOTAN_ARG_CHECK(key != nullptr, "Public key list contains a nullptr");
150 if(key->supports_operation(PublicKeyOperation::KeyAgreement) &&
151 !key->supports_operation(PublicKeyOperation::KeyEncapsulation)) {
152 return std::make_unique<KEX_to_KEM_Adapter_PublicKey>(std::move(key));
153 } else {
154 return std::move(key);
155 }
156 });
157 return result;
158}
159
160std::vector<std::unique_ptr<Private_Key>> convert_kex_to_kem_sks(std::vector<std::unique_ptr<Private_Key>> sks) {
161 std::vector<std::unique_ptr<Private_Key>> result;
162 std::transform(sks.begin(), sks.end(), std::back_inserter(result), [](auto& key) -> std::unique_ptr<Private_Key> {
163 BOTAN_ARG_CHECK(key != nullptr, "Private key list contains a nullptr");
164 if(key->supports_operation(PublicKeyOperation::KeyAgreement) &&
165 !key->supports_operation(PublicKeyOperation::KeyEncapsulation)) {
166 auto* ka_key = dynamic_cast<PK_Key_Agreement_Key*>(key.get());
167 BOTAN_ASSERT_NONNULL(ka_key);
168 (void)key.release();
169 return std::make_unique<KEX_to_KEM_Adapter_PrivateKey>(std::unique_ptr<PK_Key_Agreement_Key>(ka_key));
170 } else {
171 return std::move(key);
172 }
173 });
174 return result;
175}
176
177template <typename KEM_Operation>
178void concat_secret_combiner(KEM_Operation& op,
179 std::span<uint8_t> out_shared_secret,
180 const std::vector<secure_vector<uint8_t>>& shared_secrets,
181 size_t desired_shared_key_len) {
182 BOTAN_ARG_CHECK(out_shared_secret.size() == op.shared_key_length(desired_shared_key_len),
183 "Invalid output buffer size");
184
185 BufferStuffer shared_secret_stuffer(out_shared_secret);
186 for(const auto& ss : shared_secrets) {
187 shared_secret_stuffer.append(ss);
188 }
189 BOTAN_ASSERT_NOMSG(shared_secret_stuffer.full());
190}
191
192template <typename KEM_Operation>
193size_t concat_shared_key_length(const std::vector<KEM_Operation>& operation) {
194 return reduce(
195 operation, size_t(0), [](size_t acc, const auto& op) { return acc + op.shared_key_length(0 /*no KDF*/); });
196}
197
198/// Encryptor that simply concatenates the multiple shared secrets
199class Hybrid_TLS_KEM_Encryptor final : public KEM_Encryption_with_Combiner {
200 public:
201 Hybrid_TLS_KEM_Encryptor(const std::vector<std::unique_ptr<Public_Key>>& public_keys, std::string_view provider) :
202 KEM_Encryption_with_Combiner(public_keys, provider) {}
203
204 void combine_shared_secrets(std::span<uint8_t> out_shared_secret,
205 const std::vector<secure_vector<uint8_t>>& shared_secrets,
206 const std::vector<std::vector<uint8_t>>& /*ciphertexts*/,
207 size_t desired_shared_key_len,
208 std::span<const uint8_t> /*salt*/) override {
209 concat_secret_combiner(*this, out_shared_secret, shared_secrets, desired_shared_key_len);
210 }
211
212 size_t shared_key_length(size_t /*desired_shared_key_len*/) const override {
213 return concat_shared_key_length(encryptors());
214 }
215};
216
217/// Decryptor that simply concatenates the multiple shared secrets
218class Hybrid_TLS_KEM_Decryptor final : public KEM_Decryption_with_Combiner {
219 public:
220 Hybrid_TLS_KEM_Decryptor(const std::vector<std::unique_ptr<Private_Key>>& private_keys,
221 RandomNumberGenerator& rng,
222 const std::string_view provider) :
223 KEM_Decryption_with_Combiner(private_keys, rng, provider) {}
224
225 void combine_shared_secrets(std::span<uint8_t> out_shared_secret,
226 const std::vector<secure_vector<uint8_t>>& shared_secrets,
227 const std::vector<std::vector<uint8_t>>& /*ciphertexts*/,
228 size_t desired_shared_key_len,
229 std::span<const uint8_t> /*salt*/) override {
230 concat_secret_combiner(*this, out_shared_secret, shared_secrets, desired_shared_key_len);
231 }
232
233 size_t shared_key_length(size_t /*desired_shared_key_len*/) const override {
234 return concat_shared_key_length(decryptors());
235 }
236};
237
238} // namespace
239
240std::unique_ptr<Hybrid_KEM_PublicKey> Hybrid_KEM_PublicKey::load_for_group(
241 Group_Params group, std::span<const uint8_t> concatenated_public_keys) {
242 BOTAN_ARG_CHECK(group.is_pqc_hybrid(), "Group is not hybrid");
243 const auto public_key_lengths = public_key_lengths_for_group(group);
244 auto alg_ids = algorithm_identifiers_for_group(group);
245 BOTAN_ASSERT_NOMSG(public_key_lengths.size() == alg_ids.size());
246
247 const auto expected_public_keys_length =
248 reduce(public_key_lengths, size_t(0), [](size_t acc, size_t len) { return acc + len; });
249 if(expected_public_keys_length != concatenated_public_keys.size()) {
250 throw Decoding_Error("Concatenated public values have an unexpected length");
251 }
252
253 BufferSlicer public_key_slicer(concatenated_public_keys);
254 std::vector<std::unique_ptr<Public_Key>> pks;
255 pks.reserve(alg_ids.size());
256 for(size_t idx = 0; idx < alg_ids.size(); ++idx) {
257 pks.emplace_back(load_public_key(alg_ids[idx], public_key_slicer.take(public_key_lengths[idx])));
258 }
259 BOTAN_ASSERT_NOMSG(public_key_slicer.empty());
260 return std::make_unique<Hybrid_KEM_PublicKey>(std::move(pks));
261}
262
263Hybrid_KEM_PublicKey::Hybrid_KEM_PublicKey(std::vector<std::unique_ptr<Public_Key>> pks) :
264 Hybrid_PublicKey(convert_kex_to_kem_pks(std::move(pks))) {}
265
266Hybrid_KEM_PrivateKey::Hybrid_KEM_PrivateKey(std::vector<std::unique_ptr<Private_Key>> sks) :
267 Hybrid_PublicKey(convert_kex_to_kem_pks(extract_public_keys(sks))),
268 Hybrid_PrivateKey(convert_kex_to_kem_sks(std::move(sks))) {}
269
271 std::ostringstream algo_name;
272 algo_name << "Hybrid(";
273 for(size_t i = 0; i < public_keys().size(); ++i) {
274 if(i > 0) {
275 algo_name << ",";
276 }
277 algo_name << public_keys().at(i)->algo_name();
278 }
279 algo_name << ")";
280 return algo_name.str();
281}
282
284 throw Botan::Not_Implemented("Hybrid keys don't have an algorithm identifier");
285}
286
287std::vector<uint8_t> Hybrid_KEM_PublicKey::public_key_bits() const {
288 return raw_public_key_bits();
289}
290
291std::vector<uint8_t> Hybrid_KEM_PublicKey::raw_public_key_bits() const {
292 // draft-ietf-tls-hybrid-design-06 3.2
293 // The values are directly concatenated, without any additional encoding
294 // or length fields; this assumes that the representation and length of
295 // elements is fixed once the algorithm is fixed. If concatenation were
296 // to be used with values that are not fixed-length, a length prefix or
297 // other unambiguous encoding must be used to ensure that the composition
298 // of the two values is injective.
299 return reduce(public_keys(), std::vector<uint8_t>(), [](auto pkb, const auto& key) {
300 return concat(pkb, key->raw_public_key_bits());
301 });
302}
303
304std::unique_ptr<Private_Key> Hybrid_KEM_PublicKey::generate_another(RandomNumberGenerator& rng) const {
305 return std::make_unique<Hybrid_KEM_PrivateKey>(generate_other_sks_from_pks(rng));
306}
307
308std::unique_ptr<Botan::PK_Ops::KEM_Encryption> Hybrid_KEM_PublicKey::_create_kem_encryption_op(
309 const PK_KEM_Options_Reader& options) const {
310 if(options.using_kdf()) {
311 throw Botan::Invalid_Argument("Hybrid KEM encryption does not support KDFs");
312 }
313 // TLS uses the concatenated raw secrets directly, but they are not a
314 // uniform key, so this must be requested explicitly
315 if(!options.using_raw_shared_key()) {
316 throw Botan::Invalid_Argument("Hybrid KEM encryption requires explicitly requesting the raw shared key");
317 }
318 return std::make_unique<Hybrid_TLS_KEM_Encryptor>(public_keys(), options.provider().value_or(""));
319}
320
321std::unique_ptr<Hybrid_KEM_PrivateKey> Hybrid_KEM_PrivateKey::generate_from_group(Group_Params group,
323 const auto algo_spec = algorithm_specs_for_group(group);
324 std::vector<std::unique_ptr<Private_Key>> private_keys;
325 private_keys.reserve(algo_spec.size());
326 for(const auto& spec : algo_spec) {
327 private_keys.push_back(create_private_key(spec.first, rng, spec.second));
328 }
329 return std::make_unique<Hybrid_KEM_PrivateKey>(std::move(private_keys));
330}
331
332std::unique_ptr<Botan::PK_Ops::KEM_Decryption> Hybrid_KEM_PrivateKey::_create_kem_decryption_op(
333 RandomNumberGenerator& rng, const PK_KEM_Options_Reader& options) const {
334 if(options.using_kdf()) {
335 throw Botan::Invalid_Argument("Hybrid KEM decryption does not support KDFs");
336 }
337 if(!options.using_raw_shared_key()) {
338 throw Botan::Invalid_Argument("Hybrid KEM decryption requires explicitly requesting the raw shared key");
339 }
340 return std::make_unique<Hybrid_TLS_KEM_Decryptor>(private_keys(), rng, options.provider().value_or(""));
341}
342
343} // namespace Botan::TLS
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
std::span< const uint8_t > take(const size_t count)
static EC_Group from_name(std::string_view name)
Definition ec_group.cpp:529
std::vector< uint8_t > DER_encode(EC_Group_Encoding form) const
Definition ec_group.cpp:831
const std::vector< std::unique_ptr< Private_Key > > & private_keys() const
Definition hybrid_kem.h:119
Hybrid_PrivateKey(const Hybrid_PrivateKey &)=delete
static std::vector< std::unique_ptr< Public_Key > > extract_public_keys(const std::vector< std::unique_ptr< Private_Key > > &private_keys)
Hybrid_PublicKey(std::vector< std::unique_ptr< Public_Key > > public_keys)
Constructor for a list of multiple KEM public keys.
std::vector< std::unique_ptr< Private_Key > > generate_other_sks_from_pks(RandomNumberGenerator &rng) const
Helper function for generate_another. Generate a new private key for each public key in this hybrid k...
const std::vector< std::unique_ptr< Public_Key > > & public_keys() const
Definition hybrid_kem.h:66
const std::optional< std::string > & provider() const
constexpr bool is_pqc_hybrid() const
Definition tls_algos.h:240
static std::unique_ptr< Hybrid_KEM_PrivateKey > generate_from_group(Group_Params group, RandomNumberGenerator &rng)
std::unique_ptr< PK_Ops::KEM_Decryption > _create_kem_decryption_op(RandomNumberGenerator &rng, const PK_KEM_Options_Reader &options) const override
Hybrid_KEM_PrivateKey(std::vector< std::unique_ptr< Private_Key > > private_keys)
AlgorithmIdentifier algorithm_identifier() const override
std::vector< uint8_t > raw_public_key_bits() const override
Hybrid_KEM_PublicKey(std::vector< std::unique_ptr< Public_Key > > pks)
static std::unique_ptr< Hybrid_KEM_PublicKey > load_for_group(Group_Params group, std::span< const uint8_t > concatenated_public_values)
std::unique_ptr< Private_Key > generate_another(RandomNumberGenerator &rng) const final
std::string algo_name() const override
std::vector< uint8_t > public_key_bits() const override
std::unique_ptr< PK_Ops::KEM_Encryption > _create_kem_encryption_op(const PK_KEM_Options_Reader &options) const override
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:509
constexpr auto concat(Rs &&... ranges)
Definition concat_util.h:95
RetT reduce(const std::vector< KeyT > &keys, RetT acc, ReducerT reducer)
Definition stl_util.h:30
std::unique_ptr< Public_Key > load_public_key(const AlgorithmIdentifier &alg_id, std::span< const uint8_t > key_bits)
Definition pk_algs.cpp:130