Botan::Keccak_Permutation Class Reference

#include <keccak_perm.h>

Inheritance diagram for Botan::Keccak_Permutation:

Classes
struct	Config

Public Types
using	state_t
using	word_t

Public Member Functions
size_t &	_cursor ()
void	absorb (std::span< const uint8_t > input)
	Absorb input data into the Keccak sponge.
constexpr size_t	bit_capacity () const
constexpr size_t	bit_rate () const
constexpr size_t	byte_capacity () const
constexpr size_t	byte_rate () const
void	clear ()
size_t	cursor () const
void	finish ()
	Add final padding (as provided in the constructor) and permute.
constexpr	Keccak_Permutation (Config config)
	Instantiate a Keccak permutation.
void	permute ()
std::string	provider () const
void	squeeze (std::span< uint8_t > output)
	Expand output data from the current Keccak state.
constexpr auto &	state ()

Static Public Member Functions
static constexpr size_t	state_bits ()
static constexpr size_t	state_bytes ()

Static Public Attributes
static constexpr size_t	word_bits
static constexpr size_t	word_bytes

Protected Member Functions
void	reset_cursor ()

Detailed Description

KECCAK FIPS

This file implements Keccak[c] which is specified by NIST FIPS 202 [1], where "c" is the variable capacity of this hash primitive. Keccak[c] is not a general purpose hash function, but used as the basic primitive for algorithms such as SHA-3 and KMAC. This is not to be confused with the "informal" general purpose hash function which is referred to as "Keccak" and apparently refers to the final submission version of the Keccak submission in the SHA-3 contest, possibly what is released by NIST under the name "KECCAK - Final Algorithm Package" [2]. See also the file keccak.h for the details how the keccak hash function is defined in terms of the Keccak[c] – a detail which cannot be found in [1].

[1] FIPS PUB 202 – FEDERAL INFORMATION PROCESSING STANDARDS PUBLICATION – SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf#page=28 [2] https://csrc.nist.gov/projects/hash-functions/sha-3-project

Definition at line 55 of file keccak_perm.h.

Member Typedef Documentation

state_t

using Botan::Sponge< words, word >::state_t

inherited

Definition at line 29 of file sponge.h.

word_t

using Botan::Sponge< words, word >::word_t

inherited

Definition at line 28 of file sponge.h.

Constructor & Destructor Documentation

Keccak_Permutation()

Botan::Keccak_Permutation::Keccak_Permutation ( Config config )

inlineexplicitconstexpr

Instantiate a Keccak permutation.

Parameters

config

Keccak parameter configuration

Definition at line 68 of file keccak_perm.h.

                                                           :
            Sponge({.bit_rate = state_bits() - config.capacity_bits, .initial_state = {}}), m_padding(config.padding) {}

References Botan::Keccak_Permutation::Config::capacity_bits, Botan::Sponge< 25, uint64_t >::Sponge(), and Botan::Sponge< 25, uint64_t >::state_bits().

Member Function Documentation

_cursor()

size_t & Botan::Sponge< words, word >::_cursor ( )

inlineinherited

Definition at line 59 of file sponge.h.

{ return m_S_cursor; }

absorb()

void Botan::Keccak_Permutation::absorb

(

std::span< const uint8_t >

input

)

Absorb input data into the Keccak sponge.

This method can be called multiple times with arbitrary-length buffers.

Parameters

input

the input data

Definition at line 42 of file keccak_perm.cpp.

                                                            {
   absorb_into_sponge(*this, input);
}

References Botan::absorb_into_sponge().

bit_capacity()

size_t Botan::Sponge< words, word >::bit_capacity ( ) const

inlineconstexprinherited

Definition at line 51 of file sponge.h.

{ return state_bits() - bit_rate(); }

bit_rate()

size_t Botan::Sponge< words, word >::bit_rate ( ) const

inlineconstexprinherited

Definition at line 47 of file sponge.h.

{ return m_bit_rate; }

byte_capacity()

size_t Botan::Sponge< words, word >::byte_capacity ( ) const

inlineconstexprinherited

Definition at line 53 of file sponge.h.

{ return state_bytes() - byte_rate(); }

byte_rate()

size_t Botan::Sponge< words, word >::byte_rate ( ) const

inlineconstexprinherited

Definition at line 49 of file sponge.h.

{ return m_bit_rate / 8; }

Referenced by Botan::Keccak_Permutation::finish().

clear()

void Botan::Keccak_Permutation::clear

(

)

Definition at line 37 of file keccak_perm.cpp.

                               {
   state() = {};
   reset_cursor();
}

References Botan::Sponge< 25, uint64_t >::reset_cursor(), and Botan::Sponge< 25, uint64_t >::state().

cursor()

size_t Botan::Sponge< words, word >::cursor ( ) const

inlineinherited

Definition at line 57 of file sponge.h.

{ return m_S_cursor; }

Referenced by Botan::Keccak_Permutation::finish().

finish()

void Botan::Keccak_Permutation::finish

(

)

Add final padding (as provided in the constructor) and permute.

