Botan::cSHAKE_256_XOF Class Reference

#include <cshake_xof.h>

Inheritance diagram for Botan::cSHAKE_256_XOF:

Public Member Functions
bool	accepts_input () const final
size_t	block_size () const final
void	clear ()
std::unique_ptr< XOF >	copy_state () const final
	cSHAKE_256_XOF (std::span< const uint8_t > function_name)
	cSHAKE_256_XOF (std::string_view function_name)
	cSHAKE_256_XOF (std::vector< uint8_t > function_name)
virtual Key_Length_Specification	key_spec () const
std::string	name () const final
std::unique_ptr< XOF >	new_object () const final
template<size_t count>
std::array< uint8_t, count >	output ()
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< XOF >	create (std::string_view algo_spec, std::string_view provider="")
static std::unique_ptr< XOF >	create_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
const std::vector< uint8_t > &	function_name () const

Detailed Description

customizable SHAKE-256 as defined in NIST SP.800-185 This class is meant for internal use only and is not exposed via XOF::create().

Definition at line 87 of file cshake_xof.h.

Constructor & Destructor Documentation

cSHAKE_256_XOF() [1/3]

Botan::cSHAKE_256_XOF::cSHAKE_256_XOF ( std::vector< uint8_t > function_name )

inline

Definition at line 89 of file cshake_xof.h.

: cSHAKE_XOF(512, std::move(function_name)) {}

cSHAKE_256_XOF() [2/3]

Botan::cSHAKE_256_XOF::cSHAKE_256_XOF ( std::span< const uint8_t > function_name )

inline

Definition at line 91 of file cshake_xof.h.

: cSHAKE_XOF(512, function_name) {}

cSHAKE_256_XOF() [3/3]

Botan::cSHAKE_256_XOF::cSHAKE_256_XOF ( std::string_view function_name )

inline

Definition at line 93 of file cshake_xof.h.

: cSHAKE_XOF(512, function_name) {}

Member Function Documentation

accepts_input()

bool Botan::cSHAKE_XOF::accepts_input ( ) const

inlinefinalvirtualinherited

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.

{ return !m_output_generated; }

block_size()

size_t Botan::cSHAKE_XOF::block_size ( ) const

finalvirtualinherited

Returns

the intrinsic processing block size of this XOF

Implements Botan::XOF.

Definition at line 41 of file cshake_xof.cpp.

                                    {
   return m_keccak.byte_rate();
}

References Botan::Keccak_Permutation::byte_rate().

clear()

void Botan::XOF::clear ( )

inlineinherited

Reset the state.

Definition at line 66 of file xof.h.

                   {
         m_xof_started = false;
         reset();
      }

Referenced by Botan::Dilithium_Symmetric_Primitives_Base::H(), Botan::Dilithium_Symmetric_Primitives_Base::H(), Botan::Dilithium_Symmetric_Primitives_Base::H_256(), and Botan::FrodoKEMConstants::SHAKE_XOF().

copy_state()

std::unique_ptr< XOF > Botan::cSHAKE_256_XOF::copy_state ( ) const

inlinefinalvirtual

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

Implements Botan::XOF.

Definition at line 97 of file cshake_xof.h.

{ return std::make_unique<cSHAKE_256_XOF>(*this); }

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.

                                                                                {
   const SCAN_Name req(algo_spec);
 
   if(!provider.empty() && provider != "base") {
      return nullptr;  // unknown provider
   }
 
#if defined(BOTAN_HAS_SHAKE_XOF)
   if(req.algo_name() == "SHAKE-128" && req.arg_count() == 0) {
      return std::make_unique<SHAKE_128_XOF>();
   }
   if(req.algo_name() == "SHAKE-256" && req.arg_count() == 0) {
      return std::make_unique<SHAKE_256_XOF>();
   }
#endif
 
   return nullptr;
}

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_spec	algorithm name
provider	provider implementation to use Throws Lookup_Error if not found.

