Botan 3.14.1
Crypto and TLS for C&
Botan::GHASH Class Referencefinal

#include <ghash.h>

Inheritance diagram for Botan::GHASH:
Botan::SymmetricAlgorithm

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]

◆ 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
predicateif false, a Key_Not_Set exception is thrown

Definition at line 186 of file sym_algo.h.

186 {
187 if(!predicate) {
188 throw_key_not_set_error();
189 }
190 }

◆ 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 240 of file ghash.cpp.

240 {
241 zap(m_HM);
242 zap(m_H_pow);
243 m_H_ad = {0};
244 m_ad_len = 0;
245 this->reset_state();
246}
void reset_state()
Definition ghash.cpp:248
void zap(std::vector< T, Alloc > &vec)
Definition secmem.h:261

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

◆ final()

void Botan::GHASH::final ( std::span< uint8_t > out)

Definition at line 216 of file ghash.cpp.

216 {
217 BOTAN_ARG_CHECK(!mac.empty() && mac.size() <= GCM_BS, "GHASH output length");
218 BOTAN_STATE_CHECK(m_nonce);
220
221 ghash_zeropad(m_ghash);
222 ghash_final_block(m_ghash, m_ad_len, m_text_len);
223
224 xor_buf(mac, std::span{m_ghash}.first(mac.size()), std::span{*m_nonce}.first(mac.size()));
225
226 secure_scrub_memory(m_ghash);
227 m_text_len = 0;
228 m_nonce.reset();
229}
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
void secure_scrub_memory(void *ptr, size_t n)
Definition mem_utils.cpp:24
constexpr void xor_buf(ranges::contiguous_output_range< uint8_t > auto &&out, ranges::contiguous_range< uint8_t > auto &&in)
Definition mem_ops.h:403

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 108 of file ghash.cpp.

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

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

42{ 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.

130{ return key_spec().maximum_keylength(); }
size_t maximum_keylength() const
Definition sym_algo.h:58
virtual Key_Length_Specification key_spec() const =0

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.

136{ return key_spec().minimum_keylength(); }
size_t minimum_keylength() const
Definition sym_algo.h:52

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.

52{ 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 231 of file ghash.cpp.

231 {
233 BOTAN_STATE_CHECK(!m_nonce);
234
235 ghash_update(y0, nonce);
236 ghash_zeropad(y0);
237 ghash_final_block(y0, 0, nonce.size());
238}

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.

22 {
23#if defined(BOTAN_HAS_GHASH_AVX512_CLMUL)
25 return *feat;
26 }
27#endif
28
29#if defined(BOTAN_HAS_GHASH_CLMUL_CPU)
30 if(auto feat = CPUID::check(CPUID::Feature::HW_CLMUL)) {
31 return *feat;
32 }
33#endif
34
35#if defined(BOTAN_HAS_GHASH_CLMUL_VPERM)
37 return *feat;
38 }
39#endif
40
41 return "base";
42}
static std::optional< std::string > check(CPUID::Feature feat)
Definition cpuid.h:66

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 189 of file ghash.cpp.

189 {
190 // This should only be called in GMAC context
191 BOTAN_STATE_CHECK(m_text_len == 0);
193 m_H_ad = {0};
194 m_ad_len = 0;
195}

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 248 of file ghash.cpp.

248 {
249 secure_scrub_memory(m_ghash);
250 if(m_nonce) {
251 secure_scrub_memory(m_nonce.value());
252 m_nonce.reset();
253 }
254 m_buffer.clear();
255 m_text_len = 0;
256}

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 179 of file ghash.cpp.

179 {
180 BOTAN_STATE_CHECK(!m_nonce);
181
183 m_H_ad = {0};
184 ghash_update(m_H_ad, input);
185 ghash_zeropad(m_H_ad);
186 m_ad_len = input.size();
187}

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

◆ set_key() [1/3]

◆ 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
keythe to be set as a byte array.
lengthin bytes of key param

Definition at line 162 of file sym_algo.h.

162{ 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
keythe contiguous byte range to be set.

Definition at line 22 of file sym_algo.cpp.

22 {
23 if(!valid_keylength(key.size())) {
24 throw Invalid_Key_Length(name(), key.size());
25 }
26 key_schedule(key);
27}
bool valid_keylength(size_t length) const
Definition sym_algo.h:143
virtual std::string name() const =0

References name(), and valid_keylength().

◆ start()

void Botan::GHASH::start ( std::span< const uint8_t > nonce)

Definition at line 170 of file ghash.cpp.

170 {
171 BOTAN_ARG_CHECK(nonce.size() == 16, "GHASH requires a 128-bit nonce");
172 auto& n = m_nonce.emplace();
173 copy_mem(n, nonce);
174 copy_mem(m_ghash, m_H_ad);
175 m_buffer.clear();
176 m_text_len = 0;
177}
constexpr void copy_mem(T *out, const T *in, size_t n)
Definition mem_ops.h:144

References BOTAN_ARG_CHECK, and Botan::copy_mem().

◆ update()

void Botan::GHASH::update ( std::span< const uint8_t > in)

Definition at line 203 of file ghash.cpp.

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

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 197 of file ghash.cpp.

197 {
199 ghash_update(m_ghash, ad);
200 m_ad_len += ad.size();
201}

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
lengththe key length to be checked.
Returns
true if the key length is valid.

Definition at line 143 of file sym_algo.h.

143{ return key_spec().valid_keylength(length); }
bool valid_keylength(size_t length) const
Definition sym_algo.h:44

References key_spec().

Referenced by set_key().

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