Botan::GHASH Class Reference

#include <ghash.h>

Inheritance diagram for Botan::GHASH:

Public Member Functions
void	add_final_block (secure_vector< uint8_t > &x, size_t ad_len, size_t pt_len)
void	clear () override
void	final (std::span< uint8_t > out)
void	ghash_update (secure_vector< uint8_t > &x, std::span< const uint8_t > input)
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 (secure_vector< uint8_t > &y0, std::span< const uint8_t > nonce)
std::string	provider () const
void	reset ()
void	set_associated_data (std::span< const uint8_t > ad)
void	set_key (const SymmetricKey &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)
bool	valid_keylength (size_t length) const

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

Detailed Description

GCM's GHASH

Definition at line 18 of file ghash.h.

Member Function Documentation

add_final_block()

void Botan::GHASH::add_final_block	(	secure_vector< uint8_t > &	x,
		size_t	ad_len,
		size_t	pt_len )

Definition at line 177 of file ghash.cpp.

                                                                                        {
   /*
   * stack buffer is fine here since the text len is public
   * and the length of the AD is probably not sensitive either.
   */
   std::array<uint8_t, GCM_BS> final_block;
 
   const uint64_t ad_bits = 8 * ad_len;
   const uint64_t text_bits = 8 * text_len;
   store_be(final_block, ad_bits, text_bits);
   ghash_update(hash, final_block);
}

References ghash_update(), and Botan::store_be().

Referenced by final(), and nonce_hash().

assert_key_material_set() [1/2]

void Botan::SymmetricAlgorithm::assert_key_material_set ( ) const

inlineprotectedinherited

Definition at line 139 of file sym_algo.h.

{ assert_key_material_set(has_keying_material()); }

References Botan::SymmetricAlgorithm::assert_key_material_set().

Referenced by Botan::SymmetricAlgorithm::assert_key_material_set(), Botan::Salsa20::cipher_bytes(), Botan::AES_128::decrypt_n(), Botan::AES_192::decrypt_n(), Botan::AES_256::decrypt_n(), Botan::ARIA_128::decrypt_n(), Botan::ARIA_192::decrypt_n(), Botan::ARIA_256::decrypt_n(), Botan::Blowfish::decrypt_n(), Botan::Camellia_128::decrypt_n(), Botan::Camellia_192::decrypt_n(), Botan::Camellia_256::decrypt_n(), Botan::CAST_128::decrypt_n(), Botan::DES::decrypt_n(), Botan::TripleDES::decrypt_n(), Botan::GOST_28147_89::decrypt_n(), Botan::IDEA::decrypt_n(), Botan::Kuznyechik::decrypt_n(), Botan::Lion::decrypt_n(), Botan::Noekeon::decrypt_n(), Botan::SEED::decrypt_n(), Botan::Serpent::decrypt_n(), Botan::SHACAL2::decrypt_n(), Botan::SM4::decrypt_n(), Botan::Threefish_512::decrypt_n(), Botan::Twofish::decrypt_n(), Botan::AES_128::encrypt_n(), Botan::AES_192::encrypt_n(), Botan::AES_256::encrypt_n(), Botan::ARIA_128::encrypt_n(), Botan::ARIA_192::encrypt_n(), Botan::ARIA_256::encrypt_n(), Botan::Blowfish::encrypt_n(), Botan::Camellia_128::encrypt_n(), Botan::Camellia_192::encrypt_n(), Botan::Camellia_256::encrypt_n(), Botan::CAST_128::encrypt_n(), Botan::DES::encrypt_n(), Botan::TripleDES::encrypt_n(), Botan::GOST_28147_89::encrypt_n(), Botan::IDEA::encrypt_n(), Botan::Kuznyechik::encrypt_n(), Botan::Lion::encrypt_n(), Botan::Noekeon::encrypt_n(), Botan::SEED::encrypt_n(), Botan::Serpent::encrypt_n(), Botan::SHACAL2::encrypt_n(), Botan::SM4::encrypt_n(), Botan::Threefish_512::encrypt_n(), Botan::Twofish::encrypt_n(), final(), ghash_update(), Botan::ChaCha::seek(), Botan::CTR_BE::seek(), Botan::Salsa20::seek(), Botan::OCB_Mode::set_associated_data_n(), Botan::Salsa20::set_iv_bytes(), update(), and update_associated_data().

assert_key_material_set() [2/2]

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

inlineprotectedinherited

Definition at line 141 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 211 of file ghash.cpp.

                  {
   zap(m_H);
   zap(m_HM);
   reset();
}

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

final()

void Botan::GHASH::final

(

std::span< uint8_t >

out

)

Definition at line 190 of file ghash.cpp.

                                      {
   BOTAN_ARG_CHECK(!mac.empty() && mac.size() <= 16, "GHASH output length");
 
   assert_key_material_set();
   add_final_block(m_ghash, m_ad_len, m_text_len);
 
   for(size_t i = 0; i != mac.size(); ++i) {
      mac[i] = m_ghash[i] ^ m_nonce[i];
   }
 
   m_ghash.clear();
   m_text_len = 0;
}

References add_final_block(), Botan::SymmetricAlgorithm::assert_key_material_set(), and BOTAN_ARG_CHECK.

ghash_update()

void Botan::GHASH::ghash_update	(	secure_vector< uint8_t > &	x,
		std::span< const uint8_t >	input )

