Botan 3.14.1
Crypto and TLS for C&
sponge.h
Go to the documentation of this file.
1/*
2* Base helper class for implementing sponge constructions like Keccak or Ascon
3* (C) 2025 Jack Lloyd
4* 2025 René Meusel
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#ifndef BOTAN_SPONGE_CONSTRUCTION_H_
10#define BOTAN_SPONGE_CONSTRUCTION_H_
11
12#include <botan/assert.h>
13#include <botan/mem_ops.h>
14#include <botan/types.h>
15#include <array>
16#include <type_traits>
17
18namespace Botan {
19
20/**
21 * A generic sponge construction with a fixed state size defined in terms of
22 * "words" of an unsigned integral type.
23 *
24 * This is meant to be used as a base class for specific sponge constructions
25 * like Keccak or Ascon.
26 */
27template <size_t words, std::unsigned_integral word = uint64_t>
28class Sponge {
29 public:
30 using word_t = word;
31 using state_t = std::array<word, words>;
32 constexpr static size_t word_bytes = sizeof(word);
33 constexpr static size_t word_bits = word_bytes * 8;
34
35 struct Config final {
36 size_t bit_rate; /// The number of bits that using algorithms can modify between permutations
37 state_t initial_state; /// The state of the sponge state at initialization
38 };
39
40 public:
41 constexpr explicit Sponge(Config config) : m_S(config.initial_state), m_S_cursor(0), m_bit_rate(config.bit_rate) {
42 BOTAN_ARG_CHECK(m_bit_rate > 0 && m_bit_rate % word_bits == 0 && m_bit_rate < words * word_bits,
43 "Invalid sponge bit rate");
44 }
45
46 constexpr Sponge(const Sponge&) = default;
47 constexpr Sponge& operator=(const Sponge&) = default;
48 constexpr Sponge(Sponge&&) = default;
49 constexpr Sponge& operator=(Sponge&&) = default;
50
51 constexpr static size_t state_bytes() { return sizeof(state_t); }
52
53 constexpr static size_t state_bits() { return state_bytes() * 8; }
54
55 constexpr size_t bit_rate() const { return m_bit_rate; }
56
57 constexpr size_t byte_rate() const { return m_bit_rate / 8; }
58
59 constexpr size_t bit_capacity() const { return state_bits() - bit_rate(); }
60
61 constexpr size_t byte_capacity() const { return state_bytes() - byte_rate(); }
62
63 constexpr auto& state() { return m_S; }
64
65 size_t cursor() const { return m_S_cursor; }
66
67 size_t& _cursor() { return m_S_cursor; }
68
69 protected:
70 void reset_cursor() { m_S_cursor = 0; }
71
72 // This destructor is protected to prevent deletion through a polymorphic
73 // Sponge<>* pointer (hence the destructor doesn't need to be virtual).
74 // And it is constexpr to allow Sponge<> to be used in constexpr contexts,
75 // e.g. to define a constexpr initial sponge state.
76 constexpr ~Sponge() {
77 if(!std::is_constant_evaluated()) {
79 }
80 }
81
82 private:
83 state_t m_S;
84 size_t m_S_cursor;
85 size_t m_bit_rate;
86};
87
88} // namespace Botan
89
90#endif
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
void reset_cursor()
Definition sponge.h:70
constexpr Sponge & operator=(const Sponge &)=default
word word_t
Definition sponge.h:30
constexpr size_t bit_capacity() const
Definition sponge.h:59
constexpr Sponge(const Sponge &)=default
static constexpr size_t state_bytes()
Definition sponge.h:51
constexpr Sponge & operator=(Sponge &&)=default
static constexpr size_t word_bytes
Definition sponge.h:32
size_t & _cursor()
Definition sponge.h:67
constexpr auto & state()
Definition sponge.h:63
std::array< word, words > state_t
Definition sponge.h:31
constexpr size_t byte_rate() const
Definition sponge.h:57
constexpr size_t byte_capacity() const
Definition sponge.h:61
constexpr ~Sponge()
Definition sponge.h:76
constexpr size_t bit_rate() const
Definition sponge.h:55
size_t cursor() const
Definition sponge.h:65
static constexpr size_t word_bits
Definition sponge.h:33
constexpr Sponge(Sponge &&)=default
static constexpr size_t state_bits()
Definition sponge.h:53
constexpr Sponge(Config config)
Definition sponge.h:41
void secure_scrub_memory(void *ptr, size_t n)
Definition mem_utils.cpp:24
std::conditional_t< HasNative64BitRegisters, std::uint64_t, uint32_t > word
The native machine word, used as the limb type for multiprecision integers.
Definition types.h:131
state_t initial_state
The number of bits that using algorithms can modify between permutations.
Definition sponge.h:37