Botan 3.5.0
Crypto and TLS for C&
Botan::cSHAKE_XOF Class Referenceabstract

#include <cshake_xof.h>

Inheritance diagram for Botan::cSHAKE_XOF:
Botan::XOF Botan::cSHAKE_128_XOF Botan::cSHAKE_256_XOF

Public Member Functions

bool accepts_input () const final
 
size_t block_size () const final
 
void clear ()
 
virtual std::unique_ptr< XOFcopy_state () const =0
 
virtual Key_Length_Specification key_spec () const
 
virtual std::string name () const =0
 
virtual std::unique_ptr< XOFnew_object () const =0
 
template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T output (size_t bytes)
 
void output (std::span< uint8_t > output)
 
uint8_t output_next_byte ()
 
std::vector< uint8_t > output_stdvec (size_t bytes)
 
std::string provider () const final
 
void start (std::span< const uint8_t > salt={}, std::span< const uint8_t > key={})
 
void update (std::span< const uint8_t > input)
 
bool valid_salt_length (size_t salt_length) const final
 

Static Public Member Functions

static std::unique_ptr< XOFcreate (std::string_view algo_spec, std::string_view provider="")
 
static std::unique_ptr< XOFcreate_or_throw (std::string_view algo_spec, std::string_view provider="")
 
static std::vector< std::string > providers (std::string_view algo_spec)
 

Protected Member Functions

 cSHAKE_XOF (size_t capacity, std::span< const uint8_t > function_name)
 
 cSHAKE_XOF (size_t capacity, std::string_view function_name)
 
 cSHAKE_XOF (size_t capacity, std::vector< uint8_t > function_name)
 
const std::vector< uint8_t > & function_name () const
 

Detailed Description

Base class for cSHAKE-based XOFs

Definition at line 23 of file cshake_xof.h.

Constructor & Destructor Documentation

◆ cSHAKE_XOF() [1/3]

Botan::cSHAKE_XOF::cSHAKE_XOF ( size_t capacity,
std::vector< uint8_t > function_name )
protected

Defines a concrete instance of a cSHAKE XOF.

Parameters
capacityeither 256 or 512
function_namea domain separator for Keccak-based functions derived from cSHAKE

Definition at line 19 of file cshake_xof.cpp.

19 :
20 m_keccak(capacity, 0b00, 2), m_function_name(std::move(function_name)), m_output_generated(false) {
21 BOTAN_ASSERT_NOMSG(capacity == 256 || capacity == 512);
22}
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:59
const std::vector< uint8_t > & function_name() const
Definition cshake_xof.h:46

References BOTAN_ASSERT_NOMSG.

◆ cSHAKE_XOF() [2/3]

Botan::cSHAKE_XOF::cSHAKE_XOF ( size_t capacity,
std::span< const uint8_t > function_name )
protected

Definition at line 24 of file cshake_xof.cpp.

24 :
25 cSHAKE_XOF(capacity, std::vector<uint8_t>{function_name.begin(), function_name.end()}) {}
cSHAKE_XOF(size_t capacity, std::vector< uint8_t > function_name)

References function_name().

◆ cSHAKE_XOF() [3/3]

Botan::cSHAKE_XOF::cSHAKE_XOF ( size_t capacity,
std::string_view function_name )
protected

Definition at line 27 of file cshake_xof.cpp.

