Botan::ChaCha Class Reference

#include <chacha.h>

Inheritance diagram for Botan::ChaCha:

Public Member Functions
size_t	buffer_size () const override
	ChaCha (size_t rounds=20)
void	cipher (const uint8_t in[], uint8_t out[], size_t len)
void	cipher (std::span< const uint8_t > in, std::span< uint8_t > out)
void	cipher1 (std::span< uint8_t > buf)
void	cipher1 (uint8_t buf[], size_t len)
void	clear () override
StreamCipher *	clone () const
void	decrypt (std::span< uint8_t > inout)
size_t	default_iv_length () const override
void	encipher (std::span< uint8_t > inout)
void	encrypt (std::span< uint8_t > inout)
bool	has_keying_material () const override
Key_Length_Specification	key_spec () const override
template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T	keystream_bytes (size_t bytes)
size_t	maximum_keylength () const
size_t	minimum_keylength () const
std::string	name () const override
std::unique_ptr< StreamCipher >	new_object () const override
std::string	provider () const override
void	seek (uint64_t offset) override
void	set_iv (const uint8_t iv[], size_t iv_len)
void	set_iv (std::span< const uint8_t > iv)
void	set_key (const OctetString &key)
void	set_key (const uint8_t key[], size_t length)
void	set_key (std::span< const uint8_t > key)
bool	valid_iv_length (size_t iv_len) const override
bool	valid_keylength (size_t length) const
void	write_keystream (std::span< uint8_t > out)
void	write_keystream (uint8_t out[], size_t len)

Static Public Member Functions
static std::unique_ptr< StreamCipher >	create (std::string_view algo_spec, std::string_view provider="")
static std::unique_ptr< StreamCipher >	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
void	assert_key_material_set () const
void	assert_key_material_set (bool predicate) const

Detailed Description

DJB's ChaCha (https://cr.yp.to/chacha.html)

Definition at line 18 of file chacha.h.

Constructor & Destructor Documentation

ChaCha()

Botan::ChaCha::ChaCha ( size_t rounds = 20 )

explicit

Parameters

rounds

number of rounds

Note

Currently only 8, 12 or 20 rounds are supported, all others will throw an exception

Definition at line 85 of file chacha.cpp.

                            : m_rounds(rounds) {
   BOTAN_ARG_CHECK(m_rounds == 8 || m_rounds == 12 || m_rounds == 20, "ChaCha only supports 8, 12 or 20 rounds");
}

References BOTAN_ARG_CHECK.

Member Function Documentation

assert_key_material_set() [1/2]

void Botan::SymmetricAlgorithm::assert_key_material_set ( ) const

inlineprotectedinherited

Definition at line 146 of file sym_algo.h.

{ assert_key_material_set(has_keying_material()); }

References assert_key_material_set(), and has_keying_material().

Referenced by assert_key_material_set(), Botan::Salsa20::cipher_bytes(), Botan::Lion::decrypt_n(), Botan::Lion::encrypt_n(), Botan::GHASH::final(), Botan::GHASH::nonce_hash(), Botan::ChaCha::seek(), Botan::CTR_BE::seek(), Botan::Salsa20::seek(), Botan::GHASH::set_associated_data(), Botan::OCB_Mode::set_associated_data_n(), Botan::Salsa20::set_iv_bytes(), Botan::GHASH::update(), and Botan::GHASH::update_associated_data().

assert_key_material_set() [2/2]

void Botan::SymmetricAlgorithm::assert_key_material_set ( bool predicate ) const

inlineprotectedinherited

Definition at line 148 of file sym_algo.h.

                                                         {
         if(!predicate) {
            throw_key_not_set_error();
         }
      }

buffer_size()

size_t Botan::ChaCha::buffer_size ( ) const

overridevirtual

Return the optimium buffer size to use with this cipher

Most stream ciphers internally produce blocks of bytes. This function returns that block size. Aligning buffer sizes to a multiple of this size may improve performance by reducing internal buffering overhead.

Note the return value of this function may change for any particular algorithm due to changes in the implementation from release to release, or changes in the runtime environment (such as CPUID indicating availability of an optimized implementation). It is not intrinsic to the algorithm; it is just a suggestion for gaining best performance.

Implements Botan::StreamCipher.

Definition at line 320 of file chacha.cpp.

                                 {
   return 64;
}

cipher() [1/2]

void Botan::StreamCipher::cipher ( const uint8_t in[], uint8_t out[], size_t len )

inlineinherited

Encrypt or decrypt a message

Processes all bytes plain/ciphertext from in and writes the result to out.

Parameters

