Botan::GHASH Class Reference

#include <ghash.h>

Inheritance diagram for Botan::GHASH:

Public Member Functions
void	clear () override
void	final (std::span< uint8_t > out)
bool	has_keying_material () const override
Key_Length_Specification	key_spec () const override
size_t	maximum_keylength () const
size_t	minimum_keylength () const
std::string	name () const override
void	nonce_hash (std::span< uint8_t, GCM_BS > y0, std::span< const uint8_t > nonce)
	Hashing of non-default length nonce values for both GCM and GMAC use-cases.
std::string	provider () const
void	reset_associated_data ()
	Reset the AAD state without resetting the key (used in GMAC::final_result).
void	reset_state ()
void	set_associated_data (std::span< const uint8_t > ad)
	Monolithic setting of associated data usid in the GCM use-case.
void	set_key (const OctetString &key)
void	set_key (const uint8_t key[], size_t length)
void	set_key (std::span< const uint8_t > key)
void	start (std::span< const uint8_t > nonce)
void	update (std::span< const uint8_t > in)
void	update_associated_data (std::span< const uint8_t > ad)
	Incremental update of associated data used in the GMAC use-case.
bool	valid_keylength (size_t length) const

Protected Member Functions
void	assert_key_material_set () const
void	assert_key_material_set (bool predicate) const

Friends
class	Polyval
	Polyval reuses the GHASH tables and kernels for its non-CLMUL fallback.

Detailed Description

GCM's GHASH

Definition at line 19 of file ghash.h.

Member Function Documentation

assert_key_material_set() [1/2]

void Botan::SymmetricAlgorithm::assert_key_material_set ( ) const

inlineprotectedinherited

Throw Key_Not_Set unless a key has been set on this object

Definition at line 180 of file sym_algo.h.

{ assert_key_material_set(has_keying_material()); }

References assert_key_material_set(), and has_keying_material().

Referenced by assert_key_material_set(), Botan::Salsa20::cipher_bytes(), Botan::Lion::decrypt_n(), Botan::Lion::encrypt_n(), Botan::GHASH::final(), Botan::Polyval::final(), Botan::Salsa20::generate_keystream(), Botan::GHASH::nonce_hash(), Botan::GHASH::reset_associated_data(), Botan::ChaCha::seek(), Botan::CTR_BE::seek(), Botan::Salsa20::seek(), Botan::GHASH::set_associated_data(), Botan::OCB_Mode::set_associated_data_n(), Botan::Salsa20::set_iv_bytes(), Botan::GHASH::update(), Botan::Polyval::update(), Botan::GHASH::update_associated_data(), and Botan::Polyval::zero_pad().

assert_key_material_set() [2/2]

void Botan::SymmetricAlgorithm::assert_key_material_set ( bool predicate ) const

inlineprotectedinherited

Throw Key_Not_Set unless the predicate holds

Parameters

predicate

if false, a Key_Not_Set exception is thrown

Definition at line 186 of file sym_algo.h.

                                                         {
         if(!predicate) {
            throw_key_not_set_error();
         }
      }

clear()

void Botan::GHASH::clear ( )

overridevirtual

Reset the internal state. This includes not just the key, but any partial message that may have been in process.

Implements Botan::SymmetricAlgorithm.

Definition at line 239 of file ghash.cpp.

                  {
   zap(m_HM);
   zap(m_H_pow);
   m_H_ad = {0};
   m_ad_len = 0;
   this->reset_state();
}

References reset_state(), and Botan::zap().

final()

void Botan::GHASH::final

(

std::span< uint8_t >

out

)

Definition at line 215 of file ghash.cpp.

                                      {
   BOTAN_ARG_CHECK(!mac.empty() && mac.size() <= GCM_BS, "GHASH output length");
   BOTAN_STATE_CHECK(m_nonce);
   assert_key_material_set();
 
   ghash_zeropad(m_ghash);
   ghash_final_block(m_ghash, m_ad_len, m_text_len);
 
   xor_buf(mac, std::span{m_ghash}.first(mac.size()), std::span{*m_nonce}.first(mac.size()));
 
   secure_scrub_memory(m_ghash);
   m_text_len = 0;
   m_nonce.reset();
}

References Botan::SymmetricAlgorithm::assert_key_material_set(), BOTAN_ARG_CHECK, BOTAN_STATE_CHECK, Botan::secure_scrub_memory(), and Botan::xor_buf().

has_keying_material()

bool Botan::GHASH::has_keying_material ( ) const

overridevirtual

Test whether a key has been set on this object

Returns

