blob: 93a0015d70e2e8b3d2388af907c906bffa9ca84c [file] [log] [blame]
Paul Bakker8123e9d2011-01-06 15:37:30 +00001/**
2 * \file cipher.h
3 *
4 * \brief Generic cipher wrapper.
5 *
6 * \author Adriaan de Jong <dejong@fox-it.com>
7 *
Paul Bakker68884e32013-01-07 18:20:04 +01008 * Copyright (C) 2006-2013, Brainspark B.V.
Paul Bakker8123e9d2011-01-06 15:37:30 +00009 *
10 * This file is part of PolarSSL (http://www.polarssl.org)
11 * Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
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 <string.h>
34
Paul Bakker09b1ec62011-07-27 16:28:54 +000035#if defined(_MSC_VER) && !defined(inline)
Paul Bakkeraf5c85f2011-04-18 03:47:52 +000036#define inline _inline
Paul Bakker569df2c2011-06-21 07:48:07 +000037#else
Paul Bakker09b1ec62011-07-27 16:28:54 +000038#if defined(__ARMCC_VERSION) && !defined(inline)
Paul Bakker569df2c2011-06-21 07:48:07 +000039#define inline __inline
Paul Bakker74fb74e2011-06-21 13:36:18 +000040#endif /* __ARMCC_VERSION */
Paul Bakker569df2c2011-06-21 07:48:07 +000041#endif /*_MSC_VER */
Paul Bakkeraf5c85f2011-04-18 03:47:52 +000042
Paul Bakker343a8702011-06-09 14:27:58 +000043#define POLARSSL_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080 /**< The selected feature is not available. */
Paul Bakkerff61a782011-06-09 15:42:02 +000044#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. */
Paul Bakker343a8702011-06-09 14:27:58 +000048
Paul Bakker407a0da2013-06-27 14:29:21 +020049#ifdef __cplusplus
50extern "C" {
51#endif
52
Paul Bakker8123e9d2011-01-06 15:37:30 +000053typedef enum {
54 POLARSSL_CIPHER_ID_NONE = 0,
Paul Bakkerfab5c822012-02-06 16:45:10 +000055 POLARSSL_CIPHER_ID_NULL,
Paul Bakker8123e9d2011-01-06 15:37:30 +000056 POLARSSL_CIPHER_ID_AES,
57 POLARSSL_CIPHER_ID_DES,
58 POLARSSL_CIPHER_ID_3DES,
59 POLARSSL_CIPHER_ID_CAMELLIA,
Paul Bakker6132d0a2012-07-04 17:10:40 +000060 POLARSSL_CIPHER_ID_BLOWFISH,
Paul Bakker68884e32013-01-07 18:20:04 +010061 POLARSSL_CIPHER_ID_ARC4,
Paul Bakker8123e9d2011-01-06 15:37:30 +000062} cipher_id_t;
63
64typedef enum {
65 POLARSSL_CIPHER_NONE = 0,
Paul Bakkerfab5c822012-02-06 16:45:10 +000066 POLARSSL_CIPHER_NULL,
Paul Bakker8123e9d2011-01-06 15:37:30 +000067 POLARSSL_CIPHER_AES_128_CBC,
68 POLARSSL_CIPHER_AES_192_CBC,
69 POLARSSL_CIPHER_AES_256_CBC,
Paul Bakker343a8702011-06-09 14:27:58 +000070 POLARSSL_CIPHER_AES_128_CFB128,
71 POLARSSL_CIPHER_AES_192_CFB128,
72 POLARSSL_CIPHER_AES_256_CFB128,
73 POLARSSL_CIPHER_AES_128_CTR,
74 POLARSSL_CIPHER_AES_192_CTR,
75 POLARSSL_CIPHER_AES_256_CTR,
Paul Bakker68884e32013-01-07 18:20:04 +010076 POLARSSL_CIPHER_AES_128_GCM,
77 POLARSSL_CIPHER_AES_256_GCM,
Paul Bakker343a8702011-06-09 14:27:58 +000078 POLARSSL_CIPHER_CAMELLIA_128_CBC,
79 POLARSSL_CIPHER_CAMELLIA_192_CBC,
80 POLARSSL_CIPHER_CAMELLIA_256_CBC,
81 POLARSSL_CIPHER_CAMELLIA_128_CFB128,
82 POLARSSL_CIPHER_CAMELLIA_192_CFB128,
83 POLARSSL_CIPHER_CAMELLIA_256_CFB128,
84 POLARSSL_CIPHER_CAMELLIA_128_CTR,
85 POLARSSL_CIPHER_CAMELLIA_192_CTR,
86 POLARSSL_CIPHER_CAMELLIA_256_CTR,
Paul Bakker8123e9d2011-01-06 15:37:30 +000087 POLARSSL_CIPHER_DES_CBC,
88 POLARSSL_CIPHER_DES_EDE_CBC,
Paul Bakker6132d0a2012-07-04 17:10:40 +000089 POLARSSL_CIPHER_DES_EDE3_CBC,
90 POLARSSL_CIPHER_BLOWFISH_CBC,
91 POLARSSL_CIPHER_BLOWFISH_CFB64,
92 POLARSSL_CIPHER_BLOWFISH_CTR,
Paul Bakker68884e32013-01-07 18:20:04 +010093 POLARSSL_CIPHER_ARC4_128,
Paul Bakker8123e9d2011-01-06 15:37:30 +000094} cipher_type_t;
95
96typedef enum {
97 POLARSSL_MODE_NONE = 0,
98 POLARSSL_MODE_CBC,
Paul Bakker6132d0a2012-07-04 17:10:40 +000099 POLARSSL_MODE_CFB,
Paul Bakker8123e9d2011-01-06 15:37:30 +0000100 POLARSSL_MODE_OFB,
Paul Bakker343a8702011-06-09 14:27:58 +0000101 POLARSSL_MODE_CTR,
Paul Bakker68884e32013-01-07 18:20:04 +0100102 POLARSSL_MODE_GCM,
103 POLARSSL_MODE_STREAM,
Paul Bakker8123e9d2011-01-06 15:37:30 +0000104} cipher_mode_t;
105
106typedef enum {
Manuel Pégourié-Gonnard0e7d2c02013-07-26 16:05:14 +0200107 POLARSSL_PADDING_PKCS7 = 0, /**< PKCS7 padding (default) */
108 POLARSSL_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding */
109 POLARSSL_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding */
110 POLARSSL_PADDING_ZEROS, /**< zero padding (not reversible!) */
Manuel Pégourié-Gonnardebdc4132013-07-26 16:50:44 +0200111 POLARSSL_PADDING_NONE, /**< never pad (full blocks only) */
Manuel Pégourié-Gonnardd5fdcaf2013-07-24 18:05:00 +0200112} cipher_padding_t;
113
114typedef enum {
Paul Bakkerf7e5bb52011-11-11 10:53:37 +0000115 POLARSSL_OPERATION_NONE = -1,
Paul Bakker8123e9d2011-01-06 15:37:30 +0000116 POLARSSL_DECRYPT = 0,
117 POLARSSL_ENCRYPT,
118} operation_t;
119
120enum {
121 /** Undefined key length */
122 POLARSSL_KEY_LENGTH_NONE = 0,
Paul Bakker5e18aed2011-11-15 15:38:45 +0000123 /** Key length, in bits (including parity), for DES keys */
124 POLARSSL_KEY_LENGTH_DES = 64,
125 /** Key length, in bits (including parity), for DES in two key EDE */
126 POLARSSL_KEY_LENGTH_DES_EDE = 128,
127 /** Key length, in bits (including parity), for DES in three-key EDE */
128 POLARSSL_KEY_LENGTH_DES_EDE3 = 192,
Paul Bakker8123e9d2011-01-06 15:37:30 +0000129 /** Maximum length of any IV, in bytes */
130 POLARSSL_MAX_IV_LENGTH = 16,
131};
132
133/**
Paul Bakker343a8702011-06-09 14:27:58 +0000134 * Base cipher information. The non-mode specific functions and values.
135 */
136typedef struct {
137
138 /** Base Cipher type (e.g. POLARSSL_CIPHER_ID_AES) */
139 cipher_id_t cipher;
140
141 /** Encrypt using CBC */
142 int (*cbc_func)( void *ctx, operation_t mode, size_t length, unsigned char *iv,
143 const unsigned char *input, unsigned char *output );
144
Paul Bakker6132d0a2012-07-04 17:10:40 +0000145 /** Encrypt using CFB (Full length) */
146 int (*cfb_func)( void *ctx, operation_t mode, size_t length, size_t *iv_off,
Paul Bakker343a8702011-06-09 14:27:58 +0000147 unsigned char *iv, const unsigned char *input, unsigned char *output );
148
149 /** Encrypt using CTR */
150 int (*ctr_func)( void *ctx, size_t length, size_t *nc_off, unsigned char *nonce_counter,
151 unsigned char *stream_block, const unsigned char *input, unsigned char *output );
152
Manuel Pégourié-Gonnard37e230c2013-08-28 13:50:42 +0200153 /** Encrypt using STREAM */
154 int (*stream_func)( void *ctx, size_t length,
155 const unsigned char *input, unsigned char *output );
156
Paul Bakker343a8702011-06-09 14:27:58 +0000157 /** Set key for encryption purposes */
158 int (*setkey_enc_func)( void *ctx, const unsigned char *key, unsigned int key_length);
159
160 /** Set key for decryption purposes */
161 int (*setkey_dec_func)( void *ctx, const unsigned char *key, unsigned int key_length);
162
163 /** Allocate a new context */
164 void * (*ctx_alloc_func)( void );
165
166 /** Free the given context */
167 void (*ctx_free_func)( void *ctx );
168
169} cipher_base_t;
170
171/**
Paul Bakker8123e9d2011-01-06 15:37:30 +0000172 * Cipher information. Allows cipher functions to be called in a generic way.
173 */
174typedef struct {
175 /** Full cipher identifier (e.g. POLARSSL_CIPHER_AES_256_CBC) */
176 cipher_type_t type;
177
Paul Bakkerf7e5bb52011-11-11 10:53:37 +0000178 /** Cipher mode (e.g. POLARSSL_MODE_CBC) */
Paul Bakker8123e9d2011-01-06 15:37:30 +0000179 cipher_mode_t mode;
180
Paul Bakker5e18aed2011-11-15 15:38:45 +0000181 /** Cipher key length, in bits (default length for variable sized ciphers)
182 * (Includes parity bits for ciphers like DES) */
Paul Bakker23986e52011-04-24 08:57:21 +0000183 unsigned int key_length;
Paul Bakker8123e9d2011-01-06 15:37:30 +0000184
Paul Bakkerb6ecaf52011-04-19 14:29:23 +0000185 /** Name of the cipher */
Paul Bakker8123e9d2011-01-06 15:37:30 +0000186 const char * name;
187
Manuel Pégourié-Gonnarda235b5b2013-09-03 13:25:52 +0200188 /** IV/NONCE size, in bytes.
189 * For cipher that accept many sizes: recommended size */
Paul Bakker23986e52011-04-24 08:57:21 +0000190 unsigned int iv_size;
Paul Bakker8123e9d2011-01-06 15:37:30 +0000191
Manuel Pégourié-Gonnarda235b5b2013-09-03 13:25:52 +0200192 /** Flag for ciphers that accept many sizes of IV/NONCE */
193 int accepts_variable_iv_size;
194
Paul Bakker8123e9d2011-01-06 15:37:30 +0000195 /** block size, in bytes */
Paul Bakker23986e52011-04-24 08:57:21 +0000196 unsigned int block_size;
Paul Bakker8123e9d2011-01-06 15:37:30 +0000197
Paul Bakker343a8702011-06-09 14:27:58 +0000198 /** Base cipher information and functions */
199 const cipher_base_t *base;
Paul Bakker8123e9d2011-01-06 15:37:30 +0000200
201} cipher_info_t;
202
203/**
Paul Bakker20281562011-11-11 10:34:04 +0000204 * Generic cipher context.
Paul Bakker8123e9d2011-01-06 15:37:30 +0000205 */
206typedef struct {
207 /** Information about the associated cipher */
208 const cipher_info_t *cipher_info;
209
210 /** Key length to use */
211 int key_length;
212
213 /** Operation that the context's key has been initialised for */
214 operation_t operation;
215
Manuel Pégourié-Gonnardac56a1a2013-07-25 12:31:10 +0200216 /** Padding functions to use, if relevant for cipher mode */
217 void (*add_padding)( unsigned char *output, size_t olen, size_t data_len );
218 int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len );
219
Paul Bakker8123e9d2011-01-06 15:37:30 +0000220 /** Buffer for data that hasn't been encrypted yet */
221 unsigned char unprocessed_data[POLARSSL_MAX_IV_LENGTH];
222
223 /** Number of bytes that still need processing */
Paul Bakker23986e52011-04-24 08:57:21 +0000224 size_t unprocessed_len;
Paul Bakker8123e9d2011-01-06 15:37:30 +0000225
Paul Bakker343a8702011-06-09 14:27:58 +0000226 /** Current IV or NONCE_COUNTER for CTR-mode */
Paul Bakker8123e9d2011-01-06 15:37:30 +0000227 unsigned char iv[POLARSSL_MAX_IV_LENGTH];
228
Manuel Pégourié-Gonnard9c853b92013-09-03 13:04:44 +0200229 /** IV size in bytes (for ciphers with variable-length IVs) */
230 size_t iv_size;
231
Paul Bakker8123e9d2011-01-06 15:37:30 +0000232 /** Cipher-specific context */
233 void *cipher_ctx;
234} cipher_context_t;
235
Paul Bakker8123e9d2011-01-06 15:37:30 +0000236/**
Paul Bakker72f62662011-01-16 21:27:44 +0000237 * \brief Returns the list of ciphers supported by the generic cipher module.
238 *
239 * \return a statically allocated array of ciphers, the last entry
240 * is 0.
241 */
242const int *cipher_list( void );
243
244/**
Paul Bakker8123e9d2011-01-06 15:37:30 +0000245 * \brief Returns the cipher information structure associated
246 * with the given cipher name.
247 *
Paul Bakker23986e52011-04-24 08:57:21 +0000248 * \param cipher_name Name of the cipher to search for.
Paul Bakker8123e9d2011-01-06 15:37:30 +0000249 *
250 * \return the cipher information structure associated with the
251 * given cipher_name, or NULL if not found.
252 */
253const cipher_info_t *cipher_info_from_string( const char *cipher_name );
254
255/**
256 * \brief Returns the cipher information structure associated
257 * with the given cipher type.
258 *
259 * \param cipher_type Type of the cipher to search for.
260 *
261 * \return the cipher information structure associated with the
262 * given cipher_type, or NULL if not found.
263 */
264const cipher_info_t *cipher_info_from_type( const cipher_type_t cipher_type );
265
266/**
267 * \brief Initialises and fills the cipher context structure with
268 * the appropriate values.
269 *
270 * \param ctx context to initialise. May not be NULL.
271 * \param cipher_info cipher to use.
272 *
Paul Bakkerff61a782011-06-09 15:42:02 +0000273 * \return \c 0 on success,
274 * \c POLARSSL_ERR_CIPHER_BAD_INPUT_DATA on parameter failure,
275 * \c POLARSSL_ERR_CIPHER_ALLOC_FAILED if allocation of the
276 * cipher-specific context failed.
Paul Bakker8123e9d2011-01-06 15:37:30 +0000277 */
278int cipher_init_ctx( cipher_context_t *ctx, const cipher_info_t *cipher_info );
279
280/**
281 * \brief Free the cipher-specific context of ctx. Freeing ctx
282 * itself remains the responsibility of the caller.
283 *
284 * \param ctx Free the cipher-specific context
285 *
Paul Bakkerff61a782011-06-09 15:42:02 +0000286 * \returns 0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if
287 * parameter verification fails.
Paul Bakker8123e9d2011-01-06 15:37:30 +0000288 */
289int cipher_free_ctx( cipher_context_t *ctx );
290
291/**
292 * \brief Returns the block size of the given cipher.
293 *
294 * \param ctx cipher's context. Must have been initialised.
295 *
296 * \return size of the cipher's blocks, or 0 if ctx has not been
297 * initialised.
298 */
Paul Bakker23986e52011-04-24 08:57:21 +0000299static inline unsigned int cipher_get_block_size( const cipher_context_t *ctx )
Paul Bakker8123e9d2011-01-06 15:37:30 +0000300{
301 if( NULL == ctx || NULL == ctx->cipher_info )
302 return 0;
303
304 return ctx->cipher_info->block_size;
305}
306
307/**
Paul Bakkerf7e5bb52011-11-11 10:53:37 +0000308 * \brief Returns the mode of operation for the cipher.
309 * (e.g. POLARSSL_MODE_CBC)
310 *
311 * \param ctx cipher's context. Must have been initialised.
312 *
313 * \return mode of operation, or POLARSSL_MODE_NONE if ctx
314 * has not been initialised.
315 */
316static inline cipher_mode_t cipher_get_cipher_mode( const cipher_context_t *ctx )
317{
318 if( NULL == ctx || NULL == ctx->cipher_info )
319 return POLARSSL_MODE_NONE;
320
321 return ctx->cipher_info->mode;
322}
323
324/**
Manuel Pégourié-Gonnard9c853b92013-09-03 13:04:44 +0200325 * \brief Returns the size of the cipher's IV/NONCE in bytes.
Paul Bakker8123e9d2011-01-06 15:37:30 +0000326 *
327 * \param ctx cipher's context. Must have been initialised.
328 *
Manuel Pégourié-Gonnarda235b5b2013-09-03 13:25:52 +0200329 * \return If IV has not been set yet: (recommended) IV size
330 * (0 for ciphers not using IV/NONCE).
Manuel Pégourié-Gonnard9c853b92013-09-03 13:04:44 +0200331 * If IV has already been set: actual size.
Paul Bakker8123e9d2011-01-06 15:37:30 +0000332 */
333static inline int cipher_get_iv_size( const cipher_context_t *ctx )
334{
335 if( NULL == ctx || NULL == ctx->cipher_info )
336 return 0;
337
Manuel Pégourié-Gonnard9c853b92013-09-03 13:04:44 +0200338 if( ctx->iv_size != 0 )
339 return ctx->iv_size;
340
Paul Bakker8123e9d2011-01-06 15:37:30 +0000341 return ctx->cipher_info->iv_size;
342}
343
344/**
345 * \brief Returns the type of the given cipher.
346 *
347 * \param ctx cipher's context. Must have been initialised.
348 *
349 * \return type of the cipher, or POLARSSL_CIPHER_NONE if ctx has
350 * not been initialised.
351 */
352static inline cipher_type_t cipher_get_type( const cipher_context_t *ctx )
353{
354 if( NULL == ctx || NULL == ctx->cipher_info )
Paul Bakker894dece2012-08-23 08:34:32 +0000355 return POLARSSL_CIPHER_NONE;
Paul Bakker8123e9d2011-01-06 15:37:30 +0000356
357 return ctx->cipher_info->type;
358}
359
360/**
361 * \brief Returns the name of the given cipher, as a string.
362 *
363 * \param ctx cipher's context. Must have been initialised.
364 *
365 * \return name of the cipher, or NULL if ctx was not initialised.
366 */
367static inline const char *cipher_get_name( const cipher_context_t *ctx )
368{
369 if( NULL == ctx || NULL == ctx->cipher_info )
370 return 0;
371
372 return ctx->cipher_info->name;
373}
374
375/**
376 * \brief Returns the key length of the cipher.
377 *
378 * \param ctx cipher's context. Must have been initialised.
379 *
380 * \return cipher's key length, in bits, or
381 * POLARSSL_KEY_LENGTH_NONE if ctx has not been
382 * initialised.
383 */
384static inline int cipher_get_key_size ( const cipher_context_t *ctx )
385{
Paul Bakker68884e32013-01-07 18:20:04 +0100386 if( NULL == ctx || NULL == ctx->cipher_info )
Paul Bakker8123e9d2011-01-06 15:37:30 +0000387 return POLARSSL_KEY_LENGTH_NONE;
388
Paul Bakker68884e32013-01-07 18:20:04 +0100389 return ctx->cipher_info->key_length;
Paul Bakker8123e9d2011-01-06 15:37:30 +0000390}
391
392/**
Paul Bakkerf7e5bb52011-11-11 10:53:37 +0000393 * \brief Returns the operation of the given cipher.
394 *
395 * \param ctx cipher's context. Must have been initialised.
396 *
397 * \return operation (POLARSSL_ENCRYPT or POLARSSL_DECRYPT),
398 * or POLARSSL_OPERATION_NONE if ctx has not been
399 * initialised.
400 */
401static inline operation_t cipher_get_operation( const cipher_context_t *ctx )
402{
403 if( NULL == ctx || NULL == ctx->cipher_info )
404 return POLARSSL_OPERATION_NONE;
405
406 return ctx->operation;
407}
408
409/**
Paul Bakker8123e9d2011-01-06 15:37:30 +0000410 * \brief Set the key to use with the given context.
411 *
412 * \param ctx generic cipher context. May not be NULL. Must have been
413 * initialised using cipher_context_from_type or
Paul Bakker1f14d082011-01-20 16:33:24 +0000414 * cipher_context_from_string.
Paul Bakker8123e9d2011-01-06 15:37:30 +0000415 * \param key The key to use.
416 * \param key_length key length to use, in bits.
417 * \param operation Operation that the key will be used for, either
418 * POLARSSL_ENCRYPT or POLARSSL_DECRYPT.
419 *
Paul Bakkerff61a782011-06-09 15:42:02 +0000420 * \returns 0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if
421 * parameter verification fails or a cipher specific
422 * error code.
Paul Bakker8123e9d2011-01-06 15:37:30 +0000423 */
Paul Bakkerf3b86c12011-01-27 15:24:17 +0000424int cipher_setkey( cipher_context_t *ctx, const unsigned char *key, int key_length,
Paul Bakker8123e9d2011-01-06 15:37:30 +0000425 const operation_t operation );
426
427/**
Manuel Pégourié-Gonnardd5fdcaf2013-07-24 18:05:00 +0200428 * \brief Set padding mode, for cipher modes that use padding.
429 * (Default: PKCS7 padding.)
430 *
431 * \param ctx generic cipher context
432 * \param mode padding mode
433 *
Paul Bakker1a45d912013-08-14 12:04:26 +0200434 * \returns 0 on success, POLARSSL_ERR_CIPHER_FEATURE_UNAVAILABLE
435 * if selected padding mode is not supported, or
436 * POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
437 * does not support padding.
Manuel Pégourié-Gonnardd5fdcaf2013-07-24 18:05:00 +0200438 */
439int cipher_set_padding_mode( cipher_context_t *ctx, cipher_padding_t mode );
440
441/**
Manuel Pégourié-Gonnard9c853b92013-09-03 13:04:44 +0200442 * \brief Set the initialization vector (IV) or nonce
443 *
444 * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
Manuel Pégourié-Gonnarda235b5b2013-09-03 13:25:52 +0200445 * \param iv_len IV length for ciphers with variable-size IV;
446 * discarded by ciphers with fixed-size IV.
Manuel Pégourié-Gonnard9c853b92013-09-03 13:04:44 +0200447 *
448 * \returns O on success, or POLARSSL_ERR_CIPHER_BAD_INPUT_DATA
449 *
450 * \note Some ciphers don't use IVs nor NONCE. For these
451 * ciphers, this function has no effect.
452 */
453int cipher_set_iv( cipher_context_t *ctx,
454 const unsigned char *iv, size_t iv_len );
455
456/**
Paul Bakker8123e9d2011-01-06 15:37:30 +0000457 * \brief Reset the given context, setting the IV to iv
458 *
459 * \param ctx generic cipher context
Manuel Pégourié-Gonnard9241be72013-08-31 17:31:03 +0200460 * \param ad Additional data for AEAD ciphers, or discarded.
461 * May be NULL only if ad_len is 0.
462 * \param ad_len Length of ad for AEAD ciphers, or discarded.
Paul Bakker8123e9d2011-01-06 15:37:30 +0000463 *
Paul Bakkerff61a782011-06-09 15:42:02 +0000464 * \returns 0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA
465 * if parameter verification fails.
Paul Bakker8123e9d2011-01-06 15:37:30 +0000466 */
Manuel Pégourié-Gonnard9241be72013-08-31 17:31:03 +0200467int cipher_reset( cipher_context_t *ctx,
Manuel Pégourié-Gonnard9241be72013-08-31 17:31:03 +0200468 const unsigned char *ad, size_t ad_len );
Paul Bakker8123e9d2011-01-06 15:37:30 +0000469
470/**
471 * \brief Generic cipher update function. Encrypts/decrypts
472 * using the given cipher context. Writes as many block
473 * size'd blocks of data as possible to output. Any data
474 * that cannot be written immediately will either be added
475 * to the next block, or flushed when cipher_final is
476 * called.
477 *
478 * \param ctx generic cipher context
479 * \param input buffer holding the input data
480 * \param ilen length of the input data
481 * \param output buffer for the output data. Should be able to hold at
Paul Bakker1f14d082011-01-20 16:33:24 +0000482 * least ilen + block_size. Cannot be the same buffer as
483 * input!
Paul Bakker8123e9d2011-01-06 15:37:30 +0000484 * \param olen length of the output data, will be filled with the
485 * actual number of bytes written.
486 *
Paul Bakkerff61a782011-06-09 15:42:02 +0000487 * \returns 0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if
488 * parameter verification fails,
489 * POLARSSL_ERR_CIPHER_FEATURE_UNAVAILABLE on an
490 * unsupported mode for a cipher or a cipher specific
491 * error code.
Paul Bakker8123e9d2011-01-06 15:37:30 +0000492 */
Paul Bakker23986e52011-04-24 08:57:21 +0000493int cipher_update( cipher_context_t *ctx, const unsigned char *input, size_t ilen,
494 unsigned char *output, size_t *olen );
Paul Bakker8123e9d2011-01-06 15:37:30 +0000495
496/**
497 * \brief Generic cipher finalisation function. If data still
498 * needs to be flushed from an incomplete block, data
499 * contained within it will be padded with the size of
500 * the last block, and written to the output buffer.
501 *
Paul Bakker20281562011-11-11 10:34:04 +0000502 * \param ctx Generic cipher context
Manuel Pégourié-Gonnard9241be72013-08-31 17:31:03 +0200503 * \param output buffer to write data to. Needs block_size available.
Paul Bakker8123e9d2011-01-06 15:37:30 +0000504 * \param olen length of the data written to the output buffer.
Manuel Pégourié-Gonnard9241be72013-08-31 17:31:03 +0200505 * \param tag Ignore by non-AEAD ciphers. For AEAD ciphers:
506 * - on encryption: buffer to write the tag;
507 * - on decryption: tag to verify.
508 * May be NULL if tag_len is zero.
509 * \param tag_len Length of the tag to write/check for AEAD ciphers.
Paul Bakker8123e9d2011-01-06 15:37:30 +0000510 *
Paul Bakkerff61a782011-06-09 15:42:02 +0000511 * \returns 0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if
512 * parameter verification fails,
513 * POLARSSL_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
514 * expected a full block but was not provided one,
515 * POLARSSL_ERR_CIPHER_INVALID_PADDING on invalid padding
516 * while decrypting or a cipher specific error code.
Paul Bakker8123e9d2011-01-06 15:37:30 +0000517 */
Manuel Pégourié-Gonnard9241be72013-08-31 17:31:03 +0200518int cipher_finish( cipher_context_t *ctx,
519 unsigned char *output, size_t *olen,
520 unsigned char *tag, size_t tag_len );
Paul Bakker8123e9d2011-01-06 15:37:30 +0000521
Paul Bakker8123e9d2011-01-06 15:37:30 +0000522/**
523 * \brief Checkup routine
524 *
525 * \return 0 if successful, or 1 if the test failed
526 */
527int cipher_self_test( int verbose );
528
529#ifdef __cplusplus
530}
531#endif
532
Manuel Pégourié-Gonnard5151b452013-08-23 12:03:28 +0200533#endif /* POLARSSL_CIPHER_H */