| 1 | /** |
| 2 | * \file cipher.h |
| 3 | * |
| 4 | * \brief This file contains an abstraction interface for use with the cipher |
| 5 | * primitives provided by the library. It provides a common interface to all of |
| 6 | * the available cipher operations. |
| 7 | * |
| 8 | * \author Adriaan de Jong <dejong@fox-it.com> |
| 9 | */ |
| 10 | /* |
| 11 | * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved |
| 12 | * SPDX-License-Identifier: GPL-2.0 |
| 13 | * |
| 14 | * This program is free software; you can redistribute it and/or modify |
| 15 | * it under the terms of the GNU General Public License as published by |
| 16 | * the Free Software Foundation; either version 2 of the License, or |
| 17 | * (at your option) any later version. |
| 18 | * |
| 19 | * This program is distributed in the hope that it will be useful, |
| 20 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 21 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 22 | * GNU General Public License for more details. |
| 23 | * |
| 24 | * You should have received a copy of the GNU General Public License along |
| 25 | * with this program; if not, write to the Free Software Foundation, Inc., |
| 26 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. |
| 27 | * |
| 28 | * This file is part of Mbed TLS (https://tls.mbed.org) |
| 29 | */ |
| 30 | |
| 31 | #ifndef MBEDTLS_CIPHER_H |
| 32 | #define MBEDTLS_CIPHER_H |
| 33 | |
| 34 | #if !defined(MBEDTLS_CONFIG_FILE) |
| 35 | #include "config.h" |
| 36 | #else |
| 37 | #include MBEDTLS_CONFIG_FILE |
| 38 | #endif |
| 39 | |
| 40 | #include <stddef.h> |
| 41 | |
| 42 | #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CCM_C) || defined(MBEDTLS_CHACHAPOLY_C) |
| 43 | #define MBEDTLS_CIPHER_MODE_AEAD |
| 44 | #endif |
| 45 | |
| 46 | #if defined(MBEDTLS_CIPHER_MODE_CBC) |
| 47 | #define MBEDTLS_CIPHER_MODE_WITH_PADDING |
| 48 | #endif |
| 49 | |
| 50 | #if defined(MBEDTLS_ARC4_C) || defined(MBEDTLS_CIPHER_NULL_CIPHER) || \ |
| 51 | defined(MBEDTLS_CHACHA20_C) |
| 52 | #define MBEDTLS_CIPHER_MODE_STREAM |
| 53 | #endif |
| 54 | |
| 55 | #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \ |
| 56 | !defined(inline) && !defined(__cplusplus) |
| 57 | #define inline __inline |
| 58 | #endif |
| 59 | |
| 60 | #define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080 /**< The selected feature is not available. */ |
| 61 | #define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA -0x6100 /**< Bad input parameters. */ |
| 62 | #define MBEDTLS_ERR_CIPHER_ALLOC_FAILED -0x6180 /**< Failed to allocate memory. */ |
| 63 | #define MBEDTLS_ERR_CIPHER_INVALID_PADDING -0x6200 /**< Input data contains invalid padding and is rejected. */ |
| 64 | #define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280 /**< Decryption of block requires a full block. */ |
| 65 | #define MBEDTLS_ERR_CIPHER_AUTH_FAILED -0x6300 /**< Authentication failed (for AEAD modes). */ |
| 66 | #define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT -0x6380 /**< The context is invalid. For example, because it was freed. */ |
| 67 | #define MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED -0x6400 /**< Cipher hardware accelerator failed. */ |
| 68 | |
| 69 | #define MBEDTLS_CIPHER_VARIABLE_IV_LEN 0x01 /**< Cipher accepts IVs of variable length. */ |
| 70 | #define MBEDTLS_CIPHER_VARIABLE_KEY_LEN 0x02 /**< Cipher accepts keys of variable length. */ |
| 71 | |
| 72 | #ifdef __cplusplus |
| 73 | extern "C" { |
| 74 | #endif |
| 75 | |
| 76 | /** |
| 77 | * \brief Supported cipher types. |
| 78 | * |
| 79 | * \warning RC4 and DES are considered weak ciphers and their use |
| 80 | * constitutes a security risk. Arm recommends considering stronger |
| 81 | * ciphers instead. |
| 82 | */ |
| 83 | typedef enum { |
| 84 | MBEDTLS_CIPHER_ID_NONE = 0, /**< Placeholder to mark the end of cipher ID lists. */ |
| 85 | MBEDTLS_CIPHER_ID_NULL, /**< The identity cipher, treated as a stream cipher. */ |
| 86 | MBEDTLS_CIPHER_ID_AES, /**< The AES cipher. */ |
| 87 | MBEDTLS_CIPHER_ID_DES, /**< The DES cipher. */ |
| 88 | MBEDTLS_CIPHER_ID_3DES, /**< The Triple DES cipher. */ |
| 89 | MBEDTLS_CIPHER_ID_CAMELLIA, /**< The Camellia cipher. */ |
| 90 | MBEDTLS_CIPHER_ID_BLOWFISH, /**< The Blowfish cipher. */ |
| 91 | MBEDTLS_CIPHER_ID_ARC4, /**< The RC4 cipher. */ |
| 92 | MBEDTLS_CIPHER_ID_ARIA, /**< The Aria cipher. */ |
| 93 | MBEDTLS_CIPHER_ID_CHACHA20, /**< The ChaCha20 cipher. */ |
| 94 | } mbedtls_cipher_id_t; |
| 95 | |
| 96 | /** |
| 97 | * \brief Supported {cipher type, cipher mode} pairs. |
| 98 | * |
| 99 | * \warning RC4 and DES are considered weak ciphers and their use |
| 100 | * constitutes a security risk. Arm recommends considering stronger |
| 101 | * ciphers instead. |
| 102 | */ |
| 103 | typedef enum { |
| 104 | MBEDTLS_CIPHER_NONE = 0, /**< Placeholder to mark the end of cipher-pair lists. */ |
| 105 | MBEDTLS_CIPHER_NULL, /**< The identity stream cipher. */ |
| 106 | MBEDTLS_CIPHER_AES_128_ECB, /**< AES cipher with 128-bit ECB mode. */ |
| 107 | MBEDTLS_CIPHER_AES_192_ECB, /**< AES cipher with 192-bit ECB mode. */ |
| 108 | MBEDTLS_CIPHER_AES_256_ECB, /**< AES cipher with 256-bit ECB mode. */ |
| 109 | MBEDTLS_CIPHER_AES_128_CBC, /**< AES cipher with 128-bit CBC mode. */ |
| 110 | MBEDTLS_CIPHER_AES_192_CBC, /**< AES cipher with 192-bit CBC mode. */ |
| 111 | MBEDTLS_CIPHER_AES_256_CBC, /**< AES cipher with 256-bit CBC mode. */ |
| 112 | MBEDTLS_CIPHER_AES_128_CFB128, /**< AES cipher with 128-bit CFB128 mode. */ |
| 113 | MBEDTLS_CIPHER_AES_192_CFB128, /**< AES cipher with 192-bit CFB128 mode. */ |
| 114 | MBEDTLS_CIPHER_AES_256_CFB128, /**< AES cipher with 256-bit CFB128 mode. */ |
| 115 | MBEDTLS_CIPHER_AES_128_CTR, /**< AES cipher with 128-bit CTR mode. */ |
| 116 | MBEDTLS_CIPHER_AES_192_CTR, /**< AES cipher with 192-bit CTR mode. */ |
| 117 | MBEDTLS_CIPHER_AES_256_CTR, /**< AES cipher with 256-bit CTR mode. */ |
| 118 | MBEDTLS_CIPHER_AES_128_GCM, /**< AES cipher with 128-bit GCM mode. */ |
| 119 | MBEDTLS_CIPHER_AES_192_GCM, /**< AES cipher with 192-bit GCM mode. */ |
| 120 | MBEDTLS_CIPHER_AES_256_GCM, /**< AES cipher with 256-bit GCM mode. */ |
| 121 | MBEDTLS_CIPHER_CAMELLIA_128_ECB, /**< Camellia cipher with 128-bit ECB mode. */ |
| 122 | MBEDTLS_CIPHER_CAMELLIA_192_ECB, /**< Camellia cipher with 192-bit ECB mode. */ |
| 123 | MBEDTLS_CIPHER_CAMELLIA_256_ECB, /**< Camellia cipher with 256-bit ECB mode. */ |
| 124 | MBEDTLS_CIPHER_CAMELLIA_128_CBC, /**< Camellia cipher with 128-bit CBC mode. */ |
| 125 | MBEDTLS_CIPHER_CAMELLIA_192_CBC, /**< Camellia cipher with 192-bit CBC mode. */ |
| 126 | MBEDTLS_CIPHER_CAMELLIA_256_CBC, /**< Camellia cipher with 256-bit CBC mode. */ |
| 127 | MBEDTLS_CIPHER_CAMELLIA_128_CFB128, /**< Camellia cipher with 128-bit CFB128 mode. */ |
| 128 | MBEDTLS_CIPHER_CAMELLIA_192_CFB128, /**< Camellia cipher with 192-bit CFB128 mode. */ |
| 129 | MBEDTLS_CIPHER_CAMELLIA_256_CFB128, /**< Camellia cipher with 256-bit CFB128 mode. */ |
| 130 | MBEDTLS_CIPHER_CAMELLIA_128_CTR, /**< Camellia cipher with 128-bit CTR mode. */ |
| 131 | MBEDTLS_CIPHER_CAMELLIA_192_CTR, /**< Camellia cipher with 192-bit CTR mode. */ |
| 132 | MBEDTLS_CIPHER_CAMELLIA_256_CTR, /**< Camellia cipher with 256-bit CTR mode. */ |
| 133 | MBEDTLS_CIPHER_CAMELLIA_128_GCM, /**< Camellia cipher with 128-bit GCM mode. */ |
| 134 | MBEDTLS_CIPHER_CAMELLIA_192_GCM, /**< Camellia cipher with 192-bit GCM mode. */ |
| 135 | MBEDTLS_CIPHER_CAMELLIA_256_GCM, /**< Camellia cipher with 256-bit GCM mode. */ |
| 136 | MBEDTLS_CIPHER_DES_ECB, /**< DES cipher with ECB mode. */ |
| 137 | MBEDTLS_CIPHER_DES_CBC, /**< DES cipher with CBC mode. */ |
| 138 | MBEDTLS_CIPHER_DES_EDE_ECB, /**< DES cipher with EDE ECB mode. */ |
| 139 | MBEDTLS_CIPHER_DES_EDE_CBC, /**< DES cipher with EDE CBC mode. */ |
| 140 | MBEDTLS_CIPHER_DES_EDE3_ECB, /**< DES cipher with EDE3 ECB mode. */ |
| 141 | MBEDTLS_CIPHER_DES_EDE3_CBC, /**< DES cipher with EDE3 CBC mode. */ |
| 142 | MBEDTLS_CIPHER_BLOWFISH_ECB, /**< Blowfish cipher with ECB mode. */ |
| 143 | MBEDTLS_CIPHER_BLOWFISH_CBC, /**< Blowfish cipher with CBC mode. */ |
| 144 | MBEDTLS_CIPHER_BLOWFISH_CFB64, /**< Blowfish cipher with CFB64 mode. */ |
| 145 | MBEDTLS_CIPHER_BLOWFISH_CTR, /**< Blowfish cipher with CTR mode. */ |
| 146 | MBEDTLS_CIPHER_ARC4_128, /**< RC4 cipher with 128-bit mode. */ |
| 147 | MBEDTLS_CIPHER_AES_128_CCM, /**< AES cipher with 128-bit CCM mode. */ |
| 148 | MBEDTLS_CIPHER_AES_192_CCM, /**< AES cipher with 192-bit CCM mode. */ |
| 149 | MBEDTLS_CIPHER_AES_256_CCM, /**< AES cipher with 256-bit CCM mode. */ |
| 150 | MBEDTLS_CIPHER_CAMELLIA_128_CCM, /**< Camellia cipher with 128-bit CCM mode. */ |
| 151 | MBEDTLS_CIPHER_CAMELLIA_192_CCM, /**< Camellia cipher with 192-bit CCM mode. */ |
| 152 | MBEDTLS_CIPHER_CAMELLIA_256_CCM, /**< Camellia cipher with 256-bit CCM mode. */ |
| 153 | MBEDTLS_CIPHER_ARIA_128_ECB, /**< Aria cipher with 128-bit key and ECB mode. */ |
| 154 | MBEDTLS_CIPHER_ARIA_192_ECB, /**< Aria cipher with 192-bit key and ECB mode. */ |
| 155 | MBEDTLS_CIPHER_ARIA_256_ECB, /**< Aria cipher with 256-bit key and ECB mode. */ |
| 156 | MBEDTLS_CIPHER_ARIA_128_CBC, /**< Aria cipher with 128-bit key and CBC mode. */ |
| 157 | MBEDTLS_CIPHER_ARIA_192_CBC, /**< Aria cipher with 192-bit key and CBC mode. */ |
| 158 | MBEDTLS_CIPHER_ARIA_256_CBC, /**< Aria cipher with 256-bit key and CBC mode. */ |
| 159 | MBEDTLS_CIPHER_ARIA_128_CFB128, /**< Aria cipher with 128-bit key and CFB-128 mode. */ |
| 160 | MBEDTLS_CIPHER_ARIA_192_CFB128, /**< Aria cipher with 192-bit key and CFB-128 mode. */ |
| 161 | MBEDTLS_CIPHER_ARIA_256_CFB128, /**< Aria cipher with 256-bit key and CFB-128 mode. */ |
| 162 | MBEDTLS_CIPHER_ARIA_128_CTR, /**< Aria cipher with 128-bit key and CTR mode. */ |
| 163 | MBEDTLS_CIPHER_ARIA_192_CTR, /**< Aria cipher with 192-bit key and CTR mode. */ |
| 164 | MBEDTLS_CIPHER_ARIA_256_CTR, /**< Aria cipher with 256-bit key and CTR mode. */ |
| 165 | MBEDTLS_CIPHER_ARIA_128_GCM, /**< Aria cipher with 128-bit key and GCM mode. */ |
| 166 | MBEDTLS_CIPHER_ARIA_192_GCM, /**< Aria cipher with 192-bit key and GCM mode. */ |
| 167 | MBEDTLS_CIPHER_ARIA_256_GCM, /**< Aria cipher with 256-bit key and GCM mode. */ |
| 168 | MBEDTLS_CIPHER_ARIA_128_CCM, /**< Aria cipher with 128-bit key and CCM mode. */ |
| 169 | MBEDTLS_CIPHER_ARIA_192_CCM, /**< Aria cipher with 192-bit key and CCM mode. */ |
| 170 | MBEDTLS_CIPHER_ARIA_256_CCM, /**< Aria cipher with 256-bit key and CCM mode. */ |
| 171 | MBEDTLS_CIPHER_AES_128_OFB, /**< AES 128-bit cipher in OFB mode. */ |
| 172 | MBEDTLS_CIPHER_AES_192_OFB, /**< AES 192-bit cipher in OFB mode. */ |
| 173 | MBEDTLS_CIPHER_AES_256_OFB, /**< AES 256-bit cipher in OFB mode. */ |
| 174 | MBEDTLS_CIPHER_AES_128_XTS, /**< AES 128-bit cipher in XTS block mode. */ |
| 175 | MBEDTLS_CIPHER_AES_256_XTS, /**< AES 256-bit cipher in XTS block mode. */ |
| 176 | MBEDTLS_CIPHER_CHACHA20, /**< ChaCha20 stream cipher. */ |
| 177 | MBEDTLS_CIPHER_CHACHA20_POLY1305, /**< ChaCha20-Poly1305 AEAD cipher. */ |
| 178 | } mbedtls_cipher_type_t; |
| 179 | |
| 180 | /** Supported cipher modes. */ |
| 181 | typedef enum { |
| 182 | MBEDTLS_MODE_NONE = 0, /**< None. */ |
| 183 | MBEDTLS_MODE_ECB, /**< The ECB cipher mode. */ |
| 184 | MBEDTLS_MODE_CBC, /**< The CBC cipher mode. */ |
| 185 | MBEDTLS_MODE_CFB, /**< The CFB cipher mode. */ |
| 186 | MBEDTLS_MODE_OFB, /**< The OFB cipher mode. */ |
| 187 | MBEDTLS_MODE_CTR, /**< The CTR cipher mode. */ |
| 188 | MBEDTLS_MODE_GCM, /**< The GCM cipher mode. */ |
| 189 | MBEDTLS_MODE_STREAM, /**< The stream cipher mode. */ |
| 190 | MBEDTLS_MODE_CCM, /**< The CCM cipher mode. */ |
| 191 | MBEDTLS_MODE_XTS, /**< The XTS cipher mode. */ |
| 192 | MBEDTLS_MODE_CHACHAPOLY, /**< The ChaCha-Poly cipher mode. */ |
| 193 | } mbedtls_cipher_mode_t; |
| 194 | |
| 195 | /** Supported cipher padding types. */ |
| 196 | typedef enum { |
| 197 | MBEDTLS_PADDING_PKCS7 = 0, /**< PKCS7 padding (default). */ |
| 198 | MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding. */ |
| 199 | MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding. */ |
| 200 | MBEDTLS_PADDING_ZEROS, /**< Zero padding (not reversible). */ |
| 201 | MBEDTLS_PADDING_NONE, /**< Never pad (full blocks only). */ |
| 202 | } mbedtls_cipher_padding_t; |
| 203 | |
| 204 | /** Type of operation. */ |
| 205 | typedef enum { |
| 206 | MBEDTLS_OPERATION_NONE = -1, |
| 207 | MBEDTLS_DECRYPT = 0, |
| 208 | MBEDTLS_ENCRYPT, |
| 209 | } mbedtls_operation_t; |
| 210 | |
| 211 | enum { |
| 212 | /** Undefined key length. */ |
| 213 | MBEDTLS_KEY_LENGTH_NONE = 0, |
| 214 | /** Key length, in bits (including parity), for DES keys. */ |
| 215 | MBEDTLS_KEY_LENGTH_DES = 64, |
| 216 | /** Key length in bits, including parity, for DES in two-key EDE. */ |
| 217 | MBEDTLS_KEY_LENGTH_DES_EDE = 128, |
| 218 | /** Key length in bits, including parity, for DES in three-key EDE. */ |
| 219 | MBEDTLS_KEY_LENGTH_DES_EDE3 = 192, |
| 220 | }; |
| 221 | |
| 222 | /** Maximum length of any IV, in Bytes. */ |
| 223 | #define MBEDTLS_MAX_IV_LENGTH 16 |
| 224 | /** Maximum block size of any cipher, in Bytes. */ |
| 225 | #define MBEDTLS_MAX_BLOCK_LENGTH 16 |
| 226 | |
| 227 | /** |
| 228 | * Base cipher information (opaque struct). |
| 229 | */ |
| 230 | typedef struct mbedtls_cipher_base_t mbedtls_cipher_base_t; |
| 231 | |
| 232 | /** |
| 233 | * CMAC context (opaque struct). |
| 234 | */ |
| 235 | typedef struct mbedtls_cmac_context_t mbedtls_cmac_context_t; |
| 236 | |
| 237 | /** |
| 238 | * Cipher information. Allows calling cipher functions |
| 239 | * in a generic way. |
| 240 | */ |
| 241 | typedef struct mbedtls_cipher_info_t |
| 242 | { |
| 243 | /** Full cipher identifier. For example, |
| 244 | * MBEDTLS_CIPHER_AES_256_CBC. |
| 245 | */ |
| 246 | mbedtls_cipher_type_t type; |
| 247 | |
| 248 | /** The cipher mode. For example, MBEDTLS_MODE_CBC. */ |
| 249 | mbedtls_cipher_mode_t mode; |
| 250 | |
| 251 | /** The cipher key length, in bits. This is the |
| 252 | * default length for variable sized ciphers. |
| 253 | * Includes parity bits for ciphers like DES. |
| 254 | */ |
| 255 | unsigned int key_bitlen; |
| 256 | |
| 257 | /** Name of the cipher. */ |
| 258 | const char * name; |
| 259 | |
| 260 | /** IV or nonce size, in Bytes. |
| 261 | * For ciphers that accept variable IV sizes, |
| 262 | * this is the recommended size. |
| 263 | */ |
| 264 | unsigned int iv_size; |
| 265 | |
| 266 | /** Bitflag comprised of MBEDTLS_CIPHER_VARIABLE_IV_LEN and |
| 267 | * MBEDTLS_CIPHER_VARIABLE_KEY_LEN indicating whether the |
| 268 | * cipher supports variable IV or variable key sizes, respectively. |
| 269 | */ |
| 270 | int flags; |
| 271 | |
| 272 | /** The block size, in Bytes. */ |
| 273 | unsigned int block_size; |
| 274 | |
| 275 | /** Struct for base cipher information and functions. */ |
| 276 | const mbedtls_cipher_base_t *base; |
| 277 | |
| 278 | } mbedtls_cipher_info_t; |
| 279 | |
| 280 | /** |
| 281 | * Generic cipher context. |
| 282 | */ |
| 283 | typedef struct mbedtls_cipher_context_t |
| 284 | { |
| 285 | /** Information about the associated cipher. */ |
| 286 | const mbedtls_cipher_info_t *cipher_info; |
| 287 | |
| 288 | /** Key length to use. */ |
| 289 | int key_bitlen; |
| 290 | |
| 291 | /** Operation that the key of the context has been |
| 292 | * initialized for. |
| 293 | */ |
| 294 | mbedtls_operation_t operation; |
| 295 | |
| 296 | #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING) |
| 297 | /** Padding functions to use, if relevant for |
| 298 | * the specific cipher mode. |
| 299 | */ |
| 300 | void (*add_padding)( unsigned char *output, size_t olen, size_t data_len ); |
| 301 | int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len ); |
| 302 | #endif |
| 303 | |
| 304 | /** Buffer for input that has not been processed yet. */ |
| 305 | unsigned char unprocessed_data[MBEDTLS_MAX_BLOCK_LENGTH]; |
| 306 | |
| 307 | /** Number of Bytes that have not been processed yet. */ |
| 308 | size_t unprocessed_len; |
| 309 | |
| 310 | /** Current IV or NONCE_COUNTER for CTR-mode, data unit (or sector) number |
| 311 | * for XTS-mode. */ |
| 312 | unsigned char iv[MBEDTLS_MAX_IV_LENGTH]; |
| 313 | |
| 314 | /** IV size in Bytes, for ciphers with variable-length IVs. */ |
| 315 | size_t iv_size; |
| 316 | |
| 317 | /** The cipher-specific context. */ |
| 318 | void *cipher_ctx; |
| 319 | |
| 320 | #if defined(MBEDTLS_CMAC_C) |
| 321 | /** CMAC-specific context. */ |
| 322 | mbedtls_cmac_context_t *cmac_ctx; |
| 323 | #endif |
| 324 | } mbedtls_cipher_context_t; |
| 325 | |
| 326 | /** |
| 327 | * \brief This function retrieves the list of ciphers supported by the generic |
| 328 | * cipher module. |
| 329 | * |
| 330 | * \return A statically-allocated array of ciphers. The last entry |
| 331 | * is zero. |
| 332 | */ |
| 333 | const int *mbedtls_cipher_list( void ); |
| 334 | |
| 335 | /** |
| 336 | * \brief This function retrieves the cipher-information |
| 337 | * structure associated with the given cipher name. |
| 338 | * |
| 339 | * \param cipher_name Name of the cipher to search for. |
| 340 | * |
| 341 | * \return The cipher information structure associated with the |
| 342 | * given \p cipher_name. |
| 343 | * \return NULL if the associated cipher information is not found. |
| 344 | */ |
| 345 | const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name ); |
| 346 | |
| 347 | /** |
| 348 | * \brief This function retrieves the cipher-information |
| 349 | * structure associated with the given cipher type. |
| 350 | * |
| 351 | * \param cipher_type Type of the cipher to search for. |
| 352 | * |
| 353 | * \return The cipher information structure associated with the |
| 354 | * given \p cipher_type. |
| 355 | * \return NULL if the associated cipher information is not found. |
| 356 | */ |
| 357 | const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type( const mbedtls_cipher_type_t cipher_type ); |
| 358 | |
| 359 | /** |
| 360 | * \brief This function retrieves the cipher-information |
| 361 | * structure associated with the given cipher ID, |
| 362 | * key size and mode. |
| 363 | * |
| 364 | * \param cipher_id The ID of the cipher to search for. For example, |
| 365 | * #MBEDTLS_CIPHER_ID_AES. |
| 366 | * \param key_bitlen The length of the key in bits. |
| 367 | * \param mode The cipher mode. For example, #MBEDTLS_MODE_CBC. |
| 368 | * |
| 369 | * \return The cipher information structure associated with the |
| 370 | * given \p cipher_id. |
| 371 | * \return NULL if the associated cipher information is not found. |
| 372 | */ |
| 373 | const mbedtls_cipher_info_t *mbedtls_cipher_info_from_values( const mbedtls_cipher_id_t cipher_id, |
| 374 | int key_bitlen, |
| 375 | const mbedtls_cipher_mode_t mode ); |
| 376 | |
| 377 | /** |
| 378 | * \brief This function initializes a \p cipher_context as NONE. |
| 379 | */ |
| 380 | void mbedtls_cipher_init( mbedtls_cipher_context_t *ctx ); |
| 381 | |
| 382 | /** |
| 383 | * \brief This function frees and clears the cipher-specific |
| 384 | * context of \p ctx. Freeing \p ctx itself remains the |
| 385 | * responsibility of the caller. |
| 386 | */ |
| 387 | void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx ); |
| 388 | |
| 389 | |
| 390 | /** |
| 391 | * \brief This function initializes and fills the cipher-context |
| 392 | * structure with the appropriate values. It also clears |
| 393 | * the structure. |
| 394 | * |
| 395 | * \param ctx The context to initialize. May not be NULL. |
| 396 | * \param cipher_info The cipher to use. |
| 397 | * |
| 398 | * \return \c 0 on success. |
| 399 | * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on |
| 400 | * parameter-verification failure. |
| 401 | * \return #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the |
| 402 | * cipher-specific context fails. |
| 403 | * |
| 404 | * \internal Currently, the function also clears the structure. |
| 405 | * In future versions, the caller will be required to call |
| 406 | * mbedtls_cipher_init() on the structure first. |
| 407 | */ |
| 408 | int mbedtls_cipher_setup( mbedtls_cipher_context_t *ctx, const mbedtls_cipher_info_t *cipher_info ); |
| 409 | |
| 410 | /** |
| 411 | * \brief This function returns the block size of the given cipher. |
| 412 | * |
| 413 | * \param ctx The context of the cipher. Must be initialized. |
| 414 | * |
| 415 | * \return The size of the blocks of the cipher. |
| 416 | * \return 0 if \p ctx has not been initialized. |
| 417 | */ |
| 418 | static inline unsigned int mbedtls_cipher_get_block_size( const mbedtls_cipher_context_t *ctx ) |
| 419 | { |
| 420 | if( NULL == ctx || NULL == ctx->cipher_info ) |
| 421 | return 0; |
| 422 | |
| 423 | return ctx->cipher_info->block_size; |
| 424 | } |
| 425 | |
| 426 | /** |
| 427 | * \brief This function returns the mode of operation for |
| 428 | * the cipher. For example, MBEDTLS_MODE_CBC. |
| 429 | * |
| 430 | * \param ctx The context of the cipher. Must be initialized. |
| 431 | * |
| 432 | * \return The mode of operation. |
| 433 | * \return #MBEDTLS_MODE_NONE if \p ctx has not been initialized. |
| 434 | */ |
| 435 | static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtls_cipher_context_t *ctx ) |
| 436 | { |
| 437 | if( NULL == ctx || NULL == ctx->cipher_info ) |
| 438 | return MBEDTLS_MODE_NONE; |
| 439 | |
| 440 | return ctx->cipher_info->mode; |
| 441 | } |
| 442 | |
| 443 | /** |
| 444 | * \brief This function returns the size of the IV or nonce |
| 445 | * of the cipher, in Bytes. |
| 446 | * |
| 447 | * \param ctx The context of the cipher. Must be initialized. |
| 448 | * |
| 449 | * \return The recommended IV size if no IV has been set. |
| 450 | * \return \c 0 for ciphers not using an IV or a nonce. |
| 451 | * \return The actual size if an IV has been set. |
| 452 | */ |
| 453 | static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ctx ) |
| 454 | { |
| 455 | if( NULL == ctx || NULL == ctx->cipher_info ) |
| 456 | return 0; |
| 457 | |
| 458 | if( ctx->iv_size != 0 ) |
| 459 | return (int) ctx->iv_size; |
| 460 | |
| 461 | return (int) ctx->cipher_info->iv_size; |
| 462 | } |
| 463 | |
| 464 | /** |
| 465 | * \brief This function returns the type of the given cipher. |
| 466 | * |
| 467 | * \param ctx The context of the cipher. Must be initialized. |
| 468 | * |
| 469 | * \return The type of the cipher. |
| 470 | * \return #MBEDTLS_CIPHER_NONE if \p ctx has not been initialized. |
| 471 | */ |
| 472 | static inline mbedtls_cipher_type_t mbedtls_cipher_get_type( const mbedtls_cipher_context_t *ctx ) |
| 473 | { |
| 474 | if( NULL == ctx || NULL == ctx->cipher_info ) |
| 475 | return MBEDTLS_CIPHER_NONE; |
| 476 | |
| 477 | return ctx->cipher_info->type; |
| 478 | } |
| 479 | |
| 480 | /** |
| 481 | * \brief This function returns the name of the given cipher |
| 482 | * as a string. |
| 483 | * |
| 484 | * \param ctx The context of the cipher. Must be initialized. |
| 485 | * |
| 486 | * \return The name of the cipher. |
| 487 | * \return NULL if \p ctx has not been not initialized. |
| 488 | */ |
| 489 | static inline const char *mbedtls_cipher_get_name( const mbedtls_cipher_context_t *ctx ) |
| 490 | { |
| 491 | if( NULL == ctx || NULL == ctx->cipher_info ) |
| 492 | return 0; |
| 493 | |
| 494 | return ctx->cipher_info->name; |
| 495 | } |
| 496 | |
| 497 | /** |
| 498 | * \brief This function returns the key length of the cipher. |
| 499 | * |
| 500 | * \param ctx The context of the cipher. Must be initialized. |
| 501 | * |
| 502 | * \return The key length of the cipher in bits. |
| 503 | * \return #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been |
| 504 | * initialized. |
| 505 | */ |
| 506 | static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t *ctx ) |
| 507 | { |
| 508 | if( NULL == ctx || NULL == ctx->cipher_info ) |
| 509 | return MBEDTLS_KEY_LENGTH_NONE; |
| 510 | |
| 511 | return (int) ctx->cipher_info->key_bitlen; |
| 512 | } |
| 513 | |
| 514 | /** |
| 515 | * \brief This function returns the operation of the given cipher. |
| 516 | * |
| 517 | * \param ctx The context of the cipher. Must be initialized. |
| 518 | * |
| 519 | * \return The type of operation: #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT. |
| 520 | * \return #MBEDTLS_OPERATION_NONE if \p ctx has not been initialized. |
| 521 | */ |
| 522 | static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_cipher_context_t *ctx ) |
| 523 | { |
| 524 | if( NULL == ctx || NULL == ctx->cipher_info ) |
| 525 | return MBEDTLS_OPERATION_NONE; |
| 526 | |
| 527 | return ctx->operation; |
| 528 | } |
| 529 | |
| 530 | /** |
| 531 | * \brief This function sets the key to use with the given context. |
| 532 | * |
| 533 | * \param ctx The generic cipher context. May not be NULL. Must have |
| 534 | * been initialized using mbedtls_cipher_info_from_type() |
| 535 | * or mbedtls_cipher_info_from_string(). |
| 536 | * \param key The key to use. |
| 537 | * \param key_bitlen The key length to use, in bits. |
| 538 | * \param operation The operation that the key will be used for: |
| 539 | * #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT. |
| 540 | * |
| 541 | * \return \c 0 on success. |
| 542 | * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on |
| 543 | * parameter-verification failure. |
| 544 | * \return A cipher-specific error code on failure. |
| 545 | */ |
| 546 | int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *key, |
| 547 | int key_bitlen, const mbedtls_operation_t operation ); |
| 548 | |
| 549 | #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING) |
| 550 | /** |
| 551 | * \brief This function sets the padding mode, for cipher modes |
| 552 | * that use padding. |
| 553 | * |
| 554 | * The default passing mode is PKCS7 padding. |
| 555 | * |
| 556 | * \param ctx The generic cipher context. |
| 557 | * \param mode The padding mode. |
| 558 | * |
| 559 | * \return \c 0 on success. |
| 560 | * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE |
| 561 | * if the selected padding mode is not supported. |
| 562 | * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode |
| 563 | * does not support padding. |
| 564 | */ |
| 565 | int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_cipher_padding_t mode ); |
| 566 | #endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */ |
| 567 | |
| 568 | /** |
| 569 | * \brief This function sets the initialization vector (IV) |
| 570 | * or nonce. |
| 571 | * |
| 572 | * \note Some ciphers do not use IVs nor nonce. For these |
| 573 | * ciphers, this function has no effect. |
| 574 | * |
| 575 | * \param ctx The generic cipher context. |
| 576 | * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. |
| 577 | * \param iv_len The IV length for ciphers with variable-size IV. |
| 578 | * This parameter is discarded by ciphers with fixed-size IV. |
| 579 | * |
| 580 | * \return \c 0 on success. |
| 581 | * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on |
| 582 | * parameter-verification failure. |
| 583 | */ |
| 584 | int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx, |
| 585 | const unsigned char *iv, size_t iv_len ); |
| 586 | |
| 587 | /** |
| 588 | * \brief This function resets the cipher state. |
| 589 | * |
| 590 | * \param ctx The generic cipher context. |
| 591 | * |
| 592 | * \return \c 0 on success. |
| 593 | * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on |
| 594 | * parameter-verification failure. |
| 595 | */ |
| 596 | int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx ); |
| 597 | |
| 598 | #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C) |
| 599 | /** |
| 600 | * \brief This function adds additional data for AEAD ciphers. |
| 601 | * Currently supported with GCM and ChaCha20+Poly1305. |
| 602 | * Must be called exactly once, after mbedtls_cipher_reset(). |
| 603 | * |
| 604 | * \param ctx The generic cipher context. |
| 605 | * \param ad The additional data to use. |
| 606 | * \param ad_len the Length of \p ad. |
| 607 | * |
| 608 | * \return \c 0 on success. |
| 609 | * \return A specific error code on failure. |
| 610 | */ |
| 611 | int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx, |
| 612 | const unsigned char *ad, size_t ad_len ); |
| 613 | #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */ |
| 614 | |
| 615 | /** |
| 616 | * \brief The generic cipher update function. It encrypts or |
| 617 | * decrypts using the given cipher context. Writes as |
| 618 | * many block-sized blocks of data as possible to output. |
| 619 | * Any data that cannot be written immediately is either |
| 620 | * added to the next block, or flushed when |
| 621 | * mbedtls_cipher_finish() is called. |
| 622 | * Exception: For MBEDTLS_MODE_ECB, expects a single block |
| 623 | * in size. For example, 16 Bytes for AES. |
| 624 | * |
| 625 | * \note If the underlying cipher is used in GCM mode, all calls |
| 626 | * to this function, except for the last one before |
| 627 | * mbedtls_cipher_finish(), must have \p ilen as a |
| 628 | * multiple of the block size of the cipher. |
| 629 | * |
| 630 | * \param ctx The generic cipher context. |
| 631 | * \param input The buffer holding the input data. |
| 632 | * \param ilen The length of the input data. |
| 633 | * \param output The buffer for the output data. Must be able to hold at |
| 634 | * least \p ilen + block_size. Must not be the same buffer |
| 635 | * as input. |
| 636 | * \param olen The length of the output data, to be updated with the |
| 637 | * actual number of Bytes written. |
| 638 | * |
| 639 | * \return \c 0 on success. |
| 640 | * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on |
| 641 | * parameter-verification failure. |
| 642 | * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an |
| 643 | * unsupported mode for a cipher. |
| 644 | * \return A cipher-specific error code on failure. |
| 645 | */ |
| 646 | int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input, |
| 647 | size_t ilen, unsigned char *output, size_t *olen ); |
| 648 | |
| 649 | /** |
| 650 | * \brief The generic cipher finalization function. If data still |
| 651 | * needs to be flushed from an incomplete block, the data |
| 652 | * contained in it is padded to the size of |
| 653 | * the last block, and written to the \p output buffer. |
| 654 | * |
| 655 | * \param ctx The generic cipher context. |
| 656 | * \param output The buffer to write data to. Needs block_size available. |
| 657 | * \param olen The length of the data written to the \p output buffer. |
| 658 | * |
| 659 | * \return \c 0 on success. |
| 660 | * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on |
| 661 | * parameter-verification failure. |
| 662 | * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption |
| 663 | * expecting a full block but not receiving one. |
| 664 | * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding |
| 665 | * while decrypting. |
| 666 | * \return A cipher-specific error code on failure. |
| 667 | */ |
| 668 | int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx, |
| 669 | unsigned char *output, size_t *olen ); |
| 670 | |
| 671 | #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C) |
| 672 | /** |
| 673 | * \brief This function writes a tag for AEAD ciphers. |
| 674 | * Currently supported with GCM and ChaCha20+Poly1305. |
| 675 | * Must be called after mbedtls_cipher_finish(). |
| 676 | * |
| 677 | * \param ctx The generic cipher context. |
| 678 | * \param tag The buffer to write the tag to. |
| 679 | * \param tag_len The length of the tag to write. |
| 680 | * |
| 681 | * \return \c 0 on success. |
| 682 | * \return A specific error code on failure. |
| 683 | */ |
| 684 | int mbedtls_cipher_write_tag( mbedtls_cipher_context_t *ctx, |
| 685 | unsigned char *tag, size_t tag_len ); |
| 686 | |
| 687 | /** |
| 688 | * \brief This function checks the tag for AEAD ciphers. |
| 689 | * Currently supported with GCM and ChaCha20+Poly1305. |
| 690 | * Must be called after mbedtls_cipher_finish(). |
| 691 | * |
| 692 | * \param ctx The generic cipher context. |
| 693 | * \param tag The buffer holding the tag. |
| 694 | * \param tag_len The length of the tag to check. |
| 695 | * |
| 696 | * \return \c 0 on success. |
| 697 | * \return A specific error code on failure. |
| 698 | */ |
| 699 | int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx, |
| 700 | const unsigned char *tag, size_t tag_len ); |
| 701 | #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */ |
| 702 | |
| 703 | /** |
| 704 | * \brief The generic all-in-one encryption/decryption function, |
| 705 | * for all ciphers except AEAD constructs. |
| 706 | * |
| 707 | * \param ctx The generic cipher context. |
| 708 | * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. |
| 709 | * \param iv_len The IV length for ciphers with variable-size IV. |
| 710 | * This parameter is discarded by ciphers with fixed-size |
| 711 | * IV. |
| 712 | * \param input The buffer holding the input data. |
| 713 | * \param ilen The length of the input data. |
| 714 | * \param output The buffer for the output data. Must be able to hold at |
| 715 | * least \p ilen + block_size. Must not be the same buffer |
| 716 | * as input. |
| 717 | * \param olen The length of the output data, to be updated with the |
| 718 | * actual number of Bytes written. |
| 719 | * |
| 720 | * \note Some ciphers do not use IVs nor nonce. For these |
| 721 | * ciphers, use \p iv = NULL and \p iv_len = 0. |
| 722 | * |
| 723 | * \return \c 0 on success. |
| 724 | * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on |
| 725 | * parameter-verification failure. |
| 726 | * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption |
| 727 | * expecting a full block but not receiving one. |
| 728 | * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding |
| 729 | * while decrypting. |
| 730 | * \return A cipher-specific error code on failure. |
| 731 | */ |
| 732 | int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx, |
| 733 | const unsigned char *iv, size_t iv_len, |
| 734 | const unsigned char *input, size_t ilen, |
| 735 | unsigned char *output, size_t *olen ); |
| 736 | |
| 737 | #if defined(MBEDTLS_CIPHER_MODE_AEAD) |
| 738 | /** |
| 739 | * \brief The generic autenticated encryption (AEAD) function. |
| 740 | * |
| 741 | * \param ctx The generic cipher context. |
| 742 | * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. |
| 743 | * \param iv_len The IV length for ciphers with variable-size IV. |
| 744 | * This parameter is discarded by ciphers with fixed-size IV. |
| 745 | * \param ad The additional data to authenticate. |
| 746 | * \param ad_len The length of \p ad. |
| 747 | * \param input The buffer holding the input data. |
| 748 | * \param ilen The length of the input data. |
| 749 | * \param output The buffer for the output data. |
| 750 | * Must be able to hold at least \p ilen. |
| 751 | * \param olen The length of the output data, to be updated with the |
| 752 | * actual number of Bytes written. |
| 753 | * \param tag The buffer for the authentication tag. |
| 754 | * \param tag_len The desired length of the authentication tag. |
| 755 | * |
| 756 | * \return \c 0 on success. |
| 757 | * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on |
| 758 | * parameter-verification failure. |
| 759 | * \return A cipher-specific error code on failure. |
| 760 | */ |
| 761 | int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx, |
| 762 | const unsigned char *iv, size_t iv_len, |
| 763 | const unsigned char *ad, size_t ad_len, |
| 764 | const unsigned char *input, size_t ilen, |
| 765 | unsigned char *output, size_t *olen, |
| 766 | unsigned char *tag, size_t tag_len ); |
| 767 | |
| 768 | /** |
| 769 | * \brief The generic autenticated decryption (AEAD) function. |
| 770 | * |
| 771 | * \note If the data is not authentic, then the output buffer |
| 772 | * is zeroed out to prevent the unauthentic plaintext being |
| 773 | * used, making this interface safer. |
| 774 | * |
| 775 | * \param ctx The generic cipher context. |
| 776 | * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. |
| 777 | * \param iv_len The IV length for ciphers with variable-size IV. |
| 778 | * This parameter is discarded by ciphers with fixed-size IV. |
| 779 | * \param ad The additional data to be authenticated. |
| 780 | * \param ad_len The length of \p ad. |
| 781 | * \param input The buffer holding the input data. |
| 782 | * \param ilen The length of the input data. |
| 783 | * \param output The buffer for the output data. |
| 784 | * Must be able to hold at least \p ilen. |
| 785 | * \param olen The length of the output data, to be updated with the |
| 786 | * actual number of Bytes written. |
| 787 | * \param tag The buffer holding the authentication tag. |
| 788 | * \param tag_len The length of the authentication tag. |
| 789 | * |
| 790 | * \return \c 0 on success. |
| 791 | * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on |
| 792 | * parameter-verification failure. |
| 793 | * \return #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic. |
| 794 | * \return A cipher-specific error code on failure. |
| 795 | */ |
| 796 | int mbedtls_cipher_auth_decrypt( mbedtls_cipher_context_t *ctx, |
| 797 | const unsigned char *iv, size_t iv_len, |
| 798 | const unsigned char *ad, size_t ad_len, |
| 799 | const unsigned char *input, size_t ilen, |
| 800 | unsigned char *output, size_t *olen, |
| 801 | const unsigned char *tag, size_t tag_len ); |
| 802 | #endif /* MBEDTLS_CIPHER_MODE_AEAD */ |
| 803 | |
| 804 | #ifdef __cplusplus |
| 805 | } |
| 806 | #endif |
| 807 | |
| 808 | #endif /* MBEDTLS_CIPHER_H */ |