Botan 3.14.1
Crypto and TLS for C&
Botan::MDx_MB_Engine< W > Class Template Referencefinal

#include <hash_engine_mdx.h>

Inheritance diagram for Botan::MDx_MB_Engine< W >:
Botan::Hash_Engine

Public Types

using compress_fn = void (*)(uint8_t* states, const uint8_t* const* blocks, size_t nblocks)
using extract_fn = void (*)(const uint8_t* states, uint8_t* digests)

Public Member Functions

void batch_hash (std::span< std::span< uint8_t > > outputs, std::span< std::span< const uint8_t > > inputs)
void batch_hash (std::span< std::span< uint8_t > > outputs, std::span< std::span< const uint8_t > > inputs1, std::span< std::span< const uint8_t > > inputs2) override
 MDx_MB_Engine (std::string_view name, size_t output_length, std::span< const uint8_t > common_prefix, std::string_view provider, size_t lanes, size_t block_bytes, size_t ctr_bytes, std::span< const W > midstate, compress_fn compress, extract_fn extract)
std::string name () const override
size_t output_length () const override
size_t parallelism () const override
std::string provider () const override
size_t uncached_prefix_bytes () const override

Static Public Member Functions

static std::unique_ptr< Hash_Engine > create_or_null (std::string_view hash_fn, std::span< const uint8_t > common_prefix={}, std::string_view provider="")
static std::unique_ptr< Hash_Engine > create_or_throw (std::string_view hash_fn, std::span< const uint8_t > common_prefix={}, std::string_view provider="")
static std::vector< std::string > possible_providers (std::string_view hash_fn)

Protected Member Functions

void check_batch_args (std::span< std::span< uint8_t > > outputs, std::span< std::span< const uint8_t > > inputs1, std::span< std::span< const uint8_t > > inputs2) const
std::span< const uint8_t > common_prefix () const

Detailed Description

template<std::unsigned_integral W>
class Botan::MDx_MB_Engine< W >

Generic multi-buffer engine for big-endian Merkle-Damgard hashes

The states buffer passed to the compression function holds the 8 chaining variables for each lane, as little-endian words in variable-major order (all lanes of A, then all lanes of B, ...). blocks[l] points to the first of nblocks contiguous blocks for lane l.

The extract function transposes the states into digests, which holds the full (untruncated) big-endian digest of each lane in lane order.

Definition at line 33 of file hash_engine_mdx.h.

Member Typedef Documentation

◆ compress_fn

template<std::unsigned_integral W>
using Botan::MDx_MB_Engine< W >::compress_fn = void (*)(uint8_t* states, const uint8_t* const* blocks, size_t nblocks)

Definition at line 35 of file hash_engine_mdx.h.

◆ extract_fn

template<std::unsigned_integral W>
using Botan::MDx_MB_Engine< W >::extract_fn = void (*)(const uint8_t* states, uint8_t* digests)

Definition at line 36 of file hash_engine_mdx.h.

Constructor & Destructor Documentation

◆ MDx_MB_Engine()

template<std::unsigned_integral W>
Botan::MDx_MB_Engine< W >::MDx_MB_Engine ( std::string_view name,
size_t output_length,
std::span< const uint8_t > common_prefix,
std::string_view provider,
size_t lanes,
size_t block_bytes,
size_t ctr_bytes,
std::span< const W > midstate,
compress_fn compress,
extract_fn extract )
inline

Definition at line 38 of file hash_engine_mdx.h.

47 :
49 m_name(name),
50 m_provider(provider),
51 m_output_length(output_length),
52 m_lanes(lanes),
53 m_block_bytes(block_bytes),
54 m_ctr_bytes(ctr_bytes),
55 m_prefix_full_bytes(common_prefix.size() - common_prefix.size() % block_bytes),
56 m_compress(compress),
57 m_extract(extract),
58 m_initial_states(8 * lanes * sizeof(W)),
59 m_states(8 * lanes * sizeof(W)),
60 m_digests(8 * lanes * sizeof(W)),
61 m_ptrs(lanes) {
62 BOTAN_ASSERT_NOMSG(midstate.size() == 8);
63
64 for(size_t j = 0; j != 8; ++j) {
65 for(size_t l = 0; l != m_lanes; ++l) {
66 store_le(midstate[j], &m_initial_states[(j * m_lanes + l) * sizeof(W)]);
67 }
68 }
69 }
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
std::span< const uint8_t > common_prefix() const
Hash_Engine(const Hash_Engine &other)=delete
std::string name() const override
size_t output_length() const override
std::string provider() const override
constexpr auto store_le(ParamTs &&... params)
Definition loadstor.h:736

