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

#include <hybrid_kem_ops.h>

Inheritance diagram for Botan::KEM_Decryption_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_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) final
	KEM_Decryption_with_Combiner (const std::vector< std::unique_ptr< Private_Key > > &private_keys, RandomNumberGenerator &rng, std::string_view provider)
virtual size_t	shared_key_length (size_t desired_shared_key_len) const =0

Protected Member Functions
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_Decryptor > &	decryptors ()
const std::vector< PK_KEM_Decryptor > &	decryptors () const
virtual std::vector< std::vector< uint8_t > >	split_ciphertexts (std::span< const uint8_t > concat_ciphertext)
	Defines how the individual ciphertexts are extracted from the combined ciphertext.

Detailed Description

Abstract interface for a KEM decryption operation for KEM combiners.

Multiple private keys are used to decapsulate shared secrets from a combined ciphertext (concatenated in most cases). 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 91 of file hybrid_kem_ops.h.

Constructor & Destructor Documentation

◆ KEM_Decryption_with_Combiner()

Botan::KEM_Decryption_with_Combiner::KEM_Decryption_with_Combiner	(	const std::vector< std::unique_ptr< Private_Key > > &	private_keys,
		RandomNumberGenerator &	rng,
		std::string_view	provider )

Definition at line 65 of file hybrid_kem_ops.cpp.

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

Member Function Documentation

◆ combine_shared_secrets()

virtual void Botan::KEM_Decryption_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	the list of encapsulated shared secrets
desired_shared_key_len	the desired shared key length
salt	the salt (input of kem_decrypt)

Referenced by kem_decrypt().

◆ decryptors() [1/2]

std::vector< PK_KEM_Decryptor > & Botan::KEM_Decryption_with_Combiner::decryptors ( )

inlineprotected

Definition at line 130 of file hybrid_kem_ops.h.

130{ return m_decryptors; }

◆ decryptors() [2/2]

const std::vector< PK_KEM_Decryptor > & Botan::KEM_Decryption_with_Combiner::decryptors ( ) const

inlineprotected

Definition at line 132 of file hybrid_kem_ops.h.

132{ return m_decryptors; }

◆ encapsulated_key_length()

size_t Botan::KEM_Decryption_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_Decryption.

Definition at line 103 of file hybrid_kem_ops.h.

103{ return m_encapsulated_key_length; }

Referenced by kem_decrypt(), and split_ciphertexts().

◆ kem_decrypt()

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

finalvirtual

Implements Botan::PK_Ops::KEM_Decryption.

Definition at line 77 of file hybrid_kem_ops.cpp.

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

References BOTAN_ARG_CHECK, BOTAN_ASSERT, combine_shared_secrets(), encapsulated_key_length(), Botan::PK_Ops::KEM_Decryption::shared_key_length(), and split_ciphertexts().

◆ shared_key_length()

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

pure virtualinherited

Implemented in Botan::PK_Ops::KEM_Decryption_with_KDF.

Referenced by Botan::KEM_Decryption_with_Combiner::kem_decrypt().

◆ split_ciphertexts()

std::vector< std::vector< uint8_t > > Botan::KEM_Decryption_with_Combiner::split_ciphertexts ( std::span< const uint8_t > concat_ciphertext )

protectedvirtual

Defines how the individual ciphertexts are extracted from the combined ciphertext.

The default implementation splits concatenated ciphertexts.

Parameters

concat_ciphertext The combined ciphertext

Returns: The individual ciphertexts

Definition at line 96 of file hybrid_kem_ops.cpp.

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

References BOTAN_ARG_CHECK, BOTAN_ASSERT_NOMSG, Botan::BufferSlicer::copy_as_vector(), Botan::BufferSlicer::empty(), and encapsulated_key_length().