Botan 3.14.1
Crypto and TLS for C&
hash_engine.h
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#ifndef BOTAN_HASH_ENGINE_H_
8#define BOTAN_HASH_ENGINE_H_
9
10#include <botan/secmem.h>
11#include <botan/types.h>
12#include <memory>
13#include <span>
14#include <string>
15#include <string_view>
16#include <vector>
17
18namespace Botan {
19
21 public:
22 /**
23 * @return name of the hash
24 */
25 virtual std::string name() const = 0;
26
27 /**
28 * @return provider of the engine (eg "base", "avx2", "avx512")
29 */
30 virtual std::string provider() const = 0;
31
32 /**
33 * @return output length of the hash function
34 */
35 virtual size_t output_length() const = 0;
36
37 /**
38 * @return native parallelism of this implementation
39 */
40 virtual size_t parallelism() const = 0;
41
42 /**
43 * @return bytes of the common prefix hashed again for each message,
44 * rather than being covered by a precomputed state
45 */
46 virtual size_t uncached_prefix_bytes() const { return common_prefix().size(); }
47
48 /**
49 * Hash many inputs
50 *
51 * Computes H(common_prefix || inputs[i]) into outputs[i]. Each input
52 * must be exactly identical length.
53 *
54 * outputs[i] may alias inputs[i], but must not otherwise overlap any
55 * other input or output.
56 */
57 void batch_hash(std::span<std::span<uint8_t>> outputs, std::span<std::span<const uint8_t>> inputs) {
58 batch_hash(outputs, inputs, {});
59 }
60
61 /**
62 * Hash many inputs, each formed from two parts
63 *
64 * Computes H(common_prefix || inputs1[i] || inputs2[i]) into
65 * outputs[i]. All inputs1 must be exactly identical length, as must all
66 * inputs2. Alternately inputs2 may be an empty list.
67 *
68 * outputs[i] may alias inputs1[i] and/or inputs2[i], but must not
69 * otherwise overlap any other input or output.
70 */
71 virtual void batch_hash(std::span<std::span<uint8_t>> outputs,
72 std::span<std::span<const uint8_t>> inputs1,
73 std::span<std::span<const uint8_t>> inputs2) = 0;
74
75 /**
76 * Create a new Hash_Engine
77 *
78 * @param hash_fn the hash function to compute
79 * @param common_prefix implicitly prepended to each message hashed;
80 * implementations may precompute the resulting hash state
81 * @param provider if set, use this specific implementation
82 *
83 * The default provider splits sufficiently large batches over the
84 * global Thread_Pool, whose threads are started on the first such
85 * batch, or over the executor installed with Work_Executor::set_global.
86 *
87 * Throws Lookup_Error if the hash function or requested provider is
88 * not available
89 */
90 static std::unique_ptr<Hash_Engine> create_or_throw(std::string_view hash_fn,
91 std::span<const uint8_t> common_prefix = {},
92 std::string_view provider = "");
93
94 /**
95 * Create a new Hash_Engine
96 *
97 * @param hash_fn the hash function to compute
98 * @param common_prefix implicitly prepended to each message hashed;
99 * implementations may precompute the resulting hash state
100 * @param provider if set, use this specific implementation
101 * @return new object or nullptr if not available
102 */
103 static std::unique_ptr<Hash_Engine> create_or_null(std::string_view hash_fn,
104 std::span<const uint8_t> common_prefix = {},
105 std::string_view provider = "");
106
107 /**
108 * Return a list of possible providers for this hash function
109 */
110 static std::vector<std::string> possible_providers(std::string_view hash_fn);
111
112 Hash_Engine(const Hash_Engine& other) = delete;
113 Hash_Engine(Hash_Engine&& other) = delete;
114
115 Hash_Engine& operator=(const Hash_Engine& other) = delete;
117
118 virtual ~Hash_Engine() = default;
119
120 protected:
121 explicit Hash_Engine(std::span<const uint8_t> common_prefix) :
122 m_common_prefix(common_prefix.begin(), common_prefix.end()) {}
123
124 /**
125 * @return the prefix implicitly prepended to each message
126 */
127 std::span<const uint8_t> common_prefix() const { return m_common_prefix; }
128
129 /**
130 * Verify the batch_hash argument contract, throwing Invalid_Argument
131 * if violated
132 */
133 void check_batch_args(std::span<std::span<uint8_t>> outputs,
134 std::span<std::span<const uint8_t>> inputs1,
135 std::span<std::span<const uint8_t>> inputs2) const;
136
137 private:
138 secure_vector<uint8_t> m_common_prefix;
139};
140
141} // namespace Botan
142
143#endif
#define BOTAN_TEST_API
Definition api.h:41
Hash_Engine & operator=(const Hash_Engine &other)=delete
virtual 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)=0
virtual size_t parallelism() const =0
Hash_Engine & operator=(Hash_Engine &&other)=delete
Hash_Engine(Hash_Engine &&other)=delete
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="")
virtual size_t output_length() const =0
void batch_hash(std::span< std::span< uint8_t > > outputs, std::span< std::span< const uint8_t > > inputs)
Definition hash_engine.h:57
virtual ~Hash_Engine()=default
virtual size_t uncached_prefix_bytes() const
Definition hash_engine.h:46
Hash_Engine(std::span< const uint8_t > common_prefix)
Hash_Engine(const Hash_Engine &other)=delete
virtual std::string name() const =0
virtual std::string provider() const =0
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128