Debian Codegraph @

src/lib/pubkey/kex_to_kem_adapter/kex_to_kem_adapter.cpp

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