Definition at line 42 of file xof.cpp.

                                                                                         {
   if(auto xof = XOF::create(algo_spec, provider)) {
      return xof;
   }
   throw Lookup_Error("XOF", algo_spec, provider);
}

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

function_name()

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

inlineprotectedinherited

Definition at line 46 of file cshake_xof.h.

{ return m_function_name; }

Referenced by Botan::cSHAKE_XOF::cSHAKE_XOF(), and Botan::cSHAKE_XOF::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.

                                                        {
         // Keys are not supported by default
         return Key_Length_Specification(0);
      }

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

name()

std::string Botan::cSHAKE_256_XOF::name ( ) const

inlinefinalvirtual

Returns

the hash function name

Implements Botan::XOF.

Definition at line 95 of file cshake_xof.h.

{ return "cSHAKE-256"; }

new_object()

std::unique_ptr< XOF > Botan::cSHAKE_256_XOF::new_object ( ) const

inlinefinalvirtual

Returns

new object representing the same algorithm as *this

Implements Botan::XOF.

Definition at line 99 of file cshake_xof.h.

{ return std::make_unique<cSHAKE_256_XOF>(function_name()); }

output() [1/3]

template<size_t count>

std::array< uint8_t, count > Botan::XOF::output ( )

inlineinherited

Returns

the next count output bytes as a std::array<>.

Definition at line 165 of file xof.h.

                                        {
         std::array<uint8_t, count> out;
         generate_bytes(out);
         return out;
      }

output() [2/3]

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.

                             {
         T out(bytes);
         generate_bytes(out);
         return out;
      }

References T.

Referenced by Botan::DilithiumMessageHash::final(), Botan::Dilithium_Symmetric_Primitives_Base::H(), Botan::Dilithium_Symmetric_Primitives_Base::H_256(), Botan::FrodoMatrix::make_sample_generator(), and Botan::Kyber_Symmetric_Primitives::PRF().

output() [3/3]

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 183 of file xof.h.

{ generate_bytes(output); }

output_next_byte()

uint8_t Botan::XOF::output_next_byte ( )

inlineinherited

Returns

the next single output byte

Definition at line 188 of file xof.h.

                                 {
         uint8_t out;
         generate_bytes({&out, 1});
         return out;
      }

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 177 of file xof.h.

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

provider()

std::string Botan::cSHAKE_XOF::provider ( ) const

finalvirtualinherited

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.

                                     {
   return m_keccak.provider();
}

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_spec

algorithm name

Definition at line 50 of file xof.cpp.

                                                            {
   return probe_providers_of<XOF>(algo_spec, {"base"});
}

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

salt	a salt value to parameterize the XOF
key	a key to parameterize the XOF

Definition at line 58 of file xof.cpp.

                                                                       {
   if(!key_spec().valid_keylength(key.size())) {
      throw Invalid_Key_Length(name(), key.size());
   }
 
   if(!valid_salt_length(salt.size())) {
      throw Invalid_Argument(fmt("{} cannot accept a salt length of {}", name(), salt.size()));
   }
 
   m_xof_started = true;
   start_msg(salt, key);
}

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

input

the data that shall be

Definition at line 142 of file xof.h.

                                                {
         if(!m_xof_started) {
            // If the user didn't start() before the first input, we enforce
            // it with a default value, here.
            start();
         }
         add_data(input);
      }

Referenced by Botan::Dilithium_Symmetric_Primitives_Base::H(), Botan::Dilithium_Symmetric_Primitives_Base::H(), Botan::Dilithium_Symmetric_Primitives_Base::H_256(), and Botan::DilithiumMessageHash::update().

valid_salt_length()

bool Botan::cSHAKE_XOF::valid_salt_length ( size_t salt_len ) const

finalvirtualinherited

Returns

true if salt length is acceptable, false otherwise

Reimplemented from Botan::XOF.

Definition at line 45 of file cshake_xof.cpp.

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

---

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

• src/lib/xof/cshake_xof/cshake_xof.h