References BOTAN_ASSERT_NOMSG, Botan::Hash_Engine::common_prefix(), Botan::Hash_Engine::Hash_Engine(), name(), output_length(), provider(), and Botan::store_le().

Member Function Documentation

◆ batch_hash() [1/2]

void Botan::Hash_Engine::batch_hash ( std::span< std::span< uint8_t > > outputs,
std::span< std::span< const uint8_t > > inputs )
inlineinherited

Hash many inputs

Computes H(common_prefix || inputs[i]) into outputs[i]. Each input must be exactly identical length.

outputs[i] may alias inputs[i], but must not otherwise overlap any other input or output.

Definition at line 57 of file hash_engine.h.

57 {
58 batch_hash(outputs, inputs, {});
59 }
void batch_hash(std::span< std::span< uint8_t > > outputs, std::span< std::span< const uint8_t > > inputs)
Definition hash_engine.h:57

References batch_hash().

Referenced by batch_hash(), and Botan::lmots_compute_pubkeys().

◆ batch_hash() [2/2]

template<std::unsigned_integral W>
void Botan::MDx_MB_Engine< W >::batch_hash ( std::span< std::span< uint8_t > > outputs,
std::span< std::span< const uint8_t > > inputs1,
std::span< std::span< const uint8_t > > inputs2 )
inlineoverridevirtual

Hash many inputs, each formed from two parts

Computes H(common_prefix || inputs1[i] || inputs2[i]) into outputs[i]. All inputs1 must be exactly identical length, as must all inputs2. Alternately inputs2 may be an empty list.

outputs[i] may alias inputs1[i] and/or inputs2[i], but must not otherwise overlap any other input or output.

Implements Botan::Hash_Engine.

Definition at line 81 of file hash_engine_mdx.h.

