Abstraction layer for hybrid KEMs

src/lib/pubkey/hybrid_kem/hybrid_kem.cpp

@@ -0,0 +1,93 @@
+/**
+* Abstraction for a combined KEM public and private key.
+*
+* (C) 2024 Jack Lloyd
+* 2024 Fabian Albert, René Meusel - Rohde & Schwarz Cybersecurity
+*
+* Botan is released under the Simplified BSD License (see license.txt)
+*/
+#include <botan/hybrid_kem.h>
+
+#include <botan/pk_algs.h>
+#include <botan/internal/fmt.h>
+#include <botan/internal/kex_to_kem_adapter.h>
+#include <botan/internal/pk_ops_impl.h>
+#include <botan/internal/stl_util.h>
+
+namespace Botan {
+
+Hybrid_PublicKey::Hybrid_PublicKey(std::vector<std::unique_ptr<Public_Key>> pks) : m_pks(std::move(pks)) {
+ BOTAN_ARG_CHECK(m_pks.size() >= 2, "List of public keys must include at least two keys");
+ BOTAN_ARG_CHECK(std::all_of(m_pks.begin(), m_pks.end(), [](const auto& pk) { return pk != nullptr; }),
+ "List of public keys contains a nullptr");
+ BOTAN_ARG_CHECK(
+ std::all_of(m_pks.begin(),
+ m_pks.end(),
+ [](const auto& pk) { return pk->supports_operation(PublicKeyOperation::KeyEncapsulation); }),
+ "Some provided public key is not compatible with this hybrid wrapper");
+ m_key_length = reduce(m_pks, size_t(0), [](size_t kl, const auto& key) { return std::max(kl, key->key_length()); });
+ m_estimated_strength =
+ reduce(m_pks, size_t(0), [](size_t es, const auto& key) { return std::max(es, key->estimated_strength()); });
+}
+
+bool Hybrid_PublicKey::check_key(RandomNumberGenerator& rng, bool strong) const {
+ return reduce(public_keys(), true, [&](bool ckr, const auto& key) { return ckr && key->check_key(rng, strong); });
+}
+
+std::vector<uint8_t> Hybrid_PublicKey::public_key_bits() const {
+ return reduce(public_keys(), std::vector<uint8_t>(), [](auto pkb, const auto& key) {
+ // Technically, this is not correct! `public_key_bits()` is meant to
+ // return a BER-encoded public key.
+ //
+ // TODO: Provide something like Public_Key::raw_public_key_bits() to
+ // reflect that difference.
+ return concat(pkb, key->public_key_bits());
+ });
+}
+
+bool Hybrid_PublicKey::supports_operation(PublicKeyOperation op) const {
+ return PublicKeyOperation::KeyEncapsulation == op;
+}
+
+std::vector<std::unique_ptr<Private_Key>> Hybrid_PublicKey::generate_other_sks_from_pks(
+ RandomNumberGenerator& rng) const {
+ std::vector<std::unique_ptr<Private_Key>> new_private_keys;
+ std::transform(
+ public_keys().begin(), public_keys().end(), std::back_inserter(new_private_keys), [&](const auto& public_key) {
+ return public_key->generate_another(rng);
+ });
+ return new_private_keys;
+}
+
+Hybrid_PrivateKey::Hybrid_PrivateKey(std::vector<std::unique_ptr<Private_Key>> private_keys) :
+ m_sks(std::move(private_keys)) {
+ BOTAN_ARG_CHECK(m_sks.size() >= 2, "List of secret keys must include at least two keys");
+ BOTAN_ARG_CHECK(std::all_of(m_sks.begin(), m_sks.end(), [](const auto& sk) { return sk != nullptr; }),
+ "List of secret keys contains a nullptr");
+ BOTAN_ARG_CHECK(
+ std::all_of(m_sks.begin(),
+ m_sks.end(),
+ [](const auto& sk) { return sk->supports_operation(PublicKeyOperation::KeyEncapsulation); }),
+ "Some provided secret key is not compatible with this hybrid wrapper");
+}
+
+secure_vector<uint8_t> Hybrid_PrivateKey::private_key_bits() const {
+ throw Not_Implemented("Hybrid private keys cannot be serialized");
+}
+
+bool Hybrid_PrivateKey::check_key(RandomNumberGenerator& rng, bool strong) const {
+ return reduce(private_keys(), true, [&](bool ckr, const auto& key) { return ckr && key->check_key(rng, strong); });
+}
+
+std::vector<std::unique_ptr<Public_Key>> Hybrid_PrivateKey::extract_public_keys(
+ const std::vector<std::unique_ptr<Private_Key>>& private_keys) {
+ std::vector<std::unique_ptr<Public_Key>> public_keys;
+ public_keys.reserve(private_keys.size());
+ for(const auto& private_key : private_keys) {
+ BOTAN_ARG_CHECK(private_key != nullptr, "List of private keys contains a nullptr");
+ public_keys.push_back(private_key->public_key());
+ }
+ return public_keys;
+}
+
+} // namespace Botan

