| 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 |