cipher.h

00001 /**
00002  * \file cipher.h
00003  *
00004  * \brief The generic cipher wrapper.
00005  *
00006  * \author Adriaan de Jong <dejong@fox-it.com>
00007  */
00008 /*
00009  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
00010  *  SPDX-License-Identifier: Apache-2.0
00011  *
00012  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00013  *  not use this file except in compliance with the License.
00014  *  You may obtain a copy of the License at
00015  *
00016  *  http://www.apache.org/licenses/LICENSE-2.0
00017  *
00018  *  Unless required by applicable law or agreed to in writing, software
00019  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00020  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00021  *  See the License for the specific language governing permissions and
00022  *  limitations under the License.
00023  *
00024  *  This file is part of Mbed TLS (https://tls.mbed.org)
00025  */
00026 
00027 #ifndef MBEDTLS_CIPHER_H
00028 #define MBEDTLS_CIPHER_H
00029 
00030 #if !defined(MBEDTLS_CONFIG_FILE)
00031 #include "config.h"
00032 #else
00033 #include MBEDTLS_CONFIG_FILE
00034 #endif
00035 
00036 #include <stddef.h>
00037 
00038 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CCM_C)
00039 #define MBEDTLS_CIPHER_MODE_AEAD
00040 #endif
00041 
00042 #if defined(MBEDTLS_CIPHER_MODE_CBC)
00043 #define MBEDTLS_CIPHER_MODE_WITH_PADDING
00044 #endif
00045 
00046 #if defined(MBEDTLS_ARC4_C)
00047 #define MBEDTLS_CIPHER_MODE_STREAM
00048 #endif
00049 
00050 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
00051     !defined(inline) && !defined(__cplusplus)
00052 #define inline __inline
00053 #endif
00054 
00055 #define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE  -0x6080  /**< The selected feature is not available. */
00056 #define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA       -0x6100  /**< Bad input parameters. */
00057 #define MBEDTLS_ERR_CIPHER_ALLOC_FAILED         -0x6180  /**< Failed to allocate memory. */
00058 #define MBEDTLS_ERR_CIPHER_INVALID_PADDING      -0x6200  /**< Input data contains invalid padding and is rejected. */
00059 #define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED  -0x6280  /**< Decryption of block requires a full block. */
00060 #define MBEDTLS_ERR_CIPHER_AUTH_FAILED          -0x6300  /**< Authentication failed (for AEAD modes). */
00061 #define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT      -0x6380  /**< The context is invalid. For example, because it was freed. */
00062 #define MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED      -0x6400  /**< Cipher hardware accelerator failed. */
00063 
00064 #define MBEDTLS_CIPHER_VARIABLE_IV_LEN     0x01    /**< Cipher accepts IVs of variable length. */
00065 #define MBEDTLS_CIPHER_VARIABLE_KEY_LEN    0x02    /**< Cipher accepts keys of variable length. */
00066 
00067 #ifdef __cplusplus
00068 extern "C" {
00069 #endif
00070 
00071 /**
00072  * \brief     An enumeration of supported ciphers.
00073  *
00074  * \warning   ARC4 and DES are considered weak ciphers and their use
00075  *            constitutes a security risk. We recommend considering stronger
00076  *            ciphers instead.
00077  */
00078 typedef enum {
00079     MBEDTLS_CIPHER_ID_NONE = 0,
00080     MBEDTLS_CIPHER_ID_NULL,
00081     MBEDTLS_CIPHER_ID_AES,
00082     MBEDTLS_CIPHER_ID_DES,
00083     MBEDTLS_CIPHER_ID_3DES,
00084     MBEDTLS_CIPHER_ID_CAMELLIA,
00085     MBEDTLS_CIPHER_ID_BLOWFISH,
00086     MBEDTLS_CIPHER_ID_ARC4,
00087 } mbedtls_cipher_id_t;
00088 
00089 /**
00090  * \brief     An enumeration of supported (cipher, mode) pairs.
00091  *
00092  * \warning   ARC4 and DES are considered weak ciphers and their use
00093  *            constitutes a security risk. We recommend considering stronger
00094  *            ciphers instead.
00095  */
00096 typedef enum {
00097     MBEDTLS_CIPHER_NONE = 0,
00098     MBEDTLS_CIPHER_NULL,
00099     MBEDTLS_CIPHER_AES_128_ECB,
00100     MBEDTLS_CIPHER_AES_192_ECB,
00101     MBEDTLS_CIPHER_AES_256_ECB,
00102     MBEDTLS_CIPHER_AES_128_CBC,
00103     MBEDTLS_CIPHER_AES_192_CBC,
00104     MBEDTLS_CIPHER_AES_256_CBC,
00105     MBEDTLS_CIPHER_AES_128_CFB128,
00106     MBEDTLS_CIPHER_AES_192_CFB128,
00107     MBEDTLS_CIPHER_AES_256_CFB128,
00108     MBEDTLS_CIPHER_AES_128_CTR,
00109     MBEDTLS_CIPHER_AES_192_CTR,
00110     MBEDTLS_CIPHER_AES_256_CTR,
00111     MBEDTLS_CIPHER_AES_128_GCM,
00112     MBEDTLS_CIPHER_AES_192_GCM,
00113     MBEDTLS_CIPHER_AES_256_GCM,
00114     MBEDTLS_CIPHER_CAMELLIA_128_ECB,
00115     MBEDTLS_CIPHER_CAMELLIA_192_ECB,
00116     MBEDTLS_CIPHER_CAMELLIA_256_ECB,
00117     MBEDTLS_CIPHER_CAMELLIA_128_CBC,
00118     MBEDTLS_CIPHER_CAMELLIA_192_CBC,
00119     MBEDTLS_CIPHER_CAMELLIA_256_CBC,
00120     MBEDTLS_CIPHER_CAMELLIA_128_CFB128,
00121     MBEDTLS_CIPHER_CAMELLIA_192_CFB128,
00122     MBEDTLS_CIPHER_CAMELLIA_256_CFB128,
00123     MBEDTLS_CIPHER_CAMELLIA_128_CTR,
00124     MBEDTLS_CIPHER_CAMELLIA_192_CTR,
00125     MBEDTLS_CIPHER_CAMELLIA_256_CTR,
00126     MBEDTLS_CIPHER_CAMELLIA_128_GCM,
00127     MBEDTLS_CIPHER_CAMELLIA_192_GCM,
00128     MBEDTLS_CIPHER_CAMELLIA_256_GCM,
00129     MBEDTLS_CIPHER_DES_ECB,
00130     MBEDTLS_CIPHER_DES_CBC,
00131     MBEDTLS_CIPHER_DES_EDE_ECB,
00132     MBEDTLS_CIPHER_DES_EDE_CBC,
00133     MBEDTLS_CIPHER_DES_EDE3_ECB,
00134     MBEDTLS_CIPHER_DES_EDE3_CBC,
00135     MBEDTLS_CIPHER_BLOWFISH_ECB,
00136     MBEDTLS_CIPHER_BLOWFISH_CBC,
00137     MBEDTLS_CIPHER_BLOWFISH_CFB64,
00138     MBEDTLS_CIPHER_BLOWFISH_CTR,
00139     MBEDTLS_CIPHER_ARC4_128,
00140     MBEDTLS_CIPHER_AES_128_CCM,
00141     MBEDTLS_CIPHER_AES_192_CCM,
00142     MBEDTLS_CIPHER_AES_256_CCM,
00143     MBEDTLS_CIPHER_CAMELLIA_128_CCM,
00144     MBEDTLS_CIPHER_CAMELLIA_192_CCM,
00145     MBEDTLS_CIPHER_CAMELLIA_256_CCM,
00146 } mbedtls_cipher_type_t;
00147 
00148 /** Supported cipher modes. */
00149 typedef enum {
00150     MBEDTLS_MODE_NONE = 0,
00151     MBEDTLS_MODE_ECB,
00152     MBEDTLS_MODE_CBC,
00153     MBEDTLS_MODE_CFB,
00154     MBEDTLS_MODE_OFB, /* Unused! */
00155     MBEDTLS_MODE_CTR,
00156     MBEDTLS_MODE_GCM,
00157     MBEDTLS_MODE_STREAM,
00158     MBEDTLS_MODE_CCM,
00159 } mbedtls_cipher_mode_t;
00160 
00161 /** Supported cipher padding types. */
00162 typedef enum {
00163     MBEDTLS_PADDING_PKCS7 = 0,     /**< PKCS7 padding (default).        */
00164     MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding.         */
00165     MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding.             */
00166     MBEDTLS_PADDING_ZEROS,         /**< zero padding (not reversible). */
00167     MBEDTLS_PADDING_NONE,          /**< never pad (full blocks only).   */
00168 } mbedtls_cipher_padding_t;
00169 
00170 /** Type of operation. */
00171 typedef enum {
00172     MBEDTLS_OPERATION_NONE = -1,
00173     MBEDTLS_DECRYPT = 0,
00174     MBEDTLS_ENCRYPT,
00175 } mbedtls_operation_t;
00176 
00177 enum {
00178     /** Undefined key length. */
00179     MBEDTLS_KEY_LENGTH_NONE = 0,
00180     /** Key length, in bits (including parity), for DES keys. */
00181     MBEDTLS_KEY_LENGTH_DES  = 64,
00182     /** Key length in bits, including parity, for DES in two-key EDE. */
00183     MBEDTLS_KEY_LENGTH_DES_EDE = 128,
00184     /** Key length in bits, including parity, for DES in three-key EDE. */
00185     MBEDTLS_KEY_LENGTH_DES_EDE3 = 192,
00186 };
00187 
00188 /** Maximum length of any IV, in Bytes. */
00189 #define MBEDTLS_MAX_IV_LENGTH      16
00190 /** Maximum block size of any cipher, in Bytes. */
00191 #define MBEDTLS_MAX_BLOCK_LENGTH   16
00192 
00193 /**
00194  * Base cipher information (opaque struct).
00195  */
00196 typedef struct mbedtls_cipher_base_t mbedtls_cipher_base_t;
00197 
00198 /**
00199  * CMAC context (opaque struct).
00200  */
00201 typedef struct mbedtls_cmac_context_t mbedtls_cmac_context_t;
00202 
00203 /**
00204  * Cipher information. Allows calling cipher functions
00205  * in a generic way.
00206  */
00207 typedef struct {
00208     /** Full cipher identifier. For example,
00209      * MBEDTLS_CIPHER_AES_256_CBC.
00210      */
00211     mbedtls_cipher_type_t type;
00212 
00213     /** The cipher mode. For example, MBEDTLS_MODE_CBC. */
00214     mbedtls_cipher_mode_t mode;
00215 
00216     /** The cipher key length, in bits. This is the
00217      * default length for variable sized ciphers.
00218      * Includes parity bits for ciphers like DES.
00219      */
00220     unsigned int key_bitlen;
00221 
00222     /** Name of the cipher. */
00223     const char * name;
00224 
00225     /** IV or nonce size, in Bytes.
00226      * For ciphers that accept variable IV sizes,
00227      * this is the recommended size.
00228      */
00229     unsigned int iv_size;
00230 
00231     /** Flags to set. For example, if the cipher supports variable IV sizes or variable key sizes. */
00232     int flags;
00233 
00234     /** The block size, in Bytes. */
00235     unsigned int block_size;
00236 
00237     /** Struct for base cipher information and functions. */
00238     const mbedtls_cipher_base_t *base;
00239 
00240 } mbedtls_cipher_info_t;
00241 
00242 /**
00243  * Generic cipher context.
00244  */
00245 typedef struct {
00246     /** Information about the associated cipher. */
00247     const mbedtls_cipher_info_t *cipher_info;
00248 
00249     /** Key length to use. */
00250     int key_bitlen;
00251 
00252     /** Operation that the key of the context has been
00253      * initialized for.
00254      */
00255     mbedtls_operation_t operation;
00256 
00257 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
00258     /** Padding functions to use, if relevant for
00259      * the specific cipher mode.
00260      */
00261     void (*add_padding)( unsigned char *output, size_t olen, size_t data_len );
00262     int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len );
00263 #endif
00264 
00265     /** Buffer for input that has not been processed yet. */
00266     unsigned char unprocessed_data[MBEDTLS_MAX_BLOCK_LENGTH];
00267 
00268     /** Number of Bytes that have not been processed yet. */
00269     size_t unprocessed_len;
00270 
00271     /** Current IV or NONCE_COUNTER for CTR-mode. */
00272     unsigned char iv[MBEDTLS_MAX_IV_LENGTH];
00273 
00274     /** IV size in Bytes, for ciphers with variable-length IVs. */
00275     size_t iv_size;
00276 
00277     /** The cipher-specific context. */
00278     void *cipher_ctx;
00279 
00280 #if defined(MBEDTLS_CMAC_C)
00281     /** CMAC-specific context. */
00282     mbedtls_cmac_context_t *cmac_ctx;
00283 #endif
00284 } mbedtls_cipher_context_t;
00285 
00286 /**
00287  * \brief This function retrieves the list of ciphers supported by the generic
00288  * cipher module.
00289  *
00290  * \return      A statically-allocated array of ciphers. The last entry
00291  *              is zero.
00292  */
00293 const int *mbedtls_cipher_list( void );
00294 
00295 /**
00296  * \brief               This function retrieves the cipher-information
00297  *                      structure associated with the given cipher name.
00298  *
00299  * \param cipher_name   Name of the cipher to search for.
00300  *
00301  * \return              The cipher information structure associated with the
00302  *                      given \p cipher_name, or NULL if not found.
00303  */
00304 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name );
00305 
00306 /**
00307  * \brief               This function retrieves the cipher-information
00308  *                      structure associated with the given cipher type.
00309  *
00310  * \param cipher_type   Type of the cipher to search for.
00311  *
00312  * \return              The cipher information structure associated with the
00313  *                      given \p cipher_type, or NULL if not found.
00314  */
00315 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type( const mbedtls_cipher_type_t cipher_type );
00316 
00317 /**
00318  * \brief               This function retrieves the cipher-information
00319  *                      structure associated with the given cipher ID,
00320  *                      key size and mode.
00321  *
00322  * \param cipher_id     The ID of the cipher to search for. For example,
00323  *                      #MBEDTLS_CIPHER_ID_AES.
00324  * \param key_bitlen    The length of the key in bits.
00325  * \param mode          The cipher mode. For example, #MBEDTLS_MODE_CBC.
00326  *
00327  * \return              The cipher information structure associated with the
00328  *                      given \p cipher_id, or NULL if not found.
00329  */
00330 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_values( const mbedtls_cipher_id_t cipher_id,
00331                                               int key_bitlen,
00332                                               const mbedtls_cipher_mode_t mode );
00333 
00334 /**
00335  * \brief               This function initializes a \p cipher_context as NONE.
00336  */
00337 void mbedtls_cipher_init( mbedtls_cipher_context_t *ctx );
00338 
00339 /**
00340  * \brief               This function frees and clears the cipher-specific
00341  *                      context of \p ctx. Freeing \p ctx itself remains the
00342  *                      responsibility of the caller.
00343  */
00344 void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx );
00345 
00346 
00347 /**
00348  * \brief               This function initializes and fills the cipher-context
00349  *                      structure with the appropriate values. It also clears
00350  *                      the structure.
00351  *
00352  * \param ctx           The context to initialize. May not be NULL.
00353  * \param cipher_info   The cipher to use.
00354  *
00355  * \return              \c 0 on success,
00356  *                      #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure,
00357  *                      #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
00358  *                      cipher-specific context failed.
00359  *
00360  * \internal Currently, the function also clears the structure.
00361  * In future versions, the caller will be required to call
00362  * mbedtls_cipher_init() on the structure first.
00363  */
00364 int mbedtls_cipher_setup( mbedtls_cipher_context_t *ctx, const mbedtls_cipher_info_t *cipher_info );
00365 
00366 /**
00367  * \brief        This function returns the block size of the given cipher.
00368  *
00369  * \param ctx    The context of the cipher. Must be initialized.
00370  *
00371  * \return       The size of the blocks of the cipher, or zero if \p ctx
00372  *               has not been initialized.
00373  */
00374 static inline unsigned int mbedtls_cipher_get_block_size( const mbedtls_cipher_context_t *ctx )
00375 {
00376     if( NULL == ctx || NULL == ctx->cipher_info )
00377         return 0;
00378 
00379     return ctx->cipher_info->block_size;
00380 }
00381 
00382 /**
00383  * \brief        This function returns the mode of operation for
00384  *               the cipher. For example, MBEDTLS_MODE_CBC.
00385  *
00386  * \param ctx    The context of the cipher. Must be initialized.
00387  *
00388  * \return       The mode of operation, or #MBEDTLS_MODE_NONE if
00389  *               \p ctx has not been initialized.
00390  */
00391 static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtls_cipher_context_t *ctx )
00392 {
00393     if( NULL == ctx || NULL == ctx->cipher_info )
00394         return MBEDTLS_MODE_NONE;
00395 
00396     return ctx->cipher_info->mode;
00397 }
00398 
00399 /**
00400  * \brief       This function returns the size of the IV or nonce
00401  *              of the cipher, in Bytes.
00402  *
00403  * \param ctx   The context of the cipher. Must be initialized.
00404  *
00405  * \return      <ul><li>If no IV has been set: the recommended IV size.
00406  *              0 for ciphers not using IV or nonce.</li>
00407  *              <li>If IV has already been set: the actual size.</li></ul>
00408  */
00409 static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ctx )
00410 {
00411     if( NULL == ctx || NULL == ctx->cipher_info )
00412         return 0;
00413 
00414     if( ctx->iv_size != 0 )
00415         return (int) ctx->iv_size;
00416 
00417     return (int) ctx->cipher_info->iv_size;
00418 }
00419 
00420 /**
00421  * \brief               This function returns the type of the given cipher.
00422  *
00423  * \param ctx           The context of the cipher. Must be initialized.
00424  *
00425  * \return              The type of the cipher, or #MBEDTLS_CIPHER_NONE if
00426  *                      \p ctx has not been initialized.
00427  */
00428 static inline mbedtls_cipher_type_t mbedtls_cipher_get_type( const mbedtls_cipher_context_t *ctx )
00429 {
00430     if( NULL == ctx || NULL == ctx->cipher_info )
00431         return MBEDTLS_CIPHER_NONE;
00432 
00433     return ctx->cipher_info->type;
00434 }
00435 
00436 /**
00437  * \brief               This function returns the name of the given cipher
00438  *                      as a string.
00439  *
00440  * \param ctx           The context of the cipher. Must be initialized.
00441  *
00442  * \return              The name of the cipher, or NULL if \p ctx has not
00443  *                      been not initialized.
00444  */
00445 static inline const char *mbedtls_cipher_get_name( const mbedtls_cipher_context_t *ctx )
00446 {
00447     if( NULL == ctx || NULL == ctx->cipher_info )
00448         return 0;
00449 
00450     return ctx->cipher_info->name;
00451 }
00452 
00453 /**
00454  * \brief               This function returns the key length of the cipher.
00455  *
00456  * \param ctx           The context of the cipher. Must be initialized.
00457  *
00458  * \return              The key length of the cipher in bits, or
00459  *                      #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been
00460  *                      initialized.
00461  */
00462 static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t *ctx )
00463 {
00464     if( NULL == ctx || NULL == ctx->cipher_info )
00465         return MBEDTLS_KEY_LENGTH_NONE;
00466 
00467     return (int) ctx->cipher_info->key_bitlen;
00468 }
00469 
00470 /**
00471  * \brief          This function returns the operation of the given cipher.
00472  *
00473  * \param ctx      The context of the cipher. Must be initialized.
00474  *
00475  * \return         The type of operation: #MBEDTLS_ENCRYPT or
00476  *                 #MBEDTLS_DECRYPT, or #MBEDTLS_OPERATION_NONE if \p ctx
00477  *                 has not been initialized.
00478  */
00479 static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_cipher_context_t *ctx )
00480 {
00481     if( NULL == ctx || NULL == ctx->cipher_info )
00482         return MBEDTLS_OPERATION_NONE;
00483 
00484     return ctx->operation;
00485 }
00486 
00487 /**
00488  * \brief               This function sets the key to use with the given context.
00489  *
00490  * \param ctx           The generic cipher context. May not be NULL. Must have
00491  *                      been initialized using mbedtls_cipher_info_from_type()
00492  *                      or mbedtls_cipher_info_from_string().
00493  * \param key           The key to use.
00494  * \param key_bitlen    The key length to use, in bits.
00495  * \param operation     The operation that the key will be used for:
00496  *                      #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
00497  *
00498  * \returns             \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
00499  *                      parameter verification fails, or a cipher-specific
00500  *                      error code.
00501  */
00502 int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *key,
00503                    int key_bitlen, const mbedtls_operation_t operation );
00504 
00505 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
00506 /**
00507  * \brief               This function sets the padding mode, for cipher modes
00508  *                      that use padding.
00509  *
00510  *                      The default passing mode is PKCS7 padding.
00511  *
00512  * \param ctx           The generic cipher context.
00513  * \param mode          The padding mode.
00514  *
00515  * \returns             \c 0 on success, #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
00516  *                      if the selected padding mode is not supported, or
00517  *                      #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
00518  *                      does not support padding.
00519  */
00520 int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_cipher_padding_t mode );
00521 #endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */
00522 
00523 /**
00524  * \brief           This function sets the initialization vector (IV)
00525  *                  or nonce.
00526  *
00527  * \param ctx       The generic cipher context.
00528  * \param iv        The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
00529  * \param iv_len    The IV length for ciphers with variable-size IV.
00530  *                  This parameter is discarded by ciphers with fixed-size IV.
00531  *
00532  * \returns         \c 0 on success, or #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
00533  *
00534  * \note            Some ciphers do not use IVs nor nonce. For these
00535  *                  ciphers, this function has no effect.
00536  */
00537 int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx,
00538                    const unsigned char *iv, size_t iv_len );
00539 
00540 /**
00541  * \brief         This function resets the cipher state.
00542  *
00543  * \param ctx     The generic cipher context.
00544  *
00545  * \returns       \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
00546  *                if parameter verification fails.
00547  */
00548 int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx );
00549 
00550 #if defined(MBEDTLS_GCM_C)
00551 /**
00552  * \brief               This function adds additional data for AEAD ciphers.
00553  *                      Only supported with GCM. Must be called
00554  *                      exactly once, after mbedtls_cipher_reset().
00555  *
00556  * \param ctx           The generic cipher context.
00557  * \param ad            The additional data to use.
00558  * \param ad_len        the Length of \p ad.
00559  *
00560  * \return              \c 0 on success, or a specific error code on failure.
00561  */
00562 int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx,
00563                       const unsigned char *ad, size_t ad_len );
00564 #endif /* MBEDTLS_GCM_C */
00565 
00566 /**
00567  * \brief               The generic cipher update function. It encrypts or
00568  *                      decrypts using the given cipher context. Writes as
00569  *                      many block-sized blocks of data as possible to output.
00570  *                      Any data that cannot be written immediately is either
00571  *                      added to the next block, or flushed when
00572  *                      mbedtls_cipher_finish() is called.
00573  *                      Exception: For MBEDTLS_MODE_ECB, expects a single block
00574  *                      in size. For example, 16 Bytes for AES.
00575  *
00576  * \param ctx           The generic cipher context.
00577  * \param input         The buffer holding the input data.
00578  * \param ilen          The length of the input data.
00579  * \param output        The buffer for the output data. Must be able to hold at
00580  *                      least \p ilen + block_size. Must not be the same buffer
00581  *                      as input.
00582  * \param olen          The length of the output data, to be updated with the
00583  *                      actual number of Bytes written.
00584  *
00585  * \returns             \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
00586  *                      parameter verification fails,
00587  *                      #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an
00588  *                      unsupported mode for a cipher, or a cipher-specific
00589  *                      error code.
00590  *
00591  * \note                If the underlying cipher is GCM, all calls to this
00592  *                      function, except the last one before
00593  *                      mbedtls_cipher_finish(). Must have \p ilen as a
00594  *                      multiple of the block_size.
00595  */
00596 int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input,
00597                    size_t ilen, unsigned char *output, size_t *olen );
00598 
00599 /**
00600  * \brief               The generic cipher finalization function. If data still
00601  *                      needs to be flushed from an incomplete block, the data
00602  *                      contained in it is padded to the size of
00603  *                      the last block, and written to the \p output buffer.
00604  *
00605  * \param ctx           The generic cipher context.
00606  * \param output        The buffer to write data to. Needs block_size available.
00607  * \param olen          The length of the data written to the \p output buffer.
00608  *
00609  * \returns             \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
00610  *                      parameter verification fails,
00611  *                      #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
00612  *                      expected a full block but was not provided one,
00613  *                      #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
00614  *                      while decrypting, or a cipher-specific error code
00615  *                      on failure for any other reason.
00616  */
00617 int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx,
00618                    unsigned char *output, size_t *olen );
00619 
00620 #if defined(MBEDTLS_GCM_C)
00621 /**
00622  * \brief               This function writes a tag for AEAD ciphers.
00623  *                      Only supported with GCM.
00624  *                      Must be called after mbedtls_cipher_finish().
00625  *
00626  * \param ctx           The generic cipher context.
00627  * \param tag           The buffer to write the tag to.
00628  * \param tag_len       The length of the tag to write.
00629  *
00630  * \return              \c 0 on success, or a specific error code on failure.
00631  */
00632 int mbedtls_cipher_write_tag( mbedtls_cipher_context_t *ctx,
00633                       unsigned char *tag, size_t tag_len );
00634 
00635 /**
00636  * \brief               This function checks the tag for AEAD ciphers.
00637  *                      Only supported with GCM.
00638  *                      Must be called after mbedtls_cipher_finish().
00639  *
00640  * \param ctx           The generic cipher context.
00641  * \param tag           The buffer holding the tag.
00642  * \param tag_len       The length of the tag to check.
00643  *
00644  * \return              \c 0 on success, or a specific error code on failure.
00645  */
00646 int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx,
00647                       const unsigned char *tag, size_t tag_len );
00648 #endif /* MBEDTLS_GCM_C */
00649 
00650 /**
00651  * \brief               The generic all-in-one encryption/decryption function,
00652  *                      for all ciphers except AEAD constructs.
00653  *
00654  * \param ctx           The generic cipher context.
00655  * \param iv            The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
00656  * \param iv_len        The IV length for ciphers with variable-size IV.
00657  *                      This parameter is discarded by ciphers with fixed-size
00658  *                      IV.
00659  * \param input         The buffer holding the input data.
00660  * \param ilen          The length of the input data.
00661  * \param output        The buffer for the output data. Must be able to hold at
00662  *                      least \p ilen + block_size. Must not be the same buffer
00663  *                      as input.
00664  * \param olen          The length of the output data, to be updated with the
00665  *                      actual number of Bytes written.
00666  *
00667  * \note                Some ciphers do not use IVs nor nonce. For these
00668  *                      ciphers, use \p iv = NULL and \p iv_len = 0.
00669  *
00670  * \returns             \c 0 on success, or
00671  *                      #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
00672  *                      #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
00673  *                      expected a full block but was not provided one, or
00674  *                      #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
00675  *                      while decrypting, or a cipher-specific error code on
00676  *                      failure for any other reason.
00677  */
00678 int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx,
00679                   const unsigned char *iv, size_t iv_len,
00680                   const unsigned char *input, size_t ilen,
00681                   unsigned char *output, size_t *olen );
00682 
00683 #if defined(MBEDTLS_CIPHER_MODE_AEAD)
00684 /**
00685  * \brief               The generic autenticated encryption (AEAD) function.
00686  *
00687  * \param ctx           The generic cipher context.
00688  * \param iv            The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
00689  * \param iv_len        The IV length for ciphers with variable-size IV.
00690  *                      This parameter is discarded by ciphers with fixed-size IV.
00691  * \param ad            The additional data to authenticate.
00692  * \param ad_len        The length of \p ad.
00693  * \param input         The buffer holding the input data.
00694  * \param ilen          The length of the input data.
00695  * \param output        The buffer for the output data.
00696  *                      Must be able to hold at least \p ilen.
00697  * \param olen          The length of the output data, to be updated with the
00698  *                      actual number of Bytes written.
00699  * \param tag           The buffer for the authentication tag.
00700  * \param tag_len       The desired length of the authentication tag.
00701  *
00702  * \returns             \c 0 on success, or
00703  *                      #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
00704  *                      a cipher-specific error code.
00705  */
00706 int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx,
00707                          const unsigned char *iv, size_t iv_len,
00708                          const unsigned char *ad, size_t ad_len,
00709                          const unsigned char *input, size_t ilen,
00710                          unsigned char *output, size_t *olen,
00711                          unsigned char *tag, size_t tag_len );
00712 
00713 /**
00714  * \brief               The generic autenticated decryption (AEAD) function.
00715  *
00716  * \param ctx           The generic cipher context.
00717  * \param iv            The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
00718  * \param iv_len        The IV length for ciphers with variable-size IV.
00719  *                      This parameter is discarded by ciphers with fixed-size IV.
00720  * \param ad            The additional data to be authenticated.
00721  * \param ad_len        The length of \p ad.
00722  * \param input         The buffer holding the input data.
00723  * \param ilen          The length of the input data.
00724  * \param output        The buffer for the output data.
00725  *                      Must be able to hold at least \p ilen.
00726  * \param olen          The length of the output data, to be updated with the
00727  *                      actual number of Bytes written.
00728  * \param tag           The buffer holding the authentication tag.
00729  * \param tag_len       The length of the authentication tag.
00730  *
00731  * \returns             \c 0 on success, or
00732  *                      #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
00733  *                      #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic,
00734  *                      or a cipher-specific error code on failure for any other reason.
00735  *
00736  * \note                If the data is not authentic, then the output buffer
00737  *                      is zeroed out to prevent the unauthentic plaintext being
00738  *                      used, making this interface safer.
00739  */
00740 int mbedtls_cipher_auth_decrypt( mbedtls_cipher_context_t *ctx,
00741                          const unsigned char *iv, size_t iv_len,
00742                          const unsigned char *ad, size_t ad_len,
00743                          const unsigned char *input, size_t ilen,
00744                          unsigned char *output, size_t *olen,
00745                          const unsigned char *tag, size_t tag_len );
00746 #endif /* MBEDTLS_CIPHER_MODE_AEAD */
00747 
00748 #ifdef __cplusplus
00749 }
00750 #endif
00751 
00752 #endif /* MBEDTLS_CIPHER_H */