27 :
28 cSHAKE_XOF(capacity,
29 std::vector<uint8_t>{cast_char_ptr_to_uint8(function_name.data()),
const uint8_t * cast_char_ptr_to_uint8(const char *s)
Definition mem_ops.h:273

References Botan::cast_char_ptr_to_uint8(), and function_name().

Member Function Documentation

◆ accepts_input()

bool Botan::cSHAKE_XOF::accepts_input ( ) const
inlinefinalvirtual

Typically, this is true for new objects and becomes false once output() was called for the first time.

Returns
true iff calling update() is legal in the current object state

Implements Botan::XOF.

Definition at line 43 of file cshake_xof.h.

43{ return !m_output_generated; }

◆ block_size()

size_t Botan::cSHAKE_XOF::block_size ( ) const
finalvirtual
Returns
the intrinsic processing block size of this XOF

Implements Botan::XOF.

Definition at line 41 of file cshake_xof.cpp.

41 {
42 return m_keccak.byte_rate();
43}
size_t byte_rate() const
Definition keccak_perm.h:55

References Botan::Keccak_Permutation::byte_rate().

◆ clear()

void Botan::XOF::clear ( )
inlineinherited

Reset the state.

Definition at line 66 of file xof.h.

66 {
67 m_xof_started = false;
68 reset();
69 }

◆ copy_state()

virtual std::unique_ptr< XOF > Botan::XOF::copy_state ( ) const
pure virtualinherited

Return a new XOF object with the same state as *this.

If the XOF is not yet in the output phase, it efficiently allows using several messages with a common prefix. Otherwise, the copied state will produce the same output bit stream as the original object at the time of this invocation.

This function should be called clone but for consistency with other classes it is called copy_state.

Returns
new XOF object

Implemented in Botan::AES_256_CTR_XOF, Botan::cSHAKE_128_XOF, Botan::cSHAKE_256_XOF, Botan::SHAKE_128_XOF, and Botan::SHAKE_256_XOF.

◆ create()

std::unique_ptr< XOF > Botan::XOF::create ( std::string_view algo_spec,
std::string_view provider = "" )
staticinherited

Create an instance based on a name, or return null if the algo/provider combination cannot be found. If provider is empty then best available is chosen.

Definition at line 22 of file xof.cpp.

22 {
23 const SCAN_Name req(algo_spec);
24
25 if(!provider.empty() && provider != "base") {
26 return nullptr; // unknown provider
27 }
28
29#if defined(BOTAN_HAS_SHAKE_XOF)
30 if(req.algo_name() == "SHAKE-128" && req.arg_count() == 0) {
31 return std::make_unique<SHAKE_128_XOF>();
32 }
33 if(req.algo_name() == "SHAKE-256" && req.arg_count() == 0) {
34 return std::make_unique<SHAKE_256_XOF>();
35 }
36#endif
37
38 return nullptr;
39}
virtual std::string provider() const
Definition xof.cpp:54

References Botan::SCAN_Name::algo_name(), Botan::SCAN_Name::arg_count(), and Botan::XOF::provider().

Referenced by Botan::XOF::create_or_throw().

◆ create_or_throw()

std::unique_ptr< XOF > Botan::XOF::create_or_throw ( std::string_view algo_spec,
std::string_view provider = "" )
staticinherited

Create an instance based on a name If provider is empty then best available is chosen.

Parameters
algo_specalgorithm name
providerprovider implementation to use Throws Lookup_Error if not found.

Definition at line 42 of file xof.cpp.

42 {
43 if(auto xof = XOF::create(algo_spec, provider)) {
44 return xof;
45 }
46 throw Lookup_Error("XOF", algo_spec, provider);
47}
static std::unique_ptr< XOF > create(std::string_view algo_spec, std::string_view provider="")
Definition xof.cpp:22

References Botan::XOF::create(), and Botan::XOF::provider().

Referenced by Botan::FrodoKEMConstants::FrodoKEMConstants(), and Botan::Dilithium_Common_Symmetric_Primitives::XOF().

◆ function_name()

const std::vector< uint8_t > & Botan::cSHAKE_XOF::function_name ( ) const
inlineprotected

Definition at line 46 of file cshake_xof.h.

46{ return m_function_name; }

Referenced by cSHAKE_XOF(), and cSHAKE_XOF().

◆ key_spec()

virtual Key_Length_Specification Botan::XOF::key_spec ( ) const
inlinevirtualinherited
Returns
an object describing limits on the key size

Reimplemented in Botan::AES_256_CTR_XOF.

Definition at line 99 of file xof.h.

99 {
100 // Keys are not supported by default
101 return Key_Length_Specification(0);
102 }

Referenced by Botan::XOF::start().

◆ name()

virtual std::string Botan::XOF::name ( ) const
pure virtualinherited

◆ new_object()

virtual std::unique_ptr< XOF > Botan::XOF::new_object ( ) const
pure virtualinherited
Returns
new object representing the same algorithm as *this

Implemented in Botan::AES_256_CTR_XOF, Botan::cSHAKE_128_XOF, Botan::cSHAKE_256_XOF, Botan::SHAKE_128_XOF, and Botan::SHAKE_256_XOF.

◆ output() [1/2]

template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T Botan::XOF::output ( size_t bytes)
inlineinherited
Returns
the next bytes output bytes as the specified container type T.

Definition at line 155 of file xof.h.

155 {
156 T out(bytes);
157 generate_bytes(out);
158 return out;
159 }
FE_25519 T
Definition ge.cpp:34

References T.

Referenced by Botan::FrodoMatrix::make_sample_generator(), and Botan::Kyber_Symmetric_Primitives::PRF().

◆ output() [2/2]

void Botan::XOF::output ( std::span< uint8_t > output)
inlineinherited

Fill output with the next output bytes. The number of bytes depends on the size of output.

Definition at line 173 of file xof.h.

173{ generate_bytes(output); }
T output(size_t bytes)
Definition xof.h:155

◆ output_next_byte()

uint8_t Botan::XOF::output_next_byte ( )
inlineinherited
Returns
the next single output byte

Definition at line 178 of file xof.h.

178 {
179 uint8_t out;
180 generate_bytes({&out, 1});
181 return out;
182 }

◆ output_stdvec()

std::vector< uint8_t > Botan::XOF::output_stdvec ( size_t bytes)
inlineinherited

Convenience overload to generate a std::vector<uint8_t>. Same as calling XOF::output<std::vector<uint8_t>>().

Returns
the next bytes output bytes as a byte vector.

Definition at line 167 of file xof.h.

167{ return output<std::vector<uint8_t>>(bytes); }

◆ provider()

std::string Botan::cSHAKE_XOF::provider ( ) const
finalvirtual
Returns
provider information about this implementation. Default is "base", might also return "sse2", "avx2", "openssl", or some other arbitrary string.

Reimplemented from Botan::XOF.

Definition at line 37 of file cshake_xof.cpp.

37 {
38 return m_keccak.provider();
39}
std::string provider() const

References Botan::Keccak_Permutation::provider().

◆ providers()

std::vector< std::string > Botan::XOF::providers ( std::string_view algo_spec)
staticinherited
Returns
list of available providers for this algorithm, empty if not available
Parameters
algo_specalgorithm name

Definition at line 50 of file xof.cpp.

50 {
51 return probe_providers_of<XOF>(algo_spec, {"base"});
52}
std::vector< std::string > probe_providers_of(std::string_view algo_spec, const std::vector< std::string > &possible={"base"})
Definition scan_name.h:105

References Botan::probe_providers_of().

◆ start()

void Botan::XOF::start ( std::span< const uint8_t > salt = {},
std::span< const uint8_t > key = {} )
inherited

Some XOFs can be parameterized with a salt and/or key. If required, this must be called before calling XOF::update().

See also
XOF::valid_salt_length()
XOF::key_spec()
Parameters
salta salt value to parameterize the XOF
keya key to parameterize the XOF

Definition at line 58 of file xof.cpp.

58 {
59 if(!key_spec().valid_keylength(key.size())) {
60 throw Invalid_Key_Length(name(), key.size());
61 }
62
63 if(!valid_salt_length(salt.size())) {
64 throw Invalid_Argument(fmt("{} cannot accept a salt length of {}", name(), salt.size()));
65 }
66
67 m_xof_started = true;
68 start_msg(salt, key);
69}
virtual bool valid_salt_length(size_t salt_len) const
Definition xof.h:91
virtual Key_Length_Specification key_spec() const
Definition xof.h:99
virtual std::string name() const =0
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

References Botan::fmt(), Botan::XOF::key_spec(), Botan::XOF::name(), and Botan::XOF::valid_salt_length().

◆ update()

void Botan::XOF::update ( std::span< const uint8_t > input)
inlineinherited

Add input data to the XOF's internal state

Parameters
inputthe data that shall be

Definition at line 142 of file xof.h.

142 {
143 if(!m_xof_started) {
144 // If the user didn't start() before the first input, we enforce
145 // it with a default value, here.
146 start();
147 }
148 add_data(input);
149 }
void start(std::span< const uint8_t > salt={}, std::span< const uint8_t > key={})
Definition xof.cpp:58

◆ valid_salt_length()

bool Botan::cSHAKE_XOF::valid_salt_length ( size_t salt_len) const
finalvirtual
Returns
true if salt length is acceptable, false otherwise

Reimplemented from Botan::XOF.

Definition at line 45 of file cshake_xof.cpp.

45 {
46 // NIST SP.800-185 Section 3.2
47 // When N and S are both empty strings, cSHAKE(X, L, N, S) is equivalent to
48 // SHAKE as defined in FIPS 202.
49 //
50 // We don't implement the fallback case where N and S are empty. Hence, if
51 // the function name N was defined as 'empty', a salt must be provided.
52 return m_function_name.size() + salt_length > 0;
53}

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