Botan 3.14.1
Crypto and TLS for C&
Botan::BlockCipher Class Referenceabstract

#include <block_cipher.h>

Inheritance diagram for Botan::BlockCipher:
Botan::SymmetricAlgorithm Botan::Block_Cipher_Fixed_Params< 16, 16 > Botan::Block_Cipher_Fixed_Params< 16, 24 > Botan::Block_Cipher_Fixed_Params< 16, 32 > Botan::Block_Cipher_Fixed_Params< 8, 1, 72 > Botan::Block_Cipher_Fixed_Params< 8, 11, 16 > Botan::Block_Cipher_Fixed_Params< 8, 8 > Botan::Block_Cipher_Fixed_Params< 8, 32 > Botan::Block_Cipher_Fixed_Params< 8, 16 > Botan::Block_Cipher_Fixed_Params< 32, 16, 64, 4 > Botan::Block_Cipher_Fixed_Params< 16, 16, 32, 8 > Botan::Block_Cipher_Fixed_Params< 8, 16, 24, 8 > Botan::Block_Cipher_Fixed_Params< BS, KMIN, KMAX, KMOD, BaseClass > Botan::Cascade_Cipher Botan::Lion Botan::Tweakable_Block_Cipher

Public Member Functions

virtual size_t block_size () const =0
virtual void clear ()=0
BlockCipher * clone () const
void decrypt (const uint8_t in[], uint8_t out[]) const
void decrypt (std::span< const uint8_t > in, std::span< uint8_t > out) const
void decrypt (std::span< uint8_t > block) const
void decrypt (uint8_t block[]) const
virtual void decrypt_n (const uint8_t in[], uint8_t out[], size_t blocks) const =0
void decrypt_n_xex (uint8_t data[], const uint8_t mask[], size_t blocks) const
void encrypt (const uint8_t in[], uint8_t out[]) const
void encrypt (std::span< const uint8_t > in, std::span< uint8_t > out) const
void encrypt (std::span< uint8_t > block) const
void encrypt (uint8_t block[]) const
virtual void encrypt_n (const uint8_t in[], uint8_t out[], size_t blocks) const =0
void encrypt_n_xex (uint8_t data[], const uint8_t mask[], size_t blocks) const
virtual bool has_keying_material () const =0
virtual Key_Length_Specification key_spec () const =0
size_t maximum_keylength () const
size_t minimum_keylength () const
virtual std::string name () const =0
virtual std::unique_ptr< BlockCipher > new_object () const =0
size_t parallel_bytes () const
virtual size_t parallelism () const
virtual std::string provider () const
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_keylength (size_t length) const

Static Public Member Functions

static std::unique_ptr< BlockCipher > create (std::string_view algo_spec, std::string_view provider="")
static std::unique_ptr< BlockCipher > create_or_throw (std::string_view algo_spec, std::string_view provider="")
static std::vector< std::string > providers (std::string_view algo_spec)

Static Public Attributes

static constexpr size_t ParallelismMult = 4

Protected Member Functions

void assert_key_material_set () const
void assert_key_material_set (bool predicate) const

Detailed Description

This class represents a block cipher object.

Definition at line 22 of file block_cipher.h.

Member Function Documentation

◆ assert_key_material_set() [1/2]

◆ assert_key_material_set() [2/2]

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

Throw Key_Not_Set unless the predicate holds

Parameters
predicateif false, a Key_Not_Set exception is thrown

Definition at line 186 of file sym_algo.h.

186 {
187 if(!predicate) {
188 throw_key_not_set_error();
189 }
190 }

◆ block_size()

◆ clear()

◆ clone()

BlockCipher * Botan::BlockCipher::clone ( ) const
inline

Create a new uninitialized object of the same type

Returns
new object representing the same algorithm as *this

Definition at line 210 of file block_cipher.h.

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

References new_object().

◆ create()

