1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
|
/*
* Cipher Modes
* (C) 2013,2016 Jack Lloyd
*
* Botan is released under the Simplified BSD License (see license.txt)
*/
#ifndef BOTAN_CIPHER_MODE_H_
#define BOTAN_CIPHER_MODE_H_
#include <botan/secmem.h>
#include <botan/key_spec.h>
#include <botan/exceptn.h>
#include <botan/symkey.h>
#include <string>
#include <vector>
namespace Botan {
/**
* The two possible directions for cipher filters, determining whether they
* actually perform encryption or decryption.
*/
enum Cipher_Dir : int { ENCRYPTION, DECRYPTION };
/**
* Interface for cipher modes
*/
class BOTAN_PUBLIC_API(2,0) Cipher_Mode
{
public:
virtual ~Cipher_Mode() = default;
/**
* @return list of available providers for this algorithm, empty if not available
* @param algo_spec algorithm name
*/
static std::vector<std::string> providers(const std::string& algo_spec);
/**
* Create an AEAD mode
* @param algo the algorithm to create
* @param direction specify if this should be an encryption or decryption AEAD
* @param provider optional specification for provider to use
* @return an AEAD mode or a null pointer if not available
*/
static std::unique_ptr<Cipher_Mode> create(const std::string& algo,
Cipher_Dir direction,
const std::string& provider = "");
/**
* Create an AEAD mode, or throw
* @param algo the algorithm to create
* @param direction specify if this should be an encryption or decryption AEAD
* @param provider optional specification for provider to use
* @return an AEAD mode, or throw an exception
*/
static std::unique_ptr<Cipher_Mode> create_or_throw(const std::string& algo,
Cipher_Dir direction,
const std::string& provider = "");
/*
* Prepare for processing a message under the specified nonce
*/
virtual void start_msg(const uint8_t nonce[], size_t nonce_len) = 0;
/**
* Begin processing a message.
* @param nonce the per message nonce
*/
template<typename Alloc>
void start(const std::vector<uint8_t, Alloc>& nonce)
{
start_msg(nonce.data(), nonce.size());
}
/**
* Begin processing a message.
* @param nonce the per message nonce
* @param nonce_len length of nonce
*/
void start(const uint8_t nonce[], size_t nonce_len)
{
start_msg(nonce, nonce_len);
}
/**
* Begin processing a message.
*/
void start()
{
return start_msg(nullptr, 0);
}
/**
* Process message blocks
*
* Input must be a multiple of update_granularity
*
* Processes msg in place and returns bytes written. Normally
* this will be either msg_len (indicating the entire message was
* processed) or for certain AEAD modes zero (indicating that the
* mode requires the entire message be processed in one pass).
*
* @param msg the message to be processed
* @param msg_len length of the message in bytes
*/
virtual size_t process(uint8_t msg[], size_t msg_len) = 0;
/**
* Process some data. Input must be in size update_granularity() uint8_t blocks.
* @param buffer in/out parameter which will possibly be resized
* @param offset an offset into blocks to begin processing
*/
void update(secure_vector<uint8_t>& buffer, size_t offset = 0)
{
BOTAN_ASSERT(buffer.size() >= offset, "Offset ok");
uint8_t* buf = buffer.data() + offset;
const size_t buf_size = buffer.size() - offset;
const size_t written = process(buf, buf_size);
buffer.resize(offset + written);
}
/**
* Complete processing of a message.
*
* @param final_block in/out parameter which must be at least
* minimum_final_size() bytes, and will be set to any final output
* @param offset an offset into final_block to begin processing
*/
virtual void finish(secure_vector<uint8_t>& final_block, size_t offset = 0) = 0;
/**
* Returns the size of the output if this transform is used to process a
* message with input_length bytes. Will throw if unable to give a precise
* answer.
*/
virtual size_t output_length(size_t input_length) const = 0;
/**
* @return size of required blocks to update
*/
virtual size_t update_granularity() const = 0;
/**
* @return required minimium size to finalize() - may be any
* length larger than this.
*/
virtual size_t minimum_final_size() const = 0;
/**
* @return the default size for a nonce
*/
virtual size_t default_nonce_length() const = 0;
/**
* @return true iff nonce_len is a valid length for the nonce
*/
virtual bool valid_nonce_length(size_t nonce_len) const = 0;
virtual std::string name() const = 0;
/**
* Zeroise all state
* See also reset_msg()
*/
virtual void clear() = 0;
/**
* Resets just the message specific state and allows encrypting again under the existing key
*/
virtual void reset() = 0;
/**
* @return true iff this mode provides authentication as well as
* confidentiality.
*/
virtual bool authenticated() const { return false; }
/**
* @return the size of the authentication tag used (in bytes)
*/
virtual size_t tag_size() const { return 0; }
/**
* @return object describing limits on key size
*/
virtual Key_Length_Specification key_spec() const = 0;
/**
* Check whether a given key length is valid for this algorithm.
* @param length the key length to be checked.
* @return true if the key length is valid.
*/
bool valid_keylength(size_t length) const
{
return key_spec().valid_keylength(length);
}
/**
* Set the symmetric key of this transform
* @param key contains the key material
*/
template<typename Alloc>
void set_key(const std::vector<uint8_t, Alloc>& key)
{
set_key(key.data(), key.size());
}
/**
* Set the symmetric key of this transform
* @param key contains the key material
*/
void set_key(const SymmetricKey& key)
{
set_key(key.begin(), key.length());
}
/**
* Set the symmetric key of this transform
* @param key contains the key material
* @param length in bytes of key param
*/
void set_key(const uint8_t key[], size_t length)
{
if(!valid_keylength(length))
throw Invalid_Key_Length(name(), length);
key_schedule(key, length);
}
/**
* @return provider information about this implementation. Default is "base",
* might also return "sse2", "avx2", "openssl", or some other arbitrary string.
*/
virtual std::string provider() const { return "base"; }
private:
virtual void key_schedule(const uint8_t key[], size_t length) = 0;
};
/**
* Get a cipher mode by name (eg "AES-128/CBC" or "Serpent/XTS")
* @param algo_spec cipher name
* @param direction ENCRYPTION or DECRYPTION
* @param provider provider implementation to choose
*/
inline Cipher_Mode* get_cipher_mode(const std::string& algo_spec,
Cipher_Dir direction,
const std::string& provider = "")
{
return Cipher_Mode::create(algo_spec, direction, provider).release();
}
}
#endif
|
