Botan 3.14.1
Crypto and TLS for C&
Botan::PK_KEM_Encryptor Class Referencefinal

#include <pubkey.h>

Public Member Functions

size_t encapsulated_key_length () const
KEM_Encapsulation encrypt (RandomNumberGenerator &rng, size_t desired_shared_key_len=32, std::span< const uint8_t > salt={})
void encrypt (secure_vector< uint8_t > &out_encapsulated_key, secure_vector< uint8_t > &out_shared_key, RandomNumberGenerator &rng, size_t desired_shared_key_len=32, std::span< const uint8_t > salt={})
void encrypt (secure_vector< uint8_t > &out_encapsulated_key, secure_vector< uint8_t > &out_shared_key, size_t desired_shared_key_len, RandomNumberGenerator &rng, const uint8_t salt[], size_t salt_len)
void encrypt (secure_vector< uint8_t > &out_encapsulated_key, secure_vector< uint8_t > &out_shared_key, size_t desired_shared_key_len, RandomNumberGenerator &rng, std::span< const uint8_t > salt={})
void encrypt (std::span< uint8_t > out_encapsulated_key, std::span< uint8_t > out_shared_key, RandomNumberGenerator &rng, size_t desired_shared_key_len=32, std::span< const uint8_t > salt={})
PK_KEM_Encryptor & operator= (const PK_KEM_Encryptor &)=delete
PK_KEM_Encryptor & operator= (PK_KEM_Encryptor &&) noexcept
 PK_KEM_Encryptor (const PK_KEM_Encryptor &)=delete
 PK_KEM_Encryptor (const Public_Key &key, const PK_KEM_Options &options)
 PK_KEM_Encryptor (const Public_Key &key, RandomNumberGenerator &rng, std::string_view kem_param="", std::string_view provider="")
BOTAN_FUTURE_EXPLICIT PK_KEM_Encryptor (const Public_Key &key, std::string_view kem_param="", std::string_view provider="")
 PK_KEM_Encryptor (PK_KEM_Encryptor &&) noexcept
size_t shared_key_length (size_t desired_shared_key_len) const
 ~PK_KEM_Encryptor ()

Detailed Description

Public Key Key Encapsulation Mechanism Encryption.

Definition at line 673 of file pubkey.h.

Constructor & Destructor Documentation

◆ PK_KEM_Encryptor() [1/5]

Botan::PK_KEM_Encryptor::PK_KEM_Encryptor ( const Public_Key & key,
const PK_KEM_Options & options )

Construct an instance.

Parameters
keythe key to encrypt to
optionscontrols the behavior of the KEM, eg which KDF to use

Definition at line 182 of file pubkey.cpp.

182 {
183 const PK_KEM_Options_Reader reader(options);
184
185 m_op = key._create_kem_encryption_op(reader);
186 if(!m_op) {
187 throw Invalid_Argument(fmt("Key type {} does not support KEM encryption", key.algo_name()));
188 }
189
190 reader.throw_if_unexamined(key.algo_name());
191}
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

References Botan::Public_Key::_create_kem_encryption_op(), Botan::Asymmetric_Key::algo_name(), and Botan::fmt().

Referenced by operator=(), operator=(), PK_KEM_Encryptor(), PK_KEM_Encryptor(), PK_KEM_Encryptor(), PK_KEM_Encryptor(), and shared_key_length().

◆ PK_KEM_Encryptor() [2/5]

Botan::PK_KEM_Encryptor::PK_KEM_Encryptor ( const Public_Key & key,
std::string_view kem_param = "",
std::string_view provider = "" )

Construct an instance.

Parameters
keythe key to encrypt to
kem_paramadditional KEM parameters
providerthe provider to use

Definition at line 179 of file pubkey.cpp.

179 :
180 PK_KEM_Encryptor(key, parse_legacy_kem_options(param).with_provider(provider)) {}
PK_KEM_Encryptor(const Public_Key &key, const PK_KEM_Options &options)
Definition pubkey.cpp:182
PK_KEM_Options parse_legacy_kem_options(std::string_view params)

