← Back to branch summary

~ubuntu-branches/debian/sid/botan/sid

« back to all changes in this revision

Viewing changes to src/lib/modes/cipher_mode.h

  • Committer: Package Import Robot
  • Author(s): Laszlo Boszormenyi (GCS)
  • Date: 2018-03-01 22:23:25 UTC
  • mfrom: (1.2.2)
  • Revision ID: package-import@ubuntu.com-20180301222325-7p7vc45gu3hta34d
Tags: 2.4.0-2
* Don't remove .doctrees from the manual if it doesn't exist.
* Don't specify parallel to debhelper.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/lib/modes/cipher_mode.h
 
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_PUBLIC_API(2,0) Cipher_Mode
 
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
*/
 
218
enum Cipher_Dir : int { ENCRYPTION, DECRYPTION };
 
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