src/lib/pubkey/hybrid_kem/hybrid_kem.h

@@ -0,0 +1,129 @@
+/**
+* Abstraction for a combined KEM public and private key.
+*
+* (C) 2024 Jack Lloyd
+* 2024 Fabian Albert, René Meusel - Rohde & Schwarz Cybersecurity
+*
+* Botan is released under the Simplified BSD License (see license.txt)
+*/
+
+#ifndef BOTAN_HYBRID_KEM_H_
+#define BOTAN_HYBRID_KEM_H_
+
+#include <botan/pk_algs.h>
+#include <botan/pk_keys.h>
+#include <botan/pubkey.h>
+
+#include <memory>
+#include <vector>
+
+namespace Botan {
+
+/**
+ * @brief Abstraction for a combined KEM public key.
+ *
+ * Two or more KEM public keys are combined into a single KEM public key. Derived classes
+ * must implement the abstract methods to provide the encryption operation, e.g. by
+ * specifying how encryption results are combined to the ciphertext and how a KEM combiner
+ * is applied to derive the shared secret using the individual shared secrets, ciphertexts,
+ * and other context information.
+ */
+class BOTAN_TEST_API Hybrid_PublicKey : public virtual Public_Key {
+ public:
+ /**
+ * @brief Constructor for a list of multiple KEM public keys.
+ *
+ * To use KEX algorithms use the KEX_to_KEM_Adapter_PublicKey.
+ * @param public_keys List of public keys to combine
+ */
+ explicit Hybrid_PublicKey(std::vector<std::unique_ptr<Public_Key>> public_keys);
+
+ Hybrid_PublicKey(Hybrid_PublicKey&&) = default;
+ Hybrid_PublicKey(const Hybrid_PublicKey&) = delete;
+ Hybrid_PublicKey& operator=(Hybrid_PublicKey&&) = default;
+ Hybrid_PublicKey& operator=(const Hybrid_PublicKey&) = delete;
+ ~Hybrid_PublicKey() override = default;
+
+ size_t estimated_strength() const override { return m_estimated_strength; }
+
+ size_t key_length() const override { return m_key_length; }
+
+ bool check_key(RandomNumberGenerator& rng, bool strong) const override;
+
+ std::vector<uint8_t> public_key_bits() const override;
+
+ bool supports_operation(PublicKeyOperation op) const override;
+
+ /// @returns the public keys combined in this hybrid key
+ const std::vector<std::unique_ptr<Public_Key>>& public_keys() const { return m_pks; }
+
+ protected:
+ // Default constructor used for virtual inheritance to prevent, that the derived class
+ // calls the constructor twice.
+ Hybrid_PublicKey() = default;
+
+ std::vector<std::unique_ptr<Public_Key>> copy_public_keys() const;
+
+ /**
+ * @brief Helper function for generate_another. Generate a new private key for each
+ * public key in this hybrid key.
+ */
+ std::vector<std::unique_ptr<Private_Key>> generate_other_sks_from_pks(RandomNumberGenerator& rng) const;
+
+ private:
+ std::vector<std::unique_ptr<Public_Key>> m_pks;
+
+ size_t m_key_length;
+ size_t m_estimated_strength;
+};
+
+BOTAN_DIAGNOSTIC_PUSH
+BOTAN_DIAGNOSTIC_IGNORE_INHERITED_VIA_DOMINANCE
+
+/**
+ * @brief Abstraction for a combined KEM private key.
+ *
+ * Two or more KEM private keys are combined into a single KEM private key. Derived classes
+ * must implement the abstract methods to provide the decryption operation, e.g. by
+ * specifying how a KEM combiner is applied to derive the shared secret using the
+ * individual shared secrets, ciphertexts, and other context information.
+ */
+class BOTAN_TEST_API Hybrid_PrivateKey : virtual public Private_Key {
+ public:
+ Hybrid_PrivateKey(const Hybrid_PrivateKey&) = delete;
+ Hybrid_PrivateKey& operator=(const Hybrid_PrivateKey&) = delete;
+
+ Hybrid_PrivateKey(Hybrid_PrivateKey&&) = default;
+ Hybrid_PrivateKey& operator=(Hybrid_PrivateKey&&) = default;
+
+ ~Hybrid_PrivateKey() override = default;
+
+ /**
+ * @brief Constructor for a list of multiple KEM private keys.
+ *
+ * To use KEX algorithms use the KEX_to_KEM_Adapter_PrivateKey.
+ * @param private_keys List of private keys to combine
+ */
+ Hybrid_PrivateKey(std::vector<std::unique_ptr<Private_Key>> private_keys);
+
+ /// Disabled by default
+ secure_vector<uint8_t> private_key_bits() const override;
+
+ /// @returns the private keys combined in this hybrid key
+ const std::vector<std::unique_ptr<Private_Key>>& private_keys() const { return m_sks; }
+
+ bool check_key(RandomNumberGenerator& rng, bool strong) const override;
+
+ protected:
+ static std::vector<std::unique_ptr<Public_Key>> extract_public_keys(
+ const std::vector<std::unique_ptr<Private_Key>>& private_keys);
+
+ private:
+ std::vector<std::unique_ptr<Private_Key>> m_sks;
+};
+
+BOTAN_DIAGNOSTIC_POP
+
+} // namespace Botan
+
+#endif

