Botan  2.10.0
Crypto and TLS for C++11
Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
Botan::ChaCha Class Referencefinal

#include <chacha.h>

Inheritance diagram for Botan::ChaCha:
Botan::StreamCipher Botan::SymmetricAlgorithm

Public Member Functions

 ChaCha (size_t rounds=20)
 
void cipher (const uint8_t in[], uint8_t out[], size_t length) override
 
void cipher1 (uint8_t buf[], size_t len)
 
void clear () override
 
StreamCipherclone () const override
 
template<typename Alloc >
void decrypt (std::vector< uint8_t, Alloc > &inout)
 
size_t default_iv_length () const override
 
template<typename Alloc >
void encipher (std::vector< uint8_t, Alloc > &inout)
 
template<typename Alloc >
void encrypt (std::vector< uint8_t, Alloc > &inout)
 
Key_Length_Specification key_spec () const override
 
size_t maximum_keylength () const
 
size_t minimum_keylength () const
 
std::string name () const override
 
std::string provider () const override
 
void seek (uint64_t offset) override
 
void set_iv (const uint8_t iv[], size_t iv_len) override
 
void set_key (const SymmetricKey &key)
 
template<typename Alloc >
void set_key (const std::vector< uint8_t, Alloc > &key)
 
void set_key (const uint8_t key[], size_t length)
 
bool valid_iv_length (size_t iv_len) const override
 
bool valid_keylength (size_t length) const
 
void write_keystream (uint8_t out[], size_t len) override
 

Static Public Member Functions

static std::unique_ptr< StreamCiphercreate (const std::string &algo_spec, const std::string &provider="")
 
static std::unique_ptr< StreamCiphercreate_or_throw (const std::string &algo_spec, const std::string &provider="")
 
static std::vector< std::string > providers (const std::string &algo_spec)
 

Protected Member Functions

void verify_key_set (bool cond) 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
roundsnumber of rounds
Note
Currently only 8, 12 or 20 rounds are supported, all others will throw an exception

Definition at line 63 of file chacha.cpp.

References BOTAN_ARG_CHECK.

Referenced by clone().

63  : m_rounds(rounds)
64  {
65  BOTAN_ARG_CHECK(m_rounds == 8 || m_rounds == 12 || m_rounds == 20,
66  "ChaCha only supports 8, 12 or 20 rounds");
67  }
#define BOTAN_ARG_CHECK(expr, msg)
Definition: assert.h:37

Member Function Documentation

◆ cipher()

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

Encrypt or decrypt a message

Parameters
inthe plaintext
outthe byte array to hold the output, i.e. the ciphertext
lenthe length of both in and out in bytes

Implements Botan::StreamCipher.

Definition at line 174 of file chacha.cpp.

References Botan::SymmetricAlgorithm::verify_key_set(), and Botan::xor_buf().

175  {
176  verify_key_set(m_state.empty() == false);
177 
178  while(length >= m_buffer.size() - m_position)
179  {
180  const size_t available = m_buffer.size() - m_position;
181 
182  xor_buf(out, in, &m_buffer[m_position], available);
183  chacha_x8(m_buffer.data(), m_state.data(), m_rounds);
184 
185  length -= available;
186  in += available;
187  out += available;
188  m_position = 0;
189  }
190 
191  xor_buf(out, in, &m_buffer[m_position], length);
192 
193  m_position += length;
194  }
void verify_key_set(bool cond) const
Definition: sym_algo.h:89
void xor_buf(uint8_t out[], const uint8_t in[], size_t length)
Definition: mem_ops.h:202

◆ cipher1()

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

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

Parameters
bufthe plaintext / ciphertext
lenthe length of buf in bytes

Definition at line 78 of file stream_cipher.h.

Referenced by Botan::SIV_Encryption::finish().

79  { cipher(buf, buf, len); }
virtual void cipher(const uint8_t in[], uint8_t out[], size_t len)=0

◆ clear()

void Botan::ChaCha::clear ( )
overridevirtual

Reset the state.

Implements Botan::SymmetricAlgorithm.

Definition at line 354 of file chacha.cpp.

References Botan::zap().

355  {
356  zap(m_key);
357  zap(m_state);
358  zap(m_buffer);
359  m_position = 0;
360  }
void zap(std::vector< T, Alloc > &vec)
Definition: secmem.h:170

◆ clone()

StreamCipher * Botan::ChaCha::clone ( ) const
overridevirtual
Returns
a new object representing the same algorithm as *this

Implements Botan::StreamCipher.

Definition at line 290 of file chacha.cpp.

References ChaCha().