in	the plaintext
out	the byte array to hold the output, i.e. the ciphertext
len	the length of both in and out in bytes

Definition at line 59 of file stream_cipher.h.

{ cipher_bytes(in, out, len); }

References cipher_bytes().

Referenced by cipher1(), cipher1(), create(), Botan::Sodium::crypto_stream_salsa20_xor_ic(), Botan::Sodium::crypto_stream_xsalsa20_xor_ic(), Botan::CTR_BE::CTR_BE(), Botan::CTR_BE::CTR_BE(), decrypt(), encipher(), encrypt(), and Botan::OFB::OFB().

cipher() [2/2]

void Botan::StreamCipher::cipher ( std::span< const uint8_t > in, std::span< uint8_t > out )

inherited

Encrypt or decrypt a message

Parameters

in	the plaintext
out	the byte array to hold the output, i.e. the ciphertext with at least the same size as in

Definition at line 133 of file stream_cipher.cpp.

                                                                         {
   BOTAN_ARG_CHECK(in.size() <= out.size(), "Output buffer of stream cipher must be at least as long as input buffer");
   cipher_bytes(in.data(), out.data(), in.size());
}

References BOTAN_ARG_CHECK, and cipher_bytes().

cipher1() [1/2]

void Botan::StreamCipher::cipher1 ( std::span< uint8_t > buf )

inlineinherited

Encrypt or decrypt a message The message is encrypted/decrypted in place.

Parameters

buf	the plaintext / ciphertext

Definition at line 115 of file stream_cipher.h.

{ cipher(buf, buf); }

References cipher().

cipher1() [2/2]

void Botan::StreamCipher::cipher1 ( uint8_t buf[], size_t len )

inlineinherited

Encrypt or decrypt a message The message is encrypted/decrypted in place.

Parameters

buf	the plaintext / ciphertext
len	the length of buf in bytes

Definition at line 108 of file stream_cipher.h.

{ cipher(buf, buf, len); }

References cipher().

Referenced by generate_keystream().

clear()

void Botan::ChaCha::clear ( )

overridevirtual

Reset the internal state. This includes not just the key, but any partial message that may have been in process.

Implements Botan::SymmetricAlgorithm.

Definition at line 402 of file chacha.cpp.

                   {
   zap(m_key);
   zap(m_state);
   zap(m_buffer);
   m_position = 0;
}

References Botan::zap().

clone()

StreamCipher * Botan::StreamCipher::clone ( ) const

inlineinherited

Returns

a new object representing the same algorithm as *this

Definition at line 194 of file stream_cipher.h.

{ return this->new_object().release(); }

References new_object().

create()

