Botan  2.11.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/sym_algo.h>
13 #include <botan/exceptn.h>
14 #include <string>
15 #include <vector>
16 
17 namespace Botan {
18 
19 /**
20 * The two possible directions for cipher filters, determining whether they
21 * actually perform encryption or decryption.
22 */
24 
25 /**
26 * Interface for cipher modes
27 */
28 class BOTAN_PUBLIC_API(2,0) Cipher_Mode : public SymmetricAlgorithm
29  {
30  public:
31  /**
32  * @return list of available providers for this algorithm, empty if not available
33  * @param algo_spec algorithm name
34  */
35  static std::vector<std::string> providers(const std::string& algo_spec);
36 
37  /**
38  * Create an AEAD mode
39  * @param algo the algorithm to create
40  * @param direction specify if this should be an encryption or decryption AEAD
41  * @param provider optional specification for provider to use
42  * @return an AEAD mode or a null pointer if not available
43  */
44  static std::unique_ptr<Cipher_Mode> create(const std::string& algo,
45  Cipher_Dir direction,
46  const std::string& provider = "");
47 
48  /**
49  * Create an AEAD mode, or throw
50  * @param algo the algorithm to create
51  * @param direction specify if this should be an encryption or decryption AEAD
52  * @param provider optional specification for provider to use
53  * @return an AEAD mode, or throw an exception
54  */
55  static std::unique_ptr<Cipher_Mode> create_or_throw(const std::string& algo,
56  Cipher_Dir direction,
57  const std::string& provider = "");
58 
59  /*
60  * Prepare for processing a message under the specified nonce
61  */
62  virtual void start_msg(const uint8_t nonce[], size_t nonce_len) = 0;
63 
64  /**
65  * Begin processing a message.
66  * @param nonce the per message nonce
67  */
68  template<typename Alloc>
69  void start(const std::vector<uint8_t, Alloc>& nonce)
70  {
71  start_msg(nonce.data(), nonce.size());
72  }
73 
74  /**
75  * Begin processing a message.
76  * @param nonce the per message nonce
77  * @param nonce_len length of nonce
78  */
79  void start(const uint8_t nonce[], size_t nonce_len)
80  {
81  start_msg(nonce, nonce_len);
82  }
83 
84  /**
85  * Begin processing a message.
86  */
87  void start()
88  {
89  return start_msg(nullptr, 0);
90  }
91 
92  /**
93  * Process message blocks
94  *
95  * Input must be a multiple of update_granularity
96  *
97  * Processes msg in place and returns bytes written. Normally
98  * this will be either msg_len (indicating the entire message was
99  * processed) or for certain AEAD modes zero (indicating that the
100  * mode requires the entire message be processed in one pass).
101  *
102  * @param msg the message to be processed
103  * @param msg_len length of the message in bytes
104  */
105  virtual size_t process(uint8_t msg[], size_t msg_len) = 0;
106 
107  /**
108  * Process some data. Input must be in size update_granularity() uint8_t blocks.
109  * @param buffer in/out parameter which will possibly be resized
110  * @param offset an offset into blocks to begin processing
111  */
112  void update(secure_vector<uint8_t>& buffer, size_t offset = 0)
113  {
114  BOTAN_ASSERT(buffer.size() >= offset, "Offset ok");
115  uint8_t* buf = buffer.data() + offset;
116  const size_t buf_size = buffer.size() - offset;
117 
118  const size_t written = process(buf, buf_size);
119  buffer.resize(offset + written);
120  }
121 
122  /**
123  * Complete processing of a message.
124  *
125  * @param final_block in/out parameter which must be at least
126  * minimum_final_size() bytes, and will be set to any final output
127  * @param offset an offset into final_block to begin processing
128  */
129  virtual void finish(secure_vector<uint8_t>& final_block, size_t offset = 0) = 0;
130 
131  /**
132  * Returns the size of the output if this transform is used to process a
133  * message with input_length bytes. In most cases the answer is precise.
134  * If it is not possible to precise (namely for CBC decryption) instead a
135  * lower bound is returned.
136  */
137  virtual size_t output_length(size_t input_length) const = 0;
138 
139  /**
140  * @return size of required blocks to update
141  */
142  virtual size_t update_granularity() const = 0;
143 
144  /**
145  * @return required minimium size to finalize() - may be any
146  * length larger than this.
147  */
148  virtual size_t minimum_final_size() const = 0;
149 
150  /**
151  * @return the default size for a nonce
152  */
153  virtual size_t default_nonce_length() const = 0;
154 
155  /**
156  * @return true iff nonce_len is a valid length for the nonce
157  */
158  virtual bool valid_nonce_length(size_t nonce_len) const = 0;
159 
160  /**
161  * Resets just the message specific state and allows encrypting again under the existing key
162  */
163  virtual void reset() = 0;
164 
165  /**
166  * @return true iff this mode provides authentication as well as
167  * confidentiality.
168  */
169  virtual bool authenticated() const { return false; }
170 
171  /**
172  * @return the size of the authentication tag used (in bytes)
173  */
174  virtual size_t tag_size() const { return 0; }
175 
176  /**
177  * @return provider information about this implementation. Default is "base",
178  * might also return "sse2", "avx2", "openssl", or some other arbitrary string.
179  */
180  virtual std::string provider() const { return "base"; }
181  };
182 
183 /**
184 * Get a cipher mode by name (eg "AES-128/CBC" or "Serpent/XTS")
185 * @param algo_spec cipher name
186 * @param direction ENCRYPTION or DECRYPTION
187 * @param provider provider implementation to choose
188 */
189 inline Cipher_Mode* get_cipher_mode(const std::string& algo_spec,
190  Cipher_Dir direction,
191  const std::string& provider = "")
192  {
193  return Cipher_Mode::create(algo_spec, direction, provider).release();
194  }
195 
196 }
197 
198 #endif
size_t * tag_size
Definition: ffi.h:450
bool BigInt BigInt size_t size_t const std::vector< uint8_t > size_t offset
Definition: numthry.h:271
size_t const uint8_t size_t input_length
Definition: base32.h:30
const uint8_t size_t nonce_len
Definition: ffi.h:504
const uint8_t * buf
Definition: ffi.h:371
size_t * output_length
Definition: ffi.h:280
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:55
Definition: alg_id.cpp:13
class BOTAN_PUBLIC_API(2, 0) Cipher_Mode Cipher_Mode * get_cipher_mode(const std::string &algo_spec, Cipher_Dir direction, const std::string &provider="")
Definition: cipher_mode.h:189
class BOTAN_PUBLIC_API(2, 0) AlgorithmIdentifier final bool BOTAN_PUBLIC_API(2, 0) operator
Name Constraints.
Definition: asn1_obj.h:66
int(* update)(CTX *, const void *, CC_LONG len)
Cipher_Dir
Definition: cipher_mode.h:23
const uint8_t * nonce
Definition: ffi.h:504