Botan::XOF Class Reference

#include <xof.h>

Inheritance diagram for Botan::XOF:

Public Member Functions
virtual bool	accepts_input () const =0
virtual size_t	block_size () const =0
void	clear ()
virtual std::unique_ptr< XOF >	copy_state () const =0
virtual Key_Length_Specification	key_spec () const
virtual std::string	name () const =0
virtual std::unique_ptr< XOF >	new_object () const =0
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)
virtual std::string	provider () const
void	start (std::span< const uint8_t > salt={}, std::span< const uint8_t > key={})
void	update (std::span< const uint8_t > input)
virtual bool	valid_salt_length (size_t salt_len) const
virtual	~XOF ()=default

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)

Detailed Description

This class represents an eXtendable Output Function (XOF) objects

A XOF transforms an arbitrary length input message into an indefinite stream of output bits. Typically, it is illegal to call update() after the first call to output().

Definition at line 29 of file xof.h.

Constructor & Destructor Documentation

~XOF()

virtual Botan::XOF::~XOF ( )

virtualdefault

References create(), create_or_throw(), provider(), and providers().

Member Function Documentation

accepts_input()

virtual bool Botan::XOF::accepts_input ( ) const

pure virtual

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

Implemented in Botan::AES_256_CTR_XOF, Botan::Ascon_XOF128, Botan::cSHAKE_XOF, and Botan::SHAKE_XOF.

block_size()

virtual size_t Botan::XOF::block_size ( ) const

pure virtual

Return the internal block size of this XOF

Returns

the intrinsic processing block size of this XOF

Implemented in Botan::AES_256_CTR_XOF, Botan::Ascon_XOF128, Botan::cSHAKE_XOF, and Botan::SHAKE_XOF.

clear()

void Botan::XOF::clear ( )

inline

Reset the state.

Definition at line 66 of file xof.h.

                   {
         m_xof_started = false;
         reset();
      }

Referenced by Botan::Kyber_90s_Symmetric_Primitives::init_PRF(), Botan::Kyber_Modern_Symmetric_Primitives::init_PRF(), Botan::ML_KEM_Symmetric_Primitives::init_PRF(), Botan::Kyber_90s_Symmetric_Primitives::init_XOF(), Botan::Kyber_Modern_Symmetric_Primitives::init_XOF(), and Botan::ML_KEM_Symmetric_Primitives::init_XOF().

copy_state()

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

pure virtual

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::Ascon_XOF128, 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 = "" )

static

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 28 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
 
#if defined(BOTAN_HAS_ASCON_XOF128)
   if(req.algo_name() == "Ascon-XOF128" && req.arg_count() == 0) {
      return std::make_unique<Ascon_XOF128>();
   }
#endif
 
   return nullptr;
}

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

Referenced by botan_xof_init(), create_or_throw(), and ~XOF().

create_or_throw()

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

static

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 54 of file xof.cpp.

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

References create(), and provider().

Referenced by Botan::AES_256_CTR_XOF::AES_256_CTR_XOF(), Botan::create_pk_from_sk(), Botan::Kyber_Modern_Symmetric_Primitives::create_PRF(), Botan::ML_KEM_Symmetric_Primitives::create_PRF(), Botan::Kyber_Modern_Symmetric_Primitives::create_XOF(), Botan::ML_KEM_Symmetric_Primitives::create_XOF(), Botan::Dilithium_Symmetric_Primitives_Base::H(), Botan::Dilithium_Symmetric_Primitives_Base::H(), Botan::Dilithium_Symmetric_Primitives_Base::H_256(), Botan::Classic_McEliece_Parameters::prg(), Botan::sign_message(), and ~XOF().

key_spec()

virtual Key_Length_Specification Botan::XOF::key_spec ( ) const

inlinevirtual

Return the key lengths supported by this XOF

Returns

an object describing limits on the key size

Reimplemented in Botan::AES_256_CTR_XOF.

Definition at line 102 of file xof.h.

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

Referenced by start().

name()

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

pure virtual

Return the name of this XOF

Returns

the hash function name

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

References start().

Referenced by start().

new_object()

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

pure virtual

Create a new uninitialized object of the same type

Returns

new object representing the same algorithm as *this

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

output() [1/3]

template<size_t count>

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

inline

Generate a fixed number of output bytes into a std::array

Returns

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

Definition at line 172 of file xof.h.

                                        {
         std::array<uint8_t, count> out;  // NOLINT(*-member-init)
         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 )

inline

Generate output bytes into a newly allocated container

Returns

the next bytes output bytes as the specified container type T.

Definition at line 161 of file xof.h.

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

Referenced by Botan::FrodoMatrix::make_sample_generator(), output(), and output_stdvec().

output() [3/3]

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

inline

Generate output bytes into a caller provided buffer Fill output with the next output bytes. The number of bytes depends on the size of output.

Definition at line 191 of file xof.h.

{ generate_bytes(output); }

References output().

output_next_byte()

uint8_t Botan::XOF::output_next_byte ( )

inline

Generate a single output byte

Returns

the next single output byte

Definition at line 197 of file xof.h.

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

output_stdvec()

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

inline

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

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

References output().

provider()

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

virtual

Return the name of the provider implementing this object

Returns

provider information about this implementation. Default is "base", might also return "sse2", "avx2", "openssl", or some other arbitrary string.

Reimplemented in Botan::Ascon_XOF128, Botan::cSHAKE_XOF, and Botan::SHAKE_XOF.

Definition at line 66 of file xof.cpp.

                              {
   return "base";
}

Referenced by create(), create_or_throw(), and ~XOF().

providers()

std::vector< std::string > Botan::XOF::providers ( std::string_view algo_spec )

static

List the providers available for a given XOF

Returns

list of available providers for this algorithm, empty if not available

Parameters

algo_spec

algorithm name

Definition at line 62 of file xof.cpp.

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

References Botan::probe_providers_of().

Referenced by ~XOF().

start()

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

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 70 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(), key_spec(), name(), and valid_salt_length().

Referenced by name(), and update().

update()

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

inline

Add input data to the XOF's internal state

Parameters

input

the data that shall be

Definition at line 147 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);
      }

References start().

Referenced by Botan::Kyber_Modern_Symmetric_Primitives::init_PRF(), Botan::ML_KEM_Symmetric_Primitives::init_PRF(), Botan::Kyber_Modern_Symmetric_Primitives::init_XOF(), and Botan::ML_KEM_Symmetric_Primitives::init_XOF().

valid_salt_length()

virtual bool Botan::XOF::valid_salt_length ( size_t salt_len ) const

inlinevirtual

Test if a salt length is valid for this XOF

Returns

true if salt length is acceptable, false otherwise

Reimplemented in Botan::AES_256_CTR_XOF, and Botan::cSHAKE_XOF.

Definition at line 93 of file xof.h.

                                                            {
         // Salts are not supported by default
         return salt_len == 0;
      }

Referenced by start().

---

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

• src/lib/xof/xof.h
• src/lib/xof/xof.cpp