Botan::PK_Decryptor Class Reference

#include <pubkey.h>

Inheritance diagram for 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
PK_Decryptor &	operator= (const PK_Decryptor &)=delete
PK_Decryptor &	operator= (PK_Decryptor &&) noexcept=default
	PK_Decryptor ()=default
	PK_Decryptor (const PK_Decryptor &)=delete
	PK_Decryptor (PK_Decryptor &&) noexcept=default
virtual size_t	plaintext_length (size_t ctext_len) const =0
virtual	~PK_Decryptor ()=default

Detailed Description

Public Key Decryptor

Definition at line 78 of file pubkey.h.

Constructor & Destructor Documentation

PK_Decryptor() [1/3]

Botan::PK_Decryptor::PK_Decryptor ( )

default

~PK_Decryptor()

virtual Botan::PK_Decryptor::~PK_Decryptor ( )

virtualdefault

PK_Decryptor() [2/3]

Botan::PK_Decryptor::PK_Decryptor ( const PK_Decryptor & )

delete

PK_Decryptor() [3/3]

Botan::PK_Decryptor::PK_Decryptor ( PK_Decryptor && )

defaultnoexcept

Member Function Documentation

decrypt() [1/2]

secure_vector< uint8_t > Botan::PK_Decryptor::decrypt	(	const uint8_t	in[],
		size_t	length ) const

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

inline

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

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

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

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

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.

                                                                                              {
   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().

operator=() [1/2]

PK_Decryptor & Botan::PK_Decryptor::operator= ( const PK_Decryptor & )

delete

operator=() [2/2]

PK_Decryptor & Botan::PK_Decryptor::operator= ( PK_Decryptor && )

defaultnoexcept

plaintext_length()

virtual size_t Botan::PK_Decryptor::plaintext_length ( size_t ctext_len ) const

pure virtual

Return an upper bound on the plaintext length for a particular ciphertext input length

Implemented in Botan::PK_Decryptor_EME.

---

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

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