true if a key has been set on this object

Implements Botan::SymmetricAlgorithm.

Definition at line 107 of file ghash.cpp.

                                      {
   return !m_HM.empty() || !m_H_pow.empty();
}

key_spec()

Key_Length_Specification Botan::GHASH::key_spec ( ) const

inlineoverridevirtual

Return the key lengths supported by this algorithm

Returns

object describing limits on key size

Implements Botan::SymmetricAlgorithm.

Definition at line 42 of file ghash.h.

{ return Key_Length_Specification(16); }

maximum_keylength()

size_t Botan::SymmetricAlgorithm::maximum_keylength ( ) const

inlineinherited

Return the largest acceptable key length

Returns

maximum allowed key length

Definition at line 130 of file sym_algo.h.

{ return key_spec().maximum_keylength(); }

References key_spec().

minimum_keylength()

size_t Botan::SymmetricAlgorithm::minimum_keylength ( ) const

inlineinherited

Return the smallest acceptable key length

Returns

minimum allowed key length

Definition at line 136 of file sym_algo.h.

{ return key_spec().minimum_keylength(); }

References key_spec().

name()

std::string Botan::GHASH::name ( ) const

inlineoverridevirtual

Return the name of this algorithm

Returns

the algorithm name

Implements Botan::SymmetricAlgorithm.

Definition at line 52 of file ghash.h.

{ return "GHASH"; }

nonce_hash()

void Botan::GHASH::nonce_hash	(	std::span< uint8_t, GCM_BS >	y0,
		std::span< const uint8_t >	nonce )

Hashing of non-default length nonce values for both GCM and GMAC use-cases.

Definition at line 230 of file ghash.cpp.

                                                                                {
   assert_key_material_set();
   BOTAN_STATE_CHECK(!m_nonce);
 
   ghash_update(y0, nonce);
   ghash_zeropad(y0);
   ghash_final_block(y0, 0, nonce.size());
}

References Botan::SymmetricAlgorithm::assert_key_material_set(), and BOTAN_STATE_CHECK.

provider()

std::string Botan::GHASH::provider

(

)

const

Definition at line 22 of file ghash.cpp.

                                {
#if defined(BOTAN_HAS_GHASH_AVX512_CLMUL)
   if(auto feat = CPUID::check(CPUID::Feature::AVX512_CLMUL)) {
      return *feat;
   }
#endif
 
#if defined(BOTAN_HAS_GHASH_CLMUL_CPU)
   if(auto feat = CPUID::check(CPUID::Feature::HW_CLMUL)) {
      return *feat;
   }
#endif
 
#if defined(BOTAN_HAS_GHASH_CLMUL_VPERM)
   if(auto feat = CPUID::check(CPUID::Feature::SIMD_4X32)) {
      return *feat;
   }
#endif
 
   return "base";
}

References Botan::CPUFeature::AVX512_CLMUL, Botan::CPUID::check(), Botan::CPUFeature::HW_CLMUL, and Botan::CPUFeature::SIMD_4X32.

reset_associated_data()

void Botan::GHASH::reset_associated_data

(

)

Reset the AAD state without resetting the key (used in GMAC::final_result).

Definition at line 188 of file ghash.cpp.

                                  {
   // This should only be called in GMAC context
   BOTAN_STATE_CHECK(m_text_len == 0);
   assert_key_material_set();
   m_H_ad = {0};
   m_ad_len = 0;
}

References Botan::SymmetricAlgorithm::assert_key_material_set(), and BOTAN_STATE_CHECK.

reset_state()

void Botan::GHASH::reset_state

(

)

Reset the per-message state (nonce/ghash/text-len/buffer) but preserve any associated data set via set_associated_data

Definition at line 247 of file ghash.cpp.

                        {
   secure_scrub_memory(m_ghash);
   if(m_nonce) {
      secure_scrub_memory(m_nonce.value());
      m_nonce.reset();
   }
   m_buffer.clear();
   m_text_len = 0;
}

References Botan::secure_scrub_memory().

Referenced by clear().

set_associated_data()

void Botan::GHASH::set_associated_data

(

std::span< const uint8_t >

ad

)

Monolithic setting of associated data usid in the GCM use-case.

Definition at line 178 of file ghash.cpp.

                                                            {
   BOTAN_STATE_CHECK(!m_nonce);
 
   assert_key_material_set();
   m_H_ad = {0};
   ghash_update(m_H_ad, input);
   ghash_zeropad(m_H_ad);
   m_ad_len = input.size();
}

