Botan 3.5.0
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 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/internal/fmt.h>
14#include <botan/internal/pk_ops_impl.h>
15#include <botan/internal/stl_util.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/ecdh.h>
24#endif
25
26#if defined(BOTAN_HAS_X25519)
27 #include <botan/x25519.h>
28#endif
29
30#if defined(BOTAN_HAS_X448)
31 #include <botan/x448.h>
32#endif
33
34namespace Botan::TLS {
35
36namespace {
37
38/**
39 * This helper determines the length of the agreed-upon value depending
40 * on the key agreement public key's algorithm type. It would be better
41 * to get this value via PK_Key_Agreement::agreed_value_size(), but
42 * instantiating a PK_Key_Agreement object requires a PrivateKey object
43 * which we don't have (yet) in the context this is used.
44 *
45 * TODO: Find a way to get this information without duplicating those
46 * implementation details of the key agreement algorithms.
47 */
48size_t kex_shared_key_length(const Public_Key& kex_public_key) {
49 BOTAN_ASSERT_NOMSG(kex_public_key.supports_operation(PublicKeyOperation::KeyAgreement));
50
51#if defined(BOTAN_HAS_ECDH)
52 if(const auto* ecdh = dynamic_cast<const ECDH_PublicKey*>(&kex_public_key)) {
53 return ecdh->domain().get_p_bytes();
54 }
55#endif
56
57#if defined(BOTAN_HAS_DIFFIE_HELLMAN)
58 if(const auto* dh = dynamic_cast<const DH_PublicKey*>(&kex_public_key)) {
59 return dh->group().p_bytes();
60 }
61#endif
62
63#if defined(BOTAN_HAS_X25519)
64 if(const auto* curve = dynamic_cast<const X25519_PublicKey*>(&kex_public_key)) {
65 BOTAN_UNUSED(curve);
66 return 32; /* TODO: magic number */
67 }
68#endif
69
70#if defined(BOTAN_HAS_X448)
71 if(const auto* curve = dynamic_cast<const X448_PublicKey*>(&kex_public_key)) {
72 BOTAN_UNUSED(curve);
73 return 56; /* TODO: magic number */
74 }
75#endif
76
77 throw Not_Implemented(
78 fmt("Cannot get shared kex key length from unknown key agreement public key of type '{}' in the hybrid KEM key",
79 kex_public_key.algo_name()));
80}
81
82/**
83 * This helper generates an ephemeral key agreement private key given a
84 * public key instance of a certain key agreement algorithm.
85 */
86std::unique_ptr<PK_Key_Agreement_Key> generate_key_agreement_private_key(const Public_Key& kex_public_key,
87 RandomNumberGenerator& rng) {
88 BOTAN_ASSERT_NOMSG(kex_public_key.supports_operation(PublicKeyOperation::KeyAgreement));
89
90 auto new_kex_key = [&] {
91 auto new_private_key = kex_public_key.generate_another(rng);
92 const auto kex_key = dynamic_cast<PK_Key_Agreement_Key*>(new_private_key.get());
93 if(kex_key) [[likely]] {
94 // Intentionally leak new_private_key since we hold an alias of it in kex_key,
95 // which is captured in a unique_ptr below
96 // NOLINTNEXTLINE(*-unused-return-value)
97 (void)new_private_key.release();
98 }
99 return std::unique_ptr<PK_Key_Agreement_Key>(kex_key);
100 }();
101
102 BOTAN_ASSERT(new_kex_key, "Keys wrapped in this adapter are always key-agreement keys");
103 return new_kex_key;
104}
105
106std::unique_ptr<Public_Key> maybe_get_public_key(const std::unique_ptr<PK_Key_Agreement_Key>& private_key) {
107 BOTAN_ARG_CHECK(private_key != nullptr, "Private key is a nullptr");
108 return private_key->public_key();
109}
110
111class KEX_to_KEM_Adapter_Encryption_Operation final : public PK_Ops::KEM_Encryption_with_KDF {
112 public:
113 KEX_to_KEM_Adapter_Encryption_Operation(const Public_Key& key, std::string_view kdf, std::string_view provider) :
114 PK_Ops::KEM_Encryption_with_KDF(kdf), m_provider(provider), m_public_key(key) {}
115
116 size_t raw_kem_shared_key_length() const override { return kex_shared_key_length(m_public_key); }
117
118 size_t encapsulated_key_length() const override {
119 // Serializing the public value into a short-lived heap-allocated
120 // vector is not ideal.
121 //
122 // TODO: Find a way to get the public value length without copying
123 // the public value into a vector. See GH #3706 (point 5).
124 return m_public_key.raw_public_key_bits().size();
125 }
126
127 void raw_kem_encrypt(std::span<uint8_t> out_encapsulated_key,
128 std::span<uint8_t> raw_shared_key,
129 Botan::RandomNumberGenerator& rng) override {
130 const auto sk = generate_key_agreement_private_key(m_public_key, rng);
131 const auto shared_key = PK_Key_Agreement(*sk, rng, "Raw", m_provider)
132 .derive_key(0 /* no KDF */, m_public_key.raw_public_key_bits())
133 .bits_of();
134
135 const auto public_value = sk->public_value();
136
137 // TODO: perhaps avoid these copies by providing std::span out-params
138 // for `PK_Key_Agreement::derive_key()` and
139 // `PK_Key_Agreement_Key::public_value()`
140 BOTAN_ASSERT_EQUAL(public_value.size(),
141 out_encapsulated_key.size(),
142 "KEX-to-KEM Adapter: encapsulated key out-param has correct length");
144 shared_key.size(), raw_shared_key.size(), "KEX-to-KEM Adapter: shared key out-param has correct length");
145 std::copy(public_value.begin(), public_value.end(), out_encapsulated_key.begin());
146 std::copy(shared_key.begin(), shared_key.end(), raw_shared_key.begin());
147 }
148
149 private:
150 std::string m_provider;
151 const Public_Key& m_public_key;
152};
153
154class KEX_to_KEM_Decryption_Operation final : public PK_Ops::KEM_Decryption_with_KDF {
155 public:
156 KEX_to_KEM_Decryption_Operation(const PK_Key_Agreement_Key& key,
157 RandomNumberGenerator& rng,
158 const std::string_view kdf,
159 const std::string_view provider) :
160 PK_Ops::KEM_Decryption_with_KDF(kdf),
161 m_operation(key, rng, "Raw", provider),
162 m_encapsulated_key_length(key.public_value().size()) {}
163
164 void raw_kem_decrypt(std::span<uint8_t> out_shared_key, std::span<const uint8_t> encap_key) override {
165 secure_vector<uint8_t> shared_secret = m_operation.derive_key(0 /* no KDF */, encap_key).bits_of();
167 shared_secret.size(), out_shared_key.size(), "KEX-to-KEM Adapter: shared key out-param has correct length");
168 std::copy(shared_secret.begin(), shared_secret.end(), out_shared_key.begin());
169 }
170
171 size_t encapsulated_key_length() const override { return m_encapsulated_key_length; }
172
173 size_t raw_kem_shared_key_length() const override { return m_operation.agreed_value_size(); }
174
175 private:
176 PK_Key_Agreement m_operation;
177 size_t m_encapsulated_key_length;
178};
179
180} // namespace
181
182KEX_to_KEM_Adapter_PublicKey::KEX_to_KEM_Adapter_PublicKey(std::unique_ptr<Public_Key> public_key) :
183 m_public_key(std::move(public_key)) {
184 BOTAN_ARG_CHECK(m_public_key != nullptr, "Public key is a nullptr");
185 BOTAN_ARG_CHECK(m_public_key->supports_operation(PublicKeyOperation::KeyAgreement), "Public key is no KEX key");
186}
187
189 return fmt("KEX-to-KEM({})", m_public_key->algo_name());
190}
191
193 return m_public_key->estimated_strength();
194}
195
197 return m_public_key->key_length();
198}
199
201 return m_public_key->check_key(rng, strong);
202}
203
205 return m_public_key->algorithm_identifier();
206}
207
209 return m_public_key->raw_public_key_bits();
210}
211
213 throw Not_Implemented("The KEX-to-KEM adapter does not support ASN.1-based public key serialization");
214}
215
217 return std::make_unique<KEX_to_KEM_Adapter_PrivateKey>(generate_key_agreement_private_key(*m_public_key, rng));
218}
219
223
224KEX_to_KEM_Adapter_PrivateKey::KEX_to_KEM_Adapter_PrivateKey(std::unique_ptr<PK_Key_Agreement_Key> private_key) :
225 KEX_to_KEM_Adapter_PublicKey(maybe_get_public_key(private_key)), m_private_key(std::move(private_key)) {
226 BOTAN_ARG_CHECK(m_private_key->supports_operation(PublicKeyOperation::KeyAgreement), "Private key is no KEX key");
227}
228
230 return m_private_key->private_key_bits();
231}
232
233std::unique_ptr<Public_Key> KEX_to_KEM_Adapter_PrivateKey::public_key() const {
234 return std::make_unique<KEX_to_KEM_Adapter_PublicKey>(m_private_key->public_key());
235}
236
238 return m_private_key->check_key(rng, strong);
239}
240
241std::unique_ptr<PK_Ops::KEM_Encryption> KEX_to_KEM_Adapter_PublicKey::create_kem_encryption_op(
242 std::string_view kdf, std::string_view provider) const {
243 return std::make_unique<KEX_to_KEM_Adapter_Encryption_Operation>(*m_public_key, kdf, provider);
244}
245
246std::unique_ptr<PK_Ops::KEM_Decryption> KEX_to_KEM_Adapter_PrivateKey::create_kem_decryption_op(
247 RandomNumberGenerator& rng, std::string_view kdf, std::string_view provider) const {
248 return std::make_unique<KEX_to_KEM_Decryption_Operation>(*m_private_key, rng, kdf, provider);
249}
250
251} // namespace Botan::TLS
#define BOTAN_UNUSED
Definition assert.h:118
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:59
#define BOTAN_ASSERT_EQUAL(expr1, expr2, assertion_made)
Definition assert.h:68
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:29
#define BOTAN_ASSERT(expr, assertion_made)
Definition assert.h:50
KEX_to_KEM_Adapter_PrivateKey(std::unique_ptr< PK_Key_Agreement_Key > private_key)
std::unique_ptr< PK_Ops::KEM_Decryption > create_kem_decryption_op(RandomNumberGenerator &rng, std::string_view kdf, std::string_view provider="base") const override
bool check_key(RandomNumberGenerator &rng, bool strong) const override
secure_vector< uint8_t > private_key_bits() const override
std::unique_ptr< Public_Key > public_key() const override
bool supports_operation(PublicKeyOperation op) const override
std::unique_ptr< PK_Ops::KEM_Encryption > create_kem_encryption_op(std::string_view kdf, std::string_view provider="base") const override
bool check_key(RandomNumberGenerator &rng, bool strong) const override
std::vector< uint8_t > public_key_bits() const override
AlgorithmIdentifier algorithm_identifier() const override
std::unique_ptr< Private_Key > generate_another(RandomNumberGenerator &rng) const final
KEX_to_KEM_Adapter_PublicKey(std::unique_ptr< Public_Key > public_key)
std::vector< uint8_t > raw_public_key_bits() const override
int(* final)(unsigned char *, CTX *)
PublicKeyOperation
Definition pk_keys.h:45
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:61