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

#include <stream_cipher.h>

Inheritance diagram for Botan::StreamCipher:
Botan::SymmetricAlgorithm Botan::CTR_BE Botan::ChaCha Botan::OFB Botan::RC4 Botan::SHAKE_Cipher Botan::Salsa20 Botan::SHAKE_128_Cipher Botan::SHAKE_256_Cipher

Public Member Functions

virtual size_t buffer_size () const =0
 
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)
 
virtual void clear ()=0
 
StreamCipherclone () const
 
void decrypt (std::span< uint8_t > inout)
 
virtual size_t default_iv_length () const
 
void encipher (std::span< uint8_t > inout)
 
void encrypt (std::span< uint8_t > inout)
 
virtual bool has_keying_material () const =0
 
virtual Key_Length_Specification key_spec () const =0
 
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
 
virtual std::string name () const =0
 
virtual std::unique_ptr< StreamCiphernew_object () const =0
 
virtual std::string provider () const
 
virtual void seek (uint64_t offset)=0
 
void set_iv (const uint8_t iv[], size_t iv_len)
 
void set_iv (std::span< const uint8_t > iv)
 
void set_key (const SymmetricKey &key)
 
void set_key (const uint8_t key[], size_t length)
 
void set_key (std::span< const uint8_t > key)
 
virtual bool valid_iv_length (size_t iv_len) const
 
bool valid_keylength (size_t length) const
 
void write_keystream (std::span< uint8_t > out)
 
void write_keystream (uint8_t out[], size_t len)
 
 ~StreamCipher () override=default
 

Static Public Member Functions

static std::unique_ptr< StreamCiphercreate (std::string_view algo_spec, std::string_view provider="")
 
static std::unique_ptr< StreamCiphercreate_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
 
virtual void cipher_bytes (const uint8_t in[], uint8_t out[], size_t len)=0
 
virtual void generate_keystream (uint8_t out[], size_t len)
 
virtual void set_iv_bytes (const uint8_t iv[], size_t iv_len)=0
 

Detailed Description

Base class for all stream ciphers

Definition at line 23 of file stream_cipher.h.

Constructor & Destructor Documentation

◆ ~StreamCipher()

Botan::StreamCipher::~StreamCipher ( )
overridedefault

Member Function Documentation

◆ assert_key_material_set() [1/2]

void Botan::SymmetricAlgorithm::assert_key_material_set ( ) const
inlineprotectedinherited

Definition at line 139 of file sym_algo.h.

virtual bool has_keying_material() const =0
void assert_key_material_set() const
Definition sym_algo.h:139

References Botan::SymmetricAlgorithm::assert_key_material_set().

Referenced by Botan::SymmetricAlgorithm::assert_key_material_set(), Botan::Salsa20::cipher_bytes(), Botan::AES_128::decrypt_n(), Botan::AES_192::decrypt_n(), Botan::AES_256::decrypt_n(), Botan::ARIA_128::decrypt_n(), Botan::ARIA_192::decrypt_n(), Botan::ARIA_256::decrypt_n(), Botan::Blowfish::decrypt_n(), Botan::Camellia_128::decrypt_n(), Botan::Camellia_192::decrypt_n(), Botan::Camellia_256::decrypt_n(), Botan::CAST_128::decrypt_n(), Botan::DES::decrypt_n(), Botan::GOST_28147_89::decrypt_n(), Botan::IDEA::decrypt_n(), Botan::Kuznyechik::decrypt_n(), Botan::Lion::decrypt_n(), Botan::Noekeon::decrypt_n(), Botan::SEED::decrypt_n(), Botan::Serpent::decrypt_n(), Botan::SHACAL2::decrypt_n(), Botan::SM4::decrypt_n(), Botan::Threefish_512::decrypt_n(), Botan::TripleDES::decrypt_n(), Botan::Twofish::decrypt_n(), Botan::AES_128::encrypt_n(), Botan::AES_192::encrypt_n(), Botan::AES_256::encrypt_n(), Botan::ARIA_128::encrypt_n(), Botan::ARIA_192::encrypt_n(), Botan::ARIA_256::encrypt_n(), Botan::Blowfish::encrypt_n(), Botan::Camellia_128::encrypt_n(), Botan::Camellia_192::encrypt_n(), Botan::Camellia_256::encrypt_n(), Botan::CAST_128::encrypt_n(), Botan::DES::encrypt_n(), Botan::GOST_28147_89::encrypt_n(), Botan::IDEA::encrypt_n(), Botan::Kuznyechik::encrypt_n(), Botan::Lion::encrypt_n(), Botan::Noekeon::encrypt_n(), Botan::SEED::encrypt_n(), Botan::Serpent::encrypt_n(), Botan::SHACAL2::encrypt_n(), Botan::SM4::encrypt_n(), Botan::Threefish_512::encrypt_n(), Botan::TripleDES::encrypt_n(), Botan::Twofish::encrypt_n(), Botan::GHASH::final(), Botan::GHASH::ghash_update(), Botan::ChaCha::seek(), Botan::CTR_BE::seek(), Botan::Salsa20::seek(), 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 141 of file sym_algo.h.