std::unique_ptr< BlockCipher > Botan::BlockCipher::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 choose
Returns
a null pointer if the algo/provider combination cannot be found

Definition at line 97 of file block_cipher.cpp.

97 {
98#if defined(BOTAN_HAS_COMMONCRYPTO)
99 if(provider.empty() || provider == "commoncrypto") {
100 if(auto bc = make_commoncrypto_block_cipher(algo))
101 return bc;
102
103 if(!provider.empty())
104 return nullptr;
105 }
106#endif
107
108 // TODO: CryptoAPI
109 // TODO: /dev/crypto
110
111 // Only base providers from here on out
112 if(provider.empty() == false && provider != "base") {
113 return nullptr;
114 }
115
116#if defined(BOTAN_HAS_AES)
117 if(algo == "AES-128") {
118 return std::make_unique<AES_128>();
119 }
120
121 if(algo == "AES-192") {
122 return std::make_unique<AES_192>();
123 }
124
125 if(algo == "AES-256") {
126 return std::make_unique<AES_256>();
127 }
128#endif
129
130#if defined(BOTAN_HAS_ARIA)
131 if(algo == "ARIA-128") {
132 return std::make_unique<ARIA_128>();
133 }
134
135 if(algo == "ARIA-192") {
136 return std::make_unique<ARIA_192>();
137 }
138
139 if(algo == "ARIA-256") {
140 return std::make_unique<ARIA_256>();
141 }
142#endif
143
144#if defined(BOTAN_HAS_SERPENT)
145 if(algo == "Serpent") {
146 return std::make_unique<Serpent>();
147 }
148#endif
149
150#if defined(BOTAN_HAS_SHACAL2)
151 if(algo == "SHACAL2") {
152 return std::make_unique<SHACAL2>();
153 }
154#endif
155
156#if defined(BOTAN_HAS_TWOFISH)
157 if(algo == "Twofish") {
158 return std::make_unique<Twofish>();
159 }
160#endif
161
162#if defined(BOTAN_HAS_THREEFISH_512)
163 if(algo == "Threefish-512") {
164 return std::make_unique<Threefish_512>();
165 }
166#endif
167
168#if defined(BOTAN_HAS_BLOWFISH)
169 if(algo == "Blowfish") {
170 return std::make_unique<Blowfish>();
171 }
172#endif
173
174#if defined(BOTAN_HAS_CAMELLIA)
175 if(algo == "Camellia-128") {
176 return std::make_unique<Camellia_128>();
177 }
178
179 if(algo == "Camellia-192") {
180 return std::make_unique<Camellia_192>();
181 }
182
183 if(algo == "Camellia-256") {
184 return std::make_unique<Camellia_256>();
185 }
186#endif
187
188#if defined(BOTAN_HAS_DES)
189 if(algo == "DES") {
190 return std::make_unique<DES>();
191 }
192
193 if(algo == "TripleDES" || algo == "3DES" || algo == "DES-EDE") {
194 return std::make_unique<TripleDES>();
195 }
196#endif
197
198#if defined(BOTAN_HAS_NOEKEON)
199 if(algo == "Noekeon") {
200 return std::make_unique<Noekeon>();
201 }
202#endif
203
204#if defined(BOTAN_HAS_CAST_128)
205 if(algo == "CAST-128" || algo == "CAST5") {
206 return std::make_unique<CAST_128>();
207 }
208#endif
209
210#if defined(BOTAN_HAS_IDEA)
211 if(algo == "IDEA") {
212 return std::make_unique<IDEA>();
213 }
214#endif
215
216#if defined(BOTAN_HAS_KUZNYECHIK)
217 if(algo == "Kuznyechik") {
218 return std::make_unique<Kuznyechik>();
219 }
220#endif
221
222#if defined(BOTAN_HAS_SEED)
223 if(algo == "SEED") {
224 return std::make_unique<SEED>();
225 }
226#endif
227
228#if defined(BOTAN_HAS_SM4)
229 if(algo == "SM4") {
230 return std::make_unique<SM4>();
231 }
232#endif
233
234 const AlgorithmSpec req(algo);
235
236#if defined(BOTAN_HAS_GOST_28147_89)
237 if(auto m = req.match("GOST-28147-89({params:str=R3411_94_TestParam})")) {
238 return std::make_unique<GOST_28147_89>(m->str("params"));
239 }
240#endif
241
242#if defined(BOTAN_HAS_CASCADE)
243 if(auto m = req.match("Cascade({cipher1},{cipher2})")) {
244 auto c1 = BlockCipher::create(m->str("cipher1"));
245 auto c2 = BlockCipher::create(m->str("cipher2"));
246
247 if(c1 && c2) {
248 return std::make_unique<Cascade_Cipher>(std::move(c1), std::move(c2));
249 }
250 }
251#endif
252
253#if defined(BOTAN_HAS_LION)
254 if(auto m = req.match("Lion({hash},{stream},{block_size:int=1024})")) {
255 auto hash = HashFunction::create(m->str("hash"));
256 auto stream = StreamCipher::create(m->str("stream"));
257
258 if(hash && stream) {
259 return std::make_unique<Lion>(std::move(hash), std::move(stream), m->integer("block_size"));
260 }
261 }
262#endif
263
264 BOTAN_UNUSED(req);
266
267 return nullptr;
268}
#define BOTAN_UNUSED
Definition assert.h:151
static std::unique_ptr< BlockCipher > create(std::string_view algo_spec, std::string_view provider="")
virtual std::string provider() const
static std::unique_ptr< HashFunction > create(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:112
static std::unique_ptr< StreamCipher > create(std::string_view algo_spec, std::string_view provider="")
std::unique_ptr< BlockCipher > make_commoncrypto_block_cipher(std::string_view name)

References BOTAN_UNUSED, create(), Botan::HashFunction::create(), Botan::StreamCipher::create(), Botan::make_commoncrypto_block_cipher(), Botan::AlgorithmSpec::match(), and provider().

Referenced by botan_block_cipher_init(), Botan::AEAD_Mode::create(), create(), Botan::Cipher_Mode::create(), Botan::MessageAuthenticationCode::create(), Botan::StreamCipher::create(), and create_or_throw().

◆ create_or_throw()

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

Create an instance based on a name, or throw if the algo/provider combination cannot be found. If provider is empty then best available is chosen.

Definition at line 271 of file block_cipher.cpp.

271 {
272 if(auto bc = BlockCipher::create(algo, provider)) {
273 return bc;
274 }
275 throw Lookup_Error("Block cipher", algo, provider);
276}

References create(), and provider().

Referenced by botan_nist_kw_dec(), botan_nist_kw_enc(), Botan::TLS::Connection_Cipher_State::Connection_Cipher_State(), Botan::Encrypted_PSK_Database::Encrypted_PSK_Database(), Botan::rfc3394_keyunwrap(), and Botan::rfc3394_keywrap().

◆ decrypt() [1/4]

void Botan::BlockCipher::decrypt ( const uint8_t in[],
uint8_t out[] ) const
inline

Decrypt a block.

Parameters
inThe ciphertext block to be decrypted as a byte array. Must be of length block_size().
outThe byte array designated to hold the decrypted block. Must be of length block_size().

Definition at line 96 of file block_cipher.h.

96{ decrypt_n(in, out, 1); }
virtual void decrypt_n(const uint8_t in[], uint8_t out[], size_t blocks) const =0

References decrypt_n().

Referenced by Botan::nist_key_unwrap(), and Botan::nist_key_unwrap_padded().

◆ decrypt() [2/4]

void Botan::BlockCipher::decrypt ( std::span< const uint8_t > in,
std::span< uint8_t > out ) const
inline

Decrypt one or more blocks

Parameters
inthe input buffer (multiple of block_size())
outthe output buffer (same size as in)

Definition at line 144 of file block_cipher.h.

144 {
145 return decrypt_n(in.data(), out.data(), in.size() / block_size());
146 }
virtual size_t block_size() const =0

References block_size(), and decrypt_n().

◆ decrypt() [3/4]

void Botan::BlockCipher::decrypt ( std::span< uint8_t > block) const
inline

Decrypt one or more blocks

Parameters
Block Ciphersthe input/output buffer (multiple of block_size())

Definition at line 126 of file block_cipher.h.

126 {
127 return decrypt_n(block.data(), block.data(), block.size() / block_size());
128 }

References block_size(), and decrypt_n().

◆ decrypt() [4/4]

void Botan::BlockCipher::decrypt ( uint8_t block[]) const
inline

Decrypt a block.

Parameters
Block Ciphersthe ciphertext block to be decrypted Must be of length block_size(). Will hold the result when the function has finished.

Definition at line 112 of file block_cipher.h.

112{ decrypt_n(block, block, 1); }

References decrypt_n().

◆ decrypt_n()

virtual void Botan::BlockCipher::decrypt_n ( const uint8_t in[],
uint8_t out[],
size_t blocks ) const
pure virtual

◆ decrypt_n_xex()

void Botan::BlockCipher::decrypt_n_xex ( uint8_t data[],
const uint8_t mask[],
size_t blocks ) const
inline

Decrypt blocks in XEX mode: XOR with the mask, decrypt, then XOR again

Parameters
datathe input/output buffer of blocks*block_size() bytes
maskthe mask to XOR with, same size as data
blocksthe number of blocks to process

Definition at line 189 of file block_cipher.h.

189 {
190 const size_t BS = block_size();
191 for(size_t i = 0; i != blocks * BS; ++i) {
192 data[i] ^= mask[i];
193 }
194 decrypt_n(data, data, blocks);
195 for(size_t i = 0; i != blocks * BS; ++i) {
196 data[i] ^= mask[i];
197 }
198 }

References block_size(), decrypt_n(), and decrypt_n_xex().

Referenced by decrypt_n_xex().

◆ encrypt() [1/4]

void Botan::BlockCipher::encrypt ( const uint8_t in[],
uint8_t out[] ) const
inline

Encrypt a block.

Parameters
inThe plaintext block to be encrypted as a byte array. Must be of length block_size().
outThe byte array designated to hold the encrypted block. Must be of length block_size().

Definition at line 87 of file block_cipher.h.

87{ encrypt_n(in, out, 1); }
virtual void encrypt_n(const uint8_t in[], uint8_t out[], size_t blocks) const =0

References encrypt_n().

Referenced by Botan::nist_key_wrap(), Botan::nist_key_wrap_padded(), and Botan::CFB_Mode::shift_register().

◆ encrypt() [2/4]

void Botan::BlockCipher::encrypt ( std::span< const uint8_t > in,
std::span< uint8_t > out ) const
inline

Encrypt one or more blocks

Parameters
inthe input buffer (multiple of block_size())
outthe output buffer (same size as in)

Definition at line 135 of file block_cipher.h.

135 {
136 return encrypt_n(in.data(), out.data(), in.size() / block_size());
137 }

References block_size(), and encrypt_n().

◆ encrypt() [3/4]

void Botan::BlockCipher::encrypt ( std::span< uint8_t > block) const
inline

Encrypt one or more blocks

Parameters
Block Ciphersthe input/output buffer (multiple of block_size())

Definition at line 118 of file block_cipher.h.

118 {
119 return encrypt_n(block.data(), block.data(), block.size() / block_size());
120 }

References block_size(), and encrypt_n().

◆ encrypt() [4/4]

void Botan::BlockCipher::encrypt ( uint8_t block[]) const
inline

Encrypt a block.

Parameters
Block Ciphersthe plaintext block to be encrypted Must be of length block_size(). Will hold the result when the function has finished.

Definition at line 104 of file block_cipher.h.

104{ encrypt_n(block, block, 1); }

References encrypt_n().

◆ encrypt_n()

virtual void Botan::BlockCipher::encrypt_n ( const uint8_t in[],
uint8_t out[],
size_t blocks ) const
pure virtual

◆ encrypt_n_xex()

void Botan::BlockCipher::encrypt_n_xex ( uint8_t data[],
const uint8_t mask[],
size_t blocks ) const
inline

Encrypt blocks in XEX mode: XOR with the mask, encrypt, then XOR again

Parameters
datathe input/output buffer of blocks*block_size() bytes
maskthe mask to XOR with, same size as data
blocksthe number of blocks to process

Definition at line 171 of file block_cipher.h.

171 {
172 const size_t BS = block_size();
173 for(size_t i = 0; i != blocks * BS; ++i) {
174 data[i] ^= mask[i];
175 }
176 encrypt_n(data, data, blocks);
177 for(size_t i = 0; i != blocks * BS; ++i) {
178 data[i] ^= mask[i];
179 }
180 }

References block_size(), encrypt_n(), and encrypt_n_xex().

Referenced by encrypt_n_xex().

◆ has_keying_material()

◆ key_spec()

virtual Key_Length_Specification Botan::SymmetricAlgorithm::key_spec ( ) const
pure virtualinherited

Return the key lengths supported by this algorithm

Returns
object describing limits on key size

Implemented in Botan::ANSI_X919_MAC, Botan::Ascon_AEAD128_Mode, Botan::BLAKE2b, Botan::BLAKE2bMAC, Botan::Block_Cipher_Fixed_Params< BS, KMIN, KMAX, KMOD, BaseClass >, Botan::Block_Cipher_Fixed_Params< 16, 16 >, Botan::Block_Cipher_Fixed_Params< 16, 16, 32, 8 >, Botan::Block_Cipher_Fixed_Params< 16, 24 >, Botan::Block_Cipher_Fixed_Params< 16, 32 >, Botan::Block_Cipher_Fixed_Params< 32, 16, 64, 4 >, Botan::Block_Cipher_Fixed_Params< 64, 64, 0, 1, Tweakable_Block_Cipher >, Botan::Block_Cipher_Fixed_Params< 8, 1, 72 >, Botan::Block_Cipher_Fixed_Params< 8, 11, 16 >, Botan::Block_Cipher_Fixed_Params< 8, 16 >, Botan::Block_Cipher_Fixed_Params< 8, 16, 24, 8 >, Botan::Block_Cipher_Fixed_Params< 8, 32 >, Botan::Block_Cipher_Fixed_Params< 8, 8 >, Botan::Cascade_Cipher, Botan::CBC_Mode, Botan::CCM_Mode, Botan::CFB_Mode, Botan::ChaCha20Poly1305_Mode, Botan::ChaCha, Botan::CMAC, Botan::CTR_BE, Botan::EAX_Mode, Botan::FPE_FE1, Botan::GCM_Mode, Botan::GCM_SIV_Mode, Botan::GHASH, Botan::GMAC, Botan::HMAC, Botan::KMAC, Botan::Lion, Botan::OCB_Mode, Botan::OFB, Botan::Poly1305, Botan::Polyval, Botan::RC4, Botan::Salsa20, Botan::SHAKE_Cipher, Botan::SipHash, Botan::SIV_Mode, Botan::TLS::TLS_CBC_HMAC_AEAD_Mode, Botan::TLS::TLS_NULL_HMAC_AEAD_Mode, and Botan::XTS_Mode.

Referenced by Botan::CBC_Mode::key_spec(), Botan::CFB_Mode::key_spec(), Botan::XTS_Mode::key_spec(), maximum_keylength(), minimum_keylength(), and valid_keylength().

◆ maximum_keylength()

size_t Botan::SymmetricAlgorithm::maximum_keylength ( ) const
inlineinherited

Return the largest acceptable key length

Returns
maximum allowed key length

Definition at line 130 of file sym_algo.h.

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

References key_spec().

◆ minimum_keylength()

size_t Botan::SymmetricAlgorithm::minimum_keylength ( ) const
inlineinherited

Return the smallest acceptable key length

Returns
minimum allowed key length

Definition at line 136 of file sym_algo.h.

136{ return key_spec().minimum_keylength(); }
size_t minimum_keylength() const
Definition sym_algo.h:52

References key_spec().

◆ name()

◆ new_object()

virtual std::unique_ptr< BlockCipher > Botan::BlockCipher::new_object ( ) const
pure virtual

◆ parallel_bytes()

size_t Botan::BlockCipher::parallel_bytes ( ) const
inline

Return the preferred input size for bulk processing

Returns
preferred parallelism of this cipher in bytes

Definition at line 71 of file block_cipher.h.

static constexpr size_t ParallelismMult
virtual size_t parallelism() const

References block_size(), parallelism(), and ParallelismMult.

Referenced by Botan::CBC_Mode::ideal_granularity().

◆ parallelism()

virtual size_t Botan::BlockCipher::parallelism ( ) const
inlinevirtual

Return how many blocks this cipher processes in parallel

Returns
native parallelism of this cipher in blocks

Reimplemented in Botan::AES_128, Botan::AES_192, Botan::AES_256, Botan::ARIA_128, Botan::ARIA_192, Botan::ARIA_256, Botan::Camellia_128, Botan::Camellia_192, Botan::Camellia_256, Botan::DES, Botan::IDEA, Botan::Noekeon, Botan::SEED, Botan::Serpent, Botan::SHACAL2, Botan::SM4, Botan::TripleDES, and Botan::Twofish.

Definition at line 65 of file block_cipher.h.

65{ return 1; }

Referenced by parallel_bytes().

◆ provider()

virtual std::string Botan::BlockCipher::provider ( ) const
inlinevirtual

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::AES_128, Botan::AES_192, Botan::AES_256, Botan::ARIA_128, Botan::ARIA_192, Botan::ARIA_256, Botan::Camellia_128, Botan::Camellia_192, Botan::Camellia_256, Botan::IDEA, Botan::Noekeon, Botan::SEED, Botan::Serpent, Botan::SHACAL2, Botan::SM4, and Botan::Twofish.

Definition at line 78 of file block_cipher.h.

78{ return "base"; }

Referenced by create(), and create_or_throw().

◆ providers()

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

List the providers available for a given block cipher

Returns
list of available providers for this algorithm, empty if not available
Parameters
algo_specalgorithm name

Definition at line 278 of file block_cipher.cpp.

278 {
279 return probe_providers_of<BlockCipher>(algo, {"base", "commoncrypto"});
280}
std::vector< std::string > probe_providers_of(std::string_view algo_spec, const std::vector< std::string > &possible={"base"})

References Botan::probe_providers_of().

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

162{ 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
keythe contiguous byte range to be set.

Definition at line 22 of file sym_algo.cpp.

22 {
23 if(!valid_keylength(key.size())) {
24 throw Invalid_Key_Length(name(), key.size());
25 }
26 key_schedule(key);
27}
bool valid_keylength(size_t length) const
Definition sym_algo.h:143
virtual std::string name() const =0

References name(), and valid_keylength().

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

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

References key_spec().

Referenced by set_key().

Member Data Documentation

◆ ParallelismMult

size_t Botan::BlockCipher::ParallelismMult = 4
staticconstexpr

Multiplier on a block cipher's native parallelism

Usually notable performance gains come from further loop blocking, at least for 2 or 4x

Definition at line 53 of file block_cipher.h.

Referenced by Botan::GCM_Mode::ideal_granularity(), Botan::GCM_SIV_Mode::ideal_granularity(), and parallel_bytes().


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