Botan::Keccak_Permutation Class Reference

#include <keccak_perm.h>

Public Member Functions
void	absorb (std::span< const uint8_t > input)
	Absorb input data into the Keccak sponge.
size_t	bit_rate () const
size_t	byte_rate () const
size_t	capacity () const
void	clear ()
void	finish ()
	Add final padding (as provided in the constructor) and permute.
	Keccak_Permutation (size_t capacity_bits, uint64_t custom_padding, uint8_t custom_padding_bit_len)
	Instantiate a Keccak permutation.
std::string	provider () const
void	squeeze (std::span< uint8_t > output)
	Expand output data from the current Keccak state.

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 38 of file keccak_perm.h.

Constructor & Destructor Documentation

Keccak_Permutation()

Botan::Keccak_Permutation::Keccak_Permutation	(	size_t	capacity_bits,
		uint64_t	custom_padding,
		uint8_t	custom_padding_bit_len )

Instantiate a Keccak permutation.

The custom_padding is assumed to be init_pad || 00... || fini_pad

Parameters

capacity_bits	Keccak capacity
custom_padding	the custom bit padding that is to be appended on the call to finish
custom_padding_bit_len	the bit length of the custom_padd

Definition at line 21 of file keccak_perm.cpp.

                                                                                                               :
      m_capacity(capacity),
      m_byterate((1600 - capacity) / 8),
      m_custom_padding(custom_padding),
      m_custom_padding_bit_len(custom_padding_bit_len),
      m_S(25),  // 1600 bit
      m_S_inpos(0),
      m_S_outpos(0) {
   BOTAN_ARG_CHECK(capacity % 64 == 0, "capacity must be a multiple of 64");
}

References BOTAN_ARG_CHECK, and capacity().

Member Function Documentation

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 48 of file keccak_perm.cpp.

                                                            {
   BufferSlicer input_slicer(input);
 
   // Block-wise incorporation of the input data into the sponge state until
   // all input bytes are processed
   while(!input_slicer.empty()) {
      const size_t to_take_this_round = std::min(input_slicer.remaining(), m_byterate - m_S_inpos);
      BufferSlicer input_this_round(input_slicer.take(to_take_this_round));
 
      // If necessary, try to get aligned with the sponge state's 64-bit integer array
      for(; !input_this_round.empty() && m_S_inpos % 8; ++m_S_inpos) {
         m_S[m_S_inpos / 8] ^= static_cast<uint64_t>(input_this_round.take_byte()) << (8 * (m_S_inpos % 8));
      }
 
      // Process as many aligned 64-bit integer values as possible
      for(; input_this_round.remaining() >= 8; m_S_inpos += 8) {
         m_S[m_S_inpos / 8] ^= load_le<uint64_t>(input_this_round.take(8).data(), 0);
      }
 
      // Read remaining output data, causing misalignment, if necessary
      for(; !input_this_round.empty(); ++m_S_inpos) {
         m_S[m_S_inpos / 8] ^= static_cast<uint64_t>(input_this_round.take_byte()) << (8 * (m_S_inpos % 8));
      }
 
      // We reached the end of a sponge state block... permute() and start over
      if(m_S_inpos == m_byterate) {
         permute();
         m_S_inpos = 0;
      }
   }
}

References Botan::BufferSlicer::empty(), Botan::load_le(), Botan::BufferSlicer::remaining(), Botan::BufferSlicer::take(), and Botan::BufferSlicer::take_byte().

bit_rate()

size_t Botan::Keccak_Permutation::bit_rate ( ) const

inline

Definition at line 53 of file keccak_perm.h.

{ return m_byterate * 8; }

byte_rate()

size_t Botan::Keccak_Permutation::byte_rate ( ) const

inline

Definition at line 55 of file keccak_perm.h.

{ return m_byterate; }

Referenced by Botan::cSHAKE_XOF::block_size(), Botan::SHAKE_XOF::block_size(), Botan::SHAKE_Cipher::buffer_size(), Botan::Keccak_1600::hash_block_size(), Botan::SHA_3::hash_block_size(), Botan::SHAKE_128::hash_block_size(), and Botan::SHAKE_256::hash_block_size().

capacity()

size_t Botan::Keccak_Permutation::capacity ( ) const

inline

Definition at line 51 of file keccak_perm.h.

{ return m_capacity; }

Referenced by Keccak_Permutation().

clear()

void Botan::Keccak_Permutation::clear

(

)

Definition at line 42 of file keccak_perm.cpp.

                               {
   zeroise(m_S);
   m_S_inpos = 0;
   m_S_outpos = 0;
}

References Botan::zeroise().

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

finish()

void Botan::Keccak_Permutation::finish

(

)

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

Definition at line 112 of file keccak_perm.cpp.

                                {
   // append the first bit of the final padding after the custom padding
   uint8_t init_pad = static_cast<uint8_t>(m_custom_padding | uint64_t(1) << m_custom_padding_bit_len);
   m_S[m_S_inpos / 8] ^= static_cast<uint64_t>(init_pad) << (8 * (m_S_inpos % 8));
 
   // final bit of the padding of the last block
   m_S[(m_byterate / 8) - 1] ^= static_cast<uint64_t>(0x80) << 56;
 
   permute();
}

provider()

std::string Botan::Keccak_Permutation::provider

(

)

const

Definition at line 32 of file keccak_perm.cpp.

                                             {
#if defined(BOTAN_HAS_KECCAK_PERM_BMI2)
   if(CPUID::has_bmi2()) {
      return "bmi2";
   }
#endif
 
   return "base";
}

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().

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 80 of file keccak_perm.cpp.

                                                        {
   BufferStuffer output_stuffer(output);
 
   // Block-wise readout of the sponge state until enough bytes
   // were filled into the output buffer
   while(!output_stuffer.full()) {
      const size_t bytes_in_this_round = std::min(output_stuffer.remaining_capacity(), m_byterate - m_S_outpos);
      BufferStuffer output_this_round(output_stuffer.next(bytes_in_this_round));
 
      // If necessary, try to get aligned with the sponge state's 64-bit integer array
      for(; !output_this_round.full() && m_S_outpos % 8 != 0; ++m_S_outpos) {
         output_this_round.next_byte() = static_cast<uint8_t>(m_S[m_S_outpos / 8] >> (8 * (m_S_outpos % 8)));
      }
 
      // Read out as many aligned 64-bit integer values as possible
      for(; output_this_round.remaining_capacity() >= 8; m_S_outpos += 8) {
         store_le(m_S[m_S_outpos / 8], output_this_round.next(8).data());
      }
 
      // Read remaining output data, causing misalignment, if necessary
      for(; !output_this_round.full(); ++m_S_outpos) {
         output_this_round.next_byte() = static_cast<uint8_t>(m_S[m_S_outpos / 8] >> (8 * (m_S_outpos % 8)));
      }
 
      // We reached the end of a sponge state block... permute() and start over
      if(m_S_outpos == m_byterate) {
         permute();
         m_S_outpos = 0;
      }
   }
}

References Botan::BufferStuffer::full(), Botan::BufferStuffer::next(), Botan::BufferStuffer::next_byte(), Botan::BufferStuffer::remaining_capacity(), and Botan::store_le().

---

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