141 {
142 if(!predicate) {
143 throw_key_not_set_error();
144 }
145 }

◆ buffer_size()

virtual size_t Botan::StreamCipher::buffer_size ( ) const
pure virtual

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.

Implemented in Botan::ChaCha, Botan::CTR_BE, Botan::OFB, Botan::RC4, Botan::Salsa20, and Botan::SHAKE_Cipher.

◆ cipher() [1/2]

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

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

Definition at line 56 of file stream_cipher.h.

56{ cipher_bytes(in, out, len); }
virtual void cipher_bytes(const uint8_t in[], uint8_t out[], size_t len)=0

Referenced by create(), Botan::Sodium::crypto_stream_salsa20_xor_ic(), and Botan::Sodium::crypto_stream_xsalsa20_xor_ic().

◆ cipher() [2/2]

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

Encrypt or decrypt a message

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

Definition at line 64 of file stream_cipher.h.

64 {
65 BOTAN_ARG_CHECK(in.size() <= out.size(),
66 "Output buffer of stream cipher must be at least as long as input buffer");
67 cipher_bytes(in.data(), out.data(), in.size());
68 }
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:29

References BOTAN_ARG_CHECK.

◆ cipher1() [1/2]

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

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

Parameters
bufthe plaintext / ciphertext

Definition at line 114 of file stream_cipher.h.

114{ cipher(buf, buf); }
void cipher(const uint8_t in[], uint8_t out[], size_t len)

◆ cipher1() [2/2]

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

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 107 of file stream_cipher.h.

107{ cipher(buf, buf, len); }

Referenced by generate_keystream().

◆ cipher_bytes()

virtual void Botan::StreamCipher::cipher_bytes ( const uint8_t in[],
uint8_t out[],
size_t len )
protectedpure virtual

Encrypt or decrypt a message

Implemented in Botan::Salsa20.

◆ clear()

◆ clone()

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

Definition at line 182 of file stream_cipher.h.

182{ return this->new_object().release(); }
virtual std::unique_ptr< StreamCipher > new_object() const =0

◆ create()

std::unique_ptr< StreamCipher > Botan::StreamCipher::create ( 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_specalgorithm name
providerprovider implementation to use
Returns
a null pointer if the algo/provider combination cannot be found

Definition at line 40 of file stream_cipher.cpp.

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

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 = "" )
static

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 122 of file stream_cipher.cpp.

122 {
123 if(auto sc = StreamCipher::create(algo, provider)) {
124 return sc;
125 }
126 throw Lookup_Error("Stream cipher", algo, provider);
127}
static std::unique_ptr< StreamCipher > create(std::string_view algo_spec, std::string_view 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)
inline

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

Parameters
inoutthe plaintext / ciphertext

Definition at line 135 of file stream_cipher.h.

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

◆ default_iv_length()

size_t Botan::StreamCipher::default_iv_length ( ) const
virtual

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

Default implementation returns 0

Reimplemented in Botan::ChaCha, Botan::CTR_BE, Botan::OFB, and Botan::Salsa20.

Definition at line 133 of file stream_cipher.cpp.

133 {
134 return 0;
135}

◆ encipher()

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

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

Parameters
inoutthe plaintext / ciphertext

Definition at line 121 of file stream_cipher.h.

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

◆ encrypt()

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

Encrypt a message The message is encrypted in place.

Parameters
inoutthe plaintext / ciphertext

Definition at line 128 of file stream_cipher.h.

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

◆ generate_keystream()

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

Write keystream bytes to a buffer