References Botan::parse_legacy_kem_options(), and PK_KEM_Encryptor().

◆ PK_KEM_Encryptor() [3/5]

Botan::PK_KEM_Encryptor::PK_KEM_Encryptor ( const Public_Key & key,
RandomNumberGenerator & rng,
std::string_view kem_param = "",
std::string_view provider = "" )

Construct an instance.

Parameters
keythe key to encrypt to
Random Number Generatorsa RNG object which must outlive this operation object
kem_paramadditional KEM parameters
providerthe provider to use

Definition at line 193 of file pubkey.cpp.

196 :
197 PK_KEM_Encryptor(key, kem_param, provider) {
198 BOTAN_UNUSED(rng);
199}
#define BOTAN_UNUSED
Definition assert.h:151

References BOTAN_UNUSED, and PK_KEM_Encryptor().

◆ ~PK_KEM_Encryptor()

Botan::PK_KEM_Encryptor::~PK_KEM_Encryptor ( )
default

◆ PK_KEM_Encryptor() [4/5]

Botan::PK_KEM_Encryptor::PK_KEM_Encryptor ( const PK_KEM_Encryptor & )
delete

References PK_KEM_Encryptor().

◆ PK_KEM_Encryptor() [5/5]

Botan::PK_KEM_Encryptor::PK_KEM_Encryptor ( PK_KEM_Encryptor && )
defaultnoexcept

References PK_KEM_Encryptor().

Member Function Documentation

◆ encapsulated_key_length()

size_t Botan::PK_KEM_Encryptor::encapsulated_key_length ( ) const

Return the length in bytes of encapsulated keys returned by this KEM

Definition at line 210 of file pubkey.cpp.

210 {
211 return m_op->encapsulated_key_length();
212}

Referenced by encrypt(), and operator=().

◆ encrypt() [1/5]

KEM_Encapsulation Botan::PK_KEM_Encryptor::encrypt ( RandomNumberGenerator & rng,
size_t desired_shared_key_len = 32,
std::span< const uint8_t > salt = {} )
inline

Generate a shared key for data encryption.

Parameters
Random Number Generatorsthe RNG to use
desired_shared_key_lendesired size of the shared key in bytes for the KDF (ignored if no KDF is used)
salta salt value used in the KDF (ignored if no KDF is used)
Returns
a struct with both the shared secret and its encapsulation

Definition at line 745 of file pubkey.h.

747 {}) {
748 std::vector<uint8_t> encapsulated_shared_key(encapsulated_key_length());
749 secure_vector<uint8_t> shared_key(shared_key_length(desired_shared_key_len));
750
751 encrypt(std::span{encapsulated_shared_key}, std::span{shared_key}, rng, desired_shared_key_len, salt);
752 return KEM_Encapsulation(std::move(encapsulated_shared_key), std::move(shared_key));
753 }
KEM_Encapsulation encrypt(RandomNumberGenerator &rng, size_t desired_shared_key_len=32, std::span< const uint8_t > salt={})
Definition pubkey.h:745
size_t shared_key_length(size_t desired_shared_key_len) const
Definition pubkey.cpp:206
size_t encapsulated_key_length() const
Definition pubkey.cpp:210
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128

References encrypt().

Referenced by Botan::FrodoKEM_PrivateKey::check_key(), Botan::Kyber_PrivateKey::check_key(), encrypt(), encrypt(), encrypt(), and Botan::TLS::Callbacks::tls_kem_encapsulate().

◆ encrypt() [2/5]

void Botan::PK_KEM_Encryptor::encrypt ( secure_vector< uint8_t > & out_encapsulated_key,
secure_vector< uint8_t > & out_shared_key,
RandomNumberGenerator & rng,
size_t desired_shared_key_len = 32,
std::span< const uint8_t > salt = {} )
inline

Generate a shared key for data encryption.

Parameters
out_encapsulated_keythe generated encapsulated key
out_shared_keythe generated shared key
Random Number Generatorsthe RNG to use
desired_shared_key_lendesired size of the shared key in bytes (ignored if no KDF is used)
salta salt value used in the KDF (ignored if no KDF is used)