src/lib/pubkey/hybrid_kem/hybrid_kem_ops.cpp

@@ -0,0 +1,101 @@
+#include <botan/internal/hybrid_kem_ops.h>
+
+#include <botan/internal/stl_util.h>
+
+namespace Botan {
+
+KEM_Encryption_with_Combiner::KEM_Encryption_with_Combiner(const std::vector<std::unique_ptr<Public_Key>>& public_keys,
+ std::string_view provider) :
+ m_encapsulated_key_length(0) {
+ m_encryptors.reserve(public_keys.size());
+ for(const auto& pk : public_keys) {
+ const auto& newenc = m_encryptors.emplace_back(*pk, "Raw", provider);
+ m_encapsulated_key_length += newenc.encapsulated_key_length();
+ }
+}
+
+void KEM_Encryption_with_Combiner::kem_encrypt(std::span<uint8_t> out_encapsulated_key,
+ std::span<uint8_t> out_shared_key,
+ RandomNumberGenerator& rng,
+ size_t desired_shared_key_len,
+ std::span<const uint8_t> salt) {
+ BOTAN_ARG_CHECK(out_encapsulated_key.size() == encapsulated_key_length(),
+ "Encapsulated key output buffer has wrong size");
+ BOTAN_ARG_CHECK(out_shared_key.size() == shared_key_length(desired_shared_key_len),
+ "Shared key output buffer has wrong size");
+
+ std::vector<secure_vector<uint8_t>> shared_secrets;
+ shared_secrets.reserve(m_encryptors.size());
+
+ std::vector<std::vector<uint8_t>> ciphertexts;
+ ciphertexts.reserve(m_encryptors.size());
+
+ for(auto& encryptor : m_encryptors) {
+ auto [ct, ss] = KEM_Encapsulation::destructure(encryptor.encrypt(rng, 0 /* no KDF */));
+ shared_secrets.push_back(std::move(ss));
+ ciphertexts.push_back(std::move(ct));
+ }
+ combine_ciphertexts(out_encapsulated_key, ciphertexts, salt);
+ combine_shared_secrets(out_shared_key, shared_secrets, ciphertexts, desired_shared_key_len, salt);
+}
+
+void KEM_Encryption_with_Combiner::combine_ciphertexts(std::span<uint8_t> out_ciphertext,
+ const std::vector<std::vector<uint8_t>>& ciphertexts,
+ std::span<const uint8_t> salt) {
+ BOTAN_ARG_CHECK(salt.empty(), "Salt not supported by this KEM");
+ BOTAN_ARG_CHECK(ciphertexts.size() == m_encryptors.size(), "Invalid number of ciphertexts");
+ BOTAN_ARG_CHECK(out_ciphertext.size() == encapsulated_key_length(), "Invalid output buffer size");
+ BufferStuffer ct_stuffer(out_ciphertext);
+ for(size_t idx = 0; idx < ciphertexts.size(); idx++) {
+ BOTAN_ARG_CHECK(ciphertexts.at(idx).size() == m_encryptors.at(idx).encapsulated_key_length(),
+ "Invalid ciphertext length");
+ ct_stuffer.append(ciphertexts.at(idx));
+ }
+ BOTAN_ASSERT_NOMSG(ct_stuffer.full());
+}
+
+KEM_Decryption_with_Combiner::KEM_Decryption_with_Combiner(
+ const std::vector<std::unique_ptr<Private_Key>>& private_keys,
+ RandomNumberGenerator& rng,
+ std::string_view provider) :
+ m_encapsulated_key_length(0) {
+ m_decryptors.reserve(private_keys.size());
+ for(const auto& sk : private_keys) {
+ const auto& newenc = m_decryptors.emplace_back(*sk, rng, "Raw", provider);
+ m_encapsulated_key_length += newenc.encapsulated_key_length();
+ }
+}
+
+void KEM_Decryption_with_Combiner::kem_decrypt(std::span<uint8_t> out_shared_key,
+ std::span<const uint8_t> encapsulated_key,
+ size_t desired_shared_key_len,
+ std::span<const uint8_t> salt) {
+ BOTAN_ARG_CHECK(encapsulated_key.size() == encapsulated_key_length(), "Invalid encapsulated key length");
+ BOTAN_ARG_CHECK(out_shared_key.size() == shared_key_length(desired_shared_key_len), "Invalid output buffer size");
+
+ std::vector<secure_vector<uint8_t>> shared_secrets;
+ shared_secrets.reserve(m_decryptors.size());
+ auto ciphertexts = split_ciphertexts(encapsulated_key);
+ BOTAN_ASSERT(ciphertexts.size() == m_decryptors.size(), "Correct number of ciphertexts");
+
+ for(size_t idx = 0; idx < m_decryptors.size(); idx++) {
+ shared_secrets.push_back(m_decryptors.at(idx).decrypt(ciphertexts.at(idx), 0 /* no KDF */));
+ }
+
+ combine_shared_secrets(out_shared_key, shared_secrets, ciphertexts, desired_shared_key_len, salt);
+}
+
+std::vector<std::vector<uint8_t>> KEM_Decryption_with_Combiner::split_ciphertexts(
+ std::span<const uint8_t> concat_ciphertext) {
+ BOTAN_ARG_CHECK(concat_ciphertext.size() == encapsulated_key_length(), "Wrong ciphertext length");
+ std::vector<std::vector<uint8_t>> ciphertexts;
+ ciphertexts.reserve(m_decryptors.size());
+ BufferSlicer ct_slicer(concat_ciphertext);
+ for(const auto& decryptor : m_decryptors) {
+ ciphertexts.push_back(ct_slicer.copy_as_vector(decryptor.encapsulated_key_length()));
+ }
+ BOTAN_ASSERT_NOMSG(ct_slicer.empty());
+ return ciphertexts;
+}
+
+} // namespace Botan