Botan 3.14.1
Crypto and TLS for C&
Botan::Hash_Engine Class Referenceabstract

#include <hash_engine.h>

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

Public Member Functions

void batch_hash (std::span< std::span< uint8_t > > outputs, std::span< std::span< const uint8_t > > inputs)
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
 Hash_Engine (const Hash_Engine &other)=delete
 Hash_Engine (Hash_Engine &&other)=delete
virtual std::string name () const =0
Hash_Engine & operator= (const Hash_Engine &other)=delete
Hash_Engine & operator= (Hash_Engine &&other)=delete
virtual size_t output_length () const =0
virtual size_t parallelism () const =0
virtual std::string provider () const =0
virtual size_t uncached_prefix_bytes () const
virtual ~Hash_Engine ()=default

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
 Hash_Engine (std::span< const uint8_t > common_prefix)

Detailed Description

Definition at line 20 of file hash_engine.h.

Constructor & Destructor Documentation

◆ Hash_Engine() [1/3]

Botan::Hash_Engine::Hash_Engine ( const Hash_Engine & other)
delete

◆ Hash_Engine() [2/3]

Botan::Hash_Engine::Hash_Engine ( Hash_Engine && other)
delete

References Hash_Engine().

◆ ~Hash_Engine()

virtual Botan::Hash_Engine::~Hash_Engine ( )
virtualdefault

◆ Hash_Engine() [3/3]

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

Definition at line 121 of file hash_engine.h.

121 :
122 m_common_prefix(common_prefix.begin(), common_prefix.end()) {}
std::span< const uint8_t > common_prefix() const

References common_prefix().

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

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]

virtual void Botan::Hash_Engine::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 )
pure virtual

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.

Implemented in Botan::MDx_MB_Engine< W >.

References common_prefix(), and create_or_throw().

◆ 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
protected

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}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
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
inlineprotected

◆ 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 = "" )
static

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 = "" )
static

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

virtual std::string Botan::Hash_Engine::name ( ) const
pure virtual
Returns
name of the hash

Implemented in Botan::MDx_MB_Engine< W >.

◆ operator=() [1/2]

Hash_Engine & Botan::Hash_Engine::operator= ( const Hash_Engine & other)
delete

References Hash_Engine().

◆ operator=() [2/2]

Hash_Engine & Botan::Hash_Engine::operator= ( Hash_Engine && other)
delete

References Hash_Engine().

◆ output_length()

virtual size_t Botan::Hash_Engine::output_length ( ) const
pure virtual
Returns
output length of the hash function

Implemented in Botan::MDx_MB_Engine< W >.

Referenced by check_batch_args().

◆ parallelism()

virtual size_t Botan::Hash_Engine::parallelism ( ) const
pure virtual
Returns
native parallelism of this implementation

Implemented in Botan::MDx_MB_Engine< W >.

◆ possible_providers()

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

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

virtual std::string Botan::Hash_Engine::provider ( ) const
pure virtual
Returns
provider of the engine (eg "base", "avx2", "avx512")

Implemented in Botan::MDx_MB_Engine< W >.

Referenced by create_or_null(), and create_or_throw().

◆ uncached_prefix_bytes()

virtual size_t Botan::Hash_Engine::uncached_prefix_bytes ( ) const
inlinevirtual
Returns
bytes of the common prefix hashed again for each message, rather than being covered by a precomputed state

Reimplemented in Botan::MDx_MB_Engine< W >.

Definition at line 46 of file hash_engine.h.

46{ return common_prefix().size(); }

References common_prefix().


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