83 {
85
86 const size_t count = inputs1.size();
87 if(count == 0) {
88 return;
89 }
90
91 // The logical stream hashed for lane i is
92 // rem || inputs1[i] || inputs2[i] || padding
93 // where rem is the part of the prefix not covered by the midstate
94 const auto rem = common_prefix().subspan(m_prefix_full_bytes);
95 const size_t r = rem.size();
96 const size_t len1 = inputs1[0].size();
97 const size_t len2 = inputs2.empty() ? 0 : inputs2[0].size();
98
99 // Checked so that the padded length and the offsets derived from
100 // it cannot wrap for huge inputs, which matters on 32-bit targets
101 const auto padded_end = checked_add(r, len1, len2, 1 + m_ctr_bytes + (m_block_bytes - 1));
102 BOTAN_ARG_CHECK(padded_end.has_value(), "Hash_Engine::batch_hash inputs too long");
103
104 const size_t stream_len = r + len1 + len2;
105 const size_t blocks = *padded_end / m_block_bytes;
106 const size_t padded_len = m_block_bytes * blocks;
107 const uint64_t total_bits = 8 * static_cast<uint64_t>(common_prefix().size() + len1 + len2);
108
109 // Ranges of blocks lying entirely within one input are hashed
110 // directly from the caller's buffers. All other blocks are
111 // assembled in scratch, each in its own slot, since everything
112 // in them except the input bytes is the same for every lane.
113 const size_t d1_lo = (r + m_block_bytes - 1) / m_block_bytes;
114 const size_t d1_hi = (r + len1) / m_block_bytes;
115 const size_t d2_lo = (r + len1 + m_block_bytes - 1) / m_block_bytes;
116 const size_t d2_hi = (r + len1 + len2) / m_block_bytes;
117
119 size_t nsteps = 0;
120 size_t scratch_blocks = 0;
121
122 for(size_t b = 0; b < blocks;) {
123 BOTAN_ASSERT_NOMSG(nsteps < MAX_STEPS);
124 Step& step = steps[nsteps++];
125
126 if(b >= d1_lo && b < d1_hi) {
127 step = Step{Step::Kind::Direct1, b, d1_hi, 0};
128 } else if(b >= d2_lo && b < d2_hi) {
129 step = Step{Step::Kind::Direct2, b, d2_hi, 0};
130 } else {
131 size_t e = blocks;
132 if(b < d1_lo && d1_lo < d1_hi) {
133 e = std::min(e, d1_lo);
134 }
135 if(b < d2_lo && d2_lo < d2_hi) {
136 e = std::min(e, d2_lo);
137 }
138 step = Step{Step::Kind::Scratch, b, e, scratch_blocks};
139 scratch_blocks += e - b;
140 }
141
142 b = step.hi;
143 }
144
145 const size_t lane_stride = scratch_blocks * m_block_bytes;
146 if(m_scratch.size() < m_lanes * lane_stride) {
147 m_scratch.resize(m_lanes * lane_stride);
148 }
149 const auto scratch = [&](size_t lane, const Step& step) {
150 return &m_scratch[lane * lane_stride + step.slot * m_block_bytes];
151 };
152
153 // Write the lane invariant parts of the scratch blocks: the
154 // prefix remainder, the padding byte, zeros and the counter
155 for(size_t i = 0; i != nsteps; ++i) {
156 const Step& step = steps[i];
157 if(step.kind != Step::Kind::Scratch) {
158 continue;
159 }
160 const size_t lo = step.lo * m_block_bytes;
161 const size_t hi = step.hi * m_block_bytes;
162
163 for(size_t l = 0; l != m_lanes; ++l) {
165 clear_mem(dest, hi - lo);
166 copy_overlap(dest, lo, hi, rem, 0);
167 if(stream_len >= lo && stream_len < hi) {
168 dest[stream_len - lo] = 0x80;
169 }
170 // Low 8 bytes of the counter; any high bytes stay zero
171 if(hi == padded_len) {
173 }
174 }
175 }
176
177 for(size_t base = 0; base < count; base += m_lanes) {
178 // Excess lanes of the last batch just recompute the final message
179 const auto lane_idx = [&](size_t l) { return std::min(base + l, count - 1); };
180
181 copy_mem(m_states, m_initial_states);
182
183 for(size_t i = 0; i != nsteps; ++i) {
184 const Step& step = steps[i];
185 const size_t lo = step.lo * m_block_bytes;
186 const size_t hi = step.hi * m_block_bytes;
187
188 if(step.kind == Step::Kind::Direct1) {
189 for(size_t l = 0; l != m_lanes; ++l) {
190 m_ptrs[l] = inputs1[lane_idx(l)].data() + (lo - r);
191 }
192 } else if(step.kind == Step::Kind::Direct2) {
193 for(size_t l = 0; l != m_lanes; ++l) {
194 m_ptrs[l] = inputs2[lane_idx(l)].data() + (lo - r - len1);
195 }
196 } else {
197 for(size_t l = 0; l != m_lanes; ++l) {
199 copy_overlap(dest, lo, hi, inputs1[lane_idx(l)], r);
200 if(!inputs2.empty()) {
201 copy_overlap(dest, lo, hi, inputs2[lane_idx(l)], r + len1);
202 }
203 m_ptrs[l] = dest;
204 }
205 }
206
207 m_compress(m_states.data(), m_ptrs.data(), step.hi - step.lo);
208 }
209
210 m_extract(m_states.data(), m_digests.data());
211
212 const size_t used_lanes = std::min(m_lanes, count - base);
213 for(size_t l = 0; l != used_lanes; ++l) {
214 copy_mem(outputs[base + l].first(m_output_length),
215 std::span(m_digests).subspan(l * DIGEST_BYTES, m_output_length));
216 }
217 }
218 }
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
void check_batch_args(std::span< std::span< uint8_t > > outputs, std::span< std::span< const uint8_t > > inputs1, std::span< std::span< const uint8_t > > inputs2) const
constexpr std::optional< T > checked_add(T a, T b)
Definition int_utils.h:19
constexpr void copy_mem(T *out, const T *in, size_t n)
Definition mem_ops.h:144
constexpr auto store_be(ParamTs &&... params)
Definition loadstor.h:745
constexpr void clear_mem(T *ptr, size_t n)
Definition mem_ops.h:118

