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

#include <dlies.h>

Inheritance diagram for Botan::DLIES_Decryptor:
Botan::PK_Decryptor

Public Member Functions

secure_vector< uint8_t > decrypt (const uint8_t in[], size_t length) const
secure_vector< uint8_t > decrypt (std::span< const uint8_t > in) const
secure_vector< uint8_t > decrypt_or_random (const uint8_t in[], size_t length, size_t expected_pt_len, RandomNumberGenerator &rng) const
secure_vector< uint8_t > decrypt_or_random (const uint8_t in[], size_t length, size_t expected_pt_len, RandomNumberGenerator &rng, const uint8_t required_content_bytes[], const uint8_t required_content_offsets[], size_t required_contents) const
 DLIES_Decryptor (const DH_PrivateKey &own_priv_key, RandomNumberGenerator &rng, std::unique_ptr< KDF > kdf, std::unique_ptr< Cipher_Mode > cipher, size_t cipher_key_len, std::unique_ptr< MessageAuthenticationCode > mac, size_t mac_key_len=20)
 DLIES_Decryptor (const DH_PrivateKey &own_priv_key, RandomNumberGenerator &rng, std::unique_ptr< KDF > kdf, std::unique_ptr< MessageAuthenticationCode > mac, size_t mac_key_len=20)
void set_initialization_vector (const InitializationVector &iv)

Detailed Description

DLIES Decryption

DLIES support is deprecated prefer HPKE in new systems

Definition at line 108 of file dlies.h.

Constructor & Destructor Documentation

◆ DLIES_Decryptor() [1/2]

Botan::DLIES_Decryptor::DLIES_Decryptor ( const DH_PrivateKey & own_priv_key,
RandomNumberGenerator & rng,
std::unique_ptr< KDF > kdf,
std::unique_ptr< MessageAuthenticationCode > mac,
size_t mac_key_len = 20 )

Stream mode: use KDF to provide a stream of bytes to xor with the message

Parameters
own_priv_keyown (ephemeral) DH private key
Random Number Generatorsthe RNG to use
Key Derivation Functionsthe KDF that should be used
Message Authentication Codesthe MAC function that should be used
mac_key_lenkey length of the MAC function. Default = 20 bytes

input = (ephemeral) public key + ciphertext + tag

Definition at line 115 of file dlies.cpp.

119 :
120 DLIES_Decryptor(own_priv_key, rng, std::move(kdf), nullptr, 0, std::move(mac), mac_key_length) {}
DLIES_Decryptor(const DH_PrivateKey &own_priv_key, RandomNumberGenerator &rng, std::unique_ptr< KDF > kdf, std::unique_ptr< MessageAuthenticationCode > mac, size_t mac_key_len=20)
Definition dlies.cpp:115

References DLIES_Decryptor().

Referenced by DLIES_Decryptor().

◆ DLIES_Decryptor() [2/2]

Botan::DLIES_Decryptor::DLIES_Decryptor ( const DH_PrivateKey & own_priv_key,
RandomNumberGenerator & rng,
std::unique_ptr< KDF > kdf,
std::unique_ptr< Cipher_Mode > cipher,
size_t cipher_key_len,
std::unique_ptr< MessageAuthenticationCode > mac,
size_t mac_key_len = 20 )

Block cipher mode

Parameters
own_priv_keyown (ephemeral) DH private key
Random Number Generatorsthe RNG to use
Key Derivation Functionsthe KDF that should be used
cipherthe block cipher that should be used
cipher_key_lenthe key length of the block cipher
Message Authentication Codesthe MAC function that should be used
mac_key_lenkey length of the MAC function. Default = 20 bytes

input = (ephemeral) public key + ciphertext + tag

Definition at line 97 of file dlies.cpp.

103 :
104 m_pub_key_size(own_priv_key.public_value().size()),
105 m_ka(own_priv_key, rng, PK_Key_Agreement_Options().with_raw_shared_key()),
106 m_kdf(std::move(kdf)),
107 m_cipher(std::move(cipher)),
108 m_cipher_key_len(cipher_key_len),
109 m_mac(std::move(mac)),
110 m_mac_keylen(mac_key_length) {
113}
#define BOTAN_ASSERT_NONNULL(ptr)
Definition assert.h:121

References BOTAN_ASSERT_NONNULL.

Member Function Documentation

◆ decrypt() [1/2]

secure_vector< uint8_t > Botan::PK_Decryptor::decrypt ( const uint8_t in[],
size_t length ) const
inherited

Decrypt a ciphertext, throwing an exception if the input seems to be invalid (eg due to an accidental or malicious error in the ciphertext).

Parameters
inthe ciphertext as a byte array
lengththe length of the above byte array
Returns
decrypted message

Definition at line 24 of file pubkey.cpp.

24 {
26
27 uint8_t valid_mask = 0;
28 const size_t ptext_len = do_decrypt(valid_mask, ptext, {in, length});
29
30 // This function reveals whether decryption succeeded, and the length of the plaintext
31 CT::unpoison_all(valid_mask, ptext_len, ptext);
32
33 if(valid_mask == 0) {
34 throw Decoding_Error("Invalid public key ciphertext, cannot decrypt");
35 }
36
37 ptext.resize(ptext_len);
38 return ptext;
39}
virtual size_t plaintext_length(size_t ctext_len) const =0
constexpr void unpoison_all(const Ts &... ts)
Definition ct_utils.h:207
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128

