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 28 of file sponge.h.

word_t

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

inherited

Definition at line 27 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, and Botan::Sponge< 25, uint64_t >::state_bits().

Member Function Documentation

_cursor()

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

inlineinherited

Definition at line 60 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 38 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 52 of file sponge.h.

{ return state_bits() - bit_rate(); }

bit_rate()

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

inlineconstexprinherited

Definition at line 48 of file sponge.h.

{ return m_bit_rate; }

byte_capacity()

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

inlineconstexprinherited

Definition at line 54 of file sponge.h.

{ return state_bytes() - byte_rate(); }

byte_rate()

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

inlineconstexprinherited

Definition at line 50 of file sponge.h.

{ return m_bit_rate / 8; }

Referenced by finish().

clear()

void Botan::Keccak_Permutation::clear

(

)

Definition at line 33 of file keccak_perm.cpp.

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

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

Referenced by Botan::Keccak_1600::clear(), Botan::SHA_3::clear(), Botan::SHAKE_128::clear(), Botan::SHAKE_256::clear(), and Botan::SHAKE_Cipher::clear().

cursor()

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

inlineinherited

Definition at line 58 of file sponge.h.

{ return m_S_cursor; }

Referenced by finish().

finish()

void Botan::Keccak_Permutation::finish

(

)

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

Definition at line 46 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::KeccakPadding::bit_len, BOTAN_DEBUG_ASSERT, Botan::Sponge< 25, uint64_t >::byte_rate(), Botan::Sponge< 25, uint64_t >::cursor(), Botan::KeccakPadding::padding, 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 80 of file keccak_perm.cpp.

                                 {
#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::BMI, Botan::CPUID::has(), Botan::Keccak_Permutation_round(), Botan::Sponge< 25, uint64_t >::state(), and T.

Referenced by finish().

provider()

std::string Botan::Keccak_Permutation::provider

(

)

const

Definition at line 23 of file keccak_perm.cpp.

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

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

Referenced by Botan::cSHAKE_XOF::provider(), Botan::Keccak_1600::provider(), Botan::SHA_3::provider(), Botan::SHAKE_128::provider(), Botan::SHAKE_256::provider(), and Botan::SHAKE_XOF::provider().

reset_cursor()

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

inlineprotectedinherited

Definition at line 63 of file sponge.h.

{ m_S_cursor = 0; }

Referenced by clear(), and 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 42 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 56 of file sponge.h.

{ return m_S; }

Referenced by clear(), finish(), and permute().

state_bits()

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

inlinestaticconstexprinherited

Definition at line 46 of file sponge.h.

{ return state_bytes() * 8; }

Referenced by Keccak_Permutation().

state_bytes()

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

inlinestaticconstexprinherited

Definition at line 44 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 30 of file sponge.h.

word_bytes

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

staticconstexprinherited

Definition at line 29 of file sponge.h.

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