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

#include <ecies.h>

Inheritance diagram for Botan::ECIES_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
 ECIES_Decryptor (const PK_Key_Agreement_Key &private_key, const ECIES_System_Params &ecies_params, RandomNumberGenerator &rng)
void set_initialization_vector (const InitializationVector &iv)
void set_label (std::string_view label)
 Set the label which is appended to the input for the message authentication code.

Detailed Description

ECIES Decryption according to ISO 18033-2

Warning
ECIES is a complicated and poorly specified scheme which, while standardized, in practice has significant interop difficulties. Prefer HPKE in new systems.

TODO(Botan4) remove derivation on PK_Decryptor and provide a direct API for decryption taking all relevant params, avoiding setters/implicit state

Definition at line 360 of file ecies.h.

Constructor & Destructor Documentation

◆ ECIES_Decryptor()

Botan::ECIES_Decryptor::ECIES_Decryptor ( const PK_Key_Agreement_Key & private_key,
const ECIES_System_Params & ecies_params,
RandomNumberGenerator & rng )
Parameters
private_keythe private key which is used for the key agreement
ecies_paramssettings for ecies
Random Number Generatorsthe random generator to use

Definition at line 365 of file ecies.cpp.

367 :
368 m_ka(key, ecies_params, false, rng), m_params(ecies_params) {
369 /*
370 ISO 18033: "If v > 1 and CheckMode = 0, then we must have gcd(u, v) = 1." (v = index, u= order)
371
372 We skip this check because even if CheckMode = 0 we actually do check that
373 the point is valid. In addition the check from ISO 18033 is pretty odd; u is
374 the _prime_ order subgroup, and v is the cofactor. For gcd(u, v) > 1 to occur
375 the cofactor would have to be a multiple of the group order, implying that
376 the overall group was at least the square of the group order. Such a curve
377 would also break our assumption that one can check for membership in the
378 prime order subgroup by multiplying by the group order and checking for the
379 identity.
380 */
381
382 m_mac = m_params.create_mac();
383 m_cipher = m_params.create_cipher(Cipher_Dir::Decryption);
384}

References Botan::Decryption.

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::ECIES_Decryptor::set_initialization_vector ( const InitializationVector & iv)
inline

Set the initialization vector for the data encryption method

A new IV must be provided for each message; it is not included in the serialized ciphertext and must be conveyed separately

Definition at line 375 of file ecies.h.

375{ m_iv = iv; }

◆ set_label()

void Botan::ECIES_Decryptor::set_label ( std::string_view label)
inline

Set the label which is appended to the input for the message authentication code.

Definition at line 378 of file ecies.h.

378{ m_label = std::vector<uint8_t>(label.begin(), label.end()); }

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