Botan 3.3.0
Crypto and TLS for C&
block_cipher.h
Go to the documentation of this file.
1/*
2* Block Cipher Base Class
3* (C) 1999-2009 Jack Lloyd
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#ifndef BOTAN_BLOCK_CIPHER_H_
9#define BOTAN_BLOCK_CIPHER_H_
10
11#include <botan/mem_ops.h>
12#include <botan/sym_algo.h>
13#include <memory>
14#include <string>
15#include <string_view>
16#include <vector>
17
18namespace Botan {
19
20/**
21* This class represents a block cipher object.
22*/
24 public:
25 /**
26 * Create an instance based on a name
27 * If provider is empty then best available is chosen.
28 * @param algo_spec algorithm name
29 * @param provider provider implementation to choose
30 * @return a null pointer if the algo/provider combination cannot be found
31 */
32 static std::unique_ptr<BlockCipher> create(std::string_view algo_spec, std::string_view provider = "");
33
34 /**
35 * Create an instance based on a name, or throw if the
36 * algo/provider combination cannot be found. If provider is
37 * empty then best available is chosen.
38 */
39 static std::unique_ptr<BlockCipher> create_or_throw(std::string_view algo_spec, std::string_view provider = "");
40
41 /**
42 * @return list of available providers for this algorithm, empty if not available
43 * @param algo_spec algorithm name
44 */
45 static std::vector<std::string> providers(std::string_view algo_spec);
46
47 /**
48 * @return block size of this algorithm
49 */
50 virtual size_t block_size() const = 0;
51
52 /**
53 * @return native parallelism of this cipher in blocks
54 */
55 virtual size_t parallelism() const { return 1; }
56
57 /**
58 * @return prefererred parallelism of this cipher in bytes
59 */
60 size_t parallel_bytes() const { return parallelism() * block_size() * BOTAN_BLOCK_CIPHER_PAR_MULT; }
61
62 /**
63 * @return provider information about this implementation. Default is "base",
64 * might also return "sse2", "avx2", "openssl", or some other arbitrary string.
65 */
66 virtual std::string provider() const { return "base"; }
67
68 /**
69 * Encrypt a block.
70 * @param in The plaintext block to be encrypted as a byte array.
71 * Must be of length block_size().
72 * @param out The byte array designated to hold the encrypted block.
73 * Must be of length block_size().
74 */
75 void encrypt(const uint8_t in[], uint8_t out[]) const { encrypt_n(in, out, 1); }
76
77 /**
78 * Decrypt a block.
79 * @param in The ciphertext block to be decypted as a byte array.
80 * Must be of length block_size().
81 * @param out The byte array designated to hold the decrypted block.
82 * Must be of length block_size().
83 */
84 void decrypt(const uint8_t in[], uint8_t out[]) const { decrypt_n(in, out, 1); }
85
86 /**
87 * Encrypt a block.
88 * @param block the plaintext block to be encrypted
89 * Must be of length block_size(). Will hold the result when the function
90 * has finished.
91 */
92 void encrypt(uint8_t block[]) const { encrypt_n(block, block, 1); }
93
94 /**
95 * Decrypt a block.
96 * @param block the ciphertext block to be decrypted
97 * Must be of length block_size(). Will hold the result when the function
98 * has finished.
99 */
100 void decrypt(uint8_t block[]) const { decrypt_n(block, block, 1); }
101
102 /**
103 * Encrypt one or more blocks
104 * @param block the input/output buffer (multiple of block_size())
105 */
106 void encrypt(std::span<uint8_t> block) const {
107 return encrypt_n(block.data(), block.data(), block.size() / block_size());
108 }
109
110 /**
111 * Decrypt one or more blocks
112 * @param block the input/output buffer (multiple of block_size())
113 */
114 void decrypt(std::span<uint8_t> block) const {
115 return decrypt_n(block.data(), block.data(), block.size() / block_size());
116 }
117
118 /**
119 * Encrypt one or more blocks
120 * @param in the input buffer (multiple of block_size())
121 * @param out the output buffer (same size as in)
122 */
123 void encrypt(std::span<const uint8_t> in, std::span<uint8_t> out) const {
124 return encrypt_n(in.data(), out.data(), in.size() / block_size());
125 }
126
127 /**
128 * Decrypt one or more blocks
129 * @param in the input buffer (multiple of block_size())
130 * @param out the output buffer (same size as in)
131 */
132 void decrypt(std::span<const uint8_t> in, std::span<uint8_t> out) const {
133 return decrypt_n(in.data(), out.data(), in.size() / block_size());
134 }
135
136 /**
137 * Encrypt one or more blocks
138 * @param in the input buffer (multiple of block_size())
139 * @param out the output buffer (same size as in)
140 * @param blocks the number of blocks to process
141 */
142 virtual void encrypt_n(const uint8_t in[], uint8_t out[], size_t blocks) const = 0;
143
144 /**
145 * Decrypt one or more blocks
146 * @param in the input buffer (multiple of block_size())
147 * @param out the output buffer (same size as in)
148 * @param blocks the number of blocks to process
149 */
150 virtual void decrypt_n(const uint8_t in[], uint8_t out[], size_t blocks) const = 0;
151
152 virtual void encrypt_n_xex(uint8_t data[], const uint8_t mask[], size_t blocks) const {
153 const size_t BS = block_size();
154 xor_buf(data, mask, blocks * BS);
155 encrypt_n(data, data, blocks);
156 xor_buf(data, mask, blocks * BS);
157 }
158
159 virtual void decrypt_n_xex(uint8_t data[], const uint8_t mask[], size_t blocks) const {
160 const size_t BS = block_size();
161 xor_buf(data, mask, blocks * BS);
162 decrypt_n(data, data, blocks);
163 xor_buf(data, mask, blocks * BS);
164 }
165
166 /**
167 * @return new object representing the same algorithm as *this
168 */
169 virtual std::unique_ptr<BlockCipher> new_object() const = 0;
170
171 BlockCipher* clone() const { return this->new_object().release(); }
172
173 ~BlockCipher() override = default;
174};
175
176/**
177* Tweakable block ciphers allow setting a tweak which is a non-keyed
178* value which affects the encryption/decryption operation.
179*/
181 public:
182 /**
183 * Set the tweak value. This must be called after setting a key. The value
184 * persists until either set_tweak, set_key, or clear is called.
185 * Different algorithms support different tweak length(s). If called with
186 * an unsupported length, Invalid_Argument will be thrown.
187 */
188 virtual void set_tweak(const uint8_t tweak[], size_t len) = 0;
189};
190
191/**
192* Represents a block cipher with a single fixed block size
193*/
194template <size_t BS, size_t KMIN, size_t KMAX = 0, size_t KMOD = 1, typename BaseClass = BlockCipher>
195class Block_Cipher_Fixed_Params : public BaseClass {
196 public:
197 enum { BLOCK_SIZE = BS };
198
199 size_t block_size() const final { return BS; }
200
201 // override to take advantage of compile time constant block size
202 void encrypt_n_xex(uint8_t data[], const uint8_t mask[], size_t blocks) const final {
203 xor_buf(data, mask, blocks * BS);
204 this->encrypt_n(data, data, blocks);
205 xor_buf(data, mask, blocks * BS);
206 }
207
208 void decrypt_n_xex(uint8_t data[], const uint8_t mask[], size_t blocks) const final {
209 xor_buf(data, mask, blocks * BS);
210 this->decrypt_n(data, data, blocks);
211 xor_buf(data, mask, blocks * BS);
212 }
213
215};
216
217} // namespace Botan
218
219#endif
void encrypt(const uint8_t in[], uint8_t out[]) const
void decrypt(const uint8_t in[], uint8_t out[]) const
void decrypt(std::span< uint8_t > block) const
void decrypt(std::span< const uint8_t > in, std::span< uint8_t > out) const
~BlockCipher() override=default
void encrypt(std::span< const uint8_t > in, std::span< uint8_t > out) const
virtual void encrypt_n_xex(uint8_t data[], const uint8_t mask[], size_t blocks) const
void encrypt(std::span< uint8_t > block) const
virtual void decrypt_n(const uint8_t in[], uint8_t out[], size_t blocks) const =0
virtual void decrypt_n_xex(uint8_t data[], const uint8_t mask[], size_t blocks) const
virtual void encrypt_n(const uint8_t in[], uint8_t out[], size_t blocks) const =0
BlockCipher * clone() const
virtual std::unique_ptr< BlockCipher > new_object() const =0
virtual size_t block_size() const =0
virtual size_t parallelism() const
void decrypt(uint8_t block[]) const
virtual std::string provider() const
size_t parallel_bytes() const
void encrypt(uint8_t block[]) const
size_t block_size() const final
void encrypt_n_xex(uint8_t data[], const uint8_t mask[], size_t blocks) const final
Key_Length_Specification key_spec() const final
void decrypt_n_xex(uint8_t data[], const uint8_t mask[], size_t blocks) const final
virtual void set_tweak(const uint8_t tweak[], size_t len)=0
int(* final)(unsigned char *, CTX *)
#define BOTAN_PUBLIC_API(maj, min)
Definition compiler.h:31
#define BOTAN_BLOCK_CIPHER_PAR_MULT
Definition build.h:442
constexpr void xor_buf(ranges::contiguous_output_range< uint8_t > auto &&out, ranges::contiguous_range< uint8_t > auto &&in)
Definition mem_ops.h:340