Abstract interface for a KEM encryption operation for KEM combiners. More...

#include <hybrid_kem_ops.h>

Inheritance diagram for Botan::KEM_Encryption_with_Combiner:

Public Member Functions
size_t	encapsulated_key_length () const override
	The default implementation returns the sum of the encapsulated key lengths of the underlying KEMs.
void	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) final
	KEM_Encryption_with_Combiner (const std::vector< std::unique_ptr< Public_Key > > &public_keys, std::string_view provider)
virtual size_t	shared_key_length (size_t desired_shared_key_len) const =0

Protected Member Functions
virtual void	combine_ciphertexts (std::span< uint8_t > out_ciphertext, const std::vector< std::vector< uint8_t > > &ciphertexts, std::span< const uint8_t > salt)
	Defines how multiple ciphertexts are combined into a single ciphertext.
virtual void	combine_shared_secrets (std::span< uint8_t > out_shared_secret, const std::vector< secure_vector< uint8_t > > &shared_secrets, const std::vector< std::vector< uint8_t > > &ciphertexts, size_t desired_shared_key_len, std::span< const uint8_t > salt)=0
	Describes how the shared secrets are combined to derive the final shared secret.
std::vector< PK_KEM_Encryptor > &	encryptors ()
const std::vector< PK_KEM_Encryptor > &	encryptors () const

Detailed Description

Abstract interface for a KEM encryption operation for KEM combiners.

Multiple public keys are used to encapsulate shared secrets. These shared secrets (and maybe the ciphertexts and public keys) are combined using the KEM combiner to derive the final shared secret.

Definition at line 31 of file hybrid_kem_ops.h.

Constructor & Destructor Documentation

◆ KEM_Encryption_with_Combiner()

Botan::KEM_Encryption_with_Combiner::KEM_Encryption_with_Combiner	(	const std::vector< std::unique_ptr< Public_Key > > &	public_keys,
		std::string_view	provider )

Definition at line 15 of file hybrid_kem_ops.cpp.

                                                                                    :
      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();
   }
}

Member Function Documentation

◆ combine_ciphertexts()

void Botan::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 )

protectedvirtual

Defines how multiple ciphertexts are combined into a single ciphertext.

The default implementation concatenates the ciphertexts.

Parameters

out_ciphertext	The output buffer for the combined ciphertext
ciphertexts	The ciphertexts to combine
salt	The salt. In this default implementation the salt must be empty.

Definition at line 50 of file hybrid_kem_ops.cpp.

                                                                                    {
   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());
}

References Botan::BufferStuffer::append(), BOTAN_ARG_CHECK, BOTAN_ASSERT_NOMSG, encapsulated_key_length(), and Botan::BufferStuffer::full().

Referenced by kem_encrypt().

◆ combine_shared_secrets()

virtual void Botan::KEM_Encryption_with_Combiner::combine_shared_secrets	(	std::span< uint8_t >	out_shared_secret,
		const std::vector< secure_vector< uint8_t > > &	shared_secrets,
		const std::vector< std::vector< uint8_t > > &	ciphertexts,
		size_t	desired_shared_key_len,
		std::span< const uint8_t >	salt )

protectedpure virtual

Describes how the shared secrets are combined to derive the final shared secret.

Parameters

out_shared_secret	the output buffer for the shared secret
shared_secrets	a list of shared secrets coreesponding to the public keys
ciphertexts	a list of encapsulated shared secrets
desired_shared_key_len	the desired shared key length
salt	the salt (input of kem_encrypt)

Referenced by kem_encrypt().

◆ encapsulated_key_length()

size_t Botan::KEM_Encryption_with_Combiner::encapsulated_key_length ( ) const

inlineoverridevirtual

The default implementation returns the sum of the encapsulated key lengths of the underlying KEMs.

Implements Botan::PK_Ops::KEM_Encryption.

Definition at line 43 of file hybrid_kem_ops.h.

43{ return m_encapsulated_key_length; }

Referenced by combine_ciphertexts(), and kem_encrypt().

◆ encryptors() [1/2]

std::vector< PK_KEM_Encryptor > & Botan::KEM_Encryption_with_Combiner::encryptors ( )

inlineprotected

Definition at line 74 of file hybrid_kem_ops.h.

74{ return m_encryptors; }

◆ encryptors() [2/2]

const std::vector< PK_KEM_Encryptor > & Botan::KEM_Encryption_with_Combiner::encryptors ( ) const

inlineprotected

Definition at line 76 of file hybrid_kem_ops.h.

76{ return m_encryptors; }

◆ kem_encrypt()

void Botan::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 )

finalvirtual

Implements Botan::PK_Ops::KEM_Encryption.

Definition at line 25 of file hybrid_kem_ops.cpp.

                                                                            {
   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);
}

References BOTAN_ARG_CHECK, combine_ciphertexts(), combine_shared_secrets(), Botan::KEM_Encapsulation::destructure(), encapsulated_key_length(), and Botan::PK_Ops::KEM_Encryption::shared_key_length().

◆ shared_key_length()

virtual size_t Botan::PK_Ops::KEM_Encryption::shared_key_length ( size_t desired_shared_key_len ) const

pure virtualinherited

Implemented in Botan::PK_Ops::KEM_Encryption_with_KDF.

Referenced by Botan::KEM_Encryption_with_Combiner::kem_encrypt().

The documentation for this class was generated from the following files:

src/lib/pubkey/hybrid_kem/hybrid_kem_ops.h
src/lib/pubkey/hybrid_kem/hybrid_kem_ops.cpp

Public Member Functions

Protected Member Functions