References BOTAN_ARG_CHECK, BOTAN_ASSERT_NOMSG, Botan::Hash_Engine::check_batch_args(), Botan::checked_add(), Botan::clear_mem(), Botan::Hash_Engine::common_prefix(), Botan::copy_mem(), and Botan::store_be().

◆ check_batch_args()

void Botan::Hash_Engine::check_batch_args ( std::span< std::span< uint8_t > > outputs,
std::span< std::span< const uint8_t > > inputs1,
std::span< std::span< const uint8_t > > inputs2 ) const
protectedinherited

Verify the batch_hash argument contract, throwing Invalid_Argument if violated

Definition at line 248 of file hash_engine.cpp.

250 {
251 BOTAN_ARG_CHECK(outputs.size() == inputs1.size(),
252 "Hash_Engine::batch_hash requires same number of inputs and outputs");
253 BOTAN_ARG_CHECK(inputs2.empty() || inputs2.size() == inputs1.size(),
254 "Hash_Engine::batch_hash second inputs must be empty or match first");
255
256 const size_t out_len = output_length();
257
258 for(size_t i = 0; i != inputs1.size(); ++i) {
259 BOTAN_ARG_CHECK(inputs1[i].size() == inputs1[0].size(), "Hash_Engine::batch_hash inputs must be equal length");
260 BOTAN_ARG_CHECK(outputs[i].size() >= out_len, "Hash_Engine::batch_hash output buffer too small");
261 }
262
263 for(size_t i = 0; i != inputs2.size(); ++i) {
264 BOTAN_ARG_CHECK(inputs2[i].size() == inputs2[0].size(), "Hash_Engine::batch_hash inputs must be equal length");
265 }
266}
virtual size_t output_length() const =0

References BOTAN_ARG_CHECK, and output_length().

Referenced by Botan::MDx_MB_Engine< W >::batch_hash().

◆ common_prefix()

std::span< const uint8_t > Botan::Hash_Engine::common_prefix ( ) const
inlineprotectedinherited

◆ create_or_null()

std::unique_ptr< Hash_Engine > Botan::Hash_Engine::create_or_null ( std::string_view hash_fn,
std::span< const uint8_t > common_prefix = {},
std::string_view provider = "" )
staticinherited

Create a new Hash_Engine

Parameters
hash_fnthe hash function to compute
common_prefiximplicitly prepended to each message hashed; implementations may precompute the resulting hash state
providerif set, use this specific implementation
Returns
new object or nullptr if not available

Definition at line 268 of file hash_engine.cpp.

270 {
271#if defined(BOTAN_HAS_THREAD_UTILS)
272 if(provider.empty() || provider == "threads") {
273 // An explicit request for threads fails if the pool is disabled. The
274 // default still wraps the engine, since an executor may be installed
275 // later; the wrapper checks the worker count on each batch.
276 if(provider == "threads" && Thread_Pool::global_instance().worker_count() < 2) {
277 return nullptr;
278 }
279
280 if(auto engine = make_base_engine(hash_fn, common_prefix, "")) {
281 return std::make_unique<Threaded_Hash_Engine>(hash_fn, std::move(engine), common_prefix);
282 }
283
284 return nullptr;
285 }
286#endif
287
288 return make_base_engine(hash_fn, common_prefix, provider);
289}
virtual std::string provider() const =0
static Thread_Pool & global_instance()

References common_prefix(), Botan::Thread_Pool::global_instance(), and provider().

Referenced by create_or_throw().