Definition at line 137 of file stream_cipher.cpp.

137 {
138 clear_mem(out, len);
139 cipher1(out, len);
140}
void cipher1(uint8_t buf[], size_t len)
constexpr void clear_mem(T *ptr, size_t n)
Definition mem_ops.h:120

References cipher1(), and Botan::clear_mem().

◆ has_keying_material()

◆ key_spec()

◆ keystream_bytes()

template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T Botan::StreamCipher::keystream_bytes ( size_t bytes)
inline

Get bytes from the keystream

Parameters
bytesThe number of bytes to be produced

Definition at line 95 of file stream_cipher.h.

95 {
96 T out(bytes);
97 write_keystream(out);
98 return out;
99 }
void write_keystream(uint8_t out[], size_t len)
FE_25519 T
Definition ge.cpp:34

References T.

◆ maximum_keylength()

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

Definition at line 95 of file sym_algo.h.

95{ return key_spec().maximum_keylength(); }
size_t maximum_keylength() const
Definition sym_algo.h:54
virtual Key_Length_Specification key_spec() const =0

◆ minimum_keylength()

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

Definition at line 100 of file sym_algo.h.

100{ return key_spec().minimum_keylength(); }
size_t minimum_keylength() const
Definition sym_algo.h:49

◆ name()

◆ new_object()

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

Implemented in Botan::ChaCha, Botan::CTR_BE, Botan::OFB, Botan::RC4, Botan::Salsa20, Botan::SHAKE_128_Cipher, and Botan::SHAKE_256_Cipher.

◆ provider()

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

Reimplemented in Botan::ChaCha.

Definition at line 199 of file stream_cipher.h.

199{ return "base"; }

Referenced by create(), and create_or_throw().

◆ providers()

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

Definition at line 129 of file stream_cipher.cpp.

129 {
130 return probe_providers_of<StreamCipher>(algo_spec);
131}
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().

◆ seek()

virtual void Botan::StreamCipher::seek ( uint64_t offset)
pure virtual

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

Parameters
offsetthe offset where we begin to generate the keystream

Implemented in Botan::ChaCha, Botan::CTR_BE, Botan::OFB, Botan::RC4, Botan::Salsa20, and Botan::SHAKE_Cipher.

◆ set_iv() [1/2]

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

Resync the cipher using the IV

Parameters
ivthe initialization vector
iv_lenthe length of the IV in bytes

Definition at line 157 of file stream_cipher.h.

157{ set_iv_bytes(iv, iv_len); }
virtual void set_iv_bytes(const uint8_t iv[], size_t iv_len)=0

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)
inline

Resync the cipher using the IV

Parameters
ivthe initialization vector

Definition at line 163 of file stream_cipher.h.

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

◆ set_iv_bytes()

virtual void Botan::StreamCipher::set_iv_bytes ( const uint8_t iv[],
size_t iv_len )
protectedpure virtual

Resync the cipher using the IV

Implemented in Botan::Salsa20.

◆ set_key() [1/3]

◆ 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
keythe to be set as a byte array.
lengthin bytes of key param

Definition at line 126 of file sym_algo.h.

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

References Botan::SymmetricAlgorithm::set_key().

Referenced by Botan::SymmetricAlgorithm::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
keythe contiguous byte range to be set.

Definition at line 17 of file sym_algo.cpp.

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

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

◆ valid_iv_length()

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

Reimplemented in Botan::ChaCha, Botan::CTR_BE, Botan::OFB, and Botan::Salsa20.

Definition at line 177 of file stream_cipher.h.

177{ return (iv_len == 0); }

◆ 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 107 of file sym_algo.h.

107{ return key_spec().valid_keylength(length); }
bool valid_keylength(size_t length) const
Definition sym_algo.h:42

Referenced by Botan::SymmetricAlgorithm::set_key().

◆ write_keystream() [1/2]

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

Fill a given buffer with keystream bytes

The contents of out are ignored/overwritten

Parameters
outthe byte array to hold the keystream

Definition at line 87 of file stream_cipher.h.

87{ generate_keystream(out.data(), out.size()); }
virtual void generate_keystream(uint8_t out[], size_t len)

◆ write_keystream() [2/2]

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

Write keystream bytes to a buffer

The contents of out are ignored/overwritten

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

Definition at line 78 of file stream_cipher.h.

78{ generate_keystream(out, len); }

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


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