References Botan::SymmetricAlgorithm::assert_key_material_set(), and BOTAN_STATE_CHECK.

set_key() [1/3]

void Botan::SymmetricAlgorithm::set_key ( const OctetString & key )

inherited

Set the symmetric key of this object.

Parameters

key	the SymmetricKey to be set.

Definition at line 14 of file sym_algo.cpp.

                                                       {
   set_key(std::span{key.begin(), key.length()});
}

References Botan::OctetString::begin(), Botan::OctetString::length(), and set_key().

Referenced by Botan::create_aes_row_generator(), Botan::Sodium::crypto_stream_salsa20(), Botan::Sodium::crypto_stream_salsa20_xor_ic(), Botan::Sodium::crypto_stream_xsalsa20(), Botan::Sodium::crypto_stream_xsalsa20_xor_ic(), Botan::FPE::fe1_decrypt(), Botan::FPE::fe1_encrypt(), Botan::Sphincs_Hash_Functions_Sha2::PRF_msg(), Botan::Sodium::randombytes_buf_deterministic(), Botan::TLS::TLS_NULL_HMAC_AEAD_Mode::reset(), and set_key().

set_key() [2/3]

void Botan::SymmetricAlgorithm::set_key ( const uint8_t key[], size_t length )

inlineinherited

Set the symmetric key of this object.

Parameters

key	the to be set as a byte array.
length	in bytes of key param

Definition at line 162 of file sym_algo.h.

{ set_key(std::span{key, length}); }

References set_key().

Referenced by set_key().

set_key() [3/3]

void Botan::SymmetricAlgorithm::set_key ( std::span< const uint8_t > key )

inherited

Set the symmetric key of this object.

Parameters

key	the contiguous byte range to be set.

Definition at line 22 of file sym_algo.cpp.

                                                           {
   if(!valid_keylength(key.size())) {
      throw Invalid_Key_Length(name(), key.size());
   }
   key_schedule(key);
}

References name(), and valid_keylength().

start()

void Botan::GHASH::start

(

std::span< const uint8_t >

nonce

)

Definition at line 169 of file ghash.cpp.

                                              {
   BOTAN_ARG_CHECK(nonce.size() == 16, "GHASH requires a 128-bit nonce");
   auto& n = m_nonce.emplace();
   copy_mem(n, nonce);
   copy_mem(m_ghash, m_H_ad);
   m_buffer.clear();
   m_text_len = 0;
}

References BOTAN_ARG_CHECK, and Botan::copy_mem().

update()

void Botan::GHASH::update

(

std::span< const uint8_t >

in

)

Definition at line 202 of file ghash.cpp.

                                               {
   assert_key_material_set();
   BOTAN_STATE_CHECK(m_nonce);
   ghash_update(m_ghash, input);
   m_text_len += input.size();
 
   // NIST SP 800-38D limits plaintext/ciphertext to 2^39 - 256 bits
   constexpr uint64_t GHASH_MAX_BYTES = (((static_cast<uint64_t>(1) << 39)) - 256) / 8;
   if(m_text_len > GHASH_MAX_BYTES) {
      throw Invalid_State("GCM message length limit exceeded");
   }
}

References Botan::SymmetricAlgorithm::assert_key_material_set(), and BOTAN_STATE_CHECK.

update_associated_data()

void Botan::GHASH::update_associated_data

(

std::span< const uint8_t >

ad

)

Incremental update of associated data used in the GMAC use-case.

Definition at line 196 of file ghash.cpp.

                                                            {
   assert_key_material_set();
   ghash_update(m_ghash, ad);
   m_ad_len += ad.size();
}

References Botan::SymmetricAlgorithm::assert_key_material_set().

valid_keylength()

bool Botan::SymmetricAlgorithm::valid_keylength ( size_t length ) const

inlineinherited

Check whether a given key length is valid for this algorithm.

Parameters

length

the key length to be checked.

Returns

true if the key length is valid.

Definition at line 143 of file sym_algo.h.

{ return key_spec().valid_keylength(length); }

References key_spec().

Referenced by set_key().

Friends And Related Symbol Documentation

Polyval

friend class Polyval

friend

Polyval reuses the GHASH tables and kernels for its non-CLMUL fallback.

Definition at line 95 of file ghash.h.

References Polyval.

Referenced by Polyval.

---

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

• src/lib/utils/ghash/ghash.h
• src/lib/utils/ghash/ghash.cpp
• src/lib/utils/ghash/ghash_cpu/ghash_cpu.cpp
• src/lib/utils/ghash/ghash_vperm/ghash_vperm.cpp