Botan 3.9.0
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)
 Set the initialization vector for the data encryption method.
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

Definition at line 322 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
rngthe random generator to use

Definition at line 351 of file ecies.cpp.

353 :
354 m_ka(key, ecies_params, false, rng), m_params(ecies_params) {
355 /*
356 ISO 18033: "If v > 1 and CheckMode = 0, then we must have gcd(u, v) = 1." (v = index, u= order)
357
358 We skip this check because even if CheckMode = 0 we actually do check that
359 the point is valid. In addition the check from ISO 18033 is pretty odd; u is
360 the _prime_ order subgroup, and v is the cofactor. For gcd(u, v) > 1 to occur
361 the cofactor would have to be a multiple of the group order, implying that
362 the overall group was at least the square of the group order. Such a curve
363 would also break our assumption that one can check for membership in the
364 prime order subgroup by multiplying by the group order and checking for the
365 identity.
366 */
367
368 m_mac = m_params.create_mac();
369 m_cipher = m_params.create_cipher(Cipher_Dir::Decryption);
370}

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 23 of file pubkey.cpp.

23 {
24 uint8_t valid_mask = 0;
25
26 secure_vector<uint8_t> decoded = do_decrypt(valid_mask, in, length);
27
28 if(valid_mask == 0) {
29 throw Decoding_Error("Invalid public key ciphertext, cannot decrypt");
30 }
31
32 return decoded;
33}
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:69

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:23

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 87 of file pubkey.cpp.

90 {
91 return decrypt_or_random(in, length, expected_pt_len, rng, nullptr, nullptr, 0);
92}
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:87

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 35 of file pubkey.cpp.

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

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

◆ set_initialization_vector()

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

Set the initialization vector for the data encryption method.

Definition at line 334 of file ecies.h.

334{ 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 337 of file ecies.h.

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

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