Botan 2.19.2
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/sym_algo.h>
12#include <string>
13#include <memory>
14#include <vector>
15
16namespace Botan {
17
18/**
19* This class represents a block cipher object.
20*/
22 {
23 public:
24
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>
33 create(const std::string& algo_spec,
34 const std::string& provider = "");
35
36 /**
37 * Create an instance based on a name, or throw if the
38 * algo/provider combination cannot be found. If provider is
39 * empty then best available is chosen.
40 */
41 static std::unique_ptr<BlockCipher>
42 create_or_throw(const std::string& algo_spec,
43 const std::string& provider = "");
44
45 /**
46 * @return list of available providers for this algorithm, empty if not available
47 * @param algo_spec algorithm name
48 */
49 static std::vector<std::string> providers(const std::string& algo_spec);
50
51 /**
52 * @return block size of this algorithm
53 */
54 virtual size_t block_size() const = 0;
55
56 /**
57 * @return native parallelism of this cipher in blocks
58 */
59 virtual size_t parallelism() const { return 1; }
60
61 /**
62 * @return prefererred parallelism of this cipher in bytes
63 */
64 size_t parallel_bytes() const
65 {
66 return parallelism() * block_size() * BOTAN_BLOCK_CIPHER_PAR_MULT;
67 }
68
69 /**
70 * @return provider information about this implementation. Default is "base",
71 * might also return "sse2", "avx2", "openssl", or some other arbitrary string.
72 */
73 virtual std::string provider() const { return "base"; }
74
75 /**
76 * Encrypt a block.
77 * @param in The plaintext block to be encrypted as a byte array.
78 * Must be of length block_size().
79 * @param out The byte array designated to hold the encrypted block.
80 * Must be of length block_size().
81 */
82 void encrypt(const uint8_t in[], uint8_t out[]) const
83 { encrypt_n(in, out, 1); }
84
85 /**
86 * Decrypt a block.
87 * @param in The ciphertext block to be decypted as a byte array.
88 * Must be of length block_size().
89 * @param out The byte array designated to hold the decrypted block.
90 * Must be of length block_size().
91 */
92 void decrypt(const uint8_t in[], uint8_t out[]) const
93 { decrypt_n(in, out, 1); }
94
95 /**
96 * Encrypt a block.
97 * @param block the plaintext block to be encrypted
98 * Must be of length block_size(). Will hold the result when the function
99 * has finished.
100 */
101 void encrypt(uint8_t block[]) const { encrypt_n(block, block, 1); }
102
103 /**
104 * Decrypt a block.
105 * @param block the ciphertext block to be decrypted
106 * Must be of length block_size(). Will hold the result when the function
107 * has finished.
108 */
109 void decrypt(uint8_t block[]) const { decrypt_n(block, block, 1); }
110
111 /**
112 * Encrypt one or more blocks
113 * @param block the input/output buffer (multiple of block_size())
114 */
115 template<typename Alloc>
116 void encrypt(std::vector<uint8_t, Alloc>& block) const
117 {
118 return encrypt_n(block.data(), block.data(), block.size() / block_size());
119 }
120
121 /**
122 * Decrypt one or more blocks
123 * @param block the input/output buffer (multiple of block_size())
124 */
125 template<typename Alloc>
126 void decrypt(std::vector<uint8_t, Alloc>& block) const
127 {
128 return decrypt_n(block.data(), block.data(), block.size() / block_size());
129 }
130
131 /**
132 * Encrypt one or more blocks
133 * @param in the input buffer (multiple of block_size())
134 * @param out the output buffer (same size as in)
135 */
136 template<typename Alloc, typename Alloc2>
137 void encrypt(const std::vector<uint8_t, Alloc>& in,
138 std::vector<uint8_t, Alloc2>& out) const
139 {
140 return encrypt_n(in.data(), out.data(), in.size() / block_size());
141 }
142
143 /**
144 * Decrypt one or more blocks
145 * @param in the input buffer (multiple of block_size())
146 * @param out the output buffer (same size as in)
147 */
148 template<typename Alloc, typename Alloc2>
149 void decrypt(const std::vector<uint8_t, Alloc>& in,
150 std::vector<uint8_t, Alloc2>& out) const
151 {
152 return decrypt_n(in.data(), out.data(), in.size() / block_size());
153 }
154
155 /**
156 * Encrypt one or more blocks
157 * @param in the input buffer (multiple of block_size())
158 * @param out the output buffer (same size as in)
159 * @param blocks the number of blocks to process
160 */
161 virtual void encrypt_n(const uint8_t in[], uint8_t out[],
162 size_t blocks) const = 0;
163
164 /**
165 * Decrypt one or more blocks
166 * @param in the input buffer (multiple of block_size())
167 * @param out the output buffer (same size as in)
168 * @param blocks the number of blocks to process
169 */
170 virtual void decrypt_n(const uint8_t in[], uint8_t out[],
171 size_t blocks) const = 0;
172
173 virtual void encrypt_n_xex(uint8_t data[],
174 const uint8_t mask[],
175 size_t blocks) const
176 {
177 const size_t BS = block_size();
178 xor_buf(data, mask, blocks * BS);
179 encrypt_n(data, data, blocks);
180 xor_buf(data, mask, blocks * BS);
181 }
182
183 virtual void decrypt_n_xex(uint8_t data[],
184 const uint8_t mask[],
185 size_t blocks) const
186 {
187 const size_t BS = block_size();
188 xor_buf(data, mask, blocks * BS);
189 decrypt_n(data, data, blocks);
190 xor_buf(data, mask, blocks * BS);
191 }
192
193 /**
194 * @return new object representing the same algorithm as *this
195 */
196 virtual BlockCipher* clone() const = 0;
197
198 virtual ~BlockCipher() = default;
199 };
200
201/**
202* Tweakable block ciphers allow setting a tweak which is a non-keyed
203* value which affects the encryption/decryption operation.
204*/
206 {
207 public:
208 /**
209 * Set the tweak value. This must be called after setting a key. The value
210 * persists until either set_tweak, set_key, or clear is called.
211 * Different algorithms support different tweak length(s). If called with
212 * an unsupported length, Invalid_Argument will be thrown.
213 */
214 virtual void set_tweak(const uint8_t tweak[], size_t len) = 0;
215 };
216
217/**
218* Represents a block cipher with a single fixed block size
219*/
220template<size_t BS, size_t KMIN, size_t KMAX = 0, size_t KMOD = 1, typename BaseClass = BlockCipher>
221class Block_Cipher_Fixed_Params : public BaseClass
222 {
223 public:
224 enum { BLOCK_SIZE = BS };
225 size_t block_size() const final override { return BS; }
226
227 // override to take advantage of compile time constant block size
228 void encrypt_n_xex(uint8_t data[],
229 const uint8_t mask[],
230 size_t blocks) const final override
231 {
232 xor_buf(data, mask, blocks * BS);
233 this->encrypt_n(data, data, blocks);
234 xor_buf(data, mask, blocks * BS);
235 }
236
237 void decrypt_n_xex(uint8_t data[],
238 const uint8_t mask[],
239 size_t blocks) const final override
240 {
241 xor_buf(data, mask, blocks * BS);
242 this->decrypt_n(data, data, blocks);
243 xor_buf(data, mask, blocks * BS);
244 }
245
247 {
248 return Key_Length_Specification(KMIN, KMAX, KMOD);
249 }
250 };
251
252}
253
254#endif
void encrypt(const uint8_t in[], uint8_t out[]) const
Definition: block_cipher.h:82
void decrypt(const uint8_t in[], uint8_t out[]) const
Definition: block_cipher.h:92
virtual BlockCipher * clone() const =0
void decrypt(std::vector< uint8_t, Alloc > &block) const
Definition: block_cipher.h:126
void encrypt(std::vector< uint8_t, Alloc > &block) const
Definition: block_cipher.h:116
virtual ~BlockCipher()=default
virtual void encrypt_n_xex(uint8_t data[], const uint8_t mask[], size_t blocks) const
Definition: block_cipher.h:173
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
Definition: block_cipher.h:183
virtual void encrypt_n(const uint8_t in[], uint8_t out[], size_t blocks) const =0
void encrypt(const std::vector< uint8_t, Alloc > &in, std::vector< uint8_t, Alloc2 > &out) const
Definition: block_cipher.h:137
virtual size_t block_size() const =0
virtual size_t parallelism() const
Definition: block_cipher.h:59
void decrypt(uint8_t block[]) const
Definition: block_cipher.h:109
virtual std::string provider() const
Definition: block_cipher.h:73
size_t parallel_bytes() const
Definition: block_cipher.h:64
void decrypt(const std::vector< uint8_t, Alloc > &in, std::vector< uint8_t, Alloc2 > &out) const
Definition: block_cipher.h:149
void encrypt(uint8_t block[]) const
Definition: block_cipher.h:101
Key_Length_Specification key_spec() const final override
Definition: block_cipher.h:246
void encrypt_n_xex(uint8_t data[], const uint8_t mask[], size_t blocks) const final override
Definition: block_cipher.h:228
size_t block_size() const final override
Definition: block_cipher.h:225
void decrypt_n_xex(uint8_t data[], const uint8_t mask[], size_t blocks) const final override
Definition: block_cipher.h:237
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
Definition: alg_id.cpp:13
void xor_buf(uint8_t out[], const uint8_t in[], size_t length)
Definition: mem_ops.h:262