Botan 3.14.1
Crypto and TLS for C&
Botan::PK_Decryptor Class Referenceabstract

#include <pubkey.h>

Inheritance diagram for Botan::PK_Decryptor:
Botan::DLIES_Decryptor Botan::ECIES_Decryptor Botan::PK_Decryptor_EME

Public Member Functions

virtual size_t ciphertext_length (size_t ptext_len) const =0
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 & operator= (const PK_Decryptor &)=delete
PK_Decryptor & operator= (PK_Decryptor &&) noexcept=default
 PK_Decryptor ()=default
 PK_Decryptor (const PK_Decryptor &)=delete
 PK_Decryptor (PK_Decryptor &&) noexcept=default
virtual size_t plaintext_length (size_t ctext_len) const =0
virtual ~PK_Decryptor ()=default

Detailed Description

Public Key Decryptor

Definition at line 78 of file pubkey.h.

Constructor & Destructor Documentation

◆ PK_Decryptor() [1/3]

Botan::PK_Decryptor::PK_Decryptor ( )
default

◆ ~PK_Decryptor()

virtual Botan::PK_Decryptor::~PK_Decryptor ( )
virtualdefault

◆ PK_Decryptor() [2/3]

Botan::PK_Decryptor::PK_Decryptor ( const PK_Decryptor & )
delete

References PK_Decryptor().

◆ PK_Decryptor() [3/3]

Botan::PK_Decryptor::PK_Decryptor ( PK_Decryptor && )
defaultnoexcept

References PK_Decryptor().

Member Function Documentation

◆ ciphertext_length()

virtual size_t Botan::PK_Decryptor::ciphertext_length ( size_t ptext_len) const
pure virtual

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

Implemented in Botan::PK_Decryptor_EME.

◆ decrypt() [1/2]

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

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
inline

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

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

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 & Botan::PK_Decryptor::operator= ( const PK_Decryptor & )
delete

References PK_Decryptor().

◆ operator=() [2/2]

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

References PK_Decryptor().

◆ plaintext_length()

virtual size_t Botan::PK_Decryptor::plaintext_length ( size_t ctext_len) const
pure virtual

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

Implemented in Botan::PK_Decryptor_EME.

Referenced by decrypt(), and decrypt_or_random().


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