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 276 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 343 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 20 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 102 of file pubkey.h.

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

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 81 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 33 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 289 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 295 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