Definition at line 50 of file keccak_perm.cpp.

                                {
   // The padding for Keccak[c]-based functions spans the entire remaining
   // byterate until the next permute() call. At most that could be an entire
   // byterate. First are a few bits of "custom" padding defined by the using
   // function (e.g. SHA-3 uses "01"), then the remaining space is filled with
   // "pad10*1" (see NIST FIPS 202 Section 5.1) followed by a final permute().
 
   auto& S = state();
 
   // Apply the custom padding + the left-most 1-bit of "pad10*1" to the current
   // (partial) word of the sponge state
 
   const uint64_t start_of_padding = (m_padding.padding | uint64_t(1) << m_padding.bit_len);
   S[cursor() / word_bytes] ^= start_of_padding << (8 * (cursor() % word_bytes));
 
   // XOR'ing the 0-bits of "pad10*1" into the state is a NOOP
 
   // If the custom padding + the left-most 1-bit of "pad10*1" had resulted in a
   // byte-aligned "partial padding", the final 1-bit of of "pad10*1" could
   // potentially override parts of the already-appended "start_of_padding".
   // In case we ever introduce a Keccak-based function with such a need, we
   // have to modify this padding algorithm.
   BOTAN_DEBUG_ASSERT(m_padding.bit_len % 8 != 7);
 
   // Append the final bit of "pad10*1" into the last word of the input range
   S[(byte_rate() / word_bytes) - 1] ^= uint64_t(0x8000000000000000);
 
   // Perform the final permutation and reset the state cursor
   permute();
   reset_cursor();
 
   BOTAN_DEBUG_ASSERT(cursor() == 0);
}

References BOTAN_DEBUG_ASSERT, Botan::Sponge< 25, uint64_t >::byte_rate(), Botan::Sponge< 25, uint64_t >::cursor(), permute(), Botan::Sponge< 25, uint64_t >::reset_cursor(), Botan::Sponge< 25, uint64_t >::state(), and Botan::Sponge< 25, uint64_t >::word_bytes.

permute()

void Botan::Keccak_Permutation::permute

(

)

The Keccak permutation function

Definition at line 84 of file keccak_perm.cpp.

                                 {
#if defined(BOTAN_HAS_KECCAK_PERM_AVX512)
   if(CPUID::has(CPUID::Feature::AVX512)) {
      return permute_avx512();
   }
#endif
 
#if defined(BOTAN_HAS_KECCAK_PERM_BMI2)
   if(CPUID::has(CPUID::Feature::BMI)) {
      return permute_bmi2();
   }
#endif
 
   static const uint64_t RC[24] = {0x0000000000000001, 0x0000000000008082, 0x800000000000808A, 0x8000000080008000,
                                   0x000000000000808B, 0x0000000080000001, 0x8000000080008081, 0x8000000000008009,
                                   0x000000000000008A, 0x0000000000000088, 0x0000000080008009, 0x000000008000000A,
                                   0x000000008000808B, 0x800000000000008B, 0x8000000000008089, 0x8000000000008003,
                                   0x8000000000008002, 0x8000000000000080, 0x000000000000800A, 0x800000008000000A,
                                   0x8000000080008081, 0x8000000000008080, 0x0000000080000001, 0x8000000080008008};
 
   uint64_t T[25];
 
   for(size_t i = 0; i != 24; i += 2) {
      Keccak_Permutation_round(T, state().data(), RC[i + 0]);
      Keccak_Permutation_round(state().data(), T, RC[i + 1]);
   }
}

References Botan::CPUFeature::AVX512, Botan::CPUFeature::BMI, Botan::CPUID::has(), Botan::Keccak_Permutation_round(), and Botan::Sponge< 25, uint64_t >::state().

Referenced by finish().

provider()

std::string Botan::Keccak_Permutation::provider

(

)

const

Definition at line 21 of file keccak_perm.cpp.

                                             {
#if defined(BOTAN_HAS_KECCAK_PERM_AVX512)
   if(auto feat = CPUID::check(CPUID::Feature::AVX512)) {
      return *feat;
   }
#endif
 
#if defined(BOTAN_HAS_KECCAK_PERM_BMI2)
   if(auto feat = CPUID::check(CPUID::Feature::BMI)) {
      return *feat;
   }
#endif
 
   return "base";
}

References Botan::CPUFeature::AVX512, Botan::CPUFeature::BMI, and Botan::CPUID::check().

reset_cursor()

void Botan::Sponge< words, word >::reset_cursor ( )

inlineprotectedinherited

Definition at line 62 of file sponge.h.

{ m_S_cursor = 0; }

Referenced by Botan::Keccak_Permutation::clear(), and Botan::Keccak_Permutation::finish().

squeeze()

void Botan::Keccak_Permutation::squeeze

(

std::span< uint8_t >

output

)

Expand output data from the current Keccak state.

This method can be called multiple times with arbitrary-length buffers.

Parameters

output

the designated output memory

Definition at line 46 of file keccak_perm.cpp.

                                                        {
   squeeze_from_sponge(*this, output);
}

References Botan::squeeze_from_sponge().

state()

auto & Botan::Sponge< words, word >::state ( )

inlineconstexprinherited

Definition at line 55 of file sponge.h.

{ return m_S; }

Referenced by Botan::Keccak_Permutation::clear(), Botan::Keccak_Permutation::finish(), and Botan::Keccak_Permutation::permute().

state_bits()

constexpr size_t Botan::Sponge< words, word >::state_bits ( )

inlinestaticconstexprinherited

Definition at line 45 of file sponge.h.

{ return state_bytes() * 8; }

Referenced by Botan::Keccak_Permutation::Keccak_Permutation().

state_bytes()

constexpr size_t Botan::Sponge< words, word >::state_bytes ( )

inlinestaticconstexprinherited

Definition at line 43 of file sponge.h.

{ return sizeof(state_t); }

Member Data Documentation

word_bits

size_t Botan::Sponge< words, word >::word_bits

staticconstexprinherited

Definition at line 31 of file sponge.h.

word_bytes

size_t Botan::Sponge< words, word >::word_bytes

staticconstexprinherited

Definition at line 30 of file sponge.h.

Referenced by Botan::Keccak_Permutation::finish().

---

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

• src/lib/permutations/keccak_perm/keccak_perm.h
• src/lib/permutations/keccak_perm/keccak_perm.cpp
• src/lib/permutations/keccak_perm/keccak_perm_bmi2/keccak_perm_bmi2.cpp