◆ create_or_throw()

std::unique_ptr< Hash_Engine > Botan::Hash_Engine::create_or_throw ( std::string_view hash_fn,
std::span< const uint8_t > common_prefix = {},
std::string_view provider = "" )
staticinherited

Create a new Hash_Engine

Parameters
hash_fnthe hash function to compute
common_prefiximplicitly prepended to each message hashed; implementations may precompute the resulting hash state
providerif set, use this specific implementation

The default provider splits sufficiently large batches over the global Thread_Pool, whose threads are started on the first such batch, or over the executor installed with Work_Executor::set_global.

Throws Lookup_Error if the hash function or requested provider is not available

Definition at line 291 of file hash_engine.cpp.

293 {
294 if(auto engine = Hash_Engine::create_or_null(hash_fn, common_prefix, provider)) {
295 return engine;
296 } else {
297 throw Lookup_Error("Hash_Engine", hash_fn, provider);
298 }
299}
static std::unique_ptr< Hash_Engine > create_or_null(std::string_view hash_fn, std::span< const uint8_t > common_prefix={}, std::string_view provider="")

References common_prefix(), create_or_null(), and provider().

Referenced by batch_hash(), Botan::create_shake_row_generator(), Botan::XMSS_Hash::f_batch(), Botan::XMSS_Hash::h_batch(), Botan::lmots_compute_pubkey_from_sig(), Botan::Kyber_Symmetric_Primitives::shake_XOF_batch(), Botan::LMOTS_Private_Key::sign(), and Botan::Sphincs_Hash_Functions_Sha2::Sphincs_Hash_Functions_Sha2().

◆ name()

template<std::unsigned_integral W>
std::string Botan::MDx_MB_Engine< W >::name ( ) const
inlineoverridevirtual
Returns
name of the hash

Implements Botan::Hash_Engine.

Definition at line 71 of file hash_engine_mdx.h.

71{ return m_name; }

Referenced by MDx_MB_Engine().

◆ output_length()

template<std::unsigned_integral W>
size_t Botan::MDx_MB_Engine< W >::output_length ( ) const
inlineoverridevirtual
Returns
output length of the hash function

Implements Botan::Hash_Engine.

Definition at line 75 of file hash_engine_mdx.h.

75{ return m_output_length; }

Referenced by MDx_MB_Engine().

◆ parallelism()

template<std::unsigned_integral W>
size_t Botan::MDx_MB_Engine< W >::parallelism ( ) const
inlineoverridevirtual
Returns
native parallelism of this implementation

Implements Botan::Hash_Engine.

Definition at line 77 of file hash_engine_mdx.h.

77{ return m_lanes; }

◆ possible_providers()

std::vector< std::string > Botan::Hash_Engine::possible_providers ( std::string_view hash_fn)
staticinherited

Return a list of possible providers for this hash function

Definition at line 301 of file hash_engine.cpp.

301 {
302 BOTAN_UNUSED(hash_fn);
303 return {"base", "threads", "neon", "ssse3", "avx2", "avx512"};
304}
#define BOTAN_UNUSED
Definition assert.h:151

References BOTAN_UNUSED.

◆ provider()

template<std::unsigned_integral W>
std::string Botan::MDx_MB_Engine< W >::provider ( ) const
inlineoverridevirtual
Returns
provider of the engine (eg "base", "avx2", "avx512")

Implements Botan::Hash_Engine.

Definition at line 73 of file hash_engine_mdx.h.

73{ return m_provider; }

Referenced by MDx_MB_Engine().

◆ uncached_prefix_bytes()

template<std::unsigned_integral W>
size_t Botan::MDx_MB_Engine< W >::uncached_prefix_bytes ( ) const
inlineoverridevirtual
Returns
bytes of the common prefix hashed again for each message, rather than being covered by a precomputed state

Reimplemented from Botan::Hash_Engine.

Definition at line 79 of file hash_engine_mdx.h.

79{ return common_prefix().size() - m_prefix_full_bytes; }

References Botan::Hash_Engine::common_prefix().


The documentation for this class was generated from the following file: