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

#include <pubkey.h>

Inheritance diagram for Botan::PK_Decryptor_EME:
Botan::PK_Decryptor

Public Member Functions

size_t ciphertext_length (size_t ptext_len) const override
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
PK_Decryptor_EME & operator= (const PK_Decryptor_EME &)=delete
PK_Decryptor_EME & operator= (PK_Decryptor_EME &&) noexcept
 PK_Decryptor_EME (const PK_Decryptor_EME &)=delete
 PK_Decryptor_EME (const Private_Key &key, RandomNumberGenerator &rng, const PK_Encryption_Options &options)
 PK_Decryptor_EME (const Private_Key &key, RandomNumberGenerator &rng, std::string_view padding, std::string_view provider="")
 PK_Decryptor_EME (PK_Decryptor_EME &&) noexcept
size_t plaintext_length (size_t ctext_len) const override
 ~PK_Decryptor_EME () override

Detailed Description

Decryption with a padding scheme.

This is typically only used with RSA

Definition at line 593 of file pubkey.h.

Constructor & Destructor Documentation

◆ PK_Decryptor_EME() [1/4]

Botan::PK_Decryptor_EME::PK_Decryptor_EME ( const Private_Key & key,
RandomNumberGenerator & rng,
const PK_Encryption_Options & options )

Construct an instance.

Parameters
keythe key to use inside the decryptor
Random Number Generatorsa RNG object which must outlive this operation object
optionscontrols the behavior of the decryption, eg which padding to use

Definition at line 147 of file pubkey.cpp.

149 {
150 const PK_Encryption_Options_Reader reader(options);
151
152 m_op = key._create_decryption_op(rng, reader);
153 if(!m_op) {
154 throw Invalid_Argument(fmt("Key type {} does not support decryption", key.algo_name()));
155 }
156
157 reader.throw_if_unexamined(key.algo_name());
158}
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

References Botan::Private_Key::_create_decryption_op(), Botan::Asymmetric_Key::algo_name(), and Botan::fmt().

Referenced by operator=(), operator=(), PK_Decryptor_EME(), PK_Decryptor_EME(), PK_Decryptor_EME(), and plaintext_length().

◆ PK_Decryptor_EME() [2/4]

Botan::PK_Decryptor_EME::PK_Decryptor_EME ( const Private_Key & key,
RandomNumberGenerator & rng,
std::string_view padding,
std::string_view provider = "" )

Construct an instance.

Parameters
keythe key to use inside the decryptor
Random Number Generatorsa RNG object which must outlive this operation object
paddingthe padding scheme to use
providerthe provider to use

Definition at line 141 of file pubkey.cpp.

144 :
145 PK_Decryptor_EME(key, rng, parse_legacy_enc_options(key, padding).with_provider(provider)) {}
PK_Decryptor_EME(const Private_Key &key, RandomNumberGenerator &rng, const PK_Encryption_Options &options)
Definition pubkey.cpp:147
PK_Encryption_Options parse_legacy_enc_options(const Public_Key &key, std::string_view params)

References Botan::parse_legacy_enc_options(), and PK_Decryptor_EME().

◆ ~PK_Decryptor_EME()

Botan::PK_Decryptor_EME::~PK_Decryptor_EME ( )
overridedefault

◆ PK_Decryptor_EME() [3/4]

Botan::PK_Decryptor_EME::PK_Decryptor_EME ( const PK_Decryptor_EME & )
delete

References PK_Decryptor_EME().

◆ PK_Decryptor_EME() [4/4]

Botan::PK_Decryptor_EME::PK_Decryptor_EME ( PK_Decryptor_EME && )
defaultnoexcept

References PK_Decryptor_EME().

Member Function Documentation

◆ ciphertext_length()

size_t Botan::PK_Decryptor_EME::ciphertext_length ( size_t ptext_len) const
overridevirtual

Return an upper bound on the ciphertext length for a particular plaintext input length.

Implements Botan::PK_Decryptor.

Definition at line 169 of file pubkey.cpp.

169 {
170 return m_op->ciphertext_length(ptext_len);
171}

◆ 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().

◆ operator=() [1/2]

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

References PK_Decryptor_EME().

◆ operator=() [2/2]

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

References PK_Decryptor_EME().

◆ plaintext_length()

size_t Botan::PK_Decryptor_EME::plaintext_length ( size_t ctext_len) const
overridevirtual

Return an upper bound on the plaintext length for a particular ciphertext input length

Implements Botan::PK_Decryptor.

Definition at line 165 of file pubkey.cpp.

165 {
166 return m_op->plaintext_length(ctext_len);
167}

References PK_Decryptor_EME(), and plaintext_length().

Referenced by plaintext_length().


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