Definition at line 765 of file pubkey.h.

769 {}) {
770 out_encapsulated_key.resize(encapsulated_key_length());
771 out_shared_key.resize(shared_key_length(desired_shared_key_len));
772 encrypt(std::span{out_encapsulated_key}, std::span{out_shared_key}, rng, desired_shared_key_len, salt);
773 }

◆ encrypt() [3/5]

void Botan::PK_KEM_Encryptor::encrypt ( secure_vector< uint8_t > & out_encapsulated_key,
secure_vector< uint8_t > & out_shared_key,
size_t desired_shared_key_len,
RandomNumberGenerator & rng,
const uint8_t salt[],
size_t salt_len )
inline

Definition at line 792 of file pubkey.h.

797 {
798 this->encrypt(out_encapsulated_key, out_shared_key, rng, desired_shared_key_len, {salt, salt_len});
799 }

References encrypt().

◆ encrypt() [4/5]

void Botan::PK_KEM_Encryptor::encrypt ( secure_vector< uint8_t > & out_encapsulated_key,
secure_vector< uint8_t > & out_shared_key,
size_t desired_shared_key_len,
RandomNumberGenerator & rng,
std::span< const uint8_t > salt = {} )
inline

Definition at line 802 of file pubkey.h.

806 {}) {
807 out_encapsulated_key.resize(encapsulated_key_length());
808 out_shared_key.resize(shared_key_length(desired_shared_key_len));
809 encrypt(out_encapsulated_key, out_shared_key, rng, desired_shared_key_len, salt);
810 }

References encrypt().

◆ encrypt() [5/5]

void Botan::PK_KEM_Encryptor::encrypt ( std::span< uint8_t > out_encapsulated_key,
std::span< uint8_t > out_shared_key,
RandomNumberGenerator & rng,
size_t desired_shared_key_len = 32,
std::span< const uint8_t > salt = {} )

Generate a shared key for data encryption.

Parameters
out_encapsulated_keythe generated encapsulated key
out_shared_keythe generated shared key
Random Number Generatorsthe RNG to use
desired_shared_key_lendesired size of the shared key in bytes (ignored if no KDF is used)
salta salt value used in the KDF (ignored if no KDF is used)

Definition at line 214 of file pubkey.cpp.

218 {
219 BOTAN_ARG_CHECK(out_encapsulated_key.size() == encapsulated_key_length(), "not enough space for encapsulated key");
220 BOTAN_ARG_CHECK(out_shared_key.size() == shared_key_length(desired_shared_key_len),
221 "not enough space for shared key");
222 m_op->kem_encrypt(out_encapsulated_key, out_shared_key, rng, desired_shared_key_len, salt);
223}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33

References BOTAN_ARG_CHECK, encapsulated_key_length(), and shared_key_length().

◆ operator=() [1/2]

PK_KEM_Encryptor & Botan::PK_KEM_Encryptor::operator= ( const PK_KEM_Encryptor & )
delete

References PK_KEM_Encryptor().

◆ operator=() [2/2]

PK_KEM_Encryptor & Botan::PK_KEM_Encryptor::operator= ( PK_KEM_Encryptor && )
defaultnoexcept

◆ shared_key_length()

size_t Botan::PK_KEM_Encryptor::shared_key_length ( size_t desired_shared_key_len) const

Return the length of the shared key returned by this KEM

If this KEM was used with a KDF, then it will always return exactly the desired key length, because the output of the KEM will be hashed by the KDF.

However if the KEM was used without a KDF (with_raw_shared_key, or the legacy "Raw" kdf string), to request the algorithmic output of the KEM directly, then the desired key length will be ignored and a bytestring that depends on the algorithm is returned

Parameters
desired_shared_key_lenis the requested length

Definition at line 206 of file pubkey.cpp.

206 {
207 return m_op->shared_key_length(desired_shared_key_len);
208}

References PK_KEM_Encryptor(), and shared_key_length().

Referenced by encrypt(), operator=(), and shared_key_length().


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