Botan 2.19.5 Crypto and TLS for C&

Public Member Functions | List of all members
Botan::ECIES_Decryptor Class Referencefinal

`#include <ecies.h>`

Inheritance diagram for Botan::ECIES_Decryptor:

## Public Member Functions
template<typename Alloc >
secure_vector< uint8_t > | decrypt (const std::vector< uint8_t, Alloc > &in) const
secure_vector< uint8_t > | decrypt (const uint8_t in[], size_t length) 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. More...
void | set_label (const std::string &label)
| Set the label which is appended to the input for the message authentication code. More...

## Detailed Description

ECIES Decryption according to ISO 18033-2

Definition at line 275 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_key | the private key which is used for the key agreement
  ecies_params | settings for ecies
  rng | the random generator to use

Definition at line 317 of file ecies.cpp.

319 :
320 m_ka(key, ecies_params, false, rng),
321 m_params(ecies_params),
322 m_iv(),
323 m_label()
324 {
325 // ISO 18033: "If v > 1 and CheckMode = 0, then we must have gcd(u, v) = 1." (v = index, u= order)
326 if(!ecies_params.check_mode())
327 {
328 const Botan::BigInt& cofactor = m_params.domain().get_cofactor();
329 if(cofactor > 1 && Botan::gcd(cofactor, m_params.domain().get_order()) != 1)
330 {
331 throw Invalid_Argument("ECIES: gcd of cofactor and order must be 1 if check_mode is 0");
332 }
333 }
334
335 m_mac = m_params.create_mac();
336 m_cipher = m_params.create_cipher(DECRYPTION);
337 }
Botan::BigInt
Definition: bigint.h:25
Botan::ECIES_KA_Params::domain
const EC_Group & domain() const
Definition: ecies.h:75
Botan::ECIES_System_Params::create_cipher
std::unique_ptr< Cipher_Mode > create_cipher(Botan::Cipher_Dir direction) const
creates an instance of the data encryption method
Definition: ecies.cpp:222
Botan::ECIES_System_Params::create_mac
std::unique_ptr< MessageAuthenticationCode > create_mac() const
creates an instance of the message authentication code
Definition: ecies.cpp:217
Botan::EC_Group::get_cofactor
const BigInt & get_cofactor() const
Definition: ec_group.cpp:527
Botan::EC_Group::get_order
const BigInt & get_order() const
Definition: ec_group.cpp:512
Botan::DECRYPTION
@ DECRYPTION
Definition: cipher_mode.h:23
Botan::gcd
BigInt gcd(const BigInt &a, const BigInt &b)
Definition: numthry.cpp:52

References Botan::ECIES_KA_Params::check_mode(), Botan::ECIES_System_Params::create_cipher(), Botan::ECIES_System_Params::create_mac(), Botan::DECRYPTION, Botan::ECIES_KA_Params::domain(), Botan::gcd(), Botan::EC_Group::get_cofactor(), and Botan::EC_Group::get_order().

## Member Function Documentation

## ◆ decrypt() [1/2]

template<typename Alloc >

secure_vector< uint8_t > Botan::PK_Decryptor::decrypt | ( | const std::vector< uint8_t, Alloc > & | in | ) | const
| inline inherited

Same as above, but taking a vector

Parameters

  in | the ciphertext

Returns
  decrypted message

Definition at line 104 of file pubkey.h.

105 {
106 return decrypt(in.data(), in.size());
107 }
Botan::PK_Decryptor::decrypt
secure_vector< uint8_t > decrypt(const uint8_t in[], size_t length) const
Definition: pubkey.cpp:17

References Botan::CryptoBox::decrypt().

## ◆ decrypt() [2/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

  in | the ciphertext as a byte array
  length | the length of the above byte array

Returns
  decrypted message

Definition at line 17 of file pubkey.cpp.

18 {
19 uint8_t valid_mask = 0;
20
21 secure_vector<uint8_t> decoded = do_decrypt(valid_mask, in, length);
22
23 if(valid_mask == 0)
24 throw Decoding_Error("Invalid public key ciphertext, cannot decrypt");
25
26 return decoded;
27 }

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

## ◆ 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 78 of file pubkey.cpp.

82 {
83 return decrypt_or_random(in, length, expected_pt_len, rng,
84 nullptr, nullptr, 0);
85 }
Botan::PK_Decryptor::decrypt_or_random
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:78

References Botan::PK_Decryptor::decrypt_or_random().

Referenced by Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), and Botan::PK_Decryptor::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 30 of file pubkey.cpp.

37 {
38 const secure_vector<uint8_t> fake_pms = rng.random_vec(expected_pt_len);
39
40 uint8_t decrypt_valid = 0;
41 secure_vector<uint8_t> decoded = do_decrypt(decrypt_valid, in, length);
42
43 auto valid_mask = CT::Mask<uint8_t>::is_equal(decrypt_valid, 0xFF);
44 valid_mask &= CT::Mask<uint8_t>(CT::Mask<size_t>::is_zero(decoded.size() ^ expected_pt_len));
45
46 decoded.resize(expected_pt_len);
47
48 for(size_t i = 0; i != required_contents_length; ++i)
49 {
50 /*
51 These values are chosen by the application and for TLS are constants,
52 so this early failure via assert is fine since we know 0,1 < 48
53
54 If there is a protocol that has content checks on the key where
55 the expected offsets are controllable by the attacker this could
56 still leak.
57
58 Alternately could always reduce the offset modulo the length?
59 */
60
61 const uint8_t exp = required_content_bytes[i];
62 const uint8_t off = required_content_offsets[i];
63
64 BOTAN_ASSERT(off < expected_pt_len, "Offset in range of plaintext");
65
66 auto eq = CT::Mask<uint8_t>::is_equal(decoded[off], exp);
67
68 valid_mask &= eq;
69 }
70
71 // If valid_mask is false, assign fake pre master instead
72 valid_mask.select_n(decoded.data(), decoded.data(), fake_pms.data(), expected_pt_len);
73
74 return decoded;
75 }
BOTAN_ASSERT
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:55
Botan::CT::Mask::is_equal
static Mask< T > is_equal(T x, T y)
Definition: ct_utils.h:149
Botan::CT::Mask::is_zero
static Mask< T > is_zero(T x)
Definition: ct_utils.h:141

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 288 of file ecies.h.

289 {
290 m_iv = iv;
291 }

## ◆ set_label()

void Botan::ECIES_Decryptor::set_label | ( | const std::string & | label | ) |
| inline

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

Definition at line 294 of file ecies.h.

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

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

- src/lib/pubkey/ecies/ecies.h
- src/lib/pubkey/ecies/ecies.cpp