Botan 3.5.0
Crypto and TLS for C&
Botan::Keccak_Permutation Class Referencefinal

#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_bitsKeccak capacity
custom_paddingthe custom bit padding that is to be appended on the call to finish
custom_padding_bit_lenthe bit length of the custom_padd

Definition at line 21 of file keccak_perm.cpp.

21 :
22 m_capacity(capacity),
23 m_byterate((1600 - capacity) / 8),
24 m_custom_padding(custom_padding),
25 m_custom_padding_bit_len(custom_padding_bit_len),
26 m_S(25), // 1600 bit
27 m_S_inpos(0),
28 m_S_outpos(0) {
29 BOTAN_ARG_CHECK(capacity % 64 == 0, "capacity must be a multiple of 64");
30}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:29
size_t capacity() const
Definition keccak_perm.h:51

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
inputthe input data

Definition at line 48 of file keccak_perm.cpp.

48 {
49 BufferSlicer input_slicer(input);
50
51 // Block-wise incorporation of the input data into the sponge state until
52 // all input bytes are processed
53 while(!input_slicer.empty()) {
54 const size_t to_take_this_round = std::min(input_slicer.remaining(), m_byterate - m_S_inpos);
55 BufferSlicer input_this_round(input_slicer.take(to_take_this_round));
56
57 // If necessary, try to get aligned with the sponge state's 64-bit integer array
58 for(; !input_this_round.empty() && m_S_inpos % 8; ++m_S_inpos) {
59 m_S[m_S_inpos / 8] ^= static_cast<uint64_t>(input_this_round.take_byte()) << (8 * (m_S_inpos % 8));
60 }
61
62 // Process as many aligned 64-bit integer values as possible
63 for(; input_this_round.remaining() >= 8; m_S_inpos += 8) {
64 m_S[m_S_inpos / 8] ^= load_le<uint64_t>(input_this_round.take(8).data(), 0);
65 }
66
67 // Read remaining output data, causing misalignment, if necessary
68 for(; !input_this_round.empty(); ++m_S_inpos) {
69 m_S[m_S_inpos / 8] ^= static_cast<uint64_t>(input_this_round.take_byte()) << (8 * (m_S_inpos % 8));
70 }
71
72 // We reached the end of a sponge state block... permute() and start over
73 if(m_S_inpos == m_byterate) {
74 permute();
75 m_S_inpos = 0;
76 }
77 }
78}
constexpr auto load_le(ParamTs &&... params)
Definition loadstor.h:458

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.

53{ return m_byterate * 8; }

◆ byte_rate()

◆ capacity()

size_t Botan::Keccak_Permutation::capacity ( ) const
inline

Definition at line 51 of file keccak_perm.h.

51{ return m_capacity; }

Referenced by Keccak_Permutation().

◆ clear()

void Botan::Keccak_Permutation::clear ( )

Definition at line 42 of file keccak_perm.cpp.

42 {
43 zeroise(m_S);
44 m_S_inpos = 0;
45 m_S_outpos = 0;
46}
void zeroise(std::vector< T, Alloc > &vec)
Definition secmem.h:108

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.

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

◆ provider()

std::string Botan::Keccak_Permutation::provider ( ) const

Definition at line 32 of file keccak_perm.cpp.

32 {
33#if defined(BOTAN_HAS_KECCAK_PERM_BMI2)
34 if(CPUID::has_bmi2()) {
35 return "bmi2";
36 }
37#endif
38
39 return "base";
40}

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
outputthe designated output memory

Definition at line 80 of file keccak_perm.cpp.

80 {
81 BufferStuffer output_stuffer(output);
82
83 // Block-wise readout of the sponge state until enough bytes
84 // were filled into the output buffer
85 while(!output_stuffer.full()) {
86 const size_t bytes_in_this_round = std::min(output_stuffer.remaining_capacity(), m_byterate - m_S_outpos);
87 BufferStuffer output_this_round(output_stuffer.next(bytes_in_this_round));
88
89 // If necessary, try to get aligned with the sponge state's 64-bit integer array
90 for(; !output_this_round.full() && m_S_outpos % 8 != 0; ++m_S_outpos) {
91 output_this_round.next_byte() = static_cast<uint8_t>(m_S[m_S_outpos / 8] >> (8 * (m_S_outpos % 8)));
92 }
93
94 // Read out as many aligned 64-bit integer values as possible
95 for(; output_this_round.remaining_capacity() >= 8; m_S_outpos += 8) {
96 store_le(m_S[m_S_outpos / 8], output_this_round.next(8).data());
97 }
98
99 // Read remaining output data, causing misalignment, if necessary
100 for(; !output_this_round.full(); ++m_S_outpos) {
101 output_this_round.next_byte() = static_cast<uint8_t>(m_S[m_S_outpos / 8] >> (8 * (m_S_outpos % 8)));
102 }
103
104 // We reached the end of a sponge state block... permute() and start over
105 if(m_S_outpos == m_byterate) {
106 permute();
107 m_S_outpos = 0;
108 }
109 }
110}
constexpr auto store_le(ParamTs &&... params)
Definition loadstor.h:698

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: