Doug Anson / mbedTLSLibrary

mbed TLS library

Dependents:   HTTPClient-SSL WS_SERVER

include/polarssl/cipher.h@0:137634ff4186, 2015-06-11 (annotated)

Committer:
ansond
Date:
Thu Jun 11 03:27:03 2015 +0000
Revision:
0:137634ff4186
initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ansond 0:137634ff4186 1 /**
ansond 0:137634ff4186 2 * \file cipher.h
ansond 0:137634ff4186 3 *
ansond 0:137634ff4186 4 * \brief Generic cipher wrapper.
ansond 0:137634ff4186 5 *
ansond 0:137634ff4186 6 * \author Adriaan de Jong <dejong@fox-it.com>
ansond 0:137634ff4186 7 *
ansond 0:137634ff4186 8 * Copyright (C) 2006-2014, ARM Limited, All Rights Reserved
ansond 0:137634ff4186 9 *
ansond 0:137634ff4186 10 * This file is part of mbed TLS (https://tls.mbed.org)
ansond 0:137634ff4186 11 *
ansond 0:137634ff4186 12 * This program is free software; you can redistribute it and/or modify
ansond 0:137634ff4186 13 * it under the terms of the GNU General Public License as published by
ansond 0:137634ff4186 14 * the Free Software Foundation; either version 2 of the License, or
ansond 0:137634ff4186 15 * (at your option) any later version.
ansond 0:137634ff4186 16 *
ansond 0:137634ff4186 17 * This program is distributed in the hope that it will be useful,
ansond 0:137634ff4186 18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
ansond 0:137634ff4186 19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
ansond 0:137634ff4186 20 * GNU General Public License for more details.
ansond 0:137634ff4186 21 *
ansond 0:137634ff4186 22 * You should have received a copy of the GNU General Public License along
ansond 0:137634ff4186 23 * with this program; if not, write to the Free Software Foundation, Inc.,
ansond 0:137634ff4186 24 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
ansond 0:137634ff4186 25 */
ansond 0:137634ff4186 26
ansond 0:137634ff4186 27 #ifndef POLARSSL_CIPHER_H
ansond 0:137634ff4186 28 #define POLARSSL_CIPHER_H
ansond 0:137634ff4186 29
ansond 0:137634ff4186 30 #if !defined(POLARSSL_CONFIG_FILE)
ansond 0:137634ff4186 31 #include "config.h"
ansond 0:137634ff4186 32 #else
ansond 0:137634ff4186 33 #include POLARSSL_CONFIG_FILE
ansond 0:137634ff4186 34 #endif
ansond 0:137634ff4186 35
ansond 0:137634ff4186 36 #include <stddef.h>
ansond 0:137634ff4186 37
ansond 0:137634ff4186 38 #if defined(POLARSSL_GCM_C) || defined(POLARSSL_CCM_C)
ansond 0:137634ff4186 39 #define POLARSSL_CIPHER_MODE_AEAD
ansond 0:137634ff4186 40 #endif
ansond 0:137634ff4186 41
ansond 0:137634ff4186 42 #if defined(POLARSSL_CIPHER_MODE_CBC)
ansond 0:137634ff4186 43 #define POLARSSL_CIPHER_MODE_WITH_PADDING
ansond 0:137634ff4186 44 #endif
ansond 0:137634ff4186 45
ansond 0:137634ff4186 46 #if defined(POLARSSL_ARC4_C)
ansond 0:137634ff4186 47 #define POLARSSL_CIPHER_MODE_STREAM
ansond 0:137634ff4186 48 #endif
ansond 0:137634ff4186 49
ansond 0:137634ff4186 50 #if defined(_MSC_VER) && !defined(inline)
ansond 0:137634ff4186 51 #define inline _inline
ansond 0:137634ff4186 52 #else
ansond 0:137634ff4186 53 #if defined(__ARMCC_VERSION) && !defined(inline)
ansond 0:137634ff4186 54 #define inline __inline
ansond 0:137634ff4186 55 #endif /* __ARMCC_VERSION */
ansond 0:137634ff4186 56 #endif /*_MSC_VER */
ansond 0:137634ff4186 57
ansond 0:137634ff4186 58 #define POLARSSL_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080 /**< The selected feature is not available. */
ansond 0:137634ff4186 59 #define POLARSSL_ERR_CIPHER_BAD_INPUT_DATA -0x6100 /**< Bad input parameters to function. */
ansond 0:137634ff4186 60 #define POLARSSL_ERR_CIPHER_ALLOC_FAILED -0x6180 /**< Failed to allocate memory. */
ansond 0:137634ff4186 61 #define POLARSSL_ERR_CIPHER_INVALID_PADDING -0x6200 /**< Input data contains invalid padding and is rejected. */
ansond 0:137634ff4186 62 #define POLARSSL_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280 /**< Decryption of block requires a full block. */
ansond 0:137634ff4186 63 #define POLARSSL_ERR_CIPHER_AUTH_FAILED -0x6300 /**< Authentication failed (for AEAD modes). */
ansond 0:137634ff4186 64
ansond 0:137634ff4186 65 #define POLARSSL_CIPHER_VARIABLE_IV_LEN 0x01 /**< Cipher accepts IVs of variable length */
ansond 0:137634ff4186 66 #define POLARSSL_CIPHER_VARIABLE_KEY_LEN 0x02 /**< Cipher accepts keys of variable length */
ansond 0:137634ff4186 67
ansond 0:137634ff4186 68 #ifdef __cplusplus
ansond 0:137634ff4186 69 extern "C" {
ansond 0:137634ff4186 70 #endif
ansond 0:137634ff4186 71
ansond 0:137634ff4186 72 typedef enum {
ansond 0:137634ff4186 73 POLARSSL_CIPHER_ID_NONE = 0,
ansond 0:137634ff4186 74 POLARSSL_CIPHER_ID_NULL,
ansond 0:137634ff4186 75 POLARSSL_CIPHER_ID_AES,
ansond 0:137634ff4186 76 POLARSSL_CIPHER_ID_DES,
ansond 0:137634ff4186 77 POLARSSL_CIPHER_ID_3DES, /* Unused! */
ansond 0:137634ff4186 78 POLARSSL_CIPHER_ID_CAMELLIA,
ansond 0:137634ff4186 79 POLARSSL_CIPHER_ID_BLOWFISH,
ansond 0:137634ff4186 80 POLARSSL_CIPHER_ID_ARC4,
ansond 0:137634ff4186 81 } cipher_id_t;
ansond 0:137634ff4186 82
ansond 0:137634ff4186 83 typedef enum {
ansond 0:137634ff4186 84 POLARSSL_CIPHER_NONE = 0,
ansond 0:137634ff4186 85 POLARSSL_CIPHER_NULL,
ansond 0:137634ff4186 86 POLARSSL_CIPHER_AES_128_ECB,
ansond 0:137634ff4186 87 POLARSSL_CIPHER_AES_192_ECB,
ansond 0:137634ff4186 88 POLARSSL_CIPHER_AES_256_ECB,
ansond 0:137634ff4186 89 POLARSSL_CIPHER_AES_128_CBC,
ansond 0:137634ff4186 90 POLARSSL_CIPHER_AES_192_CBC,
ansond 0:137634ff4186 91 POLARSSL_CIPHER_AES_256_CBC,
ansond 0:137634ff4186 92 POLARSSL_CIPHER_AES_128_CFB128,
ansond 0:137634ff4186 93 POLARSSL_CIPHER_AES_192_CFB128,
ansond 0:137634ff4186 94 POLARSSL_CIPHER_AES_256_CFB128,
ansond 0:137634ff4186 95 POLARSSL_CIPHER_AES_128_CTR,
ansond 0:137634ff4186 96 POLARSSL_CIPHER_AES_192_CTR,
ansond 0:137634ff4186 97 POLARSSL_CIPHER_AES_256_CTR,
ansond 0:137634ff4186 98 POLARSSL_CIPHER_AES_128_GCM,
ansond 0:137634ff4186 99 POLARSSL_CIPHER_AES_192_GCM,
ansond 0:137634ff4186 100 POLARSSL_CIPHER_AES_256_GCM,
ansond 0:137634ff4186 101 POLARSSL_CIPHER_CAMELLIA_128_ECB,
ansond 0:137634ff4186 102 POLARSSL_CIPHER_CAMELLIA_192_ECB,
ansond 0:137634ff4186 103 POLARSSL_CIPHER_CAMELLIA_256_ECB,
ansond 0:137634ff4186 104 POLARSSL_CIPHER_CAMELLIA_128_CBC,
ansond 0:137634ff4186 105 POLARSSL_CIPHER_CAMELLIA_192_CBC,
ansond 0:137634ff4186 106 POLARSSL_CIPHER_CAMELLIA_256_CBC,
ansond 0:137634ff4186 107 POLARSSL_CIPHER_CAMELLIA_128_CFB128,
ansond 0:137634ff4186 108 POLARSSL_CIPHER_CAMELLIA_192_CFB128,
ansond 0:137634ff4186 109 POLARSSL_CIPHER_CAMELLIA_256_CFB128,
ansond 0:137634ff4186 110 POLARSSL_CIPHER_CAMELLIA_128_CTR,
ansond 0:137634ff4186 111 POLARSSL_CIPHER_CAMELLIA_192_CTR,
ansond 0:137634ff4186 112 POLARSSL_CIPHER_CAMELLIA_256_CTR,
ansond 0:137634ff4186 113 POLARSSL_CIPHER_CAMELLIA_128_GCM,
ansond 0:137634ff4186 114 POLARSSL_CIPHER_CAMELLIA_192_GCM,
ansond 0:137634ff4186 115 POLARSSL_CIPHER_CAMELLIA_256_GCM,
ansond 0:137634ff4186 116 POLARSSL_CIPHER_DES_ECB,
ansond 0:137634ff4186 117 POLARSSL_CIPHER_DES_CBC,
ansond 0:137634ff4186 118 POLARSSL_CIPHER_DES_EDE_ECB,
ansond 0:137634ff4186 119 POLARSSL_CIPHER_DES_EDE_CBC,
ansond 0:137634ff4186 120 POLARSSL_CIPHER_DES_EDE3_ECB,
ansond 0:137634ff4186 121 POLARSSL_CIPHER_DES_EDE3_CBC,
ansond 0:137634ff4186 122 POLARSSL_CIPHER_BLOWFISH_ECB,
ansond 0:137634ff4186 123 POLARSSL_CIPHER_BLOWFISH_CBC,
ansond 0:137634ff4186 124 POLARSSL_CIPHER_BLOWFISH_CFB64,
ansond 0:137634ff4186 125 POLARSSL_CIPHER_BLOWFISH_CTR,
ansond 0:137634ff4186 126 POLARSSL_CIPHER_ARC4_128,
ansond 0:137634ff4186 127 POLARSSL_CIPHER_AES_128_CCM,
ansond 0:137634ff4186 128 POLARSSL_CIPHER_AES_192_CCM,
ansond 0:137634ff4186 129 POLARSSL_CIPHER_AES_256_CCM,
ansond 0:137634ff4186 130 POLARSSL_CIPHER_CAMELLIA_128_CCM,
ansond 0:137634ff4186 131 POLARSSL_CIPHER_CAMELLIA_192_CCM,
ansond 0:137634ff4186 132 POLARSSL_CIPHER_CAMELLIA_256_CCM,
ansond 0:137634ff4186 133 } cipher_type_t;
ansond 0:137634ff4186 134
ansond 0:137634ff4186 135 typedef enum {
ansond 0:137634ff4186 136 POLARSSL_MODE_NONE = 0,
ansond 0:137634ff4186 137 POLARSSL_MODE_ECB,
ansond 0:137634ff4186 138 POLARSSL_MODE_CBC,
ansond 0:137634ff4186 139 POLARSSL_MODE_CFB,
ansond 0:137634ff4186 140 POLARSSL_MODE_OFB, /* Unused! */
ansond 0:137634ff4186 141 POLARSSL_MODE_CTR,
ansond 0:137634ff4186 142 POLARSSL_MODE_GCM,
ansond 0:137634ff4186 143 POLARSSL_MODE_STREAM,
ansond 0:137634ff4186 144 POLARSSL_MODE_CCM,
ansond 0:137634ff4186 145 } cipher_mode_t;
ansond 0:137634ff4186 146
ansond 0:137634ff4186 147 typedef enum {
ansond 0:137634ff4186 148 POLARSSL_PADDING_PKCS7 = 0, /**< PKCS7 padding (default) */
ansond 0:137634ff4186 149 POLARSSL_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding */
ansond 0:137634ff4186 150 POLARSSL_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding */
ansond 0:137634ff4186 151 POLARSSL_PADDING_ZEROS, /**< zero padding (not reversible!) */
ansond 0:137634ff4186 152 POLARSSL_PADDING_NONE, /**< never pad (full blocks only) */
ansond 0:137634ff4186 153 } cipher_padding_t;
ansond 0:137634ff4186 154
ansond 0:137634ff4186 155 typedef enum {
ansond 0:137634ff4186 156 POLARSSL_OPERATION_NONE = -1,
ansond 0:137634ff4186 157 POLARSSL_DECRYPT = 0,
ansond 0:137634ff4186 158 POLARSSL_ENCRYPT,
ansond 0:137634ff4186 159 } operation_t;
ansond 0:137634ff4186 160
ansond 0:137634ff4186 161 enum {
ansond 0:137634ff4186 162 /** Undefined key length */
ansond 0:137634ff4186 163 POLARSSL_KEY_LENGTH_NONE = 0,
ansond 0:137634ff4186 164 /** Key length, in bits (including parity), for DES keys */
ansond 0:137634ff4186 165 POLARSSL_KEY_LENGTH_DES = 64,
ansond 0:137634ff4186 166 /** Key length, in bits (including parity), for DES in two key EDE */
ansond 0:137634ff4186 167 POLARSSL_KEY_LENGTH_DES_EDE = 128,
ansond 0:137634ff4186 168 /** Key length, in bits (including parity), for DES in three-key EDE */
ansond 0:137634ff4186 169 POLARSSL_KEY_LENGTH_DES_EDE3 = 192,
ansond 0:137634ff4186 170 };
ansond 0:137634ff4186 171
ansond 0:137634ff4186 172 /** Maximum length of any IV, in bytes */
ansond 0:137634ff4186 173 #define POLARSSL_MAX_IV_LENGTH 16
ansond 0:137634ff4186 174 /** Maximum block size of any cipher, in bytes */
ansond 0:137634ff4186 175 #define POLARSSL_MAX_BLOCK_LENGTH 16
ansond 0:137634ff4186 176
ansond 0:137634ff4186 177 /**
ansond 0:137634ff4186 178 * Base cipher information. The non-mode specific functions and values.
ansond 0:137634ff4186 179 */
ansond 0:137634ff4186 180 typedef struct {
ansond 0:137634ff4186 181
ansond 0:137634ff4186 182 /** Base Cipher type (e.g. POLARSSL_CIPHER_ID_AES) */
ansond 0:137634ff4186 183 cipher_id_t cipher;
ansond 0:137634ff4186 184
ansond 0:137634ff4186 185 /** Encrypt using ECB */
ansond 0:137634ff4186 186 int (*ecb_func)( void *ctx, operation_t mode,
ansond 0:137634ff4186 187 const unsigned char *input, unsigned char *output );
ansond 0:137634ff4186 188
ansond 0:137634ff4186 189 #if defined(POLARSSL_CIPHER_MODE_CBC)
ansond 0:137634ff4186 190 /** Encrypt using CBC */
ansond 0:137634ff4186 191 int (*cbc_func)( void *ctx, operation_t mode, size_t length,
ansond 0:137634ff4186 192 unsigned char *iv, const unsigned char *input,
ansond 0:137634ff4186 193 unsigned char *output );
ansond 0:137634ff4186 194 #endif
ansond 0:137634ff4186 195
ansond 0:137634ff4186 196 #if defined(POLARSSL_CIPHER_MODE_CFB)
ansond 0:137634ff4186 197 /** Encrypt using CFB (Full length) */
ansond 0:137634ff4186 198 int (*cfb_func)( void *ctx, operation_t mode, size_t length, size_t *iv_off,
ansond 0:137634ff4186 199 unsigned char *iv, const unsigned char *input,
ansond 0:137634ff4186 200 unsigned char *output );
ansond 0:137634ff4186 201 #endif
ansond 0:137634ff4186 202
ansond 0:137634ff4186 203 #if defined(POLARSSL_CIPHER_MODE_CTR)
ansond 0:137634ff4186 204 /** Encrypt using CTR */
ansond 0:137634ff4186 205 int (*ctr_func)( void *ctx, size_t length, size_t *nc_off,
ansond 0:137634ff4186 206 unsigned char *nonce_counter, unsigned char *stream_block,
ansond 0:137634ff4186 207 const unsigned char *input, unsigned char *output );
ansond 0:137634ff4186 208 #endif
ansond 0:137634ff4186 209
ansond 0:137634ff4186 210 #if defined(POLARSSL_CIPHER_MODE_STREAM)
ansond 0:137634ff4186 211 /** Encrypt using STREAM */
ansond 0:137634ff4186 212 int (*stream_func)( void *ctx, size_t length,
ansond 0:137634ff4186 213 const unsigned char *input, unsigned char *output );
ansond 0:137634ff4186 214 #endif
ansond 0:137634ff4186 215
ansond 0:137634ff4186 216 /** Set key for encryption purposes */
ansond 0:137634ff4186 217 int (*setkey_enc_func)( void *ctx, const unsigned char *key,
ansond 0:137634ff4186 218 unsigned int key_length );
ansond 0:137634ff4186 219
ansond 0:137634ff4186 220 /** Set key for decryption purposes */
ansond 0:137634ff4186 221 int (*setkey_dec_func)( void *ctx, const unsigned char *key,
ansond 0:137634ff4186 222 unsigned int key_length);
ansond 0:137634ff4186 223
ansond 0:137634ff4186 224 /** Allocate a new context */
ansond 0:137634ff4186 225 void * (*ctx_alloc_func)( void );
ansond 0:137634ff4186 226
ansond 0:137634ff4186 227 /** Free the given context */
ansond 0:137634ff4186 228 void (*ctx_free_func)( void *ctx );
ansond 0:137634ff4186 229
ansond 0:137634ff4186 230 } cipher_base_t;
ansond 0:137634ff4186 231
ansond 0:137634ff4186 232 /**
ansond 0:137634ff4186 233 * Cipher information. Allows cipher functions to be called in a generic way.
ansond 0:137634ff4186 234 */
ansond 0:137634ff4186 235 typedef struct {
ansond 0:137634ff4186 236 /** Full cipher identifier (e.g. POLARSSL_CIPHER_AES_256_CBC) */
ansond 0:137634ff4186 237 cipher_type_t type;
ansond 0:137634ff4186 238
ansond 0:137634ff4186 239 /** Cipher mode (e.g. POLARSSL_MODE_CBC) */
ansond 0:137634ff4186 240 cipher_mode_t mode;
ansond 0:137634ff4186 241
ansond 0:137634ff4186 242 /** Cipher key length, in bits (default length for variable sized ciphers)
ansond 0:137634ff4186 243 * (Includes parity bits for ciphers like DES) */
ansond 0:137634ff4186 244 unsigned int key_length;
ansond 0:137634ff4186 245
ansond 0:137634ff4186 246 /** Name of the cipher */
ansond 0:137634ff4186 247 const char * name;
ansond 0:137634ff4186 248
ansond 0:137634ff4186 249 /** IV/NONCE size, in bytes.
ansond 0:137634ff4186 250 * For cipher that accept many sizes: recommended size */
ansond 0:137634ff4186 251 unsigned int iv_size;
ansond 0:137634ff4186 252
ansond 0:137634ff4186 253 /** Flags for variable IV size, variable key size, etc. */
ansond 0:137634ff4186 254 int flags;
ansond 0:137634ff4186 255
ansond 0:137634ff4186 256 /** block size, in bytes */
ansond 0:137634ff4186 257 unsigned int block_size;
ansond 0:137634ff4186 258
ansond 0:137634ff4186 259 /** Base cipher information and functions */
ansond 0:137634ff4186 260 const cipher_base_t *base;
ansond 0:137634ff4186 261
ansond 0:137634ff4186 262 } cipher_info_t;
ansond 0:137634ff4186 263
ansond 0:137634ff4186 264 /**
ansond 0:137634ff4186 265 * Generic cipher context.
ansond 0:137634ff4186 266 */
ansond 0:137634ff4186 267 typedef struct {
ansond 0:137634ff4186 268 /** Information about the associated cipher */
ansond 0:137634ff4186 269 const cipher_info_t *cipher_info;
ansond 0:137634ff4186 270
ansond 0:137634ff4186 271 /** Key length to use */
ansond 0:137634ff4186 272 int key_length;
ansond 0:137634ff4186 273
ansond 0:137634ff4186 274 /** Operation that the context's key has been initialised for */
ansond 0:137634ff4186 275 operation_t operation;
ansond 0:137634ff4186 276
ansond 0:137634ff4186 277 #if defined(POLARSSL_CIPHER_MODE_WITH_PADDING)
ansond 0:137634ff4186 278 /** Padding functions to use, if relevant for cipher mode */
ansond 0:137634ff4186 279 void (*add_padding)( unsigned char *output, size_t olen, size_t data_len );
ansond 0:137634ff4186 280 int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len );
ansond 0:137634ff4186 281 #endif
ansond 0:137634ff4186 282
ansond 0:137634ff4186 283 /** Buffer for data that hasn't been encrypted yet */
ansond 0:137634ff4186 284 unsigned char unprocessed_data[POLARSSL_MAX_BLOCK_LENGTH];
ansond 0:137634ff4186 285
ansond 0:137634ff4186 286 /** Number of bytes that still need processing */
ansond 0:137634ff4186 287 size_t unprocessed_len;
ansond 0:137634ff4186 288
ansond 0:137634ff4186 289 /** Current IV or NONCE_COUNTER for CTR-mode */
ansond 0:137634ff4186 290 unsigned char iv[POLARSSL_MAX_IV_LENGTH];
ansond 0:137634ff4186 291
ansond 0:137634ff4186 292 /** IV size in bytes (for ciphers with variable-length IVs) */
ansond 0:137634ff4186 293 size_t iv_size;
ansond 0:137634ff4186 294
ansond 0:137634ff4186 295 /** Cipher-specific context */
ansond 0:137634ff4186 296 void *cipher_ctx;
ansond 0:137634ff4186 297 } cipher_context_t;
ansond 0:137634ff4186 298
ansond 0:137634ff4186 299 /**
ansond 0:137634ff4186 300 * \brief Returns the list of ciphers supported by the generic cipher module.
ansond 0:137634ff4186 301 *
ansond 0:137634ff4186 302 * \return a statically allocated array of ciphers, the last entry
ansond 0:137634ff4186 303 * is 0.
ansond 0:137634ff4186 304 */
ansond 0:137634ff4186 305 const int *cipher_list( void );
ansond 0:137634ff4186 306
ansond 0:137634ff4186 307 /**
ansond 0:137634ff4186 308 * \brief Returns the cipher information structure associated
ansond 0:137634ff4186 309 * with the given cipher name.
ansond 0:137634ff4186 310 *
ansond 0:137634ff4186 311 * \param cipher_name Name of the cipher to search for.
ansond 0:137634ff4186 312 *
ansond 0:137634ff4186 313 * \return the cipher information structure associated with the
ansond 0:137634ff4186 314 * given cipher_name, or NULL if not found.
ansond 0:137634ff4186 315 */
ansond 0:137634ff4186 316 const cipher_info_t *cipher_info_from_string( const char *cipher_name );
ansond 0:137634ff4186 317
ansond 0:137634ff4186 318 /**
ansond 0:137634ff4186 319 * \brief Returns the cipher information structure associated
ansond 0:137634ff4186 320 * with the given cipher type.
ansond 0:137634ff4186 321 *
ansond 0:137634ff4186 322 * \param cipher_type Type of the cipher to search for.
ansond 0:137634ff4186 323 *
ansond 0:137634ff4186 324 * \return the cipher information structure associated with the
ansond 0:137634ff4186 325 * given cipher_type, or NULL if not found.
ansond 0:137634ff4186 326 */
ansond 0:137634ff4186 327 const cipher_info_t *cipher_info_from_type( const cipher_type_t cipher_type );
ansond 0:137634ff4186 328
ansond 0:137634ff4186 329 /**
ansond 0:137634ff4186 330 * \brief Returns the cipher information structure associated
ansond 0:137634ff4186 331 * with the given cipher id, key size and mode.
ansond 0:137634ff4186 332 *
ansond 0:137634ff4186 333 * \param cipher_id Id of the cipher to search for
ansond 0:137634ff4186 334 * (e.g. POLARSSL_CIPHER_ID_AES)
ansond 0:137634ff4186 335 * \param key_length Length of the key in bits
ansond 0:137634ff4186 336 * \param mode Cipher mode (e.g. POLARSSL_MODE_CBC)
ansond 0:137634ff4186 337 *
ansond 0:137634ff4186 338 * \return the cipher information structure associated with the
ansond 0:137634ff4186 339 * given cipher_type, or NULL if not found.
ansond 0:137634ff4186 340 */
ansond 0:137634ff4186 341 const cipher_info_t *cipher_info_from_values( const cipher_id_t cipher_id,
ansond 0:137634ff4186 342 int key_length,
ansond 0:137634ff4186 343 const cipher_mode_t mode );
ansond 0:137634ff4186 344
ansond 0:137634ff4186 345 /**
ansond 0:137634ff4186 346 * \brief Initialize a cipher_context (as NONE)
ansond 0:137634ff4186 347 */
ansond 0:137634ff4186 348 void cipher_init( cipher_context_t *ctx );
ansond 0:137634ff4186 349
ansond 0:137634ff4186 350 /**
ansond 0:137634ff4186 351 * \brief Free and clear the cipher-specific context of ctx.
ansond 0:137634ff4186 352 * Freeing ctx itself remains the responsibility of the
ansond 0:137634ff4186 353 * caller.
ansond 0:137634ff4186 354 */
ansond 0:137634ff4186 355 void cipher_free( cipher_context_t *ctx );
ansond 0:137634ff4186 356
ansond 0:137634ff4186 357 /**
ansond 0:137634ff4186 358 * \brief Initialises and fills the cipher context structure with
ansond 0:137634ff4186 359 * the appropriate values.
ansond 0:137634ff4186 360 *
ansond 0:137634ff4186 361 * \note Currently also clears structure. In future versions you
ansond 0:137634ff4186 362 * will be required to call cipher_init() on the structure
ansond 0:137634ff4186 363 * first.
ansond 0:137634ff4186 364 *
ansond 0:137634ff4186 365 * \param ctx context to initialise. May not be NULL.
ansond 0:137634ff4186 366 * \param cipher_info cipher to use.
ansond 0:137634ff4186 367 *
ansond 0:137634ff4186 368 * \return 0 on success,
ansond 0:137634ff4186 369 * POLARSSL_ERR_CIPHER_BAD_INPUT_DATA on parameter failure,
ansond 0:137634ff4186 370 * POLARSSL_ERR_CIPHER_ALLOC_FAILED if allocation of the
ansond 0:137634ff4186 371 * cipher-specific context failed.
ansond 0:137634ff4186 372 */
ansond 0:137634ff4186 373 int cipher_init_ctx( cipher_context_t *ctx, const cipher_info_t *cipher_info );
ansond 0:137634ff4186 374
ansond 0:137634ff4186 375 #if ! defined(POLARSSL_DEPRECATED_REMOVED)
ansond 0:137634ff4186 376 #if defined(POLARSSL_DEPRECATED_WARNING)
ansond 0:137634ff4186 377 #define DEPRECATED __attribute__((deprecated))
ansond 0:137634ff4186 378 #else
ansond 0:137634ff4186 379 #define DEPRECATED
ansond 0:137634ff4186 380 #endif
ansond 0:137634ff4186 381 /**
ansond 0:137634ff4186 382 * \brief Free the cipher-specific context of ctx. Freeing ctx
ansond 0:137634ff4186 383 * itself remains the responsibility of the caller.
ansond 0:137634ff4186 384 *
ansond 0:137634ff4186 385 * \deprecated Use cipher_free() instead
ansond 0:137634ff4186 386 *
ansond 0:137634ff4186 387 * \param ctx Free the cipher-specific context
ansond 0:137634ff4186 388 *
ansond 0:137634ff4186 389 * \returns 0
ansond 0:137634ff4186 390 */
ansond 0:137634ff4186 391 int cipher_free_ctx( cipher_context_t *ctx ) DEPRECATED;
ansond 0:137634ff4186 392 #undef DEPRECATED
ansond 0:137634ff4186 393 #endif /* POLARSSL_DEPRECATED_REMOVED */
ansond 0:137634ff4186 394
ansond 0:137634ff4186 395 /**
ansond 0:137634ff4186 396 * \brief Returns the block size of the given cipher.
ansond 0:137634ff4186 397 *
ansond 0:137634ff4186 398 * \param ctx cipher's context. Must have been initialised.
ansond 0:137634ff4186 399 *
ansond 0:137634ff4186 400 * \return size of the cipher's blocks, or 0 if ctx has not been
ansond 0:137634ff4186 401 * initialised.
ansond 0:137634ff4186 402 */
ansond 0:137634ff4186 403 static inline unsigned int cipher_get_block_size( const cipher_context_t *ctx )
ansond 0:137634ff4186 404 {
ansond 0:137634ff4186 405 if( NULL == ctx || NULL == ctx->cipher_info )
ansond 0:137634ff4186 406 return 0;
ansond 0:137634ff4186 407
ansond 0:137634ff4186 408 return ctx->cipher_info->block_size;
ansond 0:137634ff4186 409 }
ansond 0:137634ff4186 410
ansond 0:137634ff4186 411 /**
ansond 0:137634ff4186 412 * \brief Returns the mode of operation for the cipher.
ansond 0:137634ff4186 413 * (e.g. POLARSSL_MODE_CBC)
ansond 0:137634ff4186 414 *
ansond 0:137634ff4186 415 * \param ctx cipher's context. Must have been initialised.
ansond 0:137634ff4186 416 *
ansond 0:137634ff4186 417 * \return mode of operation, or POLARSSL_MODE_NONE if ctx
ansond 0:137634ff4186 418 * has not been initialised.
ansond 0:137634ff4186 419 */
ansond 0:137634ff4186 420 static inline cipher_mode_t cipher_get_cipher_mode( const cipher_context_t *ctx )
ansond 0:137634ff4186 421 {
ansond 0:137634ff4186 422 if( NULL == ctx || NULL == ctx->cipher_info )
ansond 0:137634ff4186 423 return POLARSSL_MODE_NONE;
ansond 0:137634ff4186 424
ansond 0:137634ff4186 425 return ctx->cipher_info->mode;
ansond 0:137634ff4186 426 }
ansond 0:137634ff4186 427
ansond 0:137634ff4186 428 /**
ansond 0:137634ff4186 429 * \brief Returns the size of the cipher's IV/NONCE in bytes.
ansond 0:137634ff4186 430 *
ansond 0:137634ff4186 431 * \param ctx cipher's context. Must have been initialised.
ansond 0:137634ff4186 432 *
ansond 0:137634ff4186 433 * \return If IV has not been set yet: (recommended) IV size
ansond 0:137634ff4186 434 * (0 for ciphers not using IV/NONCE).
ansond 0:137634ff4186 435 * If IV has already been set: actual size.
ansond 0:137634ff4186 436 */
ansond 0:137634ff4186 437 static inline int cipher_get_iv_size( const cipher_context_t *ctx )
ansond 0:137634ff4186 438 {
ansond 0:137634ff4186 439 if( NULL == ctx || NULL == ctx->cipher_info )
ansond 0:137634ff4186 440 return 0;
ansond 0:137634ff4186 441
ansond 0:137634ff4186 442 if( ctx->iv_size != 0 )
ansond 0:137634ff4186 443 return (int) ctx->iv_size;
ansond 0:137634ff4186 444
ansond 0:137634ff4186 445 return ctx->cipher_info->iv_size;
ansond 0:137634ff4186 446 }
ansond 0:137634ff4186 447
ansond 0:137634ff4186 448 /**
ansond 0:137634ff4186 449 * \brief Returns the type of the given cipher.
ansond 0:137634ff4186 450 *
ansond 0:137634ff4186 451 * \param ctx cipher's context. Must have been initialised.
ansond 0:137634ff4186 452 *
ansond 0:137634ff4186 453 * \return type of the cipher, or POLARSSL_CIPHER_NONE if ctx has
ansond 0:137634ff4186 454 * not been initialised.
ansond 0:137634ff4186 455 */
ansond 0:137634ff4186 456 static inline cipher_type_t cipher_get_type( const cipher_context_t *ctx )
ansond 0:137634ff4186 457 {
ansond 0:137634ff4186 458 if( NULL == ctx || NULL == ctx->cipher_info )
ansond 0:137634ff4186 459 return POLARSSL_CIPHER_NONE;
ansond 0:137634ff4186 460
ansond 0:137634ff4186 461 return ctx->cipher_info->type;
ansond 0:137634ff4186 462 }
ansond 0:137634ff4186 463
ansond 0:137634ff4186 464 /**
ansond 0:137634ff4186 465 * \brief Returns the name of the given cipher, as a string.
ansond 0:137634ff4186 466 *
ansond 0:137634ff4186 467 * \param ctx cipher's context. Must have been initialised.
ansond 0:137634ff4186 468 *
ansond 0:137634ff4186 469 * \return name of the cipher, or NULL if ctx was not initialised.
ansond 0:137634ff4186 470 */
ansond 0:137634ff4186 471 static inline const char *cipher_get_name( const cipher_context_t *ctx )
ansond 0:137634ff4186 472 {
ansond 0:137634ff4186 473 if( NULL == ctx || NULL == ctx->cipher_info )
ansond 0:137634ff4186 474 return 0;
ansond 0:137634ff4186 475
ansond 0:137634ff4186 476 return ctx->cipher_info->name;
ansond 0:137634ff4186 477 }
ansond 0:137634ff4186 478
ansond 0:137634ff4186 479 /**
ansond 0:137634ff4186 480 * \brief Returns the key length of the cipher.
ansond 0:137634ff4186 481 *
ansond 0:137634ff4186 482 * \param ctx cipher's context. Must have been initialised.
ansond 0:137634ff4186 483 *
ansond 0:137634ff4186 484 * \return cipher's key length, in bits, or
ansond 0:137634ff4186 485 * POLARSSL_KEY_LENGTH_NONE if ctx has not been
ansond 0:137634ff4186 486 * initialised.
ansond 0:137634ff4186 487 */
ansond 0:137634ff4186 488 static inline int cipher_get_key_size( const cipher_context_t *ctx )
ansond 0:137634ff4186 489 {
ansond 0:137634ff4186 490 if( NULL == ctx || NULL == ctx->cipher_info )
ansond 0:137634ff4186 491 return POLARSSL_KEY_LENGTH_NONE;
ansond 0:137634ff4186 492
ansond 0:137634ff4186 493 return ctx->cipher_info->key_length;
ansond 0:137634ff4186 494 }
ansond 0:137634ff4186 495
ansond 0:137634ff4186 496 /**
ansond 0:137634ff4186 497 * \brief Returns the operation of the given cipher.
ansond 0:137634ff4186 498 *
ansond 0:137634ff4186 499 * \param ctx cipher's context. Must have been initialised.
ansond 0:137634ff4186 500 *
ansond 0:137634ff4186 501 * \return operation (POLARSSL_ENCRYPT or POLARSSL_DECRYPT),
ansond 0:137634ff4186 502 * or POLARSSL_OPERATION_NONE if ctx has not been
ansond 0:137634ff4186 503 * initialised.
ansond 0:137634ff4186 504 */
ansond 0:137634ff4186 505 static inline operation_t cipher_get_operation( const cipher_context_t *ctx )
ansond 0:137634ff4186 506 {
ansond 0:137634ff4186 507 if( NULL == ctx || NULL == ctx->cipher_info )
ansond 0:137634ff4186 508 return POLARSSL_OPERATION_NONE;
ansond 0:137634ff4186 509
ansond 0:137634ff4186 510 return ctx->operation;
ansond 0:137634ff4186 511 }
ansond 0:137634ff4186 512
ansond 0:137634ff4186 513 /**
ansond 0:137634ff4186 514 * \brief Set the key to use with the given context.
ansond 0:137634ff4186 515 *
ansond 0:137634ff4186 516 * \param ctx generic cipher context. May not be NULL. Must have been
ansond 0:137634ff4186 517 * initialised using cipher_context_from_type or
ansond 0:137634ff4186 518 * cipher_context_from_string.
ansond 0:137634ff4186 519 * \param key The key to use.
ansond 0:137634ff4186 520 * \param key_length key length to use, in bits.
ansond 0:137634ff4186 521 * \param operation Operation that the key will be used for, either
ansond 0:137634ff4186 522 * POLARSSL_ENCRYPT or POLARSSL_DECRYPT.
ansond 0:137634ff4186 523 *
ansond 0:137634ff4186 524 * \returns 0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if
ansond 0:137634ff4186 525 * parameter verification fails or a cipher specific
ansond 0:137634ff4186 526 * error code.
ansond 0:137634ff4186 527 */
ansond 0:137634ff4186 528 int cipher_setkey( cipher_context_t *ctx, const unsigned char *key,
ansond 0:137634ff4186 529 int key_length, const operation_t operation );
ansond 0:137634ff4186 530
ansond 0:137634ff4186 531 #if defined(POLARSSL_CIPHER_MODE_WITH_PADDING)
ansond 0:137634ff4186 532 /**
ansond 0:137634ff4186 533 * \brief Set padding mode, for cipher modes that use padding.
ansond 0:137634ff4186 534 * (Default: PKCS7 padding.)
ansond 0:137634ff4186 535 *
ansond 0:137634ff4186 536 * \param ctx generic cipher context
ansond 0:137634ff4186 537 * \param mode padding mode
ansond 0:137634ff4186 538 *
ansond 0:137634ff4186 539 * \returns 0 on success, POLARSSL_ERR_CIPHER_FEATURE_UNAVAILABLE
ansond 0:137634ff4186 540 * if selected padding mode is not supported, or
ansond 0:137634ff4186 541 * POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
ansond 0:137634ff4186 542 * does not support padding.
ansond 0:137634ff4186 543 */
ansond 0:137634ff4186 544 int cipher_set_padding_mode( cipher_context_t *ctx, cipher_padding_t mode );
ansond 0:137634ff4186 545 #endif /* POLARSSL_CIPHER_MODE_WITH_PADDING */
ansond 0:137634ff4186 546
ansond 0:137634ff4186 547 /**
ansond 0:137634ff4186 548 * \brief Set the initialization vector (IV) or nonce
ansond 0:137634ff4186 549 *
ansond 0:137634ff4186 550 * \param ctx generic cipher context
ansond 0:137634ff4186 551 * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
ansond 0:137634ff4186 552 * \param iv_len IV length for ciphers with variable-size IV;
ansond 0:137634ff4186 553 * discarded by ciphers with fixed-size IV.
ansond 0:137634ff4186 554 *
ansond 0:137634ff4186 555 * \returns 0 on success, or POLARSSL_ERR_CIPHER_BAD_INPUT_DATA
ansond 0:137634ff4186 556 *
ansond 0:137634ff4186 557 * \note Some ciphers don't use IVs nor NONCE. For these
ansond 0:137634ff4186 558 * ciphers, this function has no effect.
ansond 0:137634ff4186 559 */
ansond 0:137634ff4186 560 int cipher_set_iv( cipher_context_t *ctx,
ansond 0:137634ff4186 561 const unsigned char *iv, size_t iv_len );
ansond 0:137634ff4186 562
ansond 0:137634ff4186 563 /**
ansond 0:137634ff4186 564 * \brief Finish preparation of the given context
ansond 0:137634ff4186 565 *
ansond 0:137634ff4186 566 * \param ctx generic cipher context
ansond 0:137634ff4186 567 *
ansond 0:137634ff4186 568 * \returns 0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA
ansond 0:137634ff4186 569 * if parameter verification fails.
ansond 0:137634ff4186 570 */
ansond 0:137634ff4186 571 int cipher_reset( cipher_context_t *ctx );
ansond 0:137634ff4186 572
ansond 0:137634ff4186 573 #if defined(POLARSSL_GCM_C)
ansond 0:137634ff4186 574 /**
ansond 0:137634ff4186 575 * \brief Add additional data (for AEAD ciphers).
ansond 0:137634ff4186 576 * Currently only supported with GCM.
ansond 0:137634ff4186 577 * Must be called exactly once, after cipher_reset().
ansond 0:137634ff4186 578 *
ansond 0:137634ff4186 579 * \param ctx generic cipher context
ansond 0:137634ff4186 580 * \param ad Additional data to use.
ansond 0:137634ff4186 581 * \param ad_len Length of ad.
ansond 0:137634ff4186 582 *
ansond 0:137634ff4186 583 * \return 0 on success, or a specific error code.
ansond 0:137634ff4186 584 */
ansond 0:137634ff4186 585 int cipher_update_ad( cipher_context_t *ctx,
ansond 0:137634ff4186 586 const unsigned char *ad, size_t ad_len );
ansond 0:137634ff4186 587 #endif /* POLARSSL_GCM_C */
ansond 0:137634ff4186 588
ansond 0:137634ff4186 589 /**
ansond 0:137634ff4186 590 * \brief Generic cipher update function. Encrypts/decrypts
ansond 0:137634ff4186 591 * using the given cipher context. Writes as many block
ansond 0:137634ff4186 592 * size'd blocks of data as possible to output. Any data
ansond 0:137634ff4186 593 * that cannot be written immediately will either be added
ansond 0:137634ff4186 594 * to the next block, or flushed when cipher_final is
ansond 0:137634ff4186 595 * called.
ansond 0:137634ff4186 596 * Exception: for POLARSSL_MODE_ECB, expects single block
ansond 0:137634ff4186 597 * in size (e.g. 16 bytes for AES)
ansond 0:137634ff4186 598 *
ansond 0:137634ff4186 599 * \param ctx generic cipher context
ansond 0:137634ff4186 600 * \param input buffer holding the input data
ansond 0:137634ff4186 601 * \param ilen length of the input data
ansond 0:137634ff4186 602 * \param output buffer for the output data. Should be able to hold at
ansond 0:137634ff4186 603 * least ilen + block_size. Cannot be the same buffer as
ansond 0:137634ff4186 604 * input!
ansond 0:137634ff4186 605 * \param olen length of the output data, will be filled with the
ansond 0:137634ff4186 606 * actual number of bytes written.
ansond 0:137634ff4186 607 *
ansond 0:137634ff4186 608 * \returns 0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if
ansond 0:137634ff4186 609 * parameter verification fails,
ansond 0:137634ff4186 610 * POLARSSL_ERR_CIPHER_FEATURE_UNAVAILABLE on an
ansond 0:137634ff4186 611 * unsupported mode for a cipher or a cipher specific
ansond 0:137634ff4186 612 * error code.
ansond 0:137634ff4186 613 *
ansond 0:137634ff4186 614 * \note If the underlying cipher is GCM, all calls to this
ansond 0:137634ff4186 615 * function, except the last one before cipher_finish(),
ansond 0:137634ff4186 616 * must have ilen a multiple of the block size.
ansond 0:137634ff4186 617 */
ansond 0:137634ff4186 618 int cipher_update( cipher_context_t *ctx, const unsigned char *input,
ansond 0:137634ff4186 619 size_t ilen, unsigned char *output, size_t *olen );
ansond 0:137634ff4186 620
ansond 0:137634ff4186 621 /**
ansond 0:137634ff4186 622 * \brief Generic cipher finalisation function. If data still
ansond 0:137634ff4186 623 * needs to be flushed from an incomplete block, data
ansond 0:137634ff4186 624 * contained within it will be padded with the size of
ansond 0:137634ff4186 625 * the last block, and written to the output buffer.
ansond 0:137634ff4186 626 *
ansond 0:137634ff4186 627 * \param ctx Generic cipher context
ansond 0:137634ff4186 628 * \param output buffer to write data to. Needs block_size available.
ansond 0:137634ff4186 629 * \param olen length of the data written to the output buffer.
ansond 0:137634ff4186 630 *
ansond 0:137634ff4186 631 * \returns 0 on success, POLARSSL_ERR_CIPHER_BAD_INPUT_DATA if
ansond 0:137634ff4186 632 * parameter verification fails,
ansond 0:137634ff4186 633 * POLARSSL_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
ansond 0:137634ff4186 634 * expected a full block but was not provided one,
ansond 0:137634ff4186 635 * POLARSSL_ERR_CIPHER_INVALID_PADDING on invalid padding
ansond 0:137634ff4186 636 * while decrypting or a cipher specific error code.
ansond 0:137634ff4186 637 */
ansond 0:137634ff4186 638 int cipher_finish( cipher_context_t *ctx,
ansond 0:137634ff4186 639 unsigned char *output, size_t *olen );
ansond 0:137634ff4186 640
ansond 0:137634ff4186 641 #if defined(POLARSSL_GCM_C)
ansond 0:137634ff4186 642 /**
ansond 0:137634ff4186 643 * \brief Write tag for AEAD ciphers.
ansond 0:137634ff4186 644 * Currently only supported with GCM.
ansond 0:137634ff4186 645 * Must be called after cipher_finish().
ansond 0:137634ff4186 646 *
ansond 0:137634ff4186 647 * \param ctx Generic cipher context
ansond 0:137634ff4186 648 * \param tag buffer to write the tag
ansond 0:137634ff4186 649 * \param tag_len Length of the tag to write
ansond 0:137634ff4186 650 *
ansond 0:137634ff4186 651 * \return 0 on success, or a specific error code.
ansond 0:137634ff4186 652 */
ansond 0:137634ff4186 653 int cipher_write_tag( cipher_context_t *ctx,
ansond 0:137634ff4186 654 unsigned char *tag, size_t tag_len );
ansond 0:137634ff4186 655
ansond 0:137634ff4186 656 /**
ansond 0:137634ff4186 657 * \brief Check tag for AEAD ciphers.
ansond 0:137634ff4186 658 * Currently only supported with GCM.
ansond 0:137634ff4186 659 * Must be called after cipher_finish().
ansond 0:137634ff4186 660 *
ansond 0:137634ff4186 661 * \param ctx Generic cipher context
ansond 0:137634ff4186 662 * \param tag Buffer holding the tag
ansond 0:137634ff4186 663 * \param tag_len Length of the tag to check
ansond 0:137634ff4186 664 *
ansond 0:137634ff4186 665 * \return 0 on success, or a specific error code.
ansond 0:137634ff4186 666 */
ansond 0:137634ff4186 667 int cipher_check_tag( cipher_context_t *ctx,
ansond 0:137634ff4186 668 const unsigned char *tag, size_t tag_len );
ansond 0:137634ff4186 669 #endif /* POLARSSL_GCM_C */
ansond 0:137634ff4186 670
ansond 0:137634ff4186 671 /**
ansond 0:137634ff4186 672 * \brief Generic all-in-one encryption/decryption
ansond 0:137634ff4186 673 * (for all ciphers except AEAD constructs).
ansond 0:137634ff4186 674 *
ansond 0:137634ff4186 675 * \param ctx generic cipher context
ansond 0:137634ff4186 676 * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
ansond 0:137634ff4186 677 * \param iv_len IV length for ciphers with variable-size IV;
ansond 0:137634ff4186 678 * discarded by ciphers with fixed-size IV.
ansond 0:137634ff4186 679 * \param input buffer holding the input data
ansond 0:137634ff4186 680 * \param ilen length of the input data
ansond 0:137634ff4186 681 * \param output buffer for the output data. Should be able to hold at
ansond 0:137634ff4186 682 * least ilen + block_size. Cannot be the same buffer as
ansond 0:137634ff4186 683 * input!
ansond 0:137634ff4186 684 * \param olen length of the output data, will be filled with the
ansond 0:137634ff4186 685 * actual number of bytes written.
ansond 0:137634ff4186 686 *
ansond 0:137634ff4186 687 * \note Some ciphers don't use IVs nor NONCE. For these
ansond 0:137634ff4186 688 * ciphers, use iv = NULL and iv_len = 0.
ansond 0:137634ff4186 689 *
ansond 0:137634ff4186 690 * \returns 0 on success, or
ansond 0:137634ff4186 691 * POLARSSL_ERR_CIPHER_BAD_INPUT_DATA, or
ansond 0:137634ff4186 692 * POLARSSL_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
ansond 0:137634ff4186 693 * expected a full block but was not provided one, or
ansond 0:137634ff4186 694 * POLARSSL_ERR_CIPHER_INVALID_PADDING on invalid padding
ansond 0:137634ff4186 695 * while decrypting, or
ansond 0:137634ff4186 696 * a cipher specific error code.
ansond 0:137634ff4186 697 */
ansond 0:137634ff4186 698 int cipher_crypt( cipher_context_t *ctx,
ansond 0:137634ff4186 699 const unsigned char *iv, size_t iv_len,
ansond 0:137634ff4186 700 const unsigned char *input, size_t ilen,
ansond 0:137634ff4186 701 unsigned char *output, size_t *olen );
ansond 0:137634ff4186 702
ansond 0:137634ff4186 703 #if defined(POLARSSL_CIPHER_MODE_AEAD)
ansond 0:137634ff4186 704 /**
ansond 0:137634ff4186 705 * \brief Generic autenticated encryption (AEAD ciphers).
ansond 0:137634ff4186 706 *
ansond 0:137634ff4186 707 * \param ctx generic cipher context
ansond 0:137634ff4186 708 * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
ansond 0:137634ff4186 709 * \param iv_len IV length for ciphers with variable-size IV;
ansond 0:137634ff4186 710 * discarded by ciphers with fixed-size IV.
ansond 0:137634ff4186 711 * \param ad Additional data to authenticate.
ansond 0:137634ff4186 712 * \param ad_len Length of ad.
ansond 0:137634ff4186 713 * \param input buffer holding the input data
ansond 0:137634ff4186 714 * \param ilen length of the input data
ansond 0:137634ff4186 715 * \param output buffer for the output data.
ansond 0:137634ff4186 716 * Should be able to hold at least ilen.
ansond 0:137634ff4186 717 * \param olen length of the output data, will be filled with the
ansond 0:137634ff4186 718 * actual number of bytes written.
ansond 0:137634ff4186 719 * \param tag buffer for the authentication tag
ansond 0:137634ff4186 720 * \param tag_len desired tag length
ansond 0:137634ff4186 721 *
ansond 0:137634ff4186 722 * \returns 0 on success, or
ansond 0:137634ff4186 723 * POLARSSL_ERR_CIPHER_BAD_INPUT_DATA, or
ansond 0:137634ff4186 724 * a cipher specific error code.
ansond 0:137634ff4186 725 */
ansond 0:137634ff4186 726 int cipher_auth_encrypt( cipher_context_t *ctx,
ansond 0:137634ff4186 727 const unsigned char *iv, size_t iv_len,
ansond 0:137634ff4186 728 const unsigned char *ad, size_t ad_len,
ansond 0:137634ff4186 729 const unsigned char *input, size_t ilen,
ansond 0:137634ff4186 730 unsigned char *output, size_t *olen,
ansond 0:137634ff4186 731 unsigned char *tag, size_t tag_len );
ansond 0:137634ff4186 732
ansond 0:137634ff4186 733 /**
ansond 0:137634ff4186 734 * \brief Generic autenticated decryption (AEAD ciphers).
ansond 0:137634ff4186 735 *
ansond 0:137634ff4186 736 * \param ctx generic cipher context
ansond 0:137634ff4186 737 * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
ansond 0:137634ff4186 738 * \param iv_len IV length for ciphers with variable-size IV;
ansond 0:137634ff4186 739 * discarded by ciphers with fixed-size IV.
ansond 0:137634ff4186 740 * \param ad Additional data to be authenticated.
ansond 0:137634ff4186 741 * \param ad_len Length of ad.
ansond 0:137634ff4186 742 * \param input buffer holding the input data
ansond 0:137634ff4186 743 * \param ilen length of the input data
ansond 0:137634ff4186 744 * \param output buffer for the output data.
ansond 0:137634ff4186 745 * Should be able to hold at least ilen.
ansond 0:137634ff4186 746 * \param olen length of the output data, will be filled with the
ansond 0:137634ff4186 747 * actual number of bytes written.
ansond 0:137634ff4186 748 * \param tag buffer holding the authentication tag
ansond 0:137634ff4186 749 * \param tag_len length of the authentication tag
ansond 0:137634ff4186 750 *
ansond 0:137634ff4186 751 * \returns 0 on success, or
ansond 0:137634ff4186 752 * POLARSSL_ERR_CIPHER_BAD_INPUT_DATA, or
ansond 0:137634ff4186 753 * POLARSSL_ERR_CIPHER_AUTH_FAILED if data isn't authentic,
ansond 0:137634ff4186 754 * or a cipher specific error code.
ansond 0:137634ff4186 755 *
ansond 0:137634ff4186 756 * \note If the data is not authentic, then the output buffer
ansond 0:137634ff4186 757 * is zeroed out to prevent the unauthentic plaintext to
ansond 0:137634ff4186 758 * be used by mistake, making this interface safer.
ansond 0:137634ff4186 759 */
ansond 0:137634ff4186 760 int cipher_auth_decrypt( cipher_context_t *ctx,
ansond 0:137634ff4186 761 const unsigned char *iv, size_t iv_len,
ansond 0:137634ff4186 762 const unsigned char *ad, size_t ad_len,
ansond 0:137634ff4186 763 const unsigned char *input, size_t ilen,
ansond 0:137634ff4186 764 unsigned char *output, size_t *olen,
ansond 0:137634ff4186 765 const unsigned char *tag, size_t tag_len );
ansond 0:137634ff4186 766 #endif /* POLARSSL_CIPHER_MODE_AEAD */
ansond 0:137634ff4186 767
ansond 0:137634ff4186 768 /**
ansond 0:137634ff4186 769 * \brief Checkup routine
ansond 0:137634ff4186 770 *
ansond 0:137634ff4186 771 * \return 0 if successful, or 1 if the test failed
ansond 0:137634ff4186 772 */
ansond 0:137634ff4186 773 int cipher_self_test( int verbose );
ansond 0:137634ff4186 774
ansond 0:137634ff4186 775 #ifdef __cplusplus
ansond 0:137634ff4186 776 }
ansond 0:137634ff4186 777 #endif
ansond 0:137634ff4186 778
ansond 0:137634ff4186 779 #endif /* POLARSSL_CIPHER_H */
ansond 0:137634ff4186 780