Definition at line 83 of file ghash.cpp.

                                                                                    {
   assert_key_material_set(!m_H.empty());
 
   /*
   This assumes if less than block size input then we're just on the
   final block and should pad with zeros
   */
 
   const size_t full_blocks = input.size() / GCM_BS;
   const size_t final_bytes = input.size() - (full_blocks * GCM_BS);
 
   if(full_blocks > 0) {
      ghash_multiply(ghash, input.first(full_blocks * GCM_BS), full_blocks);
   }
 
   if(final_bytes) {
      uint8_t last_block[GCM_BS] = {0};
      copy_mem(last_block, input.subspan(full_blocks * GCM_BS).data(), final_bytes);
      ghash_multiply(ghash, last_block, 1);
      secure_scrub_memory(last_block, final_bytes);
   }
}

References Botan::SymmetricAlgorithm::assert_key_material_set(), Botan::copy_mem(), and Botan::secure_scrub_memory().

Referenced by add_final_block(), nonce_hash(), set_associated_data(), update(), and update_associated_data().

has_keying_material()

bool Botan::GHASH::has_keying_material ( ) const

overridevirtual

Returns

true if a key has been set on this object

Implements Botan::SymmetricAlgorithm.

Definition at line 106 of file ghash.cpp.

                                      {
   return !m_ghash.empty();
}

key_spec()

Key_Length_Specification Botan::GHASH::key_spec ( ) const

inlineoverridevirtual

Returns

object describing limits on key size

Implements Botan::SymmetricAlgorithm.

Definition at line 38 of file ghash.h.

{ return Key_Length_Specification(16); }

maximum_keylength()

size_t Botan::SymmetricAlgorithm::maximum_keylength ( ) const

inlineinherited

Returns

maximum allowed key length

Definition at line 95 of file sym_algo.h.

{ return key_spec().maximum_keylength(); }

minimum_keylength()

size_t Botan::SymmetricAlgorithm::minimum_keylength ( ) const

inlineinherited

Returns

minimum allowed key length

Definition at line 100 of file sym_algo.h.

{ return key_spec().minimum_keylength(); }

name()

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

inlineoverridevirtual

Returns

the algorithm name

Implements Botan::SymmetricAlgorithm.

Definition at line 46 of file ghash.h.

{ return "GHASH"; }

nonce_hash()

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

Definition at line 204 of file ghash.cpp.

                                                                               {
   BOTAN_ASSERT(m_ghash.empty(), "nonce_hash called during wrong time");
 
   ghash_update(y0, nonce);
   add_final_block(y0, 0, nonce.size());
}

References add_final_block(), BOTAN_ASSERT, and ghash_update().

provider()

std::string Botan::GHASH::provider

(

)

const

Definition at line 20 of file ghash.cpp.

                                {
#if defined(BOTAN_HAS_GHASH_CLMUL_CPU)
   if(CPUID::has_carryless_multiply()) {
      return "clmul";
   }
#endif
 
#if defined(BOTAN_HAS_GHASH_CLMUL_VPERM)
   if(CPUID::has_vperm()) {
      return "vperm";
   }
#endif
 
   return "base";
}

References Botan::CPUID::has_carryless_multiply(), and Botan::CPUID::has_vperm().

reset()

void Botan::GHASH::reset

(

)

Definition at line 217 of file ghash.cpp.

                  {
   zeroise(m_H_ad);
   m_ghash.clear();
   m_nonce.clear();
   m_text_len = m_ad_len = 0;
}

References Botan::zeroise().

Referenced by clear().

set_associated_data()

void Botan::GHASH::set_associated_data

(

std::span< const uint8_t >

ad

)

Definition at line 154 of file ghash.cpp.

                                                            {
   if(m_ghash.empty() == false) {
      throw Invalid_State("Too late to set AD in GHASH");
   }
 
   zeroise(m_H_ad);
 
   ghash_update(m_H_ad, input);
   m_ad_len = input.size();
}

References ghash_update(), and Botan::zeroise().

set_key() [1/3]

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

inlineinherited

Set the symmetric key of this object.

Parameters

key	the SymmetricKey to be set.

Definition at line 113 of file sym_algo.h.

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

References Botan::OctetString::begin(), Botan::OctetString::length(), and Botan::SymmetricAlgorithm::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(), and Botan::SymmetricAlgorithm::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 126 of file sym_algo.h.

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

References Botan::SymmetricAlgorithm::set_key().

Referenced by Botan::SymmetricAlgorithm::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 17 of file sym_algo.cpp.

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

References Botan::SymmetricAlgorithm::name(), and Botan::SymmetricAlgorithm::valid_keylength().

start()

void Botan::GHASH::start

(

std::span< const uint8_t >

nonce

)

Definition at line 148 of file ghash.cpp.

                                              {
   BOTAN_ARG_CHECK(nonce.size() == 16, "GHASH requires a 128-bit nonce");
   m_nonce.assign(nonce.begin(), nonce.end());  // TODO: C++23: assign_range
   m_ghash = m_H_ad;
}

References BOTAN_ARG_CHECK.

update()

void Botan::GHASH::update

(

std::span< const uint8_t >

in

)

Definition at line 171 of file ghash.cpp.

                                               {
   assert_key_material_set();
   m_text_len += input.size();
   ghash_update(m_ghash, input);
}

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

update_associated_data()

void Botan::GHASH::update_associated_data

(

std::span< const uint8_t >

ad

)

Definition at line 165 of file ghash.cpp.

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

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

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 107 of file sym_algo.h.

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

Referenced by Botan::SymmetricAlgorithm::set_key().

---

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