cipher.h

00001 /**
00002  * \file cipher.h
00003  *
00004  * \brief Generic cipher wrapper.
00005  *
00006  * \author Adriaan de Jong <dejong@fox-it.com>
00007  *
00008  *  Copyright (C) 2006-2014, ARM Limited, All Rights Reserved
00009  *
00010  *  This file is part of mbed TLS (https://tls.mbed.org)
00011  *
00012  *  This program is free software; you can redistribute it and/or modify
00013  *  it under the terms of the GNU General Public License as published by
00014  *  the Free Software Foundation; either version 2 of the License, or
00015  *  (at your option) any later version.
00016  *
00017  *  This program is distributed in the hope that it will be useful,
00018  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  *  GNU General Public License for more details.
00021  *
00022  *  You should have received a copy of the GNU General Public License along
00023  *  with this program; if not, write to the Free Software Foundation, Inc.,
00024  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
00025  */
00026 
00027 #ifndef POLARSSL_CIPHER_H
00028 #define POLARSSL_CIPHER_H
00029 
00030 #if !defined(POLARSSL_CONFIG_FILE)
00031 #include "config.h"
00032 #else
00033 #include POLARSSL_CONFIG_FILE
00034 #endif
00035 
00036 #include <stddef.h>
00037 
00038 #if defined(POLARSSL_GCM_C) || defined(POLARSSL_CCM_C)
00039 #define POLARSSL_CIPHER_MODE_AEAD
00040 #endif
00041 
00042 #if defined(POLARSSL_CIPHER_MODE_CBC)
00043 #define POLARSSL_CIPHER_MODE_WITH_PADDING
00044 #endif
00045 
00046 #if defined(POLARSSL_ARC4_C)
00047 #define POLARSSL_CIPHER_MODE_STREAM
00048 #endif
00049 
00050 #if defined(_MSC_VER) && !defined(inline)
00051 #define inline _inline
00052 #else
00053 #if defined(__ARMCC_VERSION) && !defined(inline)
00054 #define inline __inline
00055 #endif /* __ARMCC_VERSION */
00056 #endif /*_MSC_VER */
00057 
00058 #define POLARSSL_ERR_CIPHER_FEATURE_UNAVAILABLE            -0x6080  /**< The selected feature is not available. */
00059 #define POLARSSL_ERR_CIPHER_BAD_INPUT_DATA                 -0x6100  /**< Bad input parameters to function. */
00060 #define POLARSSL_ERR_CIPHER_ALLOC_FAILED                   -0x6180  /**< Failed to allocate memory. */
00061 #define POLARSSL_ERR_CIPHER_INVALID_PADDING                -0x6200  /**< Input data contains invalid padding and is rejected. */
00062 #define POLARSSL_ERR_CIPHER_FULL_BLOCK_EXPECTED            -0x6280  /**< Decryption of block requires a full block. */
00063 #define POLARSSL_ERR_CIPHER_AUTH_FAILED                    -0x6300  /**< Authentication failed (for AEAD modes). */
00064 
00065 #define POLARSSL_CIPHER_VARIABLE_IV_LEN     0x01    /**< Cipher accepts IVs of variable length */
00066 #define POLARSSL_CIPHER_VARIABLE_KEY_LEN    0x02    /**< Cipher accepts keys of variable length */
00067 
00068 #ifdef __cplusplus
00069 extern "C" {
00070 #endif
00071 
00072 typedef enum {
00073     POLARSSL_CIPHER_ID_NONE = 0,
00074     POLARSSL_CIPHER_ID_NULL,
00075     POLARSSL_CIPHER_ID_AES,
00076     POLARSSL_CIPHER_ID_DES,
00077     POLARSSL_CIPHER_ID_3DES, /* Unused! */
00078     POLARSSL_CIPHER_ID_CAMELLIA,
00079     POLARSSL_CIPHER_ID_BLOWFISH,
00080     POLARSSL_CIPHER_ID_ARC4,
00081 } cipher_id_t;
00082 
00083 typedef enum {
00084     POLARSSL_CIPHER_NONE = 0,
00085     POLARSSL_CIPHER_NULL,
00086     POLARSSL_CIPHER_AES_128_ECB,
00087     POLARSSL_CIPHER_AES_192_ECB,
00088     POLARSSL_CIPHER_AES_256_ECB,
00089     POLARSSL_CIPHER_AES_128_CBC,
00090     POLARSSL_CIPHER_AES_192_CBC,
00091     POLARSSL_CIPHER_AES_256_CBC,
00092     POLARSSL_CIPHER_AES_128_CFB128,
00093     POLARSSL_CIPHER_AES_192_CFB128,
00094     POLARSSL_CIPHER_AES_256_CFB128,
00095     POLARSSL_CIPHER_AES_128_CTR,
00096     POLARSSL_CIPHER_AES_192_CTR,
00097     POLARSSL_CIPHER_AES_256_CTR,
00098     POLARSSL_CIPHER_AES_128_GCM,
00099     POLARSSL_CIPHER_AES_192_GCM,
00100     POLARSSL_CIPHER_AES_256_GCM,
00101     POLARSSL_CIPHER_CAMELLIA_128_ECB,
00102     POLARSSL_CIPHER_CAMELLIA_192_ECB,
00103     POLARSSL_CIPHER_CAMELLIA_256_ECB,
00104     POLARSSL_CIPHER_CAMELLIA_128_CBC,
00105     POLARSSL_CIPHER_CAMELLIA_192_CBC,
00106     POLARSSL_CIPHER_CAMELLIA_256_CBC,
00107     POLARSSL_CIPHER_CAMELLIA_128_CFB128,
00108     POLARSSL_CIPHER_CAMELLIA_192_CFB128,
00109     POLARSSL_CIPHER_CAMELLIA_256_CFB128,
00110     POLARSSL_CIPHER_CAMELLIA_128_CTR,
00111     POLARSSL_CIPHER_CAMELLIA_192_CTR,
00112     POLARSSL_CIPHER_CAMELLIA_256_CTR,
00113     POLARSSL_CIPHER_CAMELLIA_128_GCM,
00114     POLARSSL_CIPHER_CAMELLIA_192_GCM,
00115     POLARSSL_CIPHER_CAMELLIA_256_GCM,
00116     POLARSSL_CIPHER_DES_ECB,
00117     POLARSSL_CIPHER_DES_CBC,
00118     POLARSSL_CIPHER_DES_EDE_ECB,
00119     POLARSSL_CIPHER_DES_EDE_CBC,
00120     POLARSSL_CIPHER_DES_EDE3_ECB,
00121     POLARSSL_CIPHER_DES_EDE3_CBC,
00122     POLARSSL_CIPHER_BLOWFISH_ECB,
00123     POLARSSL_CIPHER_BLOWFISH_CBC,
00124     POLARSSL_CIPHER_BLOWFISH_CFB64,
00125     POLARSSL_CIPHER_BLOWFISH_CTR,
00126     POLARSSL_CIPHER_ARC4_128,
00127     POLARSSL_CIPHER_AES_128_CCM,
00128     POLARSSL_CIPHER_AES_192_CCM,
00129     POLARSSL_CIPHER_AES_256_CCM,
00130     POLARSSL_CIPHER_CAMELLIA_128_CCM,
00131     POLARSSL_CIPHER_CAMELLIA_192_CCM,
00132     POLARSSL_CIPHER_CAMELLIA_256_CCM,
00133 } cipher_type_t;
00134 
00135 typedef enum {
00136     POLARSSL_MODE_NONE = 0,
00137     POLARSSL_MODE_ECB,
00138     POLARSSL_MODE_CBC,
00139     POLARSSL_MODE_CFB,
00140     POLARSSL_MODE_OFB, /* Unused! */
00141     POLARSSL_MODE_CTR,
00142     POLARSSL_MODE_GCM,
00143     POLARSSL_MODE_STREAM,
00144     POLARSSL_MODE_CCM,
00145 } cipher_mode_t;
00146 
00147 typedef enum {
00148     POLARSSL_PADDING_PKCS7 = 0,     /**< PKCS7 padding (default)        */
00149     POLARSSL_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding         */
00150     POLARSSL_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding             */
00151     POLARSSL_PADDING_ZEROS,         /**< zero padding (not reversible!) */
00152     POLARSSL_PADDING_NONE,          /**< never pad (full blocks only)   */
00153 } cipher_padding_t ;
00154 
00155 typedef enum {
00156     POLARSSL_OPERATION_NONE = -1,
00157     POLARSSL_DECRYPT = 0,
00158     POLARSSL_ENCRYPT,
00159 } operation_t;
00160 
00161 enum {
00162     /** Undefined key length */
00163     POLARSSL_KEY_LENGTH_NONE = 0,
00164     /** Key length, in bits (including parity), for DES keys */
00165     POLARSSL_KEY_LENGTH_DES  = 64,
00166     /** Key length, in bits (including parity), for DES in two key EDE */
00167     POLARSSL_KEY_LENGTH_DES_EDE = 128,
00168     /** Key length, in bits (including parity), for DES in three-key EDE */
00169     POLARSSL_KEY_LENGTH_DES_EDE3 = 192,
00170 };
00171 
00172 /** Maximum length of any IV, in bytes */
00173 #define POLARSSL_MAX_IV_LENGTH      16
00174 /** Maximum block size of any cipher, in bytes */
00175 #define POLARSSL_MAX_BLOCK_LENGTH   16
00176 
00177 /**
00178  * Base cipher information. The non-mode specific functions and values.
00179  */
00180 typedef struct {
00181 
00182     /** Base Cipher type (e.g. POLARSSL_CIPHER_ID_AES) */
00183     cipher_id_t cipher;
00184 
00185     /** Encrypt using ECB */
00186     int (*ecb_func)( void *ctx, operation_t mode,
00187                      const unsigned char *input, unsigned char *output );
00188 
00189 #if defined(POLARSSL_CIPHER_MODE_CBC)
00190     /** Encrypt using CBC */
00191     int (*cbc_func)( void *ctx, operation_t mode, size_t length,
00192                      unsigned char *iv, const unsigned char *input,
00193                      unsigned char *output );
00194 #endif
00195 
00196 #if defined(POLARSSL_CIPHER_MODE_CFB)
00197     /** Encrypt using CFB (Full length) */
00198     int (*cfb_func)( void *ctx, operation_t mode, size_t length, size_t *iv_off,
00199                      unsigned char *iv, const unsigned char *input,
00200                      unsigned char *output );
00201 #endif
00202 
00203 #if defined(POLARSSL_CIPHER_MODE_CTR)
00204     /** Encrypt using CTR */
00205     int (*ctr_func)( void *ctx, size_t length, size_t *nc_off,
00206                      unsigned char *nonce_counter, unsigned char *stream_block,
00207                      const unsigned char *input, unsigned char *output );
00208 #endif
00209 
00210 #if defined(POLARSSL_CIPHER_MODE_STREAM)
00211     /** Encrypt using STREAM */
00212     int (*stream_func)( void *ctx, size_t length,
00213                         const unsigned char *input, unsigned char *output );
00214 #endif
00215 
00216     /** Set key for encryption purposes */
00217     int (*setkey_enc_func)( void *ctx, const unsigned char *key,
00218                             unsigned int key_length );
00219 
00220     /** Set key for decryption purposes */
00221     int (*setkey_dec_func)( void *ctx, const unsigned char *key,
00222                             unsigned int key_length);
00223 
00224     /** Allocate a new context */
00225     void * (*ctx_alloc_func)( void );
00226 
00227     /** Free the given context */
00228     void (*ctx_free_func)( void *ctx );
00229 
00230 } cipher_base_t;
00231 
00232 /**
00233  * Cipher information. Allows cipher functions to be called in a generic way.
00234  */
00235 typedef struct {
00236     /** Full cipher identifier (e.g. POLARSSL_CIPHER_AES_256_CBC) */
00237     cipher_type_t type;
00238 
00239     /** Cipher mode (e.g. POLARSSL_MODE_CBC) */
00240     cipher_mode_t mode;
00241 
00242     /** Cipher key length, in bits (default length for variable sized ciphers)
00243      *  (Includes parity bits for ciphers like DES) */
00244     unsigned int key_length;
00245 
00246     /** Name of the cipher */
00247     const char * name;
00248 
00249     /** IV/NONCE size, in bytes.
00250      *  For cipher that accept many sizes: recommended size */
00251     unsigned int iv_size;
00252 
00253     /** Flags for variable IV size, variable key size, etc. */
00254     int flags;
00255 
00256     /** block size, in bytes */
00257     unsigned int block_size;
00258 
00259     /** Base cipher information and functions */
00260     const cipher_base_t *base;
00261 
00262 } cipher_info_t;
00263 
00264 /**
00265  * Generic cipher context.
00266  */
00267 typedef struct {
00268     /** Information about the associated cipher */
00269     const cipher_info_t *cipher_info;
00270 
00271     /** Key length to use */
00272     int key_length;
00273 
00274     /** Operation that the context's key has been initialised for */
00275     operation_t operation;
00276 
00277 #if defined(POLARSSL_CIPHER_MODE_WITH_PADDING)
00278     /** Padding functions to use, if relevant for cipher mode */
00279     void (*add_padding)( unsigned char *output, size_t olen, size_t data_len );
00280     int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len );
00281 #endif
00282 
00283     /** Buffer for data that hasn't been encrypted yet */
00284     unsigned char unprocessed_data[POLARSSL_MAX_BLOCK_LENGTH];
00285 
00286     /** Number of bytes that still need processing */
00287     size_t unprocessed_len;
00288 
00289     /** Current IV or NONCE_COUNTER for CTR-mode */
00290     unsigned char iv[POLARSSL_MAX_IV_LENGTH];
00291 
00292     /** IV size in bytes (for ciphers with variable-length IVs) */
00293     size_t iv_size;
00294 
00295     /** Cipher-specific context */
00296     void *cipher_ctx;
00297 } cipher_context_t;
00298 
00299 /**
00300  * \brief Returns the list of ciphers supported by the generic cipher module.
00301  *
00302  * \return              a statically allocated array of ciphers, the last entry
00303  *                      is 0.
00304  */
00305 const int *cipher_list( void );
00306 
00307 /**
00308  * \brief               Returns the cipher information structure associated
00309  *                      with the given cipher name.
00310  *
00311  * \param cipher_name   Name of the cipher to search for.
00312  *
00313  * \return              the cipher information structure associated with the
00314  *                      given cipher_name, or NULL if not found.
00315  */
00316 const cipher_info_t *cipher_info_from_string( const char *cipher_name );
00317 
00318 /**
00319  * \brief               Returns the cipher information structure associated
00320  *                      with the given cipher type.
00321  *
00322  * \param cipher_type   Type of the cipher to search for.
00323  *
00324  * \return              the cipher information structure associated with the
00325  *                      given cipher_type, or NULL if not found.
00326  */
00327 const cipher_info_t *cipher_info_from_type( const cipher_type_t cipher_type );
00328 
00329 /**
00330  * \brief               Returns the cipher information structure associated
00331  *                      with the given cipher id, key size and mode.
00332  *
00333  * \param cipher_id     Id of the cipher to search for
00334  *                      (e.g. POLARSSL_CIPHER_ID_AES)
00335  * \param key_length    Length of the key in bits
00336  * \param mode          Cipher mode (e.g. POLARSSL_MODE_CBC)
00337  *
00338  * \return              the cipher information structure associated with the
00339  *                      given cipher_type, or NULL if not found.
00340  */
00341 const cipher_info_t *cipher_info_from_values( const cipher_id_t cipher_id,
00342                                               int key_length,
00343                                               const cipher_mode_t mode );
00344 
00345 /**
00346  * \brief               Initialize a cipher_context (as NONE)
00347  */
00348 void cipher_init( cipher_context_t *ctx );
00349 
00350 /**
00351  * \brief               Free and clear the cipher-specific context of ctx.
00352  *                      Freeing ctx itself remains the responsibility of the
00353  *                      caller.
00354  */
00355 void cipher_free( cipher_context_t *ctx );
00356 
00357 /**
00358  * \brief               Initialises and fills the cipher context structure with
00359  *                      the appropriate values.
00360  *
00361  * \note                Currently also clears structure. In future versions you
00362  *                      will be required to call cipher_init() on the structure
00363  *                      first.
00364  *
00365  * \param ctx           context to initialise. May not be NULL.
00366  * \param cipher_info   cipher to use.
00367  *
00368  * \return              0 on success,
00369  *                      POLARSSL_ERR_CIPHER_BAD_INPUT_DATA on parameter failure,
00370  *                      POLARSSL_ERR_CIPHER_ALLOC_FAILED if allocation of the
00371  *                      cipher-specific context failed.
00372  */
00373 int cipher_init_ctx( cipher_context_t *ctx, const cipher_info_t *cipher_info );
00374 
00375 #if ! defined(POLARSSL_DEPRECATED_REMOVED)
00376 #if defined(POLARSSL_DEPRECATED_WARNING)
00377 #define DEPRECATED    __attribute__((deprecated))
00378 #else
00379 #define DEPRECATED
00380 #endif
00381 /**
00382  * \brief               Free the cipher-specific context of ctx. Freeing ctx
00383  *                      itself remains the responsibility of the caller.
00384  *
00385  * \deprecated          Use cipher_free() instead
00386  *
00387  * \param ctx           Free the cipher-specific context
00388  *
00389  * \returns             0
00390  */
00391 int cipher_free_ctx( cipher_context_t *ctx ) DEPRECATED;
00392 #undef DEPRECATED
00393 #endif /* POLARSSL_DEPRECATED_REMOVED */
00394 
00395 /**
00396  * \brief               Returns the block size of the given cipher.
00397  *
00398  * \param ctx           cipher's context. Must have been initialised.
00399  *
00400  * \return              size of the cipher's blocks, or 0 if ctx has not been
00401  *                      initialised.
00402  */
00403 static inline unsigned int cipher_get_block_size( const cipher_context_t *ctx )
00404 {
00405     if( NULL == ctx || NULL == ctx->cipher_info )
00406         return 0;
00407 
00408     return ctx->cipher_info->block_size;
00409 }
00410 
00411 /**
00412  * \brief               Returns the mode of operation for the cipher.
00413  *                      (e.g. POLARSSL_MODE_CBC)
00414  *
00415  * \param ctx           cipher's context. Must have been initialised.
00416  *
00417  * \return              mode of operation, or POLARSSL_MODE_NONE if ctx
00418  *                      has not been initialised.
00419  */
00420 static inline cipher_mode_t cipher_get_cipher_mode( const cipher_context_t *ctx )
00421 {
00422     if( NULL == ctx || NULL == ctx->cipher_info )
00423         return POLARSSL_MODE_NONE;
00424 
00425     return ctx->cipher_info->mode;
00426 }
00427 
00428 /**
00429  * \brief               Returns the size of the cipher's IV/NONCE in bytes.
00430  *
00431  * \param ctx           cipher's context. Must have been initialised.
00432  *
00433  * \return              If IV has not been set yet: (recommended) IV size
00434  *                      (0 for ciphers not using IV/NONCE).
00435  *                      If IV has already been set: actual size.
00436  */
00437 static inline int cipher_get_iv_size( const cipher_context_t *ctx )
00438 {
00439     if( NULL == ctx || NULL == ctx->cipher_info )
00440         return 0;
00441 
00442     if( ctx->iv_size != 0 )
00443         return (int) ctx->iv_size;
00444 
00445     return ctx->cipher_info->iv_size;
00446 }
00447 
00448 /**
00449  * \brief               Returns the type of the given cipher.
00450  *
00451  * \param ctx           cipher's context. Must have been initialised.
00452  *
00453  * \return              type of the cipher, or POLARSSL_CIPHER_NONE if ctx has
00454  *                      not been initialised.
00455  */
00456 static inline cipher_type_t cipher_get_type( const cipher_context_t *ctx )
00457 {
00458     if( NULL == ctx || NULL == ctx->cipher_info )
00459         return POLARSSL_CIPHER_NONE;
00460 
00461     return ctx->cipher_info->type;
00462 }
00463 
00464 /**
00465  * \brief               Returns the name of the given cipher, as a string.
00466  *
00467  * \param ctx           cipher's context. Must have been initialised.
00468  *
00469  * \return              name of the cipher, or NULL if ctx was not initialised.
00470  */
00471 static inline const char *cipher_get_name( const cipher_context_t *ctx )
00472 {
00473     if( NULL == ctx || NULL == ctx->cipher_info )
00474         return 0;
00475 
00476     return ctx->cipher_info->name;
00477 }
00478 
00479 /**
00480  * \brief               Returns the key length of the cipher.
00481  *
00482  * \param ctx           cipher's context. Must have been initialised.
00483  *
00484  * \return              cipher's key length, in bits, or
00485  *                      POLARSSL_KEY_LENGTH_NONE if ctx has not been
00486  *                      initialised.
00487  */
00488 static inline int cipher_get_key_size( const cipher_context_t *ctx )
00489 {
00490     if( NULL == ctx || NULL == ctx->cipher_info )
00491         return POLARSSL_KEY_LENGTH_NONE;
00492 
00493     return ctx->cipher_info->key_length;
00494 }
00495 
00496 /**
00497  * \brief               Returns the operation of the given cipher.
00498  *
00499  * \param ctx           cipher's context. Must have been initialised.
00500  *
00501  * \return              operation (POLARSSL_ENCRYPT or POLARSSL_DECRYPT),
00502  *                      or POLARSSL_OPERATION_NONE if ctx has not been
00503  *                      initialised.
00504  */
00505 static inline operation_t cipher_get_operation( const cipher_context_t *ctx )
00506 {
00507     if( NULL == ctx || NULL == ctx->cipher_info )
00508         return POLARSSL_OPERATION_NONE;
00509 
00510     return ctx->operation;
00511 }
00512 
00513 /**
00514  * \brief               Set the key to use with the given context.
00515  *
00516  * \param ctx           generic cipher context. May not be NULL. Must have been
00517  *                      initialised using cipher_context_from_type or
00518  *                      cipher_context_from_string.
00519  * \param key           The key to use.
00520  * \param key_length    key length to use, in bits.
00521  * \param operation     Operation that the key will be used for, either
00522  *                      POLARSSL_ENCRYPT or POLARSSL_DECRYPT.
00523  *
00524  * \returns             0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if
00525  *                      parameter verification fails or a cipher specific
00526  *                      error code.
00527  */
00528 int cipher_setkey( cipher_context_t *ctx, const unsigned char *key,
00529                    int key_length, const operation_t operation );
00530 
00531 #if defined(POLARSSL_CIPHER_MODE_WITH_PADDING)
00532 /**
00533  * \brief               Set padding mode, for cipher modes that use padding.
00534  *                      (Default: PKCS7 padding.)
00535  *
00536  * \param ctx           generic cipher context
00537  * \param mode          padding mode
00538  *
00539  * \returns             0 on success, POLARSSL_ERR_CIPHER_FEATURE_UNAVAILABLE
00540  *                      if selected padding mode is not supported, or
00541  *                      POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
00542  *                      does not support padding.
00543  */
00544 int cipher_set_padding_mode( cipher_context_t *ctx, cipher_padding_t  mode );
00545 #endif /* POLARSSL_CIPHER_MODE_WITH_PADDING */
00546 
00547 /**
00548  * \brief               Set the initialization vector (IV) or nonce
00549  *
00550  * \param ctx           generic cipher context
00551  * \param iv            IV to use (or NONCE_COUNTER for CTR-mode ciphers)
00552  * \param iv_len        IV length for ciphers with variable-size IV;
00553  *                      discarded by ciphers with fixed-size IV.
00554  *
00555  * \returns             0 on success, or POLARSSL_ERR_CIPHER_BAD_INPUT_DATA
00556  *
00557  * \note                Some ciphers don't use IVs nor NONCE. For these
00558  *                      ciphers, this function has no effect.
00559  */
00560 int cipher_set_iv( cipher_context_t *ctx,
00561                    const unsigned char *iv, size_t iv_len );
00562 
00563 /**
00564  * \brief               Finish preparation of the given context
00565  *
00566  * \param ctx           generic cipher context
00567  *
00568  * \returns             0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA
00569  *                      if parameter verification fails.
00570  */
00571 int cipher_reset( cipher_context_t *ctx );
00572 
00573 #if defined(POLARSSL_GCM_C)
00574 /**
00575  * \brief               Add additional data (for AEAD ciphers).
00576  *                      Currently only supported with GCM.
00577  *                      Must be called exactly once, after cipher_reset().
00578  *
00579  * \param ctx           generic cipher context
00580  * \param ad            Additional data to use.
00581  * \param ad_len        Length of ad.
00582  *
00583  * \return              0 on success, or a specific error code.
00584  */
00585 int cipher_update_ad( cipher_context_t *ctx,
00586                       const unsigned char *ad, size_t ad_len );
00587 #endif /* POLARSSL_GCM_C */
00588 
00589 /**
00590  * \brief               Generic cipher update function. Encrypts/decrypts
00591  *                      using the given cipher context. Writes as many block
00592  *                      size'd blocks of data as possible to output. Any data
00593  *                      that cannot be written immediately will either be added
00594  *                      to the next block, or flushed when cipher_final is
00595  *                      called.
00596  *                      Exception: for POLARSSL_MODE_ECB, expects single block
00597  *                                 in size (e.g. 16 bytes for AES)
00598  *
00599  * \param ctx           generic cipher context
00600  * \param input         buffer holding the input data
00601  * \param ilen          length of the input data
00602  * \param output        buffer for the output data. Should be able to hold at
00603  *                      least ilen + block_size. Cannot be the same buffer as
00604  *                      input!
00605  * \param olen          length of the output data, will be filled with the
00606  *                      actual number of bytes written.
00607  *
00608  * \returns             0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if
00609  *                      parameter verification fails,
00610  *                      POLARSSL_ERR_CIPHER_FEATURE_UNAVAILABLE on an
00611  *                      unsupported mode for a cipher or a cipher specific
00612  *                      error code.
00613  *
00614  * \note                If the underlying cipher is GCM, all calls to this
00615  *                      function, except the last one before cipher_finish(),
00616  *                      must have ilen a multiple of the block size.
00617  */
00618 int cipher_update( cipher_context_t *ctx, const unsigned char *input,
00619                    size_t ilen, unsigned char *output, size_t *olen );
00620 
00621 /**
00622  * \brief               Generic cipher finalisation function. If data still
00623  *                      needs to be flushed from an incomplete block, data
00624  *                      contained within it will be padded with the size of
00625  *                      the last block, and written to the output buffer.
00626  *
00627  * \param ctx           Generic cipher context
00628  * \param output        buffer to write data to. Needs block_size available.
00629  * \param olen          length of the data written to the output buffer.
00630  *
00631  * \returns             0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if
00632  *                      parameter verification fails,
00633  *                      POLARSSL_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
00634  *                      expected a full block but was not provided one,
00635  *                      POLARSSL_ERR_CIPHER_INVALID_PADDING on invalid padding
00636  *                      while decrypting or a cipher specific error code.
00637  */
00638 int cipher_finish( cipher_context_t *ctx,
00639                    unsigned char *output, size_t *olen );
00640 
00641 #if defined(POLARSSL_GCM_C)
00642 /**
00643  * \brief               Write tag for AEAD ciphers.
00644  *                      Currently only supported with GCM.
00645  *                      Must be called after cipher_finish().
00646  *
00647  * \param ctx           Generic cipher context
00648  * \param tag           buffer to write the tag
00649  * \param tag_len       Length of the tag to write
00650  *
00651  * \return              0 on success, or a specific error code.
00652  */
00653 int cipher_write_tag( cipher_context_t *ctx,
00654                       unsigned char *tag, size_t tag_len );
00655 
00656 /**
00657  * \brief               Check tag for AEAD ciphers.
00658  *                      Currently only supported with GCM.
00659  *                      Must be called after cipher_finish().
00660  *
00661  * \param ctx           Generic cipher context
00662  * \param tag           Buffer holding the tag
00663  * \param tag_len       Length of the tag to check
00664  *
00665  * \return              0 on success, or a specific error code.
00666  */
00667 int cipher_check_tag( cipher_context_t *ctx,
00668                       const unsigned char *tag, size_t tag_len );
00669 #endif /* POLARSSL_GCM_C */
00670 
00671 /**
00672  * \brief               Generic all-in-one encryption/decryption
00673  *                      (for all ciphers except AEAD constructs).
00674  *
00675  * \param ctx           generic cipher context
00676  * \param iv            IV to use (or NONCE_COUNTER for CTR-mode ciphers)
00677  * \param iv_len        IV length for ciphers with variable-size IV;
00678  *                      discarded by ciphers with fixed-size IV.
00679  * \param input         buffer holding the input data
00680  * \param ilen          length of the input data
00681  * \param output        buffer for the output data. Should be able to hold at
00682  *                      least ilen + block_size. Cannot be the same buffer as
00683  *                      input!
00684  * \param olen          length of the output data, will be filled with the
00685  *                      actual number of bytes written.
00686  *
00687  * \note                Some ciphers don't use IVs nor NONCE. For these
00688  *                      ciphers, use iv = NULL and iv_len = 0.
00689  *
00690  * \returns             0 on success, or
00691  *                      POLARSSL_ERR_CIPHER_BAD_INPUT_DATA, or
00692  *                      POLARSSL_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
00693  *                      expected a full block but was not provided one, or
00694  *                      POLARSSL_ERR_CIPHER_INVALID_PADDING on invalid padding
00695  *                      while decrypting, or
00696  *                      a cipher specific error code.
00697  */
00698 int cipher_crypt( cipher_context_t *ctx,
00699                   const unsigned char *iv, size_t iv_len,
00700                   const unsigned char *input, size_t ilen,
00701                   unsigned char *output, size_t *olen );
00702 
00703 #if defined(POLARSSL_CIPHER_MODE_AEAD)
00704 /**
00705  * \brief               Generic autenticated encryption (AEAD ciphers).
00706  *
00707  * \param ctx           generic cipher context
00708  * \param iv            IV to use (or NONCE_COUNTER for CTR-mode ciphers)
00709  * \param iv_len        IV length for ciphers with variable-size IV;
00710  *                      discarded by ciphers with fixed-size IV.
00711  * \param ad            Additional data to authenticate.
00712  * \param ad_len        Length of ad.
00713  * \param input         buffer holding the input data
00714  * \param ilen          length of the input data
00715  * \param output        buffer for the output data.
00716  *                      Should be able to hold at least ilen.
00717  * \param olen          length of the output data, will be filled with the
00718  *                      actual number of bytes written.
00719  * \param tag           buffer for the authentication tag
00720  * \param tag_len       desired tag length
00721  *
00722  * \returns             0 on success, or
00723  *                      POLARSSL_ERR_CIPHER_BAD_INPUT_DATA, or
00724  *                      a cipher specific error code.
00725  */
00726 int cipher_auth_encrypt( cipher_context_t *ctx,
00727                          const unsigned char *iv, size_t iv_len,
00728                          const unsigned char *ad, size_t ad_len,
00729                          const unsigned char *input, size_t ilen,
00730                          unsigned char *output, size_t *olen,
00731                          unsigned char *tag, size_t tag_len );
00732 
00733 /**
00734  * \brief               Generic autenticated decryption (AEAD ciphers).
00735  *
00736  * \param ctx           generic cipher context
00737  * \param iv            IV to use (or NONCE_COUNTER for CTR-mode ciphers)
00738  * \param iv_len        IV length for ciphers with variable-size IV;
00739  *                      discarded by ciphers with fixed-size IV.
00740  * \param ad            Additional data to be authenticated.
00741  * \param ad_len        Length of ad.
00742  * \param input         buffer holding the input data
00743  * \param ilen          length of the input data
00744  * \param output        buffer for the output data.
00745  *                      Should be able to hold at least ilen.
00746  * \param olen          length of the output data, will be filled with the
00747  *                      actual number of bytes written.
00748  * \param tag           buffer holding the authentication tag
00749  * \param tag_len       length of the authentication tag
00750  *
00751  * \returns             0 on success, or
00752  *                      POLARSSL_ERR_CIPHER_BAD_INPUT_DATA, or
00753  *                      POLARSSL_ERR_CIPHER_AUTH_FAILED if data isn't authentic,
00754  *                      or a cipher specific error code.
00755  *
00756  * \note                If the data is not authentic, then the output buffer
00757  *                      is zeroed out to prevent the unauthentic plaintext to
00758  *                      be used by mistake, making this interface safer.
00759  */
00760 int cipher_auth_decrypt( cipher_context_t *ctx,
00761                          const unsigned char *iv, size_t iv_len,
00762                          const unsigned char *ad, size_t ad_len,
00763                          const unsigned char *input, size_t ilen,
00764                          unsigned char *output, size_t *olen,
00765                          const unsigned char *tag, size_t tag_len );
00766 #endif /* POLARSSL_CIPHER_MODE_AEAD */
00767 
00768 /**
00769  * \brief          Checkup routine
00770  *
00771  * \return         0 if successful, or 1 if the test failed
00772  */
00773 int cipher_self_test( int verbose );
00774 
00775 #ifdef __cplusplus
00776 }
00777 #endif
00778 
00779 #endif /* POLARSSL_CIPHER_H */
00780