Go to most recent revision | Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
5496 | leency | 1 | /** |
2 | * \file cipher.h |
||
3 | * |
||
4 | * \brief Generic cipher wrapper. |
||
5 | * |
||
6 | * \author Adriaan de Jong |
||
7 | * |
||
8 | * Copyright (C) 2006-2012, Brainspark B.V. |
||
9 | * |
||
10 | * This file is part of PolarSSL (http://www.polarssl.org) |
||
11 | * Lead Maintainer: Paul Bakker |
||
12 | * |
||
13 | * All rights reserved. |
||
14 | * |
||
15 | * This program is free software; you can redistribute it and/or modify |
||
16 | * it under the terms of the GNU General Public License as published by |
||
17 | * the Free Software Foundation; either version 2 of the License, or |
||
18 | * (at your option) any later version. |
||
19 | * |
||
20 | * This program is distributed in the hope that it will be useful, |
||
21 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
||
22 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
||
23 | * GNU General Public License for more details. |
||
24 | * |
||
25 | * You should have received a copy of the GNU General Public License along |
||
26 | * with this program; if not, write to the Free Software Foundation, Inc., |
||
27 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. |
||
28 | */ |
||
29 | |||
30 | #ifndef POLARSSL_CIPHER_H |
||
31 | #define POLARSSL_CIPHER_H |
||
32 | |||
33 | #include |
||
34 | |||
35 | #if defined(_MSC_VER) && !defined(inline) |
||
36 | #define inline _inline |
||
37 | #else |
||
38 | #if defined(__ARMCC_VERSION) && !defined(inline) |
||
39 | #define inline __inline |
||
40 | #endif /* __ARMCC_VERSION */ |
||
41 | #endif /*_MSC_VER */ |
||
42 | |||
43 | #define POLARSSL_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080 /**< The selected feature is not available. */ |
||
44 | #define POLARSSL_ERR_CIPHER_BAD_INPUT_DATA -0x6100 /**< Bad input parameters to function. */ |
||
45 | #define POLARSSL_ERR_CIPHER_ALLOC_FAILED -0x6180 /**< Failed to allocate memory. */ |
||
46 | #define POLARSSL_ERR_CIPHER_INVALID_PADDING -0x6200 /**< Input data contains invalid padding and is rejected. */ |
||
47 | #define POLARSSL_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280 /**< Decryption of block requires a full block. */ |
||
48 | |||
49 | typedef enum { |
||
50 | POLARSSL_CIPHER_ID_NONE = 0, |
||
51 | POLARSSL_CIPHER_ID_NULL, |
||
52 | POLARSSL_CIPHER_ID_AES, |
||
53 | POLARSSL_CIPHER_ID_DES, |
||
54 | POLARSSL_CIPHER_ID_3DES, |
||
55 | POLARSSL_CIPHER_ID_CAMELLIA, |
||
56 | POLARSSL_CIPHER_ID_BLOWFISH, |
||
57 | } cipher_id_t; |
||
58 | |||
59 | typedef enum { |
||
60 | POLARSSL_CIPHER_NONE = 0, |
||
61 | POLARSSL_CIPHER_NULL, |
||
62 | POLARSSL_CIPHER_AES_128_CBC, |
||
63 | POLARSSL_CIPHER_AES_192_CBC, |
||
64 | POLARSSL_CIPHER_AES_256_CBC, |
||
65 | POLARSSL_CIPHER_AES_128_CFB128, |
||
66 | POLARSSL_CIPHER_AES_192_CFB128, |
||
67 | POLARSSL_CIPHER_AES_256_CFB128, |
||
68 | POLARSSL_CIPHER_AES_128_CTR, |
||
69 | POLARSSL_CIPHER_AES_192_CTR, |
||
70 | POLARSSL_CIPHER_AES_256_CTR, |
||
71 | POLARSSL_CIPHER_CAMELLIA_128_CBC, |
||
72 | POLARSSL_CIPHER_CAMELLIA_192_CBC, |
||
73 | POLARSSL_CIPHER_CAMELLIA_256_CBC, |
||
74 | POLARSSL_CIPHER_CAMELLIA_128_CFB128, |
||
75 | POLARSSL_CIPHER_CAMELLIA_192_CFB128, |
||
76 | POLARSSL_CIPHER_CAMELLIA_256_CFB128, |
||
77 | POLARSSL_CIPHER_CAMELLIA_128_CTR, |
||
78 | POLARSSL_CIPHER_CAMELLIA_192_CTR, |
||
79 | POLARSSL_CIPHER_CAMELLIA_256_CTR, |
||
80 | POLARSSL_CIPHER_DES_CBC, |
||
81 | POLARSSL_CIPHER_DES_EDE_CBC, |
||
82 | POLARSSL_CIPHER_DES_EDE3_CBC, |
||
83 | POLARSSL_CIPHER_BLOWFISH_CBC, |
||
84 | POLARSSL_CIPHER_BLOWFISH_CFB64, |
||
85 | POLARSSL_CIPHER_BLOWFISH_CTR, |
||
86 | } cipher_type_t; |
||
87 | |||
88 | typedef enum { |
||
89 | POLARSSL_MODE_NONE = 0, |
||
90 | POLARSSL_MODE_NULL, |
||
91 | POLARSSL_MODE_CBC, |
||
92 | POLARSSL_MODE_CFB, |
||
93 | POLARSSL_MODE_OFB, |
||
94 | POLARSSL_MODE_CTR, |
||
95 | } cipher_mode_t; |
||
96 | |||
97 | typedef enum { |
||
98 | POLARSSL_OPERATION_NONE = -1, |
||
99 | POLARSSL_DECRYPT = 0, |
||
100 | POLARSSL_ENCRYPT, |
||
101 | } operation_t; |
||
102 | |||
103 | enum { |
||
104 | /** Undefined key length */ |
||
105 | POLARSSL_KEY_LENGTH_NONE = 0, |
||
106 | /** Key length, in bits (including parity), for DES keys */ |
||
107 | POLARSSL_KEY_LENGTH_DES = 64, |
||
108 | /** Key length, in bits (including parity), for DES in two key EDE */ |
||
109 | POLARSSL_KEY_LENGTH_DES_EDE = 128, |
||
110 | /** Key length, in bits (including parity), for DES in three-key EDE */ |
||
111 | POLARSSL_KEY_LENGTH_DES_EDE3 = 192, |
||
112 | /** Maximum length of any IV, in bytes */ |
||
113 | POLARSSL_MAX_IV_LENGTH = 16, |
||
114 | }; |
||
115 | |||
116 | /** |
||
117 | * Base cipher information. The non-mode specific functions and values. |
||
118 | */ |
||
119 | typedef struct { |
||
120 | |||
121 | /** Base Cipher type (e.g. POLARSSL_CIPHER_ID_AES) */ |
||
122 | cipher_id_t cipher; |
||
123 | |||
124 | /** Encrypt using CBC */ |
||
125 | int (*cbc_func)( void *ctx, operation_t mode, size_t length, unsigned char *iv, |
||
126 | const unsigned char *input, unsigned char *output ); |
||
127 | |||
128 | /** Encrypt using CFB (Full length) */ |
||
129 | int (*cfb_func)( void *ctx, operation_t mode, size_t length, size_t *iv_off, |
||
130 | unsigned char *iv, const unsigned char *input, unsigned char *output ); |
||
131 | |||
132 | /** Encrypt using CTR */ |
||
133 | int (*ctr_func)( void *ctx, size_t length, size_t *nc_off, unsigned char *nonce_counter, |
||
134 | unsigned char *stream_block, const unsigned char *input, unsigned char *output ); |
||
135 | |||
136 | /** Set key for encryption purposes */ |
||
137 | int (*setkey_enc_func)( void *ctx, const unsigned char *key, unsigned int key_length); |
||
138 | |||
139 | /** Set key for decryption purposes */ |
||
140 | int (*setkey_dec_func)( void *ctx, const unsigned char *key, unsigned int key_length); |
||
141 | |||
142 | /** Allocate a new context */ |
||
143 | void * (*ctx_alloc_func)( void ); |
||
144 | |||
145 | /** Free the given context */ |
||
146 | void (*ctx_free_func)( void *ctx ); |
||
147 | |||
148 | } cipher_base_t; |
||
149 | |||
150 | /** |
||
151 | * Cipher information. Allows cipher functions to be called in a generic way. |
||
152 | */ |
||
153 | typedef struct { |
||
154 | /** Full cipher identifier (e.g. POLARSSL_CIPHER_AES_256_CBC) */ |
||
155 | cipher_type_t type; |
||
156 | |||
157 | /** Cipher mode (e.g. POLARSSL_MODE_CBC) */ |
||
158 | cipher_mode_t mode; |
||
159 | |||
160 | /** Cipher key length, in bits (default length for variable sized ciphers) |
||
161 | * (Includes parity bits for ciphers like DES) */ |
||
162 | unsigned int key_length; |
||
163 | |||
164 | /** Name of the cipher */ |
||
165 | const char * name; |
||
166 | |||
167 | /** IV size, in bytes */ |
||
168 | unsigned int iv_size; |
||
169 | |||
170 | /** block size, in bytes */ |
||
171 | unsigned int block_size; |
||
172 | |||
173 | /** Base cipher information and functions */ |
||
174 | const cipher_base_t *base; |
||
175 | |||
176 | } cipher_info_t; |
||
177 | |||
178 | /** |
||
179 | * Generic cipher context. |
||
180 | */ |
||
181 | typedef struct { |
||
182 | /** Information about the associated cipher */ |
||
183 | const cipher_info_t *cipher_info; |
||
184 | |||
185 | /** Key length to use */ |
||
186 | int key_length; |
||
187 | |||
188 | /** Operation that the context's key has been initialised for */ |
||
189 | operation_t operation; |
||
190 | |||
191 | /** Buffer for data that hasn't been encrypted yet */ |
||
192 | unsigned char unprocessed_data[POLARSSL_MAX_IV_LENGTH]; |
||
193 | |||
194 | /** Number of bytes that still need processing */ |
||
195 | size_t unprocessed_len; |
||
196 | |||
197 | /** Current IV or NONCE_COUNTER for CTR-mode */ |
||
198 | unsigned char iv[POLARSSL_MAX_IV_LENGTH]; |
||
199 | |||
200 | /** Cipher-specific context */ |
||
201 | void *cipher_ctx; |
||
202 | } cipher_context_t; |
||
203 | |||
204 | #ifdef __cplusplus |
||
205 | extern "C" { |
||
206 | #endif |
||
207 | |||
208 | /** |
||
209 | * \brief Returns the list of ciphers supported by the generic cipher module. |
||
210 | * |
||
211 | * \return a statically allocated array of ciphers, the last entry |
||
212 | * is 0. |
||
213 | */ |
||
214 | const int *cipher_list( void ); |
||
215 | |||
216 | /** |
||
217 | * \brief Returns the cipher information structure associated |
||
218 | * with the given cipher name. |
||
219 | * |
||
220 | * \param cipher_name Name of the cipher to search for. |
||
221 | * |
||
222 | * \return the cipher information structure associated with the |
||
223 | * given cipher_name, or NULL if not found. |
||
224 | */ |
||
225 | const cipher_info_t *cipher_info_from_string( const char *cipher_name ); |
||
226 | |||
227 | /** |
||
228 | * \brief Returns the cipher information structure associated |
||
229 | * with the given cipher type. |
||
230 | * |
||
231 | * \param cipher_type Type of the cipher to search for. |
||
232 | * |
||
233 | * \return the cipher information structure associated with the |
||
234 | * given cipher_type, or NULL if not found. |
||
235 | */ |
||
236 | const cipher_info_t *cipher_info_from_type( const cipher_type_t cipher_type ); |
||
237 | |||
238 | /** |
||
239 | * \brief Initialises and fills the cipher context structure with |
||
240 | * the appropriate values. |
||
241 | * |
||
242 | * \param ctx context to initialise. May not be NULL. |
||
243 | * \param cipher_info cipher to use. |
||
244 | * |
||
245 | * \return \c 0 on success, |
||
246 | * \c POLARSSL_ERR_CIPHER_BAD_INPUT_DATA on parameter failure, |
||
247 | * \c POLARSSL_ERR_CIPHER_ALLOC_FAILED if allocation of the |
||
248 | * cipher-specific context failed. |
||
249 | */ |
||
250 | int cipher_init_ctx( cipher_context_t *ctx, const cipher_info_t *cipher_info ); |
||
251 | |||
252 | /** |
||
253 | * \brief Free the cipher-specific context of ctx. Freeing ctx |
||
254 | * itself remains the responsibility of the caller. |
||
255 | * |
||
256 | * \param ctx Free the cipher-specific context |
||
257 | * |
||
258 | * \returns 0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if |
||
259 | * parameter verification fails. |
||
260 | */ |
||
261 | int cipher_free_ctx( cipher_context_t *ctx ); |
||
262 | |||
263 | /** |
||
264 | * \brief Returns the block size of the given cipher. |
||
265 | * |
||
266 | * \param ctx cipher's context. Must have been initialised. |
||
267 | * |
||
268 | * \return size of the cipher's blocks, or 0 if ctx has not been |
||
269 | * initialised. |
||
270 | */ |
||
271 | static inline unsigned int cipher_get_block_size( const cipher_context_t *ctx ) |
||
272 | { |
||
273 | if( NULL == ctx || NULL == ctx->cipher_info ) |
||
274 | return 0; |
||
275 | |||
276 | return ctx->cipher_info->block_size; |
||
277 | } |
||
278 | |||
279 | /** |
||
280 | * \brief Returns the mode of operation for the cipher. |
||
281 | * (e.g. POLARSSL_MODE_CBC) |
||
282 | * |
||
283 | * \param ctx cipher's context. Must have been initialised. |
||
284 | * |
||
285 | * \return mode of operation, or POLARSSL_MODE_NONE if ctx |
||
286 | * has not been initialised. |
||
287 | */ |
||
288 | static inline cipher_mode_t cipher_get_cipher_mode( const cipher_context_t *ctx ) |
||
289 | { |
||
290 | if( NULL == ctx || NULL == ctx->cipher_info ) |
||
291 | return POLARSSL_MODE_NONE; |
||
292 | |||
293 | return ctx->cipher_info->mode; |
||
294 | } |
||
295 | |||
296 | /** |
||
297 | * \brief Returns the size of the cipher's IV. |
||
298 | * |
||
299 | * \param ctx cipher's context. Must have been initialised. |
||
300 | * |
||
301 | * \return size of the cipher's IV, or 0 if ctx has not been |
||
302 | * initialised. |
||
303 | */ |
||
304 | static inline int cipher_get_iv_size( const cipher_context_t *ctx ) |
||
305 | { |
||
306 | if( NULL == ctx || NULL == ctx->cipher_info ) |
||
307 | return 0; |
||
308 | |||
309 | return ctx->cipher_info->iv_size; |
||
310 | } |
||
311 | |||
312 | /** |
||
313 | * \brief Returns the type of the given cipher. |
||
314 | * |
||
315 | * \param ctx cipher's context. Must have been initialised. |
||
316 | * |
||
317 | * \return type of the cipher, or POLARSSL_CIPHER_NONE if ctx has |
||
318 | * not been initialised. |
||
319 | */ |
||
320 | static inline cipher_type_t cipher_get_type( const cipher_context_t *ctx ) |
||
321 | { |
||
322 | if( NULL == ctx || NULL == ctx->cipher_info ) |
||
323 | return POLARSSL_CIPHER_NONE; |
||
324 | |||
325 | return ctx->cipher_info->type; |
||
326 | } |
||
327 | |||
328 | /** |
||
329 | * \brief Returns the name of the given cipher, as a string. |
||
330 | * |
||
331 | * \param ctx cipher's context. Must have been initialised. |
||
332 | * |
||
333 | * \return name of the cipher, or NULL if ctx was not initialised. |
||
334 | */ |
||
335 | static inline const char *cipher_get_name( const cipher_context_t *ctx ) |
||
336 | { |
||
337 | if( NULL == ctx || NULL == ctx->cipher_info ) |
||
338 | return 0; |
||
339 | |||
340 | return ctx->cipher_info->name; |
||
341 | } |
||
342 | |||
343 | /** |
||
344 | * \brief Returns the key length of the cipher. |
||
345 | * |
||
346 | * \param ctx cipher's context. Must have been initialised. |
||
347 | * |
||
348 | * \return cipher's key length, in bits, or |
||
349 | * POLARSSL_KEY_LENGTH_NONE if ctx has not been |
||
350 | * initialised. |
||
351 | */ |
||
352 | static inline int cipher_get_key_size ( const cipher_context_t *ctx ) |
||
353 | { |
||
354 | if( NULL == ctx ) |
||
355 | return POLARSSL_KEY_LENGTH_NONE; |
||
356 | |||
357 | return ctx->key_length; |
||
358 | } |
||
359 | |||
360 | /** |
||
361 | * \brief Returns the operation of the given cipher. |
||
362 | * |
||
363 | * \param ctx cipher's context. Must have been initialised. |
||
364 | * |
||
365 | * \return operation (POLARSSL_ENCRYPT or POLARSSL_DECRYPT), |
||
366 | * or POLARSSL_OPERATION_NONE if ctx has not been |
||
367 | * initialised. |
||
368 | */ |
||
369 | static inline operation_t cipher_get_operation( const cipher_context_t *ctx ) |
||
370 | { |
||
371 | if( NULL == ctx || NULL == ctx->cipher_info ) |
||
372 | return POLARSSL_OPERATION_NONE; |
||
373 | |||
374 | return ctx->operation; |
||
375 | } |
||
376 | |||
377 | /** |
||
378 | * \brief Set the key to use with the given context. |
||
379 | * |
||
380 | * \param ctx generic cipher context. May not be NULL. Must have been |
||
381 | * initialised using cipher_context_from_type or |
||
382 | * cipher_context_from_string. |
||
383 | * \param key The key to use. |
||
384 | * \param key_length key length to use, in bits. |
||
385 | * \param operation Operation that the key will be used for, either |
||
386 | * POLARSSL_ENCRYPT or POLARSSL_DECRYPT. |
||
387 | * |
||
388 | * \returns 0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if |
||
389 | * parameter verification fails or a cipher specific |
||
390 | * error code. |
||
391 | */ |
||
392 | int cipher_setkey( cipher_context_t *ctx, const unsigned char *key, int key_length, |
||
393 | const operation_t operation ); |
||
394 | |||
395 | /** |
||
396 | * \brief Reset the given context, setting the IV to iv |
||
397 | * |
||
398 | * \param ctx generic cipher context |
||
399 | * \param iv IV to use or NONCE_COUNTER in the case of a CTR-mode cipher |
||
400 | * |
||
401 | * \returns 0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA |
||
402 | * if parameter verification fails. |
||
403 | */ |
||
404 | int cipher_reset( cipher_context_t *ctx, const unsigned char *iv ); |
||
405 | |||
406 | /** |
||
407 | * \brief Generic cipher update function. Encrypts/decrypts |
||
408 | * using the given cipher context. Writes as many block |
||
409 | * size'd blocks of data as possible to output. Any data |
||
410 | * that cannot be written immediately will either be added |
||
411 | * to the next block, or flushed when cipher_final is |
||
412 | * called. |
||
413 | * |
||
414 | * \param ctx generic cipher context |
||
415 | * \param input buffer holding the input data |
||
416 | * \param ilen length of the input data |
||
417 | * \param output buffer for the output data. Should be able to hold at |
||
418 | * least ilen + block_size. Cannot be the same buffer as |
||
419 | * input! |
||
420 | * \param olen length of the output data, will be filled with the |
||
421 | * actual number of bytes written. |
||
422 | * |
||
423 | * \returns 0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if |
||
424 | * parameter verification fails, |
||
425 | * POLARSSL_ERR_CIPHER_FEATURE_UNAVAILABLE on an |
||
426 | * unsupported mode for a cipher or a cipher specific |
||
427 | * error code. |
||
428 | */ |
||
429 | int cipher_update( cipher_context_t *ctx, const unsigned char *input, size_t ilen, |
||
430 | unsigned char *output, size_t *olen ); |
||
431 | |||
432 | /** |
||
433 | * \brief Generic cipher finalisation function. If data still |
||
434 | * needs to be flushed from an incomplete block, data |
||
435 | * contained within it will be padded with the size of |
||
436 | * the last block, and written to the output buffer. |
||
437 | * |
||
438 | * \param ctx Generic cipher context |
||
439 | * \param output buffer to write data to. Needs block_size data available. |
||
440 | * \param olen length of the data written to the output buffer. |
||
441 | * |
||
442 | * \returns 0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if |
||
443 | * parameter verification fails, |
||
444 | * POLARSSL_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption |
||
445 | * expected a full block but was not provided one, |
||
446 | * POLARSSL_ERR_CIPHER_INVALID_PADDING on invalid padding |
||
447 | * while decrypting or a cipher specific error code. |
||
448 | */ |
||
449 | int cipher_finish( cipher_context_t *ctx, unsigned char *output, size_t *olen); |
||
450 | |||
451 | |||
452 | /** |
||
453 | * \brief Checkup routine |
||
454 | * |
||
455 | * \return 0 if successful, or 1 if the test failed |
||
456 | */ |
||
457 | int cipher_self_test( int verbose ); |
||
458 | |||
459 | #ifdef __cplusplus |
||
460 | } |
||
461 | #endif |
||
462 | |||
463 | #endif /* POLARSSL_MD_H */>>>>> |