Botan 3.9.0
Crypto and TLS for C&
Public Member Functions | List of all members
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 24 of file keccak_perm.cpp.

24 :
25 m_capacity(capacity),
26 m_byterate((1600 - capacity) / 8),
27 m_custom_padding(custom_padding),
28 m_custom_padding_bit_len(custom_padding_bit_len),
29 m_S(25), // 1600 bit
30 m_S_inpos(0),
31 m_S_outpos(0) {
32 BOTAN_ARG_CHECK(capacity % 64 == 0, "capacity must be a multiple of 64");
33}
BOTAN_ARG_CHECK
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
Botan::Keccak_Permutation::capacity
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 51 of file keccak_perm.cpp.

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

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

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

Definition at line 55 of file keccak_perm.h.

55{ return m_byterate; }

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

45 {
46 zeroise(m_S);
47 m_S_inpos = 0;
48 m_S_outpos = 0;
49}
Botan::zeroise
void zeroise(std::vector< T, Alloc > &vec)
Definition secmem.h:125

References Botan::zeroise().

◆ finish()

void Botan::Keccak_Permutation::finish ( )

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

Definition at line 115 of file keccak_perm.cpp.

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

◆ provider()

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

Definition at line 35 of file keccak_perm.cpp.

35 {
36#if defined(BOTAN_HAS_KECCAK_PERM_BMI2)
37 if(auto feat = CPUID::check(CPUID::Feature::BMI)) {
38 return *feat;
39 }
40#endif
41
42 return "base";
43}
Botan::CPUID::check
static std::optional< std::string > check(CPUID::Feature feat)
Definition cpuid.h:67

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

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

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

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:
Generated by doxygen 1.14.0