sandbox / mbedtls

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of mbedtls by Christopher Haster

mbedtls/cipher.h@1:24750b9ad5ef, 2016-01-22 (annotated)

Committer:
Christopher Haster
Date:
Fri Jan 22 16:44:49 2016 -0600
Revision:
1:24750b9ad5ef
Initial move of mbedtls to mercurial

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Christopher Haster 1:24750b9ad5ef 1 /**
Christopher Haster 1:24750b9ad5ef 2 * \file cipher.h
Christopher Haster 1:24750b9ad5ef 3 *
Christopher Haster 1:24750b9ad5ef 4 * \brief Generic cipher wrapper.
Christopher Haster 1:24750b9ad5ef 5 *
Christopher Haster 1:24750b9ad5ef 6 * \author Adriaan de Jong <dejong@fox-it.com>
Christopher Haster 1:24750b9ad5ef 7 *
Christopher Haster 1:24750b9ad5ef 8 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
Christopher Haster 1:24750b9ad5ef 9 * SPDX-License-Identifier: Apache-2.0
Christopher Haster 1:24750b9ad5ef 10 *
Christopher Haster 1:24750b9ad5ef 11 * Licensed under the Apache License, Version 2.0 (the "License"); you may
Christopher Haster 1:24750b9ad5ef 12 * not use this file except in compliance with the License.
Christopher Haster 1:24750b9ad5ef 13 * You may obtain a copy of the License at
Christopher Haster 1:24750b9ad5ef 14 *
Christopher Haster 1:24750b9ad5ef 15 * http://www.apache.org/licenses/LICENSE-2.0
Christopher Haster 1:24750b9ad5ef 16 *
Christopher Haster 1:24750b9ad5ef 17 * Unless required by applicable law or agreed to in writing, software
Christopher Haster 1:24750b9ad5ef 18 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
Christopher Haster 1:24750b9ad5ef 19 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Christopher Haster 1:24750b9ad5ef 20 * See the License for the specific language governing permissions and
Christopher Haster 1:24750b9ad5ef 21 * limitations under the License.
Christopher Haster 1:24750b9ad5ef 22 *
Christopher Haster 1:24750b9ad5ef 23 * This file is part of mbed TLS (https://tls.mbed.org)
Christopher Haster 1:24750b9ad5ef 24 */
Christopher Haster 1:24750b9ad5ef 25
Christopher Haster 1:24750b9ad5ef 26 #ifndef MBEDTLS_CIPHER_H
Christopher Haster 1:24750b9ad5ef 27 #define MBEDTLS_CIPHER_H
Christopher Haster 1:24750b9ad5ef 28
Christopher Haster 1:24750b9ad5ef 29 #if !defined(MBEDTLS_CONFIG_FILE)
Christopher Haster 1:24750b9ad5ef 30 #include "config.h"
Christopher Haster 1:24750b9ad5ef 31 #else
Christopher Haster 1:24750b9ad5ef 32 #include MBEDTLS_CONFIG_FILE
Christopher Haster 1:24750b9ad5ef 33 #endif
Christopher Haster 1:24750b9ad5ef 34
Christopher Haster 1:24750b9ad5ef 35 #include <stddef.h>
Christopher Haster 1:24750b9ad5ef 36
Christopher Haster 1:24750b9ad5ef 37 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CCM_C)
Christopher Haster 1:24750b9ad5ef 38 #define MBEDTLS_CIPHER_MODE_AEAD
Christopher Haster 1:24750b9ad5ef 39 #endif
Christopher Haster 1:24750b9ad5ef 40
Christopher Haster 1:24750b9ad5ef 41 #if defined(MBEDTLS_CIPHER_MODE_CBC)
Christopher Haster 1:24750b9ad5ef 42 #define MBEDTLS_CIPHER_MODE_WITH_PADDING
Christopher Haster 1:24750b9ad5ef 43 #endif
Christopher Haster 1:24750b9ad5ef 44
Christopher Haster 1:24750b9ad5ef 45 #if defined(MBEDTLS_ARC4_C)
Christopher Haster 1:24750b9ad5ef 46 #define MBEDTLS_CIPHER_MODE_STREAM
Christopher Haster 1:24750b9ad5ef 47 #endif
Christopher Haster 1:24750b9ad5ef 48
Christopher Haster 1:24750b9ad5ef 49 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
Christopher Haster 1:24750b9ad5ef 50 !defined(inline) && !defined(__cplusplus)
Christopher Haster 1:24750b9ad5ef 51 #define inline __inline
Christopher Haster 1:24750b9ad5ef 52 #endif
Christopher Haster 1:24750b9ad5ef 53
Christopher Haster 1:24750b9ad5ef 54 #define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080 /**< The selected feature is not available. */
Christopher Haster 1:24750b9ad5ef 55 #define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA -0x6100 /**< Bad input parameters to function. */
Christopher Haster 1:24750b9ad5ef 56 #define MBEDTLS_ERR_CIPHER_ALLOC_FAILED -0x6180 /**< Failed to allocate memory. */
Christopher Haster 1:24750b9ad5ef 57 #define MBEDTLS_ERR_CIPHER_INVALID_PADDING -0x6200 /**< Input data contains invalid padding and is rejected. */
Christopher Haster 1:24750b9ad5ef 58 #define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280 /**< Decryption of block requires a full block. */
Christopher Haster 1:24750b9ad5ef 59 #define MBEDTLS_ERR_CIPHER_AUTH_FAILED -0x6300 /**< Authentication failed (for AEAD modes). */
Christopher Haster 1:24750b9ad5ef 60
Christopher Haster 1:24750b9ad5ef 61 #define MBEDTLS_CIPHER_VARIABLE_IV_LEN 0x01 /**< Cipher accepts IVs of variable length */
Christopher Haster 1:24750b9ad5ef 62 #define MBEDTLS_CIPHER_VARIABLE_KEY_LEN 0x02 /**< Cipher accepts keys of variable length */
Christopher Haster 1:24750b9ad5ef 63
Christopher Haster 1:24750b9ad5ef 64 #ifdef __cplusplus
Christopher Haster 1:24750b9ad5ef 65 extern "C" {
Christopher Haster 1:24750b9ad5ef 66 #endif
Christopher Haster 1:24750b9ad5ef 67
Christopher Haster 1:24750b9ad5ef 68 typedef enum {
Christopher Haster 1:24750b9ad5ef 69 MBEDTLS_CIPHER_ID_NONE = 0,
Christopher Haster 1:24750b9ad5ef 70 MBEDTLS_CIPHER_ID_NULL,
Christopher Haster 1:24750b9ad5ef 71 MBEDTLS_CIPHER_ID_AES,
Christopher Haster 1:24750b9ad5ef 72 MBEDTLS_CIPHER_ID_DES,
Christopher Haster 1:24750b9ad5ef 73 MBEDTLS_CIPHER_ID_3DES,
Christopher Haster 1:24750b9ad5ef 74 MBEDTLS_CIPHER_ID_CAMELLIA,
Christopher Haster 1:24750b9ad5ef 75 MBEDTLS_CIPHER_ID_BLOWFISH,
Christopher Haster 1:24750b9ad5ef 76 MBEDTLS_CIPHER_ID_ARC4,
Christopher Haster 1:24750b9ad5ef 77 } mbedtls_cipher_id_t;
Christopher Haster 1:24750b9ad5ef 78
Christopher Haster 1:24750b9ad5ef 79 typedef enum {
Christopher Haster 1:24750b9ad5ef 80 MBEDTLS_CIPHER_NONE = 0,
Christopher Haster 1:24750b9ad5ef 81 MBEDTLS_CIPHER_NULL,
Christopher Haster 1:24750b9ad5ef 82 MBEDTLS_CIPHER_AES_128_ECB,
Christopher Haster 1:24750b9ad5ef 83 MBEDTLS_CIPHER_AES_192_ECB,
Christopher Haster 1:24750b9ad5ef 84 MBEDTLS_CIPHER_AES_256_ECB,
Christopher Haster 1:24750b9ad5ef 85 MBEDTLS_CIPHER_AES_128_CBC,
Christopher Haster 1:24750b9ad5ef 86 MBEDTLS_CIPHER_AES_192_CBC,
Christopher Haster 1:24750b9ad5ef 87 MBEDTLS_CIPHER_AES_256_CBC,
Christopher Haster 1:24750b9ad5ef 88 MBEDTLS_CIPHER_AES_128_CFB128,
Christopher Haster 1:24750b9ad5ef 89 MBEDTLS_CIPHER_AES_192_CFB128,
Christopher Haster 1:24750b9ad5ef 90 MBEDTLS_CIPHER_AES_256_CFB128,
Christopher Haster 1:24750b9ad5ef 91 MBEDTLS_CIPHER_AES_128_CTR,
Christopher Haster 1:24750b9ad5ef 92 MBEDTLS_CIPHER_AES_192_CTR,
Christopher Haster 1:24750b9ad5ef 93 MBEDTLS_CIPHER_AES_256_CTR,
Christopher Haster 1:24750b9ad5ef 94 MBEDTLS_CIPHER_AES_128_GCM,
Christopher Haster 1:24750b9ad5ef 95 MBEDTLS_CIPHER_AES_192_GCM,
Christopher Haster 1:24750b9ad5ef 96 MBEDTLS_CIPHER_AES_256_GCM,
Christopher Haster 1:24750b9ad5ef 97 MBEDTLS_CIPHER_CAMELLIA_128_ECB,
Christopher Haster 1:24750b9ad5ef 98 MBEDTLS_CIPHER_CAMELLIA_192_ECB,
Christopher Haster 1:24750b9ad5ef 99 MBEDTLS_CIPHER_CAMELLIA_256_ECB,
Christopher Haster 1:24750b9ad5ef 100 MBEDTLS_CIPHER_CAMELLIA_128_CBC,
Christopher Haster 1:24750b9ad5ef 101 MBEDTLS_CIPHER_CAMELLIA_192_CBC,
Christopher Haster 1:24750b9ad5ef 102 MBEDTLS_CIPHER_CAMELLIA_256_CBC,
Christopher Haster 1:24750b9ad5ef 103 MBEDTLS_CIPHER_CAMELLIA_128_CFB128,
Christopher Haster 1:24750b9ad5ef 104 MBEDTLS_CIPHER_CAMELLIA_192_CFB128,
Christopher Haster 1:24750b9ad5ef 105 MBEDTLS_CIPHER_CAMELLIA_256_CFB128,
Christopher Haster 1:24750b9ad5ef 106 MBEDTLS_CIPHER_CAMELLIA_128_CTR,
Christopher Haster 1:24750b9ad5ef 107 MBEDTLS_CIPHER_CAMELLIA_192_CTR,
Christopher Haster 1:24750b9ad5ef 108 MBEDTLS_CIPHER_CAMELLIA_256_CTR,
Christopher Haster 1:24750b9ad5ef 109 MBEDTLS_CIPHER_CAMELLIA_128_GCM,
Christopher Haster 1:24750b9ad5ef 110 MBEDTLS_CIPHER_CAMELLIA_192_GCM,
Christopher Haster 1:24750b9ad5ef 111 MBEDTLS_CIPHER_CAMELLIA_256_GCM,
Christopher Haster 1:24750b9ad5ef 112 MBEDTLS_CIPHER_DES_ECB,
Christopher Haster 1:24750b9ad5ef 113 MBEDTLS_CIPHER_DES_CBC,
Christopher Haster 1:24750b9ad5ef 114 MBEDTLS_CIPHER_DES_EDE_ECB,
Christopher Haster 1:24750b9ad5ef 115 MBEDTLS_CIPHER_DES_EDE_CBC,
Christopher Haster 1:24750b9ad5ef 116 MBEDTLS_CIPHER_DES_EDE3_ECB,
Christopher Haster 1:24750b9ad5ef 117 MBEDTLS_CIPHER_DES_EDE3_CBC,
Christopher Haster 1:24750b9ad5ef 118 MBEDTLS_CIPHER_BLOWFISH_ECB,
Christopher Haster 1:24750b9ad5ef 119 MBEDTLS_CIPHER_BLOWFISH_CBC,
Christopher Haster 1:24750b9ad5ef 120 MBEDTLS_CIPHER_BLOWFISH_CFB64,
Christopher Haster 1:24750b9ad5ef 121 MBEDTLS_CIPHER_BLOWFISH_CTR,
Christopher Haster 1:24750b9ad5ef 122 MBEDTLS_CIPHER_ARC4_128,
Christopher Haster 1:24750b9ad5ef 123 MBEDTLS_CIPHER_AES_128_CCM,
Christopher Haster 1:24750b9ad5ef 124 MBEDTLS_CIPHER_AES_192_CCM,
Christopher Haster 1:24750b9ad5ef 125 MBEDTLS_CIPHER_AES_256_CCM,
Christopher Haster 1:24750b9ad5ef 126 MBEDTLS_CIPHER_CAMELLIA_128_CCM,
Christopher Haster 1:24750b9ad5ef 127 MBEDTLS_CIPHER_CAMELLIA_192_CCM,
Christopher Haster 1:24750b9ad5ef 128 MBEDTLS_CIPHER_CAMELLIA_256_CCM,
Christopher Haster 1:24750b9ad5ef 129 } mbedtls_cipher_type_t;
Christopher Haster 1:24750b9ad5ef 130
Christopher Haster 1:24750b9ad5ef 131 typedef enum {
Christopher Haster 1:24750b9ad5ef 132 MBEDTLS_MODE_NONE = 0,
Christopher Haster 1:24750b9ad5ef 133 MBEDTLS_MODE_ECB,
Christopher Haster 1:24750b9ad5ef 134 MBEDTLS_MODE_CBC,
Christopher Haster 1:24750b9ad5ef 135 MBEDTLS_MODE_CFB,
Christopher Haster 1:24750b9ad5ef 136 MBEDTLS_MODE_OFB, /* Unused! */
Christopher Haster 1:24750b9ad5ef 137 MBEDTLS_MODE_CTR,
Christopher Haster 1:24750b9ad5ef 138 MBEDTLS_MODE_GCM,
Christopher Haster 1:24750b9ad5ef 139 MBEDTLS_MODE_STREAM,
Christopher Haster 1:24750b9ad5ef 140 MBEDTLS_MODE_CCM,
Christopher Haster 1:24750b9ad5ef 141 } mbedtls_cipher_mode_t;
Christopher Haster 1:24750b9ad5ef 142
Christopher Haster 1:24750b9ad5ef 143 typedef enum {
Christopher Haster 1:24750b9ad5ef 144 MBEDTLS_PADDING_PKCS7 = 0, /**< PKCS7 padding (default) */
Christopher Haster 1:24750b9ad5ef 145 MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding */
Christopher Haster 1:24750b9ad5ef 146 MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding */
Christopher Haster 1:24750b9ad5ef 147 MBEDTLS_PADDING_ZEROS, /**< zero padding (not reversible!) */
Christopher Haster 1:24750b9ad5ef 148 MBEDTLS_PADDING_NONE, /**< never pad (full blocks only) */
Christopher Haster 1:24750b9ad5ef 149 } mbedtls_cipher_padding_t;
Christopher Haster 1:24750b9ad5ef 150
Christopher Haster 1:24750b9ad5ef 151 typedef enum {
Christopher Haster 1:24750b9ad5ef 152 MBEDTLS_OPERATION_NONE = -1,
Christopher Haster 1:24750b9ad5ef 153 MBEDTLS_DECRYPT = 0,
Christopher Haster 1:24750b9ad5ef 154 MBEDTLS_ENCRYPT,
Christopher Haster 1:24750b9ad5ef 155 } mbedtls_operation_t;
Christopher Haster 1:24750b9ad5ef 156
Christopher Haster 1:24750b9ad5ef 157 enum {
Christopher Haster 1:24750b9ad5ef 158 /** Undefined key length */
Christopher Haster 1:24750b9ad5ef 159 MBEDTLS_KEY_LENGTH_NONE = 0,
Christopher Haster 1:24750b9ad5ef 160 /** Key length, in bits (including parity), for DES keys */
Christopher Haster 1:24750b9ad5ef 161 MBEDTLS_KEY_LENGTH_DES = 64,
Christopher Haster 1:24750b9ad5ef 162 /** Key length, in bits (including parity), for DES in two key EDE */
Christopher Haster 1:24750b9ad5ef 163 MBEDTLS_KEY_LENGTH_DES_EDE = 128,
Christopher Haster 1:24750b9ad5ef 164 /** Key length, in bits (including parity), for DES in three-key EDE */
Christopher Haster 1:24750b9ad5ef 165 MBEDTLS_KEY_LENGTH_DES_EDE3 = 192,
Christopher Haster 1:24750b9ad5ef 166 };
Christopher Haster 1:24750b9ad5ef 167
Christopher Haster 1:24750b9ad5ef 168 /** Maximum length of any IV, in bytes */
Christopher Haster 1:24750b9ad5ef 169 #define MBEDTLS_MAX_IV_LENGTH 16
Christopher Haster 1:24750b9ad5ef 170 /** Maximum block size of any cipher, in bytes */
Christopher Haster 1:24750b9ad5ef 171 #define MBEDTLS_MAX_BLOCK_LENGTH 16
Christopher Haster 1:24750b9ad5ef 172
Christopher Haster 1:24750b9ad5ef 173 /**
Christopher Haster 1:24750b9ad5ef 174 * Base cipher information (opaque struct).
Christopher Haster 1:24750b9ad5ef 175 */
Christopher Haster 1:24750b9ad5ef 176 typedef struct mbedtls_cipher_base_t mbedtls_cipher_base_t;
Christopher Haster 1:24750b9ad5ef 177
Christopher Haster 1:24750b9ad5ef 178 /**
Christopher Haster 1:24750b9ad5ef 179 * Cipher information. Allows cipher functions to be called in a generic way.
Christopher Haster 1:24750b9ad5ef 180 */
Christopher Haster 1:24750b9ad5ef 181 typedef struct {
Christopher Haster 1:24750b9ad5ef 182 /** Full cipher identifier (e.g. MBEDTLS_CIPHER_AES_256_CBC) */
Christopher Haster 1:24750b9ad5ef 183 mbedtls_cipher_type_t type;
Christopher Haster 1:24750b9ad5ef 184
Christopher Haster 1:24750b9ad5ef 185 /** Cipher mode (e.g. MBEDTLS_MODE_CBC) */
Christopher Haster 1:24750b9ad5ef 186 mbedtls_cipher_mode_t mode;
Christopher Haster 1:24750b9ad5ef 187
Christopher Haster 1:24750b9ad5ef 188 /** Cipher key length, in bits (default length for variable sized ciphers)
Christopher Haster 1:24750b9ad5ef 189 * (Includes parity bits for ciphers like DES) */
Christopher Haster 1:24750b9ad5ef 190 unsigned int key_bitlen;
Christopher Haster 1:24750b9ad5ef 191
Christopher Haster 1:24750b9ad5ef 192 /** Name of the cipher */
Christopher Haster 1:24750b9ad5ef 193 const char * name;
Christopher Haster 1:24750b9ad5ef 194
Christopher Haster 1:24750b9ad5ef 195 /** IV/NONCE size, in bytes.
Christopher Haster 1:24750b9ad5ef 196 * For cipher that accept many sizes: recommended size */
Christopher Haster 1:24750b9ad5ef 197 unsigned int iv_size;
Christopher Haster 1:24750b9ad5ef 198
Christopher Haster 1:24750b9ad5ef 199 /** Flags for variable IV size, variable key size, etc. */
Christopher Haster 1:24750b9ad5ef 200 int flags;
Christopher Haster 1:24750b9ad5ef 201
Christopher Haster 1:24750b9ad5ef 202 /** block size, in bytes */
Christopher Haster 1:24750b9ad5ef 203 unsigned int block_size;
Christopher Haster 1:24750b9ad5ef 204
Christopher Haster 1:24750b9ad5ef 205 /** Base cipher information and functions */
Christopher Haster 1:24750b9ad5ef 206 const mbedtls_cipher_base_t *base;
Christopher Haster 1:24750b9ad5ef 207
Christopher Haster 1:24750b9ad5ef 208 } mbedtls_cipher_info_t;
Christopher Haster 1:24750b9ad5ef 209
Christopher Haster 1:24750b9ad5ef 210 /**
Christopher Haster 1:24750b9ad5ef 211 * Generic cipher context.
Christopher Haster 1:24750b9ad5ef 212 */
Christopher Haster 1:24750b9ad5ef 213 typedef struct {
Christopher Haster 1:24750b9ad5ef 214 /** Information about the associated cipher */
Christopher Haster 1:24750b9ad5ef 215 const mbedtls_cipher_info_t *cipher_info;
Christopher Haster 1:24750b9ad5ef 216
Christopher Haster 1:24750b9ad5ef 217 /** Key length to use */
Christopher Haster 1:24750b9ad5ef 218 int key_bitlen;
Christopher Haster 1:24750b9ad5ef 219
Christopher Haster 1:24750b9ad5ef 220 /** Operation that the context's key has been initialised for */
Christopher Haster 1:24750b9ad5ef 221 mbedtls_operation_t operation;
Christopher Haster 1:24750b9ad5ef 222
Christopher Haster 1:24750b9ad5ef 223 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
Christopher Haster 1:24750b9ad5ef 224 /** Padding functions to use, if relevant for cipher mode */
Christopher Haster 1:24750b9ad5ef 225 void (*add_padding)( unsigned char *output, size_t olen, size_t data_len );
Christopher Haster 1:24750b9ad5ef 226 int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len );
Christopher Haster 1:24750b9ad5ef 227 #endif
Christopher Haster 1:24750b9ad5ef 228
Christopher Haster 1:24750b9ad5ef 229 /** Buffer for data that hasn't been encrypted yet */
Christopher Haster 1:24750b9ad5ef 230 unsigned char unprocessed_data[MBEDTLS_MAX_BLOCK_LENGTH];
Christopher Haster 1:24750b9ad5ef 231
Christopher Haster 1:24750b9ad5ef 232 /** Number of bytes that still need processing */
Christopher Haster 1:24750b9ad5ef 233 size_t unprocessed_len;
Christopher Haster 1:24750b9ad5ef 234
Christopher Haster 1:24750b9ad5ef 235 /** Current IV or NONCE_COUNTER for CTR-mode */
Christopher Haster 1:24750b9ad5ef 236 unsigned char iv[MBEDTLS_MAX_IV_LENGTH];
Christopher Haster 1:24750b9ad5ef 237
Christopher Haster 1:24750b9ad5ef 238 /** IV size in bytes (for ciphers with variable-length IVs) */
Christopher Haster 1:24750b9ad5ef 239 size_t iv_size;
Christopher Haster 1:24750b9ad5ef 240
Christopher Haster 1:24750b9ad5ef 241 /** Cipher-specific context */
Christopher Haster 1:24750b9ad5ef 242 void *cipher_ctx;
Christopher Haster 1:24750b9ad5ef 243 } mbedtls_cipher_context_t;
Christopher Haster 1:24750b9ad5ef 244
Christopher Haster 1:24750b9ad5ef 245 /**
Christopher Haster 1:24750b9ad5ef 246 * \brief Returns the list of ciphers supported by the generic cipher module.
Christopher Haster 1:24750b9ad5ef 247 *
Christopher Haster 1:24750b9ad5ef 248 * \return a statically allocated array of ciphers, the last entry
Christopher Haster 1:24750b9ad5ef 249 * is 0.
Christopher Haster 1:24750b9ad5ef 250 */
Christopher Haster 1:24750b9ad5ef 251 const int *mbedtls_cipher_list( void );
Christopher Haster 1:24750b9ad5ef 252
Christopher Haster 1:24750b9ad5ef 253 /**
Christopher Haster 1:24750b9ad5ef 254 * \brief Returns the cipher information structure associated
Christopher Haster 1:24750b9ad5ef 255 * with the given cipher name.
Christopher Haster 1:24750b9ad5ef 256 *
Christopher Haster 1:24750b9ad5ef 257 * \param cipher_name Name of the cipher to search for.
Christopher Haster 1:24750b9ad5ef 258 *
Christopher Haster 1:24750b9ad5ef 259 * \return the cipher information structure associated with the
Christopher Haster 1:24750b9ad5ef 260 * given cipher_name, or NULL if not found.
Christopher Haster 1:24750b9ad5ef 261 */
Christopher Haster 1:24750b9ad5ef 262 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name );
Christopher Haster 1:24750b9ad5ef 263
Christopher Haster 1:24750b9ad5ef 264 /**
Christopher Haster 1:24750b9ad5ef 265 * \brief Returns the cipher information structure associated
Christopher Haster 1:24750b9ad5ef 266 * with the given cipher type.
Christopher Haster 1:24750b9ad5ef 267 *
Christopher Haster 1:24750b9ad5ef 268 * \param cipher_type Type of the cipher to search for.
Christopher Haster 1:24750b9ad5ef 269 *
Christopher Haster 1:24750b9ad5ef 270 * \return the cipher information structure associated with the
Christopher Haster 1:24750b9ad5ef 271 * given cipher_type, or NULL if not found.
Christopher Haster 1:24750b9ad5ef 272 */
Christopher Haster 1:24750b9ad5ef 273 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type( const mbedtls_cipher_type_t cipher_type );
Christopher Haster 1:24750b9ad5ef 274
Christopher Haster 1:24750b9ad5ef 275 /**
Christopher Haster 1:24750b9ad5ef 276 * \brief Returns the cipher information structure associated
Christopher Haster 1:24750b9ad5ef 277 * with the given cipher id, key size and mode.
Christopher Haster 1:24750b9ad5ef 278 *
Christopher Haster 1:24750b9ad5ef 279 * \param cipher_id Id of the cipher to search for
Christopher Haster 1:24750b9ad5ef 280 * (e.g. MBEDTLS_CIPHER_ID_AES)
Christopher Haster 1:24750b9ad5ef 281 * \param key_bitlen Length of the key in bits
Christopher Haster 1:24750b9ad5ef 282 * \param mode Cipher mode (e.g. MBEDTLS_MODE_CBC)
Christopher Haster 1:24750b9ad5ef 283 *
Christopher Haster 1:24750b9ad5ef 284 * \return the cipher information structure associated with the
Christopher Haster 1:24750b9ad5ef 285 * given cipher_type, or NULL if not found.
Christopher Haster 1:24750b9ad5ef 286 */
Christopher Haster 1:24750b9ad5ef 287 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_values( const mbedtls_cipher_id_t cipher_id,
Christopher Haster 1:24750b9ad5ef 288 int key_bitlen,
Christopher Haster 1:24750b9ad5ef 289 const mbedtls_cipher_mode_t mode );
Christopher Haster 1:24750b9ad5ef 290
Christopher Haster 1:24750b9ad5ef 291 /**
Christopher Haster 1:24750b9ad5ef 292 * \brief Initialize a cipher_context (as NONE)
Christopher Haster 1:24750b9ad5ef 293 */
Christopher Haster 1:24750b9ad5ef 294 void mbedtls_cipher_init( mbedtls_cipher_context_t *ctx );
Christopher Haster 1:24750b9ad5ef 295
Christopher Haster 1:24750b9ad5ef 296 /**
Christopher Haster 1:24750b9ad5ef 297 * \brief Free and clear the cipher-specific context of ctx.
Christopher Haster 1:24750b9ad5ef 298 * Freeing ctx itself remains the responsibility of the
Christopher Haster 1:24750b9ad5ef 299 * caller.
Christopher Haster 1:24750b9ad5ef 300 */
Christopher Haster 1:24750b9ad5ef 301 void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx );
Christopher Haster 1:24750b9ad5ef 302
Christopher Haster 1:24750b9ad5ef 303 /**
Christopher Haster 1:24750b9ad5ef 304 * \brief Initialises and fills the cipher context structure with
Christopher Haster 1:24750b9ad5ef 305 * the appropriate values.
Christopher Haster 1:24750b9ad5ef 306 *
Christopher Haster 1:24750b9ad5ef 307 * \note Currently also clears structure. In future versions you
Christopher Haster 1:24750b9ad5ef 308 * will be required to call mbedtls_cipher_init() on the structure
Christopher Haster 1:24750b9ad5ef 309 * first.
Christopher Haster 1:24750b9ad5ef 310 *
Christopher Haster 1:24750b9ad5ef 311 * \param ctx context to initialise. May not be NULL.
Christopher Haster 1:24750b9ad5ef 312 * \param cipher_info cipher to use.
Christopher Haster 1:24750b9ad5ef 313 *
Christopher Haster 1:24750b9ad5ef 314 * \return 0 on success,
Christopher Haster 1:24750b9ad5ef 315 * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure,
Christopher Haster 1:24750b9ad5ef 316 * MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
Christopher Haster 1:24750b9ad5ef 317 * cipher-specific context failed.
Christopher Haster 1:24750b9ad5ef 318 */
Christopher Haster 1:24750b9ad5ef 319 int mbedtls_cipher_setup( mbedtls_cipher_context_t *ctx, const mbedtls_cipher_info_t *cipher_info );
Christopher Haster 1:24750b9ad5ef 320
Christopher Haster 1:24750b9ad5ef 321 /**
Christopher Haster 1:24750b9ad5ef 322 * \brief Returns the block size of the given cipher.
Christopher Haster 1:24750b9ad5ef 323 *
Christopher Haster 1:24750b9ad5ef 324 * \param ctx cipher's context. Must have been initialised.
Christopher Haster 1:24750b9ad5ef 325 *
Christopher Haster 1:24750b9ad5ef 326 * \return size of the cipher's blocks, or 0 if ctx has not been
Christopher Haster 1:24750b9ad5ef 327 * initialised.
Christopher Haster 1:24750b9ad5ef 328 */
Christopher Haster 1:24750b9ad5ef 329 static inline unsigned int mbedtls_cipher_get_block_size( const mbedtls_cipher_context_t *ctx )
Christopher Haster 1:24750b9ad5ef 330 {
Christopher Haster 1:24750b9ad5ef 331 if( NULL == ctx || NULL == ctx->cipher_info )
Christopher Haster 1:24750b9ad5ef 332 return 0;
Christopher Haster 1:24750b9ad5ef 333
Christopher Haster 1:24750b9ad5ef 334 return ctx->cipher_info->block_size;
Christopher Haster 1:24750b9ad5ef 335 }
Christopher Haster 1:24750b9ad5ef 336
Christopher Haster 1:24750b9ad5ef 337 /**
Christopher Haster 1:24750b9ad5ef 338 * \brief Returns the mode of operation for the cipher.
Christopher Haster 1:24750b9ad5ef 339 * (e.g. MBEDTLS_MODE_CBC)
Christopher Haster 1:24750b9ad5ef 340 *
Christopher Haster 1:24750b9ad5ef 341 * \param ctx cipher's context. Must have been initialised.
Christopher Haster 1:24750b9ad5ef 342 *
Christopher Haster 1:24750b9ad5ef 343 * \return mode of operation, or MBEDTLS_MODE_NONE if ctx
Christopher Haster 1:24750b9ad5ef 344 * has not been initialised.
Christopher Haster 1:24750b9ad5ef 345 */
Christopher Haster 1:24750b9ad5ef 346 static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtls_cipher_context_t *ctx )
Christopher Haster 1:24750b9ad5ef 347 {
Christopher Haster 1:24750b9ad5ef 348 if( NULL == ctx || NULL == ctx->cipher_info )
Christopher Haster 1:24750b9ad5ef 349 return MBEDTLS_MODE_NONE;
Christopher Haster 1:24750b9ad5ef 350
Christopher Haster 1:24750b9ad5ef 351 return ctx->cipher_info->mode;
Christopher Haster 1:24750b9ad5ef 352 }
Christopher Haster 1:24750b9ad5ef 353
Christopher Haster 1:24750b9ad5ef 354 /**
Christopher Haster 1:24750b9ad5ef 355 * \brief Returns the size of the cipher's IV/NONCE in bytes.
Christopher Haster 1:24750b9ad5ef 356 *
Christopher Haster 1:24750b9ad5ef 357 * \param ctx cipher's context. Must have been initialised.
Christopher Haster 1:24750b9ad5ef 358 *
Christopher Haster 1:24750b9ad5ef 359 * \return If IV has not been set yet: (recommended) IV size
Christopher Haster 1:24750b9ad5ef 360 * (0 for ciphers not using IV/NONCE).
Christopher Haster 1:24750b9ad5ef 361 * If IV has already been set: actual size.
Christopher Haster 1:24750b9ad5ef 362 */
Christopher Haster 1:24750b9ad5ef 363 static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ctx )
Christopher Haster 1:24750b9ad5ef 364 {
Christopher Haster 1:24750b9ad5ef 365 if( NULL == ctx || NULL == ctx->cipher_info )
Christopher Haster 1:24750b9ad5ef 366 return 0;
Christopher Haster 1:24750b9ad5ef 367
Christopher Haster 1:24750b9ad5ef 368 if( ctx->iv_size != 0 )
Christopher Haster 1:24750b9ad5ef 369 return (int) ctx->iv_size;
Christopher Haster 1:24750b9ad5ef 370
Christopher Haster 1:24750b9ad5ef 371 return (int) ctx->cipher_info->iv_size;
Christopher Haster 1:24750b9ad5ef 372 }
Christopher Haster 1:24750b9ad5ef 373
Christopher Haster 1:24750b9ad5ef 374 /**
Christopher Haster 1:24750b9ad5ef 375 * \brief Returns the type of the given cipher.
Christopher Haster 1:24750b9ad5ef 376 *
Christopher Haster 1:24750b9ad5ef 377 * \param ctx cipher's context. Must have been initialised.
Christopher Haster 1:24750b9ad5ef 378 *
Christopher Haster 1:24750b9ad5ef 379 * \return type of the cipher, or MBEDTLS_CIPHER_NONE if ctx has
Christopher Haster 1:24750b9ad5ef 380 * not been initialised.
Christopher Haster 1:24750b9ad5ef 381 */
Christopher Haster 1:24750b9ad5ef 382 static inline mbedtls_cipher_type_t mbedtls_cipher_get_type( const mbedtls_cipher_context_t *ctx )
Christopher Haster 1:24750b9ad5ef 383 {
Christopher Haster 1:24750b9ad5ef 384 if( NULL == ctx || NULL == ctx->cipher_info )
Christopher Haster 1:24750b9ad5ef 385 return MBEDTLS_CIPHER_NONE;
Christopher Haster 1:24750b9ad5ef 386
Christopher Haster 1:24750b9ad5ef 387 return ctx->cipher_info->type;
Christopher Haster 1:24750b9ad5ef 388 }
Christopher Haster 1:24750b9ad5ef 389
Christopher Haster 1:24750b9ad5ef 390 /**
Christopher Haster 1:24750b9ad5ef 391 * \brief Returns the name of the given cipher, as a string.
Christopher Haster 1:24750b9ad5ef 392 *
Christopher Haster 1:24750b9ad5ef 393 * \param ctx cipher's context. Must have been initialised.
Christopher Haster 1:24750b9ad5ef 394 *
Christopher Haster 1:24750b9ad5ef 395 * \return name of the cipher, or NULL if ctx was not initialised.
Christopher Haster 1:24750b9ad5ef 396 */
Christopher Haster 1:24750b9ad5ef 397 static inline const char *mbedtls_cipher_get_name( const mbedtls_cipher_context_t *ctx )
Christopher Haster 1:24750b9ad5ef 398 {
Christopher Haster 1:24750b9ad5ef 399 if( NULL == ctx || NULL == ctx->cipher_info )
Christopher Haster 1:24750b9ad5ef 400 return 0;
Christopher Haster 1:24750b9ad5ef 401
Christopher Haster 1:24750b9ad5ef 402 return ctx->cipher_info->name;
Christopher Haster 1:24750b9ad5ef 403 }
Christopher Haster 1:24750b9ad5ef 404
Christopher Haster 1:24750b9ad5ef 405 /**
Christopher Haster 1:24750b9ad5ef 406 * \brief Returns the key length of the cipher.
Christopher Haster 1:24750b9ad5ef 407 *
Christopher Haster 1:24750b9ad5ef 408 * \param ctx cipher's context. Must have been initialised.
Christopher Haster 1:24750b9ad5ef 409 *
Christopher Haster 1:24750b9ad5ef 410 * \return cipher's key length, in bits, or
Christopher Haster 1:24750b9ad5ef 411 * MBEDTLS_KEY_LENGTH_NONE if ctx has not been
Christopher Haster 1:24750b9ad5ef 412 * initialised.
Christopher Haster 1:24750b9ad5ef 413 */
Christopher Haster 1:24750b9ad5ef 414 static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t *ctx )
Christopher Haster 1:24750b9ad5ef 415 {
Christopher Haster 1:24750b9ad5ef 416 if( NULL == ctx || NULL == ctx->cipher_info )
Christopher Haster 1:24750b9ad5ef 417 return MBEDTLS_KEY_LENGTH_NONE;
Christopher Haster 1:24750b9ad5ef 418
Christopher Haster 1:24750b9ad5ef 419 return (int) ctx->cipher_info->key_bitlen;
Christopher Haster 1:24750b9ad5ef 420 }
Christopher Haster 1:24750b9ad5ef 421
Christopher Haster 1:24750b9ad5ef 422 /**
Christopher Haster 1:24750b9ad5ef 423 * \brief Returns the operation of the given cipher.
Christopher Haster 1:24750b9ad5ef 424 *
Christopher Haster 1:24750b9ad5ef 425 * \param ctx cipher's context. Must have been initialised.
Christopher Haster 1:24750b9ad5ef 426 *
Christopher Haster 1:24750b9ad5ef 427 * \return operation (MBEDTLS_ENCRYPT or MBEDTLS_DECRYPT),
Christopher Haster 1:24750b9ad5ef 428 * or MBEDTLS_OPERATION_NONE if ctx has not been
Christopher Haster 1:24750b9ad5ef 429 * initialised.
Christopher Haster 1:24750b9ad5ef 430 */
Christopher Haster 1:24750b9ad5ef 431 static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_cipher_context_t *ctx )
Christopher Haster 1:24750b9ad5ef 432 {
Christopher Haster 1:24750b9ad5ef 433 if( NULL == ctx || NULL == ctx->cipher_info )
Christopher Haster 1:24750b9ad5ef 434 return MBEDTLS_OPERATION_NONE;
Christopher Haster 1:24750b9ad5ef 435
Christopher Haster 1:24750b9ad5ef 436 return ctx->operation;
Christopher Haster 1:24750b9ad5ef 437 }
Christopher Haster 1:24750b9ad5ef 438
Christopher Haster 1:24750b9ad5ef 439 /**
Christopher Haster 1:24750b9ad5ef 440 * \brief Set the key to use with the given context.
Christopher Haster 1:24750b9ad5ef 441 *
Christopher Haster 1:24750b9ad5ef 442 * \param ctx generic cipher context. May not be NULL. Must have been
Christopher Haster 1:24750b9ad5ef 443 * initialised using cipher_context_from_type or
Christopher Haster 1:24750b9ad5ef 444 * cipher_context_from_string.
Christopher Haster 1:24750b9ad5ef 445 * \param key The key to use.
Christopher Haster 1:24750b9ad5ef 446 * \param key_bitlen key length to use, in bits.
Christopher Haster 1:24750b9ad5ef 447 * \param operation Operation that the key will be used for, either
Christopher Haster 1:24750b9ad5ef 448 * MBEDTLS_ENCRYPT or MBEDTLS_DECRYPT.
Christopher Haster 1:24750b9ad5ef 449 *
Christopher Haster 1:24750b9ad5ef 450 * \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
Christopher Haster 1:24750b9ad5ef 451 * parameter verification fails or a cipher specific
Christopher Haster 1:24750b9ad5ef 452 * error code.
Christopher Haster 1:24750b9ad5ef 453 */
Christopher Haster 1:24750b9ad5ef 454 int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *key,
Christopher Haster 1:24750b9ad5ef 455 int key_bitlen, const mbedtls_operation_t operation );
Christopher Haster 1:24750b9ad5ef 456
Christopher Haster 1:24750b9ad5ef 457 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
Christopher Haster 1:24750b9ad5ef 458 /**
Christopher Haster 1:24750b9ad5ef 459 * \brief Set padding mode, for cipher modes that use padding.
Christopher Haster 1:24750b9ad5ef 460 * (Default: PKCS7 padding.)
Christopher Haster 1:24750b9ad5ef 461 *
Christopher Haster 1:24750b9ad5ef 462 * \param ctx generic cipher context
Christopher Haster 1:24750b9ad5ef 463 * \param mode padding mode
Christopher Haster 1:24750b9ad5ef 464 *
Christopher Haster 1:24750b9ad5ef 465 * \returns 0 on success, MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
Christopher Haster 1:24750b9ad5ef 466 * if selected padding mode is not supported, or
Christopher Haster 1:24750b9ad5ef 467 * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
Christopher Haster 1:24750b9ad5ef 468 * does not support padding.
Christopher Haster 1:24750b9ad5ef 469 */
Christopher Haster 1:24750b9ad5ef 470 int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_cipher_padding_t mode );
Christopher Haster 1:24750b9ad5ef 471 #endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */
Christopher Haster 1:24750b9ad5ef 472
Christopher Haster 1:24750b9ad5ef 473 /**
Christopher Haster 1:24750b9ad5ef 474 * \brief Set the initialization vector (IV) or nonce
Christopher Haster 1:24750b9ad5ef 475 *
Christopher Haster 1:24750b9ad5ef 476 * \param ctx generic cipher context
Christopher Haster 1:24750b9ad5ef 477 * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
Christopher Haster 1:24750b9ad5ef 478 * \param iv_len IV length for ciphers with variable-size IV;
Christopher Haster 1:24750b9ad5ef 479 * discarded by ciphers with fixed-size IV.
Christopher Haster 1:24750b9ad5ef 480 *
Christopher Haster 1:24750b9ad5ef 481 * \returns 0 on success, or MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
Christopher Haster 1:24750b9ad5ef 482 *
Christopher Haster 1:24750b9ad5ef 483 * \note Some ciphers don't use IVs nor NONCE. For these
Christopher Haster 1:24750b9ad5ef 484 * ciphers, this function has no effect.
Christopher Haster 1:24750b9ad5ef 485 */
Christopher Haster 1:24750b9ad5ef 486 int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx,
Christopher Haster 1:24750b9ad5ef 487 const unsigned char *iv, size_t iv_len );
Christopher Haster 1:24750b9ad5ef 488
Christopher Haster 1:24750b9ad5ef 489 /**
Christopher Haster 1:24750b9ad5ef 490 * \brief Finish preparation of the given context
Christopher Haster 1:24750b9ad5ef 491 *
Christopher Haster 1:24750b9ad5ef 492 * \param ctx generic cipher context
Christopher Haster 1:24750b9ad5ef 493 *
Christopher Haster 1:24750b9ad5ef 494 * \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
Christopher Haster 1:24750b9ad5ef 495 * if parameter verification fails.
Christopher Haster 1:24750b9ad5ef 496 */
Christopher Haster 1:24750b9ad5ef 497 int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx );
Christopher Haster 1:24750b9ad5ef 498
Christopher Haster 1:24750b9ad5ef 499 #if defined(MBEDTLS_GCM_C)
Christopher Haster 1:24750b9ad5ef 500 /**
Christopher Haster 1:24750b9ad5ef 501 * \brief Add additional data (for AEAD ciphers).
Christopher Haster 1:24750b9ad5ef 502 * Currently only supported with GCM.
Christopher Haster 1:24750b9ad5ef 503 * Must be called exactly once, after mbedtls_cipher_reset().
Christopher Haster 1:24750b9ad5ef 504 *
Christopher Haster 1:24750b9ad5ef 505 * \param ctx generic cipher context
Christopher Haster 1:24750b9ad5ef 506 * \param ad Additional data to use.
Christopher Haster 1:24750b9ad5ef 507 * \param ad_len Length of ad.
Christopher Haster 1:24750b9ad5ef 508 *
Christopher Haster 1:24750b9ad5ef 509 * \return 0 on success, or a specific error code.
Christopher Haster 1:24750b9ad5ef 510 */
Christopher Haster 1:24750b9ad5ef 511 int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx,
Christopher Haster 1:24750b9ad5ef 512 const unsigned char *ad, size_t ad_len );
Christopher Haster 1:24750b9ad5ef 513 #endif /* MBEDTLS_GCM_C */
Christopher Haster 1:24750b9ad5ef 514
Christopher Haster 1:24750b9ad5ef 515 /**
Christopher Haster 1:24750b9ad5ef 516 * \brief Generic cipher update function. Encrypts/decrypts
Christopher Haster 1:24750b9ad5ef 517 * using the given cipher context. Writes as many block
Christopher Haster 1:24750b9ad5ef 518 * size'd blocks of data as possible to output. Any data
Christopher Haster 1:24750b9ad5ef 519 * that cannot be written immediately will either be added
Christopher Haster 1:24750b9ad5ef 520 * to the next block, or flushed when cipher_final is
Christopher Haster 1:24750b9ad5ef 521 * called.
Christopher Haster 1:24750b9ad5ef 522 * Exception: for MBEDTLS_MODE_ECB, expects single block
Christopher Haster 1:24750b9ad5ef 523 * in size (e.g. 16 bytes for AES)
Christopher Haster 1:24750b9ad5ef 524 *
Christopher Haster 1:24750b9ad5ef 525 * \param ctx generic cipher context
Christopher Haster 1:24750b9ad5ef 526 * \param input buffer holding the input data
Christopher Haster 1:24750b9ad5ef 527 * \param ilen length of the input data
Christopher Haster 1:24750b9ad5ef 528 * \param output buffer for the output data. Should be able to hold at
Christopher Haster 1:24750b9ad5ef 529 * least ilen + block_size. Cannot be the same buffer as
Christopher Haster 1:24750b9ad5ef 530 * input!
Christopher Haster 1:24750b9ad5ef 531 * \param olen length of the output data, will be filled with the
Christopher Haster 1:24750b9ad5ef 532 * actual number of bytes written.
Christopher Haster 1:24750b9ad5ef 533 *
Christopher Haster 1:24750b9ad5ef 534 * \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
Christopher Haster 1:24750b9ad5ef 535 * parameter verification fails,
Christopher Haster 1:24750b9ad5ef 536 * MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an
Christopher Haster 1:24750b9ad5ef 537 * unsupported mode for a cipher or a cipher specific
Christopher Haster 1:24750b9ad5ef 538 * error code.
Christopher Haster 1:24750b9ad5ef 539 *
Christopher Haster 1:24750b9ad5ef 540 * \note If the underlying cipher is GCM, all calls to this
Christopher Haster 1:24750b9ad5ef 541 * function, except the last one before mbedtls_cipher_finish(),
Christopher Haster 1:24750b9ad5ef 542 * must have ilen a multiple of the block size.
Christopher Haster 1:24750b9ad5ef 543 */
Christopher Haster 1:24750b9ad5ef 544 int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input,
Christopher Haster 1:24750b9ad5ef 545 size_t ilen, unsigned char *output, size_t *olen );
Christopher Haster 1:24750b9ad5ef 546
Christopher Haster 1:24750b9ad5ef 547 /**
Christopher Haster 1:24750b9ad5ef 548 * \brief Generic cipher finalisation function. If data still
Christopher Haster 1:24750b9ad5ef 549 * needs to be flushed from an incomplete block, data
Christopher Haster 1:24750b9ad5ef 550 * contained within it will be padded with the size of
Christopher Haster 1:24750b9ad5ef 551 * the last block, and written to the output buffer.
Christopher Haster 1:24750b9ad5ef 552 *
Christopher Haster 1:24750b9ad5ef 553 * \param ctx Generic cipher context
Christopher Haster 1:24750b9ad5ef 554 * \param output buffer to write data to. Needs block_size available.
Christopher Haster 1:24750b9ad5ef 555 * \param olen length of the data written to the output buffer.
Christopher Haster 1:24750b9ad5ef 556 *
Christopher Haster 1:24750b9ad5ef 557 * \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
Christopher Haster 1:24750b9ad5ef 558 * parameter verification fails,
Christopher Haster 1:24750b9ad5ef 559 * MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
Christopher Haster 1:24750b9ad5ef 560 * expected a full block but was not provided one,
Christopher Haster 1:24750b9ad5ef 561 * MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
Christopher Haster 1:24750b9ad5ef 562 * while decrypting or a cipher specific error code.
Christopher Haster 1:24750b9ad5ef 563 */
Christopher Haster 1:24750b9ad5ef 564 int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx,
Christopher Haster 1:24750b9ad5ef 565 unsigned char *output, size_t *olen );
Christopher Haster 1:24750b9ad5ef 566
Christopher Haster 1:24750b9ad5ef 567 #if defined(MBEDTLS_GCM_C)
Christopher Haster 1:24750b9ad5ef 568 /**
Christopher Haster 1:24750b9ad5ef 569 * \brief Write tag for AEAD ciphers.
Christopher Haster 1:24750b9ad5ef 570 * Currently only supported with GCM.
Christopher Haster 1:24750b9ad5ef 571 * Must be called after mbedtls_cipher_finish().
Christopher Haster 1:24750b9ad5ef 572 *
Christopher Haster 1:24750b9ad5ef 573 * \param ctx Generic cipher context
Christopher Haster 1:24750b9ad5ef 574 * \param tag buffer to write the tag
Christopher Haster 1:24750b9ad5ef 575 * \param tag_len Length of the tag to write
Christopher Haster 1:24750b9ad5ef 576 *
Christopher Haster 1:24750b9ad5ef 577 * \return 0 on success, or a specific error code.
Christopher Haster 1:24750b9ad5ef 578 */
Christopher Haster 1:24750b9ad5ef 579 int mbedtls_cipher_write_tag( mbedtls_cipher_context_t *ctx,
Christopher Haster 1:24750b9ad5ef 580 unsigned char *tag, size_t tag_len );
Christopher Haster 1:24750b9ad5ef 581
Christopher Haster 1:24750b9ad5ef 582 /**
Christopher Haster 1:24750b9ad5ef 583 * \brief Check tag for AEAD ciphers.
Christopher Haster 1:24750b9ad5ef 584 * Currently only supported with GCM.
Christopher Haster 1:24750b9ad5ef 585 * Must be called after mbedtls_cipher_finish().
Christopher Haster 1:24750b9ad5ef 586 *
Christopher Haster 1:24750b9ad5ef 587 * \param ctx Generic cipher context
Christopher Haster 1:24750b9ad5ef 588 * \param tag Buffer holding the tag
Christopher Haster 1:24750b9ad5ef 589 * \param tag_len Length of the tag to check
Christopher Haster 1:24750b9ad5ef 590 *
Christopher Haster 1:24750b9ad5ef 591 * \return 0 on success, or a specific error code.
Christopher Haster 1:24750b9ad5ef 592 */
Christopher Haster 1:24750b9ad5ef 593 int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx,
Christopher Haster 1:24750b9ad5ef 594 const unsigned char *tag, size_t tag_len );
Christopher Haster 1:24750b9ad5ef 595 #endif /* MBEDTLS_GCM_C */
Christopher Haster 1:24750b9ad5ef 596
Christopher Haster 1:24750b9ad5ef 597 /**
Christopher Haster 1:24750b9ad5ef 598 * \brief Generic all-in-one encryption/decryption
Christopher Haster 1:24750b9ad5ef 599 * (for all ciphers except AEAD constructs).
Christopher Haster 1:24750b9ad5ef 600 *
Christopher Haster 1:24750b9ad5ef 601 * \param ctx generic cipher context
Christopher Haster 1:24750b9ad5ef 602 * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
Christopher Haster 1:24750b9ad5ef 603 * \param iv_len IV length for ciphers with variable-size IV;
Christopher Haster 1:24750b9ad5ef 604 * discarded by ciphers with fixed-size IV.
Christopher Haster 1:24750b9ad5ef 605 * \param input buffer holding the input data
Christopher Haster 1:24750b9ad5ef 606 * \param ilen length of the input data
Christopher Haster 1:24750b9ad5ef 607 * \param output buffer for the output data. Should be able to hold at
Christopher Haster 1:24750b9ad5ef 608 * least ilen + block_size. Cannot be the same buffer as
Christopher Haster 1:24750b9ad5ef 609 * input!
Christopher Haster 1:24750b9ad5ef 610 * \param olen length of the output data, will be filled with the
Christopher Haster 1:24750b9ad5ef 611 * actual number of bytes written.
Christopher Haster 1:24750b9ad5ef 612 *
Christopher Haster 1:24750b9ad5ef 613 * \note Some ciphers don't use IVs nor NONCE. For these
Christopher Haster 1:24750b9ad5ef 614 * ciphers, use iv = NULL and iv_len = 0.
Christopher Haster 1:24750b9ad5ef 615 *
Christopher Haster 1:24750b9ad5ef 616 * \returns 0 on success, or
Christopher Haster 1:24750b9ad5ef 617 * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
Christopher Haster 1:24750b9ad5ef 618 * MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
Christopher Haster 1:24750b9ad5ef 619 * expected a full block but was not provided one, or
Christopher Haster 1:24750b9ad5ef 620 * MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
Christopher Haster 1:24750b9ad5ef 621 * while decrypting, or
Christopher Haster 1:24750b9ad5ef 622 * a cipher specific error code.
Christopher Haster 1:24750b9ad5ef 623 */
Christopher Haster 1:24750b9ad5ef 624 int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx,
Christopher Haster 1:24750b9ad5ef 625 const unsigned char *iv, size_t iv_len,
Christopher Haster 1:24750b9ad5ef 626 const unsigned char *input, size_t ilen,
Christopher Haster 1:24750b9ad5ef 627 unsigned char *output, size_t *olen );
Christopher Haster 1:24750b9ad5ef 628
Christopher Haster 1:24750b9ad5ef 629 #if defined(MBEDTLS_CIPHER_MODE_AEAD)
Christopher Haster 1:24750b9ad5ef 630 /**
Christopher Haster 1:24750b9ad5ef 631 * \brief Generic autenticated encryption (AEAD ciphers).
Christopher Haster 1:24750b9ad5ef 632 *
Christopher Haster 1:24750b9ad5ef 633 * \param ctx generic cipher context
Christopher Haster 1:24750b9ad5ef 634 * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
Christopher Haster 1:24750b9ad5ef 635 * \param iv_len IV length for ciphers with variable-size IV;
Christopher Haster 1:24750b9ad5ef 636 * discarded by ciphers with fixed-size IV.
Christopher Haster 1:24750b9ad5ef 637 * \param ad Additional data to authenticate.
Christopher Haster 1:24750b9ad5ef 638 * \param ad_len Length of ad.
Christopher Haster 1:24750b9ad5ef 639 * \param input buffer holding the input data
Christopher Haster 1:24750b9ad5ef 640 * \param ilen length of the input data
Christopher Haster 1:24750b9ad5ef 641 * \param output buffer for the output data.
Christopher Haster 1:24750b9ad5ef 642 * Should be able to hold at least ilen.
Christopher Haster 1:24750b9ad5ef 643 * \param olen length of the output data, will be filled with the
Christopher Haster 1:24750b9ad5ef 644 * actual number of bytes written.
Christopher Haster 1:24750b9ad5ef 645 * \param tag buffer for the authentication tag
Christopher Haster 1:24750b9ad5ef 646 * \param tag_len desired tag length
Christopher Haster 1:24750b9ad5ef 647 *
Christopher Haster 1:24750b9ad5ef 648 * \returns 0 on success, or
Christopher Haster 1:24750b9ad5ef 649 * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
Christopher Haster 1:24750b9ad5ef 650 * a cipher specific error code.
Christopher Haster 1:24750b9ad5ef 651 */
Christopher Haster 1:24750b9ad5ef 652 int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx,
Christopher Haster 1:24750b9ad5ef 653 const unsigned char *iv, size_t iv_len,
Christopher Haster 1:24750b9ad5ef 654 const unsigned char *ad, size_t ad_len,
Christopher Haster 1:24750b9ad5ef 655 const unsigned char *input, size_t ilen,
Christopher Haster 1:24750b9ad5ef 656 unsigned char *output, size_t *olen,
Christopher Haster 1:24750b9ad5ef 657 unsigned char *tag, size_t tag_len );
Christopher Haster 1:24750b9ad5ef 658
Christopher Haster 1:24750b9ad5ef 659 /**
Christopher Haster 1:24750b9ad5ef 660 * \brief Generic autenticated decryption (AEAD ciphers).
Christopher Haster 1:24750b9ad5ef 661 *
Christopher Haster 1:24750b9ad5ef 662 * \param ctx generic cipher context
Christopher Haster 1:24750b9ad5ef 663 * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
Christopher Haster 1:24750b9ad5ef 664 * \param iv_len IV length for ciphers with variable-size IV;
Christopher Haster 1:24750b9ad5ef 665 * discarded by ciphers with fixed-size IV.
Christopher Haster 1:24750b9ad5ef 666 * \param ad Additional data to be authenticated.
Christopher Haster 1:24750b9ad5ef 667 * \param ad_len Length of ad.
Christopher Haster 1:24750b9ad5ef 668 * \param input buffer holding the input data
Christopher Haster 1:24750b9ad5ef 669 * \param ilen length of the input data
Christopher Haster 1:24750b9ad5ef 670 * \param output buffer for the output data.
Christopher Haster 1:24750b9ad5ef 671 * Should be able to hold at least ilen.
Christopher Haster 1:24750b9ad5ef 672 * \param olen length of the output data, will be filled with the
Christopher Haster 1:24750b9ad5ef 673 * actual number of bytes written.
Christopher Haster 1:24750b9ad5ef 674 * \param tag buffer holding the authentication tag
Christopher Haster 1:24750b9ad5ef 675 * \param tag_len length of the authentication tag
Christopher Haster 1:24750b9ad5ef 676 *
Christopher Haster 1:24750b9ad5ef 677 * \returns 0 on success, or
Christopher Haster 1:24750b9ad5ef 678 * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
Christopher Haster 1:24750b9ad5ef 679 * MBEDTLS_ERR_CIPHER_AUTH_FAILED if data isn't authentic,
Christopher Haster 1:24750b9ad5ef 680 * or a cipher specific error code.
Christopher Haster 1:24750b9ad5ef 681 *
Christopher Haster 1:24750b9ad5ef 682 * \note If the data is not authentic, then the output buffer
Christopher Haster 1:24750b9ad5ef 683 * is zeroed out to prevent the unauthentic plaintext to
Christopher Haster 1:24750b9ad5ef 684 * be used by mistake, making this interface safer.
Christopher Haster 1:24750b9ad5ef 685 */
Christopher Haster 1:24750b9ad5ef 686 int mbedtls_cipher_auth_decrypt( mbedtls_cipher_context_t *ctx,
Christopher Haster 1:24750b9ad5ef 687 const unsigned char *iv, size_t iv_len,
Christopher Haster 1:24750b9ad5ef 688 const unsigned char *ad, size_t ad_len,
Christopher Haster 1:24750b9ad5ef 689 const unsigned char *input, size_t ilen,
Christopher Haster 1:24750b9ad5ef 690 unsigned char *output, size_t *olen,
Christopher Haster 1:24750b9ad5ef 691 const unsigned char *tag, size_t tag_len );
Christopher Haster 1:24750b9ad5ef 692 #endif /* MBEDTLS_CIPHER_MODE_AEAD */
Christopher Haster 1:24750b9ad5ef 693
Christopher Haster 1:24750b9ad5ef 694 #ifdef __cplusplus
Christopher Haster 1:24750b9ad5ef 695 }
Christopher Haster 1:24750b9ad5ef 696 #endif
Christopher Haster 1:24750b9ad5ef 697
Christopher Haster 1:24750b9ad5ef 698 #endif /* MBEDTLS_CIPHER_H */