Botan 2.1.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

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