291  {
292  return new ChaCha(m_rounds);
293  }
ChaCha(size_t rounds=20)
Definition: chacha.cpp:63

◆ create()

std::unique_ptr< StreamCipher > Botan::StreamCipher::create ( const std::string &  algo_spec,
const std::string &  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
Returns
a null pointer if the algo/provider combination cannot be found

Definition at line 42 of file stream_cipher.cpp.

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, Botan::StreamCipher::cipher(), and Botan::BlockCipher::create().

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

44  {
45  const SCAN_Name req(algo_spec);
46 
47 #if defined(BOTAN_HAS_CTR_BE)
48  if((req.algo_name() == "CTR-BE" || req.algo_name() == "CTR") && req.arg_count_between(1,2))
49  {
50  if(provider.empty() || provider == "base")
51  {
52  auto cipher = BlockCipher::create(req.arg(0));
53  if(cipher)
54  {
55  size_t ctr_size = req.arg_as_integer(1, cipher->block_size());
56  return std::unique_ptr<StreamCipher>(new CTR_BE(cipher.release(), ctr_size));
57  }
58  }
59  }
60 #endif
61 
62 #if defined(BOTAN_HAS_CHACHA)
63  if(req.algo_name() == "ChaCha")
64  {
65  if(provider.empty() || provider == "base")
66  return std::unique_ptr<StreamCipher>(new ChaCha(req.arg_as_integer(0, 20)));
67  }
68 
69  if(req.algo_name() == "ChaCha20")
70  {
71  if(provider.empty() || provider == "base")
72  return std::unique_ptr<StreamCipher>(new ChaCha(20));
73  }
74 #endif
75 
76 #if defined(BOTAN_HAS_SALSA20)
77  if(req.algo_name() == "Salsa20")
78  {
79  if(provider.empty() || provider == "base")
80  return std::unique_ptr<StreamCipher>(new Salsa20);
81  }
82 #endif
83 
84 #if defined(BOTAN_HAS_SHAKE_CIPHER)
85  if(req.algo_name() == "SHAKE-128" || req.algo_name() == "SHAKE-128-XOF")
86  {
87  if(provider.empty() || provider == "base")
88  return std::unique_ptr<StreamCipher>(new SHAKE_128_Cipher);
89  }
90 #endif
91 
92 #if defined(BOTAN_HAS_OFB)
93  if(req.algo_name() == "OFB" && req.arg_count() == 1)
94  {
95  if(provider.empty() || provider == "base")
96  {
97  if(auto c = BlockCipher::create(req.arg(0)))
98  return std::unique_ptr<StreamCipher>(new OFB(c.release()));
99  }
100  }
101 #endif
102 
103 #if defined(BOTAN_HAS_RC4)
104 
105  if(req.algo_name() == "RC4" ||
106  req.algo_name() == "ARC4" ||
107  req.algo_name() == "MARK-4")
108  {
109  const size_t skip = (req.algo_name() == "MARK-4") ? 256 : req.arg_as_integer(0, 0);
110 
111 #if defined(BOTAN_HAS_OPENSSL)
112  if(provider.empty() || provider == "openssl")
113  {
114  return std::unique_ptr<StreamCipher>(make_openssl_rc4(skip));
115  }
116 #endif
117 
118  if(provider.empty() || provider == "base")
119  {
120  return std::unique_ptr<StreamCipher>(new RC4(skip));
121  }
122  }
123 
124 #endif
125 
126  BOTAN_UNUSED(req);
128 
129  return nullptr;
130  }
virtual void cipher(const uint8_t in[], uint8_t out[], size_t len)=0
virtual std::string provider() const
#define BOTAN_UNUSED(...)
Definition: assert.h:142
static std::unique_ptr< BlockCipher > create(const std::string &algo_spec, const std::string &provider="")

◆ create_or_throw()

std::unique_ptr< StreamCipher > Botan::StreamCipher::create_or_throw ( const std::string &  algo_spec,
const std::string &  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 a Lookup_Error if the algo/provider combination cannot be found

Definition at line 134 of file stream_cipher.cpp.

References Botan::StreamCipher::create().

Referenced by Botan::ChaCha_RNG::ChaCha_RNG().

136  {
137  if(auto sc = StreamCipher::create(algo, provider))
138  {
139  return sc;
140  }
141  throw Lookup_Error("Stream cipher", algo, provider);
142  }
virtual std::string provider() const
static std::unique_ptr< StreamCipher > create(const std::string &algo_spec, const std::string &provider="")

◆ decrypt()

template<typename Alloc >
void Botan::StreamCipher::decrypt ( std::vector< uint8_t, Alloc > &  inout)
inlineinherited

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

Parameters
inoutthe plaintext / ciphertext

Definition at line 105 of file stream_cipher.h.

106  { cipher(inout.data(), inout.data(), inout.size()); }
virtual void cipher(const uint8_t in[], uint8_t out[], size_t len)=0

◆ default_iv_length()

size_t Botan::ChaCha::default_iv_length ( ) const
overridevirtual

Return the default (preferred) nonce length If this function returns 0, then this cipher does not support nonces

Reimplemented from Botan::StreamCipher.

Definition at line 280 of file chacha.cpp.

281  {
282  return 24;
283  }

◆ encipher()

template<typename Alloc >
void Botan::StreamCipher::encipher ( std::vector< uint8_t, Alloc > &  inout)
inlineinherited

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

Parameters
inoutthe plaintext / ciphertext

Definition at line 87 of file stream_cipher.h.

88  { cipher(inout.data(), inout.data(), inout.size()); }
virtual void cipher(const uint8_t in[], uint8_t out[], size_t len)=0

◆ encrypt()

template<typename Alloc >
void Botan::StreamCipher::encrypt ( std::vector< uint8_t, Alloc > &  inout)
inlineinherited

Encrypt a message The message is encrypted in place.

Parameters
inoutthe plaintext / ciphertext

Definition at line 96 of file stream_cipher.h.

97  { cipher(inout.data(), inout.data(), inout.size()); }
virtual void cipher(const uint8_t in[], uint8_t out[], size_t len)=0

◆ key_spec()

Key_Length_Specification Botan::ChaCha::key_spec ( ) const
overridevirtual
Returns
object describing limits on key size

Implements Botan::SymmetricAlgorithm.

Definition at line 285 of file chacha.cpp.

286  {
287  return Key_Length_Specification(16, 32, 16);
288  }

◆ maximum_keylength()

size_t Botan::SymmetricAlgorithm::maximum_keylength ( ) const
inlineinherited
Returns
minimum allowed key length

Definition at line 38 of file sym_algo.h.

39  {
40  return key_spec().maximum_keylength();
41  }
size_t maximum_keylength() const
Definition: key_spec.h:69
virtual Key_Length_Specification key_spec() const =0

◆ minimum_keylength()

size_t Botan::SymmetricAlgorithm::minimum_keylength ( ) const
inlineinherited
Returns
maximum allowed key length

Definition at line 46 of file sym_algo.h.

Referenced by botan_block_cipher_get_keyspec(), and botan_mac_get_keyspec().

47  {
48  return key_spec().minimum_keylength();
49  }
virtual Key_Length_Specification key_spec() const =0
size_t minimum_keylength() const
Definition: key_spec.h:61

◆ name()

std::string Botan::ChaCha::name ( ) const
overridevirtual
Returns
the algorithm name

Implements Botan::SymmetricAlgorithm.

Definition at line 362 of file chacha.cpp.

References Botan::ASN1::to_string().

Referenced by set_iv().

363  {
364  return "ChaCha(" + std::to_string(m_rounds) + ")";
365  }
std::string to_string(const BER_Object &obj)
Definition: asn1_obj.cpp:210

◆ provider()

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

Reimplemented from Botan::StreamCipher.

Definition at line 69 of file chacha.cpp.

References BOTAN_ASSERT, CHACHA_QUARTER_ROUND, Botan::CPUID::has_simd_32(), and Botan::store_le().

70  {
71 #if defined(BOTAN_HAS_CHACHA_AVX2)
72  if(CPUID::has_avx2())
73  {
74  return "avx2";
75  }
76 #endif
77 
78 #if defined(BOTAN_HAS_CHACHA_SIMD32)
79  if(CPUID::has_simd_32())
80  {
81  return "simd32";
82  }
83 #endif
84 
85  return "base";
86  }
static bool has_simd_32()
Definition: cpuid.cpp:23

◆ providers()

std::vector< std::string > Botan::StreamCipher::providers ( const std::string &  algo_spec)
staticinherited
Returns
list of available providers for this algorithm, empty if not available

Definition at line 144 of file stream_cipher.cpp.

Referenced by Botan::TLS::Ciphersuite::by_id().

145  {
146  return probe_providers_of<StreamCipher>(algo_spec, {"base", "openssl"});
147  }

◆ seek()

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

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

Parameters
offsetthe offset where we begin to generate the keystream

Implements Botan::StreamCipher.

Definition at line 367 of file chacha.cpp.

References Botan::load_le< uint32_t >(), Botan::store_le(), and Botan::SymmetricAlgorithm::verify_key_set().

368  {
369  verify_key_set(m_state.empty() == false);
370 
371  // Find the block offset
372  const uint64_t counter = offset / 64;
373 
374  uint8_t out[8];
375 
376  store_le(counter, out);
377 
378  m_state[12] = load_le<uint32_t>(out, 0);
379  m_state[13] += load_le<uint32_t>(out, 1);
380 
381  chacha_x8(m_buffer.data(), m_state.data(), m_rounds);
382  m_position = offset % 64;
383  }
void verify_key_set(bool cond) const
Definition: sym_algo.h:89
uint32_t load_le< uint32_t >(const uint8_t in[], size_t off)
Definition: loadstor.h:196
void store_le(uint16_t in, uint8_t out[2])
Definition: loadstor.h:452

◆ set_iv()

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

Resync the cipher using the IV

Parameters
ivthe initialization vector
iv_lenthe length of the IV in bytes

Implements Botan::StreamCipher.

Definition at line 300 of file chacha.cpp.

References Botan::load_le< uint32_t >(), name(), valid_iv_length(), and Botan::SymmetricAlgorithm::verify_key_set().

Referenced by write_keystream().

301  {
302  verify_key_set(m_state.empty() == false);
303 
304  if(!valid_iv_length(length))
305  throw Invalid_IV_Length(name(), length);
306 
307  initialize_state();
308 
309  if(length == 0)
310  {
311  // Treat zero length IV same as an all-zero IV
312  m_state[14] = 0;
313  m_state[15] = 0;
314  }
315  else if(length == 8)
316  {
317  m_state[14] = load_le<uint32_t>(iv, 0);
318  m_state[15] = load_le<uint32_t>(iv, 1);
319  }
320  else if(length == 12)
321  {
322  m_state[13] = load_le<uint32_t>(iv, 0);
323  m_state[14] = load_le<uint32_t>(iv, 1);
324  m_state[15] = load_le<uint32_t>(iv, 2);
325  }
326  else if(length == 24)
327  {
328  m_state[12] = load_le<uint32_t>(iv, 0);
329  m_state[13] = load_le<uint32_t>(iv, 1);
330  m_state[14] = load_le<uint32_t>(iv, 2);
331  m_state[15] = load_le<uint32_t>(iv, 3);
332 
333  secure_vector<uint32_t> hc(8);
334  hchacha(hc.data(), m_state.data(), m_rounds);
335 
336  m_state[ 4] = hc[0];
337  m_state[ 5] = hc[1];
338  m_state[ 6] = hc[2];
339  m_state[ 7] = hc[3];
340  m_state[ 8] = hc[4];
341  m_state[ 9] = hc[5];
342  m_state[10] = hc[6];
343  m_state[11] = hc[7];
344  m_state[12] = 0;
345  m_state[13] = 0;
346  m_state[14] = load_le<uint32_t>(iv, 4);
347  m_state[15] = load_le<uint32_t>(iv, 5);
348  }
349 
350  chacha_x8(m_buffer.data(), m_state.data(), m_rounds);
351  m_position = 0;
352  }
void verify_key_set(bool cond) const
Definition: sym_algo.h:89
uint32_t load_le< uint32_t >(const uint8_t in[], size_t off)
Definition: loadstor.h:196
bool valid_iv_length(size_t iv_len) const override
Definition: chacha.cpp:295
std::string name() const override
Definition: chacha.cpp:362

◆ set_key() [1/3]

void Botan::SymmetricAlgorithm::set_key ( const SymmetricKey key)
inlineinherited

◆ set_key() [2/3]

template<typename Alloc >
void Botan::SymmetricAlgorithm::set_key ( const std::vector< uint8_t, Alloc > &  key)
inlineinherited

Definition at line 71 of file sym_algo.h.

References name.

72  {
73  set_key(key.data(), key.size());
74  }
void set_key(const SymmetricKey &key)
Definition: sym_algo.h:65

◆ set_key() [3/3]

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

Set the symmetric key of this object.

Parameters
keythe to be set as a byte array.
lengthin bytes of key param

Definition at line 17 of file sym_algo.cpp.

References Botan::SymmetricAlgorithm::name(), and Botan::SymmetricAlgorithm::valid_keylength().

18  {
19  if(!valid_keylength(length))
20  throw Invalid_Key_Length(name(), length);
21  key_schedule(key, length);
22  }
bool valid_keylength(size_t length) const
Definition: sym_algo.h:56
virtual std::string name() const =0

◆ valid_iv_length()

bool Botan::ChaCha::valid_iv_length ( size_t  iv_len) const
overridevirtual
Parameters
iv_lenthe length of the IV in bytes
Returns
if the length is valid for this algorithm

Reimplemented from Botan::StreamCipher.

Definition at line 295 of file chacha.cpp.

Referenced by set_iv().

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

◆ valid_keylength()

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

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

Parameters
lengththe key length to be checked.
Returns
true if the key length is valid.

Definition at line 56 of file sym_algo.h.

Referenced by Botan::aont_package(), Botan::aont_unpackage(), and Botan::SymmetricAlgorithm::set_key().

57  {
58  return key_spec().valid_keylength(length);
59  }
bool valid_keylength(size_t length) const
Definition: key_spec.h:51
virtual Key_Length_Specification key_spec() const =0

◆ verify_key_set()

void Botan::SymmetricAlgorithm::verify_key_set ( bool  cond) const
inlineprotectedinherited

Definition at line 89 of file sym_algo.h.

Referenced by Botan::Salsa20::cipher(), Botan::CTR_BE::cipher(), Botan::RC4::cipher(), Botan::SHAKE_128_Cipher::cipher(), cipher(), Botan::Poly1305::clear(), Botan::SHACAL2::decrypt_n(), Botan::MISTY1::decrypt_n(), Botan::KASUMI::decrypt_n(), Botan::Noekeon::decrypt_n(), Botan::CAST_256::decrypt_n(), Botan::SEED::decrypt_n(), Botan::IDEA::decrypt_n(), Botan::CAST_128::decrypt_n(), Botan::Twofish::decrypt_n(), Botan::DES::decrypt_n(), Botan::SM4::decrypt_n(), Botan::XTEA::decrypt_n(), Botan::Blowfish::decrypt_n(), Botan::DESX::decrypt_n(), Botan::Threefish_512::decrypt_n(), Botan::Serpent::decrypt_n(), Botan::Lion::decrypt_n(), Botan::TripleDES::decrypt_n(), Botan::GOST_28147_89::decrypt_n(), Botan::XTEA::encrypt_n(), Botan::CAST_256::encrypt_n(), Botan::MISTY1::encrypt_n(), Botan::DESX::encrypt_n(), Botan::Noekeon::encrypt_n(), Botan::IDEA::encrypt_n(), Botan::CAST_128::encrypt_n(), Botan::SEED::encrypt_n(), Botan::DES::encrypt_n(), Botan::SHACAL2::encrypt_n(), Botan::SM4::encrypt_n(), Botan::Blowfish::encrypt_n(), Botan::KASUMI::encrypt_n(), Botan::Twofish::encrypt_n(), Botan::Threefish_512::encrypt_n(), Botan::Serpent::encrypt_n(), Botan::Lion::encrypt_n(), Botan::TripleDES::encrypt_n(), Botan::GOST_28147_89::encrypt_n(), Botan::OCB_Encryption::finish(), Botan::OCB_Decryption::finish(), Botan::GHASH::ghash_update(), Botan::CFB_Encryption::process(), Botan::CFB_Decryption::process(), Botan::Salsa20::seek(), Botan::CTR_BE::seek(), seek(), Botan::OCB_Mode::set_associated_data(), Botan::Salsa20::set_iv(), set_iv(), Botan::GHASH::update(), Botan::GHASH::update_associated_data(), Botan::CFB_Mode::valid_nonce_length(), and write_keystream().

90  {
91  if(cond == false)
92  throw_key_not_set_error();
93  }

◆ write_keystream()

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

Write keystream bytes to a buffer

Parameters
outthe byte array to hold the keystream
lenthe length of out in bytes

Reimplemented from Botan::StreamCipher.

Definition at line 196 of file chacha.cpp.

References Botan::copy_mem(), Botan::load_le< uint32_t >(), set_iv(), and Botan::SymmetricAlgorithm::verify_key_set().

197  {
198  verify_key_set(m_state.empty() == false);
199 
200  while(length >= m_buffer.size() - m_position)
201  {
202  const size_t available = m_buffer.size() - m_position;
203 
204  copy_mem(out, &m_buffer[m_position], available);
205  chacha_x8(m_buffer.data(), m_state.data(), m_rounds);
206 
207  length -= available;
208  out += available;
209  m_position = 0;
210  }
211 
212  copy_mem(out, &m_buffer[m_position], length);
213 
214  m_position += length;
215  }
void verify_key_set(bool cond) const
Definition: sym_algo.h:89
void copy_mem(T *out, const T *in, size_t n)
Definition: mem_ops.h:122

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