References plaintext_length(), and Botan::CT::unpoison_all().

Referenced by Botan::KeyPair::encryption_consistency_check().

◆ decrypt() [2/2]

secure_vector< uint8_t > Botan::PK_Decryptor::decrypt ( std::span< const uint8_t > in) const
inlineinherited

Same as above, but taking a vector

Parameters
inthe ciphertext
Returns
decrypted message

Definition at line 96 of file pubkey.h.

96{ return decrypt(in.data(), in.size()); }
secure_vector< uint8_t > decrypt(const uint8_t in[], size_t length) const
Definition pubkey.cpp:24

References decrypt().

Referenced by decrypt().

◆ decrypt_or_random() [1/2]

secure_vector< uint8_t > Botan::PK_Decryptor::decrypt_or_random ( const uint8_t in[],
size_t length,
size_t expected_pt_len,
RandomNumberGenerator & rng ) const
inherited

Decrypt a ciphertext. If the ciphertext is invalid (eg due to invalid padding) or is not the expected length, instead returns a random string of the expected length. Use to avoid oracle attacks, especially against PKCS #1 v1.5 decryption.

Definition at line 98 of file pubkey.cpp.

101 {
102 return decrypt_or_random(in, length, expected_pt_len, rng, nullptr, nullptr, 0);
103}
secure_vector< uint8_t > decrypt_or_random(const uint8_t in[], size_t length, size_t expected_pt_len, RandomNumberGenerator &rng) const
Definition pubkey.cpp:98

References decrypt_or_random().

Referenced by Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), and decrypt_or_random().

◆ decrypt_or_random() [2/2]

secure_vector< uint8_t > Botan::PK_Decryptor::decrypt_or_random ( const uint8_t in[],
size_t length,
size_t expected_pt_len,
RandomNumberGenerator & rng,
const uint8_t required_content_bytes[],
const uint8_t required_content_offsets[],
size_t required_contents ) const
inherited

Decrypt a ciphertext. If the ciphertext is invalid (eg due to invalid padding) or is not the expected length, instead returns a random string of the expected length. Use to avoid oracle attacks, especially against PKCS #1 v1.5 decryption.

Additionally checks (also in const time) that: contents[required_content_offsets[i]] == required_content_bytes[i] for 0 <= i < required_contents

Used for example in TLS, which encodes the client version in the content bytes: if there is any timing variation the version check can be used as an oracle to recover the key.

Definition at line 41 of file pubkey.cpp.

47 {
48 const secure_vector<uint8_t> fake_pms = [&]() {
49 auto pms = rng.random_vec(expected_pt_len);
50
51 for(size_t i = 0; i != required_contents_length; ++i) {
52 const uint8_t exp = required_content_bytes[i];
53
54 /*
55 If an offset repeats we don't detect this and just return a PMS that satisfies
56 the last requested index. If the requested (idx,value) tuple is the same, that's
57 fine and just redundant. If they disagree, decryption will always fail, since the
58 same byte cannot possibly have two distinct values.
59 */
60 const uint8_t off = required_content_offsets[i];
61 BOTAN_ASSERT(off < expected_pt_len, "Offset in range of plaintext");
62 pms[off] = exp;
63 }
64
65 return pms;
66 }();
67
68 // Whether the ciphertext was valid, and the length of the plaintext, are secret
69 secure_vector<uint8_t> decoded(std::max(plaintext_length(length), expected_pt_len));
70
71 uint8_t decrypt_valid = 0;
72 const size_t decoded_len = do_decrypt(decrypt_valid, decoded, {in, length});
73
74 auto valid_mask = CT::Mask<uint8_t>::is_equal(decrypt_valid, 0xFF);
75 valid_mask &= CT::Mask<uint8_t>(CT::Mask<size_t>::is_equal(decoded_len, expected_pt_len));
76
77 decoded.resize(expected_pt_len);
78
79 for(size_t i = 0; i != required_contents_length; ++i) {
80 const uint8_t exp = required_content_bytes[i];
81
82 // We know off is in range because we already checked it when creating the fake premaster above
83 const uint8_t off = required_content_offsets[i];
84
85 const auto eq = CT::Mask<uint8_t>::is_equal(decoded[off], exp);
86
87 valid_mask &= eq;
88 }
89
90 // If valid_mask is false, assign fake pre master instead
91 valid_mask.select_n(decoded.data(), decoded.data(), fake_pms.data(), expected_pt_len);
92
93 // Any further secret handling of the output is up to the caller
94 CT::unpoison(decoded);
95 return decoded;
96}
#define BOTAN_ASSERT(expr, assertion_made)
Definition assert.h:69
static constexpr Mask< T > is_equal(T x, T y)
Definition ct_utils.h:447
constexpr void unpoison(const T *p, size_t n)
Definition ct_utils.h:67

References BOTAN_ASSERT, Botan::CT::Mask< T >::is_equal(), plaintext_length(), Botan::RandomNumberGenerator::random_vec(), and Botan::CT::unpoison().

◆ set_initialization_vector()

void Botan::DLIES_Decryptor::set_initialization_vector ( const InitializationVector & iv)
inline

Set the initialization vector for the data decryption method

If DLIES is being used with a cipher, a fresh IV must be provided for each message; it is not included in the serialized ciphertext and must be conveyed separately.

Definition at line 155 of file dlies.h.

155{ m_iv = iv; }

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