Botan 3.14.1
Crypto and TLS for C&
kex_to_kem_adapter.cpp
Go to the documentation of this file.
1/**
2 * Adapter that allows using a KEX key as a KEM, using an ephemeral
3 * key in the KEM encapsulation.
4 *
5 * (C) 2023 Jack Lloyd
6 * 2023,2024 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/kex_to_kem_adapter.h>
12
13#include <botan/assert.h>
14#include <botan/internal/fmt.h>
15#include <botan/internal/pk_ops_impl.h>
16
17#if defined(BOTAN_HAS_DIFFIE_HELLMAN)
18 #include <botan/dh.h>
19 #include <botan/dl_group.h>
20#endif
21
22#if defined(BOTAN_HAS_ECDH)
23 #include <botan/ec_group.h>
24 #include <botan/ecdh.h>
25#endif
26
27#if defined(BOTAN_HAS_X25519)
28 #include <botan/pk_options_readers.h>
29 #include <botan/x25519.h>
30#endif
31
32#if defined(BOTAN_HAS_X448)
33 #include <botan/x448.h>
34#endif
35
36namespace Botan {
37
38namespace {
39
40/**
41 * This helper determines the length of the agreed-upon value depending
42 * on the key agreement public key's algorithm type. It would be better
43 * to get this value via PK_Key_Agreement::agreed_value_size(), but
44 * instantiating a PK_Key_Agreement object requires a PrivateKey object
45 * which we don't have (yet) in the context this is used.
46 *
47 * TODO: Find a way to get this information without duplicating those
48 * implementation details of the key agreement algorithms.
49 */
50size_t kex_shared_key_length(const Public_Key& kex_public_key) {
51 BOTAN_ASSERT_NOMSG(kex_public_key.supports_operation(PublicKeyOperation::KeyAgreement));
52
53#if defined(BOTAN_HAS_ECDH)
54 if(const auto* ecdh = dynamic_cast<const ECDH_PublicKey*>(&kex_public_key)) {
55 return ecdh->domain().get_p_bytes();
56 }
57#endif
58
59#if defined(BOTAN_HAS_DIFFIE_HELLMAN)
60 if(const auto* dh = dynamic_cast<const DH_PublicKey*>(&kex_public_key)) {
61 return dh->group().p_bytes();
62 }
63#endif
64
65#if defined(BOTAN_HAS_X25519)
66 if(const auto* curve = dynamic_cast<const X25519_PublicKey*>(&kex_public_key)) {
67 BOTAN_UNUSED(curve);
68 return 32; /* TODO: magic number */
69 }
70#endif
71
72#if defined(BOTAN_HAS_X448)
73 if(const auto* curve = dynamic_cast<const X448_PublicKey*>(&kex_public_key)) {
74 BOTAN_UNUSED(curve);
75 return 56; /* TODO: magic number */
76 }
77#endif
78
79 throw Not_Implemented(
80 fmt("Cannot get shared kex key length from unknown key agreement public key of type '{}' in the hybrid KEM key",
81 kex_public_key.algo_name()));
82}
83
84/**
85 * This helper generates an ephemeral key agreement private key given a
86 * public key instance of a certain key agreement algorithm.
87 */
88std::unique_ptr<PK_Key_Agreement_Key> generate_key_agreement_private_key(const Public_Key& kex_public_key,
90 BOTAN_ASSERT_NOMSG(kex_public_key.supports_operation(PublicKeyOperation::KeyAgreement));
91
92 auto new_kex_key = [&] {
93 auto new_private_key = kex_public_key.generate_another(rng);
94 auto* const kex_key = dynamic_cast<PK_Key_Agreement_Key*>(new_private_key.get());
95 if(kex_key != nullptr) [[likely]] {
96 // Intentionally leak new_private_key since we hold an alias of it in kex_key,
97 // which is captured in a unique_ptr below
98 // NOLINTNEXTLINE(*-unused-return-value)
99 (void)new_private_key.release();
100 }
101 return std::unique_ptr<PK_Key_Agreement_Key>(kex_key);
102 }();
103
104 BOTAN_ASSERT(new_kex_key, "Keys wrapped in this adapter are always key-agreement keys");
105 return new_kex_key;
106}
107
108std::unique_ptr<Public_Key> maybe_get_public_key(const std::unique_ptr<Private_Key>& private_key) {
109 BOTAN_ARG_CHECK(private_key != nullptr, "Private key is a nullptr");
110 return private_key->public_key();
111}
112
113class KEX_to_KEM_Adapter_Encryption_Operation final : public PK_Ops::KEM_Encryption_with_KDF {
114 public:
115 // The raw shared secret of a key agreement is a group element, not a uniform key
116 KEX_to_KEM_Adapter_Encryption_Operation(std::shared_ptr<const Public_Key> key,
117 const PK_KEM_Options_Reader& options,
118 std::string_view provider) :
119 PK_Ops::KEM_Encryption_with_KDF(options, PK_Ops::KemSharedKeyQuality::RequiresKDF),
120 m_provider(provider),
121 m_public_key(std::move(key)) {}
122
123 size_t raw_kem_shared_key_length() const override { return kex_shared_key_length(*m_public_key); }
124
125 size_t encapsulated_key_length() const override {
126 // Serializing the public value into a short-lived heap-allocated
127 // vector is not ideal.
128 //
129 // TODO: Find a way to get the public value length without copying
130 // the public value into a vector. See GH #3706 (point 5).
131 return m_public_key->raw_public_key_bits().size();
132 }
133
134 void raw_kem_encrypt(std::span<uint8_t> out_encapsulated_key,
135 std::span<uint8_t> raw_shared_key,
136 Botan::RandomNumberGenerator& rng) override {
137 const auto sk = generate_key_agreement_private_key(*m_public_key, rng);
138 const auto shared_key =
139 PK_Key_Agreement(*sk, rng, PK_Key_Agreement_Options().with_raw_shared_key().with_provider(m_provider))
140 .derive_key(0 /* no KDF */, m_public_key->raw_public_key_bits())
141 .bits_of();
142
143 const auto public_value = sk->public_value();
144
145 // TODO: perhaps avoid these copies by providing std::span out-params
146 // for `PK_Key_Agreement::derive_key()` and
147 // `PK_Key_Agreement_Key::public_value()`
148 BOTAN_ASSERT_EQUAL(public_value.size(),
149 out_encapsulated_key.size(),
150 "KEX-to-KEM Adapter: encapsulated key out-param has correct length");
152 shared_key.size(), raw_shared_key.size(), "KEX-to-KEM Adapter: shared key out-param has correct length");
153 std::copy(public_value.begin(), public_value.end(), out_encapsulated_key.begin());
154 std::copy(shared_key.begin(), shared_key.end(), raw_shared_key.begin());
155 }
156
157 private:
158 std::string m_provider;
159 std::shared_ptr<const Public_Key> m_public_key;
160};
161
162class KEX_to_KEM_Decryption_Operation final : public PK_Ops::KEM_Decryption_with_KDF {
163 public:
164 KEX_to_KEM_Decryption_Operation(const PK_Key_Agreement_Key& key,
165 RandomNumberGenerator& rng,
166 const PK_KEM_Options_Reader& options,
167 const std::string_view provider) :
168 PK_Ops::KEM_Decryption_with_KDF(options, PK_Ops::KemSharedKeyQuality::RequiresKDF),
169 m_operation(key, rng, PK_Key_Agreement_Options().with_raw_shared_key().with_provider(provider)),
170 m_encapsulated_key_length(key.public_value().size()) {}
171
172 void raw_kem_decrypt(std::span<uint8_t> out_shared_key, std::span<const uint8_t> encap_key) override {
173 secure_vector<uint8_t> shared_secret = m_operation.derive_key(0 /* no KDF */, encap_key).bits_of();
175 shared_secret.size(), out_shared_key.size(), "KEX-to-KEM Adapter: shared key out-param has correct length");
176 std::copy(shared_secret.begin(), shared_secret.end(), out_shared_key.begin());
177 }
178
179 size_t encapsulated_key_length() const override { return m_encapsulated_key_length; }
180
181 size_t raw_kem_shared_key_length() const override { return m_operation.agreed_value_size(); }
182
183 private:
184 PK_Key_Agreement m_operation;
185 size_t m_encapsulated_key_length;
186};
187
188} // namespace
189
190KEX_to_KEM_Adapter_PublicKey::KEX_to_KEM_Adapter_PublicKey(std::unique_ptr<Public_Key> public_key) :
191 m_public_key(std::move(public_key)) {
192 BOTAN_ARG_CHECK(m_public_key != nullptr, "Public key is a nullptr");
193 BOTAN_ARG_CHECK(m_public_key->supports_operation(PublicKeyOperation::KeyAgreement), "Public key is no KEX key");
194}
195
197 return fmt("KEX-to-KEM({})", m_public_key->algo_name());
198}
199
201 return m_public_key->estimated_strength();
202}
203
205 return m_public_key->key_length();
206}
207
209 return m_public_key->check_key(rng, strong);
210}
211
213 return m_public_key->algorithm_identifier();
214}
215
217 return m_public_key->raw_public_key_bits();
218}
219
221 return m_public_key->public_key_bits();
222}
223
225 return std::make_unique<KEX_to_KEM_Adapter_PrivateKey>(generate_key_agreement_private_key(*m_public_key, rng));
226}
227
231
232namespace {
233
234std::unique_ptr<PK_Key_Agreement_Key> capture_as_ka_key(std::unique_ptr<Private_Key> private_key) {
235 auto* raw_ptr = private_key.release();
236 if(auto* sk = dynamic_cast<PK_Key_Agreement_Key*>(raw_ptr)) {
237 return std::unique_ptr<PK_Key_Agreement_Key>(sk);
238 } else {
239 delete raw_ptr; // NOLINT(*-owning-memory)
241 "Private key must implement PK_Key_Agreement_Key", "KEX_to_KEM_Adapter_PrivateKey", __FILE__);
242 }
243}
244
245} // namespace
246
247KEX_to_KEM_Adapter_PrivateKey::KEX_to_KEM_Adapter_PrivateKey(std::unique_ptr<Private_Key> private_key) :
248 KEX_to_KEM_Adapter_PublicKey(maybe_get_public_key(private_key)),
249 m_private_key(capture_as_ka_key(std::move(private_key))) {}
250
252 return m_private_key->private_key_bits();
253}
254
256 return m_private_key->raw_private_key_bits();
257}
258
259std::unique_ptr<Public_Key> KEX_to_KEM_Adapter_PrivateKey::public_key() const {
260 return std::make_unique<KEX_to_KEM_Adapter_PublicKey>(m_private_key->public_key());
261}
262
264 return m_private_key->check_key(rng, strong);
265}
266
267std::unique_ptr<PK_Ops::KEM_Encryption> KEX_to_KEM_Adapter_PublicKey::_create_kem_encryption_op(
268 const PK_KEM_Options_Reader& options) const {
269 // The provider selects the implementation of the underlying key agreement
270 return std::make_unique<KEX_to_KEM_Adapter_Encryption_Operation>(
271 m_public_key, options, options.provider().value_or(""));
272}
273
274std::unique_ptr<PK_Ops::KEM_Decryption> KEX_to_KEM_Adapter_PrivateKey::_create_kem_decryption_op(
275 RandomNumberGenerator& rng, const PK_KEM_Options_Reader& options) const {
276 return std::make_unique<KEX_to_KEM_Decryption_Operation>(
277 *m_private_key, rng, options, options.provider().value_or(""));
278}
279
280} // namespace Botan
#define BOTAN_UNUSED
Definition assert.h:151
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
#define BOTAN_ASSERT_EQUAL(expr1, expr2, assertion_made)
Definition assert.h:95
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
#define BOTAN_ASSERT(expr, assertion_made)
Definition assert.h:69
secure_vector< uint8_t > private_key_bits() const override
std::unique_ptr< Public_Key > public_key() const override
secure_vector< uint8_t > raw_private_key_bits() const override
KEX_to_KEM_Adapter_PrivateKey(std::unique_ptr< Private_Key > private_key)
std::unique_ptr< PK_Ops::KEM_Decryption > _create_kem_decryption_op(RandomNumberGenerator &rng, const PK_KEM_Options_Reader &options) const override
bool check_key(RandomNumberGenerator &rng, bool strong) const override
KEX_to_KEM_Adapter_PublicKey(std::unique_ptr< Public_Key > public_key)
std::string algo_name() const override
std::unique_ptr< PK_Ops::KEM_Encryption > _create_kem_encryption_op(const PK_KEM_Options_Reader &options) const override
bool check_key(RandomNumberGenerator &rng, bool strong) const override
std::vector< uint8_t > raw_public_key_bits() const override
std::unique_ptr< Private_Key > generate_another(RandomNumberGenerator &rng) const final
AlgorithmIdentifier algorithm_identifier() const override
bool supports_operation(PublicKeyOperation op) const override
std::vector< uint8_t > public_key_bits() const override
const std::optional< std::string > & provider() const
A public key for the X448 key agreement scheme according to RFC 7748.
Definition x448.h:24
void throw_invalid_argument(const char *message, const char *func, const char *file)
Definition assert.cpp:23
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53
PublicKeyOperation
Definition pk_keys.h:50
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128