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