std::unique_ptr< StreamCipher > Botan::StreamCipher::create ( 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

Returns

a null pointer if the algo/provider combination cannot be found

Definition at line 40 of file stream_cipher.cpp.

                                                                                                  {
#if defined(BOTAN_HAS_SHAKE_CIPHER)
   if(algo_spec == "SHAKE-128" || algo_spec == "SHAKE-128-XOF") {
      if(provider.empty() || provider == "base") {
         return std::make_unique<SHAKE_128_Cipher>();
      }
   }
 
   if(algo_spec == "SHAKE-256" || algo_spec == "SHAKE-256-XOF") {
      if(provider.empty() || provider == "base") {
         return std::make_unique<SHAKE_256_Cipher>();
      }
   }
#endif
 
#if defined(BOTAN_HAS_CHACHA)
   if(algo_spec == "ChaCha20") {
      if(provider.empty() || provider == "base") {
         return std::make_unique<ChaCha>(20);
      }
   }
#endif
 
#if defined(BOTAN_HAS_SALSA20)
   if(algo_spec == "Salsa20") {
      if(provider.empty() || provider == "base") {
         return std::make_unique<Salsa20>();
      }
   }
#endif
 
   const SCAN_Name req(algo_spec);
 
#if defined(BOTAN_HAS_CTR_BE)
   if((req.algo_name() == "CTR-BE" || req.algo_name() == "CTR") && req.arg_count_between(1, 2)) {
      if(provider.empty() || provider == "base") {
         auto cipher = BlockCipher::create(req.arg(0));
         if(cipher) {
            size_t ctr_size = req.arg_as_integer(1, cipher->block_size());
            return std::make_unique<CTR_BE>(std::move(cipher), ctr_size);
         }
      }
   }
#endif
 
#if defined(BOTAN_HAS_CHACHA)
   if(req.algo_name() == "ChaCha") {
      if(provider.empty() || provider == "base") {
         return std::make_unique<ChaCha>(req.arg_as_integer(0, 20));
      }
   }
#endif
 
#if defined(BOTAN_HAS_OFB)
   if(req.algo_name() == "OFB" && req.arg_count() == 1) {
      if(provider.empty() || provider == "base") {
         if(auto cipher = BlockCipher::create(req.arg(0))) {
            return std::make_unique<OFB>(std::move(cipher));
         }
      }
   }
#endif
 
#if defined(BOTAN_HAS_RC4)
 
   if(req.algo_name() == "RC4" || req.algo_name() == "ARC4" || req.algo_name() == "MARK-4") {
      const size_t skip = (req.algo_name() == "MARK-4") ? 256 : req.arg_as_integer(0, 0);
 
      if(provider.empty() || provider == "base") {
         return std::make_unique<RC4>(skip);
      }
   }
 
#endif
 
   BOTAN_UNUSED(req);
   BOTAN_UNUSED(provider);
 
   return nullptr;
}

References Botan::SCAN_Name::algo_name(), Botan::SCAN_Name::arg(), Botan::SCAN_Name::arg_as_integer(), Botan::SCAN_Name::arg_count(), Botan::SCAN_Name::arg_count_between(), BOTAN_UNUSED, cipher(), Botan::BlockCipher::create(), and provider().

Referenced by Botan::BlockCipher::create(), Botan::Cipher_Mode::create(), and create_or_throw().

create_or_throw()

std::unique_ptr< StreamCipher > Botan::StreamCipher::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 a Lookup_Error if the algo/provider combination cannot be found

Definition at line 122 of file stream_cipher.cpp.

                                                                                                      {
   if(auto sc = StreamCipher::create(algo, provider)) {
      return sc;
   }
   throw Lookup_Error("Stream cipher", algo, provider);
}

References create(), and provider().

Referenced by Botan::ChaCha_RNG::ChaCha_RNG(), Botan::ChaCha_RNG::ChaCha_RNG(), Botan::ChaCha_RNG::ChaCha_RNG(), Botan::ChaCha_RNG::ChaCha_RNG(), Botan::ChaCha_RNG::ChaCha_RNG(), Botan::Sodium::crypto_secretbox_detached(), Botan::Sodium::crypto_secretbox_open_detached(), Botan::Sodium::crypto_secretbox_xsalsa20poly1305(), Botan::Sodium::crypto_secretbox_xsalsa20poly1305_open(), Botan::Sodium::crypto_stream_chacha20(), Botan::Sodium::crypto_stream_chacha20_ietf(), Botan::Sodium::crypto_stream_chacha20_ietf_xor_ic(), Botan::Sodium::crypto_stream_chacha20_xor_ic(), Botan::Sodium::crypto_stream_xchacha20(), and Botan::Sodium::crypto_stream_xchacha20_xor_ic().

decrypt()

void Botan::StreamCipher::decrypt ( std::span< uint8_t > inout )

inlineinherited

Decrypt a message in place The message is decrypted in place.

Parameters

inout

the plaintext / ciphertext

Definition at line 136 of file stream_cipher.h.

{ cipher(inout.data(), inout.data(), inout.size()); }

References cipher().

default_iv_length()

size_t Botan::ChaCha::default_iv_length ( ) const

overridevirtual

Return the default (preferred) nonce length

If this function returns zero, then this cipher does not support nonces; in this case any call to set_iv with a (non-empty) value will fail.

Default implementation returns 0

Reimplemented from Botan::StreamCipher.

Definition at line 339 of file chacha.cpp.

                                       {
   return 24;
}

encipher()

void Botan::StreamCipher::encipher ( std::span< uint8_t > inout )

inlineinherited

Encrypt a message The message is encrypted/decrypted in place.

Parameters

inout

the plaintext / ciphertext

Definition at line 122 of file stream_cipher.h.

{ cipher(inout.data(), inout.data(), inout.size()); }

References cipher().

encrypt()

void Botan::StreamCipher::encrypt ( std::span< uint8_t > inout )

inlineinherited

Encrypt a message The message is encrypted in place.

Parameters

inout

the plaintext / ciphertext

Definition at line 129 of file stream_cipher.h.

{ cipher(inout.data(), inout.data(), inout.size()); }

References cipher().

has_keying_material()

bool Botan::ChaCha::has_keying_material ( ) const

overridevirtual

Returns

true if a key has been set on this object

Implements Botan::SymmetricAlgorithm.

Definition at line 316 of file chacha.cpp.

                                       {
   return !m_state.empty();
}

key_spec()

Key_Length_Specification Botan::ChaCha::key_spec ( ) const

overridevirtual

Returns

object describing limits on key size

Implements Botan::SymmetricAlgorithm.

Definition at line 343 of file chacha.cpp.

                                                {
   return Key_Length_Specification(16, 32, 16);
}

keystream_bytes()

template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>

T Botan::StreamCipher::keystream_bytes ( size_t bytes )

inlineinherited

Get bytes from the keystream

The bytes are written into a continous byte buffer of your choosing.

Parameters

bytes

The number of bytes to be produced

Definition at line 96 of file stream_cipher.h.

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

References write_keystream().

maximum_keylength()

size_t Botan::SymmetricAlgorithm::maximum_keylength ( ) const

inlineinherited

Returns

maximum allowed key length

Definition at line 102 of file sym_algo.h.

{ return key_spec().maximum_keylength(); }

References key_spec().

minimum_keylength()

size_t Botan::SymmetricAlgorithm::minimum_keylength ( ) const

inlineinherited

Returns

minimum allowed key length

Definition at line 107 of file sym_algo.h.

{ return key_spec().minimum_keylength(); }

References key_spec().

name()

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

overridevirtual

Returns

the algorithm name

Implements Botan::SymmetricAlgorithm.

Definition at line 409 of file chacha.cpp.

                             {
   return fmt("ChaCha({})", m_rounds);
}

References Botan::fmt().

new_object()

std::unique_ptr< StreamCipher > Botan::ChaCha::new_object ( ) const

overridevirtual

Returns

new object representing the same algorithm as *this

Implements Botan::StreamCipher.

Definition at line 347 of file chacha.cpp.

                                                     {
   return std::make_unique<ChaCha>(m_rounds);
}

provider()

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

overridevirtual

Returns

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

Reimplemented from Botan::StreamCipher.

Definition at line 105 of file chacha.cpp.

                                 {
#if defined(BOTAN_HAS_CHACHA_AVX512)
   if(auto feat = CPUID::check(CPUID::Feature::AVX512)) {
      return *feat;
   }
#endif
 
#if defined(BOTAN_HAS_CHACHA_AVX2)
   if(auto feat = CPUID::check(CPUID::Feature::AVX2)) {
      return *feat;
   }
#endif
 
#if defined(BOTAN_HAS_CHACHA_SIMD32)
   if(auto feat = CPUID::check(CPUID::Feature::SIMD_4X32)) {
      return *feat;
   }
#endif
 
   return "base";
}

References Botan::CPUFeature::AVX2, Botan::CPUFeature::AVX512, Botan::CPUID::check(), and Botan::CPUFeature::SIMD_4X32.

providers()

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

staticinherited

Returns

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

Definition at line 129 of file stream_cipher.cpp.

                                                                     {
   return probe_providers_of<StreamCipher>(algo_spec);
}

References Botan::probe_providers_of().

seek()

void Botan::ChaCha::seek ( uint64_t offset )

overridevirtual

Set the offset and the state used later to generate the keystream

Sets the state of the stream cipher and keystream according to the passed offset, exactly as if offset bytes had first been encrypted. The key and (if required) the IV have to be set before this can be called.

Note

Not all ciphers support seeking; such objects will throw Not_Implemented in this case.

Parameters

offset

the offset where we begin to generate the keystream

Implements Botan::StreamCipher.

Definition at line 413 of file chacha.cpp.

                                 {
   assert_key_material_set();
 
   // Find the block offset
   const uint64_t counter = offset / 64;
 
   uint8_t out[8];
 
   store_le(counter, out);
 
   m_state[12] = load_le<uint32_t>(out, 0);
   m_state[13] += load_le<uint32_t>(out, 1);
 
   chacha(m_buffer.data(), m_buffer.size() / 64, m_state.data(), m_rounds);
   m_position = offset % 64;
}

References Botan::SymmetricAlgorithm::assert_key_material_set(), Botan::load_le(), and Botan::store_le().

set_iv() [1/2]

void Botan::StreamCipher::set_iv ( const uint8_t iv[], size_t iv_len )

inlineinherited

Resync the cipher using the IV

Load IV into the stream cipher state. This should happen after the key is set (set_key()) and before any operation (encrypt(), decrypt() or seek()) is called.

If the cipher does not support IVs, then a call with an empty IV will be accepted and any other length will cause an Invalid_IV_Length exception.

Parameters

iv	the initialization vector
iv_len	the length of the IV in bytes

Definition at line 166 of file stream_cipher.h.

{ set_iv_bytes(iv, iv_len); }

References set_iv_bytes().

Referenced by Botan::Sodium::crypto_stream_salsa20(), Botan::Sodium::crypto_stream_salsa20_xor_ic(), Botan::Sodium::crypto_stream_xsalsa20(), Botan::Sodium::crypto_stream_xsalsa20_xor_ic(), Botan::Sodium::randombytes_buf_deterministic(), and Botan::SIV_Mode::set_ctr_iv().

set_iv() [2/2]

void Botan::StreamCipher::set_iv ( std::span< const uint8_t > iv )

inlineinherited

Resync the cipher using the IV

Parameters

iv	the initialization vector

Exceptions

Invalid_IV_Length

if an incompatible IV was passed.

Definition at line 173 of file stream_cipher.h.

{ set_iv_bytes(iv.data(), iv.size()); }

References set_iv_bytes().

set_key() [1/3]

void Botan::SymmetricAlgorithm::set_key ( const OctetString & key )

inherited

Set the symmetric key of this object.

Parameters

key	the SymmetricKey to be set.

Definition at line 14 of file sym_algo.cpp.

                                                       {
   set_key(std::span{key.begin(), key.length()});
}

References Botan::OctetString::begin(), Botan::OctetString::length(), and set_key().

Referenced by Botan::create_aes_row_generator(), Botan::Sodium::crypto_stream_salsa20(), Botan::Sodium::crypto_stream_salsa20_xor_ic(), Botan::Sodium::crypto_stream_xsalsa20(), Botan::Sodium::crypto_stream_xsalsa20_xor_ic(), Botan::FPE::fe1_decrypt(), Botan::FPE::fe1_encrypt(), Botan::Sphincs_Hash_Functions_Sha2::PRF_msg(), Botan::Sodium::randombytes_buf_deterministic(), Botan::TLS::TLS_NULL_HMAC_AEAD_Mode::reset(), and set_key().

set_key() [2/3]

void Botan::SymmetricAlgorithm::set_key ( const uint8_t key[], size_t length )

inlineinherited

Set the symmetric key of this object.

Parameters

key	the to be set as a byte array.
length	in bytes of key param

Definition at line 133 of file sym_algo.h.

{ set_key(std::span{key, length}); }

References set_key().

Referenced by set_key().

set_key() [3/3]

void Botan::SymmetricAlgorithm::set_key ( std::span< const uint8_t > key )

inherited

Set the symmetric key of this object.

Parameters

key	the contiguous byte range to be set.

Definition at line 22 of file sym_algo.cpp.

                                                           {
   if(!valid_keylength(key.size())) {
      throw Invalid_Key_Length(name(), key.size());
   }
   key_schedule(key);
}

References name(), and valid_keylength().

valid_iv_length()

bool Botan::ChaCha::valid_iv_length ( size_t iv_len ) const

overridevirtual

Parameters

iv_len

the length of the IV in bytes

Returns

if the length is valid for this algorithm

Reimplemented from Botan::StreamCipher.

Definition at line 351 of file chacha.cpp.

                                                {
   return (iv_len == 0 || iv_len == 8 || iv_len == 12 || iv_len == 24);
}

valid_keylength()

bool Botan::SymmetricAlgorithm::valid_keylength ( size_t length ) const

inlineinherited

Check whether a given key length is valid for this algorithm.

Parameters

length

the key length to be checked.

Returns

true if the key length is valid.

Definition at line 114 of file sym_algo.h.

{ return key_spec().valid_keylength(length); }

References key_spec().

Referenced by set_key().

write_keystream() [1/2]

void Botan::StreamCipher::write_keystream ( std::span< uint8_t > out )

inlineinherited

Fill a given buffer with keystream bytes

The contents of out are ignored/overwritten

Parameters

out	the byte array to hold the keystream

Definition at line 86 of file stream_cipher.h.

{ generate_keystream(out.data(), out.size()); }

References generate_keystream().

write_keystream() [2/2]

void Botan::StreamCipher::write_keystream ( uint8_t out[], size_t len )

inlineinherited

Write keystream bytes to a buffer

The contents of out are ignored/overwritten

Parameters

out	the byte array to hold the keystream
len	the length of out in bytes

Definition at line 77 of file stream_cipher.h.

{ generate_keystream(out, len); }

References generate_keystream().

Referenced by Botan::Sodium::crypto_stream_salsa20(), Botan::Sodium::crypto_stream_xsalsa20(), keystream_bytes(), and Botan::Sodium::randombytes_buf_deterministic().

---

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

• src/lib/stream/chacha/chacha.h
• src/lib/stream/chacha/chacha.cpp
• src/lib/stream/chacha/chacha_avx2/chacha_avx2.cpp
• src/lib/stream/chacha/chacha_avx512/chacha_avx512.cpp
• src/lib/stream/chacha/chacha_simd32/chacha_simd32.cpp