Botan::ECIES_Decryptor Class Reference

#include <ecies.h>

Inheritance diagram for Botan::ECIES_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 243 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 293 of file ecies.cpp.

                                                             :
      m_ka(key, ecies_params, false, rng), m_params(ecies_params), m_iv(), m_label() {
   // ISO 18033: "If v > 1 and CheckMode = 0, then we must have gcd(u, v) = 1." (v = index, u= order)
   if(!ecies_params.check_mode()) {
      const BigInt& cofactor = m_params.domain().get_cofactor();
      if(cofactor > 1 && gcd(cofactor, m_params.domain().get_order()) != 1) {
         throw Invalid_Argument("ECIES: gcd of cofactor and order must be 1 if check_mode is 0");
      }
   }
 
   m_mac = m_params.create_mac();
   m_cipher = m_params.create_cipher(Cipher_Dir::Decryption);
}

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]

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

                                                                                    {
   uint8_t valid_mask = 0;
 
   secure_vector<uint8_t> decoded = do_decrypt(valid_mask, in, length);
 
   if(valid_mask == 0) {
      throw Decoding_Error("Invalid public key ciphertext, cannot decrypt");
   }
 
   return decoded;
}

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

in	the ciphertext

Returns

decrypted message

Definition at line 96 of file pubkey.h.

{ return decrypt(in.data(), in.size()); }

References Botan::PK_Decryptor::decrypt().

Referenced by Botan::PK_Decryptor::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 79 of file pubkey.cpp.

                                                                                         {
   return decrypt_or_random(in, length, expected_pt_len, rng, nullptr, nullptr, 0);
}

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

                                                                                              {
   const secure_vector<uint8_t> fake_pms = rng.random_vec(expected_pt_len);
 
   uint8_t decrypt_valid = 0;
   secure_vector<uint8_t> decoded = do_decrypt(decrypt_valid, in, length);
 
   auto valid_mask = CT::Mask<uint8_t>::is_equal(decrypt_valid, 0xFF);
   valid_mask &= CT::Mask<uint8_t>(CT::Mask<size_t>::is_zero(decoded.size() ^ expected_pt_len));
 
   decoded.resize(expected_pt_len);
 
   for(size_t i = 0; i != required_contents_length; ++i) {
      /*
      These values are chosen by the application and for TLS are constants,
      so this early failure via assert is fine since we know 0,1 < 48
 
      If there is a protocol that has content checks on the key where
      the expected offsets are controllable by the attacker this could
      still leak.
 
      Alternately could always reduce the offset modulo the length?
      */
 
      const uint8_t exp = required_content_bytes[i];
      const uint8_t off = required_content_offsets[i];
 
      BOTAN_ASSERT(off < expected_pt_len, "Offset in range of plaintext");
 
      auto eq = CT::Mask<uint8_t>::is_equal(decoded[off], exp);
 
      valid_mask &= eq;
   }
 
   // If valid_mask is false, assign fake pre master instead
   valid_mask.select_n(decoded.data(), decoded.data(), fake_pms.data(), expected_pt_len);
 
   return decoded;
}

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

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

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

---

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

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