Botan  2.1.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 */
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 */
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
void set_key(const uint8_t key[], size_t length)
Definition: cipher_mode.h:191
void update(secure_vector< uint8_t > &buffer, size_t offset=0)
Definition: cipher_mode.h:81
Cipher_Mode * get_cipher_mode(const std::string &algo, Cipher_Dir direction)
Definition: cipher_mode.cpp:39
size_t length() const
Definition: symkey.h:25
void start(const std::vector< uint8_t, Alloc > &nonce)
Definition: cipher_mode.h:38
virtual bool authenticated() const
Definition: cipher_mode.h:145
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:27
virtual size_t tag_size() const
Definition: cipher_mode.h:150
virtual std::string provider() const
Definition: cipher_mode.h:202
void start(const uint8_t nonce[], size_t nonce_len)
Definition: cipher_mode.h:48
std::vector< T, secure_allocator< T >> secure_vector
Definition: secmem.h:121
Definition: alg_id.cpp:13
void set_key(const SymmetricKey &key)
Definition: cipher_mode.h:181
void set_key(const std::vector< uint8_t, Alloc > &key)
Definition: cipher_mode.h:172
bool valid_keylength(size_t length) const
Definition: cipher_mode.h:162
const uint8_t * begin() const
Definition: symkey.h:36