Botan 3.14.1
Crypto and TLS for C&
hash_engine.cpp
Go to the documentation of this file.
1/*
2* (C) 2026 Jack Lloyd
3*
4* Botan is released under the Simplified BSD License (see license.txt)
5*/
6
7#include <botan/internal/hash_engine.h>
8
9#include <botan/assert.h>
10#include <botan/exceptn.h>
11#include <botan/hash.h>
12#include <algorithm>
13
14#if defined(BOTAN_HAS_HASH_ENGINE_SHA2_32)
15 #include <botan/internal/hash_engine_sha2_32.h>
16#endif
17
18#if defined(BOTAN_HAS_HASH_ENGINE_SHA2_64)
19 #include <botan/internal/hash_engine_sha2_64.h>
20#endif
21
22#if defined(BOTAN_HAS_HASH_ENGINE_KECCAK)
23 #include <botan/internal/hash_engine_keccak.h>
24#endif
25
26#if defined(BOTAN_HAS_THREAD_UTILS)
27 #include <botan/internal/bit_ops.h>
28 #include <botan/internal/thread_pool.h>
29 #include <atomic>
30 #include <exception>
31#endif
32
33namespace Botan {
34
35namespace {
36
37class Base_Hash_Engine final : public Hash_Engine {
38 public:
39 Base_Hash_Engine(std::unique_ptr<HashFunction> hash, std::span<const uint8_t> common_prefix) :
40 Hash_Engine(common_prefix), m_hash(std::move(hash)) {}
41
42 std::string name() const override { return m_hash->name(); }
43
44 std::string provider() const override { return "base"; }
45
46 size_t output_length() const override { return m_hash->output_length(); }
47
48 size_t parallelism() const override { return 1; }
49
50 void batch_hash(std::span<std::span<uint8_t>> outputs,
51 std::span<std::span<const uint8_t>> inputs1,
52 std::span<std::span<const uint8_t>> inputs2) override {
53 check_batch_args(outputs, inputs1, inputs2);
54
55 for(size_t i = 0; i != inputs1.size(); ++i) {
56 m_hash->update(common_prefix());
57 m_hash->update(inputs1[i]);
58 if(!inputs2.empty()) {
59 m_hash->update(inputs2[i]);
60 }
61 m_hash->final(outputs[i].first(output_length()));
62 }
63 }
64
65 private:
66 std::unique_ptr<HashFunction> m_hash;
67};
68
69std::unique_ptr<Hash_Engine> make_base_engine(std::string_view hash_fn,
70 std::span<const uint8_t> common_prefix,
71 std::string_view provider) {
72#if defined(BOTAN_HAS_HASH_ENGINE_SHA2_32)
73 if(auto engine = create_sha2_32_mb_engine(hash_fn, common_prefix, provider)) {
74 return engine;
75 }
76#endif
77
78#if defined(BOTAN_HAS_HASH_ENGINE_SHA2_64)
79 if(auto engine = create_sha2_64_mb_engine(hash_fn, common_prefix, provider)) {
80 return engine;
81 }
82#endif
83
84#if defined(BOTAN_HAS_HASH_ENGINE_KECCAK)
85 if(auto engine = create_keccak_mb_engine(hash_fn, common_prefix, provider)) {
86 return engine;
87 }
88#endif
89
90 if(provider.empty() || provider == "base") {
91 if(auto hash = HashFunction::create(hash_fn)) {
92 return std::make_unique<Base_Hash_Engine>(std::move(hash), common_prefix);
93 }
94 }
95
96 return nullptr;
97}
98
99#if defined(BOTAN_HAS_THREAD_UTILS)
100
101class Threaded_Hash_Engine final : public Hash_Engine {
102 public:
103 Threaded_Hash_Engine(std::string_view hash_fn,
104 std::unique_ptr<Hash_Engine> first_engine,
105 std::span<const uint8_t> common_prefix) :
106 Hash_Engine(common_prefix), m_hash_fn(hash_fn), m_pool(Thread_Pool::global_instance()) {
107 // Engines beyond the first are only instantiated once a batch is
108 // actually large enough to be worth splitting over threads
109 BOTAN_ASSERT_NONNULL(first_engine);
110 m_engines.push_back(std::move(first_engine));
111 }
112
113 std::string name() const override { return m_engines[0]->name(); }
114
115 std::string provider() const override { return "threads"; }
116
117 size_t output_length() const override { return m_engines[0]->output_length(); }
118
119 size_t parallelism() const override {
120 return std::max<size_t>(m_pool.worker_count(), 1) * m_engines[0]->parallelism();
121 }
122
123 size_t uncached_prefix_bytes() const override { return m_engines[0]->uncached_prefix_bytes(); }
124
125 void batch_hash(std::span<std::span<uint8_t>> outputs,
126 std::span<std::span<const uint8_t>> inputs1,
127 std::span<std::span<const uint8_t>> inputs2) override {
128 check_batch_args(outputs, inputs1, inputs2);
129
130 const size_t count = inputs1.size();
131 if(count == 0) {
132 return;
133 }
134
135 // Both inputs and outputs count towards the work estimate; for
136 // XOFs with long outputs squeezing dominates. The +64 approximates
137 // padding and finalization overhead.
138 const size_t per_hash_bytes = m_engines[0]->uncached_prefix_bytes() + inputs1[0].size() +
139 (inputs2.empty() ? 0 : inputs2[0].size()) + output_length() + 64;
140
141 // Chunk work to not spread too thinly since just queuing the work
142 // in the pool has nonzero overhead.
143 constexpr size_t MIN_BYTES_PER_THREAD = 32 * 1024;
144 const size_t by_bytes = (count * per_hash_bytes) / MIN_BYTES_PER_THREAD;
145
146 if(count < 2 || by_bytes < 2) {
147 m_engines[0]->batch_hash(outputs, inputs1, inputs2);
148 return;
149 }
150
151 // A SIMD engine hashes a group of lanes at once, so there is no
152 // point in more threads than groups, nor in threads that do not
153 // reduce the maximum number of groups any one thread must hash
154 const size_t lanes = m_engines[0]->parallelism();
155 const size_t groups = (count + lanes - 1) / lanes;
156
157 const size_t threads = [&]() {
158 const size_t t = std::min({m_pool.worker_count(), groups, by_bytes});
159
160 if(t <= 1) {
161 return t;
162 } else {
163 const size_t rounds = (groups + t - 1) / t;
164 return (groups + rounds - 1) / rounds;
165 }
166 }();
167
168 if(threads <= 1) {
169 m_engines[0]->batch_hash(outputs, inputs1, inputs2);
170 return;
171 }
172
173 while(m_engines.size() < threads) {
174 auto eng = make_base_engine(m_hash_fn, common_prefix(), "");
175 BOTAN_ASSERT_NONNULL(eng); // previous attempt already succeeded
176 m_engines.push_back(std::move(eng));
177 }
178
179 dispatch(threads, count, [&](size_t t, size_t offset, size_t n) {
180 const auto in2 = inputs2.empty() ? inputs2 : inputs2.subspan(offset, n);
181 m_engines[t]->batch_hash(outputs.subspan(offset, n), inputs1.subspan(offset, n), in2);
182 });
183 }
184
185 private:
186 template <typename F>
187 void dispatch(size_t threads, size_t count, F work_fn) {
188 const size_t lanes = m_engines[0]->parallelism();
189 // Roughly four chunks per thread, each a whole number of lanes
190 const size_t chunk = lanes * std::max<size_t>(1, ceil_division(count / (4 * threads), lanes));
191
192 std::atomic<size_t> next = 0;
193
194 const auto claim_chunks = [&](size_t t) {
195 for(;;) {
196 const size_t offset = next.fetch_add(chunk);
197 if(offset >= count) {
198 break;
199 }
200 work_fn(t, offset, std::min(chunk, count - offset));
201 }
202 };
203
204 // The calling thread works through chunks as well, using the
205 // last engine, rather than just waiting on the pool
206 std::vector<Joining_Future<void>> futures;
207 futures.reserve(threads - 1);
208
209 for(size_t t = 0; t != threads - 1; ++t) {
210 futures.push_back(m_pool.run(claim_chunks, t));
211 }
212
213 // The workers reference this frame, so whatever happens every
214 // one of them must have finished before returning or unwinding
215 std::exception_ptr error;
216
217 try {
218 // Hash the last chunk in the current thread:
219 claim_chunks(threads - 1);
220 } catch(...) {
221 error = std::current_exception();
222 }
223
224 for(auto& f : futures) {
225 try {
226 f.get();
227 } catch(...) {
228 if(!error) {
229 error = std::current_exception();
230 }
231 }
232 }
233
234 if(error) {
235 std::rethrow_exception(error);
236 }
237 }
238
239 std::string m_hash_fn;
240 Thread_Pool& m_pool;
241 std::vector<std::unique_ptr<Hash_Engine>> m_engines;
242};
243
244#endif
245
246} // namespace
247
248void Hash_Engine::check_batch_args(std::span<std::span<uint8_t>> outputs,
249 std::span<std::span<const uint8_t>> inputs1,
250 std::span<std::span<const uint8_t>> inputs2) const {
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}
267
268std::unique_ptr<Hash_Engine> Hash_Engine::create_or_null(std::string_view hash_fn,
269 std::span<const uint8_t> common_prefix,
270 std::string_view provider) {
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}
290
291std::unique_ptr<Hash_Engine> Hash_Engine::create_or_throw(std::string_view hash_fn,
292 std::span<const uint8_t> common_prefix,
293 std::string_view provider) {
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}
300
301std::vector<std::string> Hash_Engine::possible_providers(std::string_view hash_fn) {
302 BOTAN_UNUSED(hash_fn);
303 return {"base", "threads", "neon", "ssse3", "avx2", "avx512"};
304}
305
306} // namespace Botan
#define BOTAN_UNUSED
Definition assert.h:151
#define BOTAN_ASSERT_NONNULL(ptr)
Definition assert.h:121
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
static std::unique_ptr< HashFunction > create(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:112
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
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)
virtual size_t output_length() const =0
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="")
virtual std::string provider() const =0
static Thread_Pool & global_instance()
const char * name
Definition ffi_tls.h:59
std::unique_ptr< Hash_Engine > create_sha2_32_mb_engine(std::string_view hash_fn, std::span< const uint8_t > common_prefix, std::string_view provider)
BOTAN_FORCE_INLINE constexpr T ceil_division(T a, T b)
Definition bit_ops.h:167
std::unique_ptr< Hash_Engine > create_sha2_64_mb_engine(std::string_view hash_fn, std::span< const uint8_t > common_prefix, std::string_view provider)
std::unique_ptr< Hash_Engine > create_keccak_mb_engine(std::string_view hash_fn, std::span< const uint8_t > common_prefix, std::string_view provider)