1 /** 2 * \file aes.h 3 * 4 * \brief The Advanced Encryption Standard (AES) specifies a FIPS-approved 5 * cryptographic algorithm that can be used to protect electronic 6 * data. 7 * 8 * The AES algorithm is a symmetric block cipher that can 9 * encrypt and decrypt information. For more information, see 10 * <em>FIPS Publication 197: Advanced Encryption Standard</em> and 11 * <em>ISO/IEC 18033-2:2006: Information technology -- Security 12 * techniques -- Encryption algorithms -- Part 2: Asymmetric 13 * ciphers</em>. 14 */ 15 /* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved. 16 * SPDX-License-Identifier: GPL-2.0 17 * 18 * This program is free software; you can redistribute it and/or modify 19 * it under the terms of the GNU General Public License as published by 20 * the Free Software Foundation; either version 2 of the License, or 21 * (at your option) any later version. 22 * 23 * This program is distributed in the hope that it will be useful, 24 * but WITHOUT ANY WARRANTY; without even the implied warranty of 25 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 26 * GNU General Public License for more details. 27 * 28 * You should have received a copy of the GNU General Public License along 29 * with this program; if not, write to the Free Software Foundation, Inc., 30 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 31 * 32 * This file is part of Mbed TLS (https://tls.mbed.org) 33 */ 34 35 #ifndef MBEDTLS_AES_H 36 #define MBEDTLS_AES_H 37 38 #if !defined(MBEDTLS_CONFIG_FILE) 39 #include "config.h" 40 #else 41 #include MBEDTLS_CONFIG_FILE 42 #endif 43 44 #include <stddef.h> 45 #include <stdint.h> 46 47 /* padlock.c and aesni.c rely on these values! */ 48 #define MBEDTLS_AES_ENCRYPT 1 /**< AES encryption. */ 49 #define MBEDTLS_AES_DECRYPT 0 /**< AES decryption. */ 50 51 /* Error codes in range 0x0020-0x0022 */ 52 #define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH -0x0020 /**< Invalid key length. */ 53 #define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH -0x0022 /**< Invalid data input length. */ 54 55 /* Error codes in range 0x0023-0x0025 */ 56 #define MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE -0x0023 /**< Feature not available. For example, an unsupported AES key size. */ 57 #define MBEDTLS_ERR_AES_HW_ACCEL_FAILED -0x0025 /**< AES hardware accelerator failed. */ 58 59 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \ 60 !defined(inline) && !defined(__cplusplus) 61 #define inline __inline 62 #endif 63 64 #if !defined(MBEDTLS_AES_ALT) 65 // Regular implementation 66 // 67 68 #ifdef __cplusplus 69 extern "C" { 70 #endif 71 72 /** 73 * \brief The AES context-type definition. 74 */ 75 typedef struct 76 { 77 int nr; /*!< The number of rounds. */ 78 uint32_t *rk; /*!< AES round keys. */ 79 uint32_t buf[68]; /*!< Unaligned data buffer. This buffer can 80 hold 32 extra Bytes, which can be used for 81 one of the following purposes: 82 <ul><li>Alignment if VIA padlock is 83 used.</li> 84 <li>Simplifying key expansion in the 256-bit 85 case by generating an extra round key. 86 </li></ul> */ 87 } 88 mbedtls_aes_context; 89 90 /** 91 * \brief This function initializes the specified AES context. 92 * 93 * It must be the first API called before using 94 * the context. 95 * 96 * \param ctx The AES context to initialize. 97 */ 98 void mbedtls_aes_init( mbedtls_aes_context *ctx ); 99 100 /** 101 * \brief This function releases and clears the specified AES context. 102 * 103 * \param ctx The AES context to clear. 104 */ 105 void mbedtls_aes_free( mbedtls_aes_context *ctx ); 106 107 /** 108 * \brief This function sets the encryption key. 109 * 110 * \param ctx The AES context to which the key should be bound. 111 * \param key The encryption key. 112 * \param keybits The size of data passed in bits. Valid options are: 113 * <ul><li>128 bits</li> 114 * <li>192 bits</li> 115 * <li>256 bits</li></ul> 116 * 117 * \return \c 0 on success or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH 118 * on failure. 119 */ 120 int mbedtls_aes_setkey_enc( mbedtls_aes_context *ctx, const unsigned char *key, 121 unsigned int keybits ); 122 123 /** 124 * \brief This function sets the decryption key. 125 * 126 * \param ctx The AES context to which the key should be bound. 127 * \param key The decryption key. 128 * \param keybits The size of data passed. Valid options are: 129 * <ul><li>128 bits</li> 130 * <li>192 bits</li> 131 * <li>256 bits</li></ul> 132 * 133 * \return \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure. 134 */ 135 int mbedtls_aes_setkey_dec( mbedtls_aes_context *ctx, const unsigned char *key, 136 unsigned int keybits ); 137 138 /** 139 * \brief This function performs an AES single-block encryption or 140 * decryption operation. 141 * 142 * It performs the operation defined in the \p mode parameter 143 * (encrypt or decrypt), on the input data buffer defined in 144 * the \p input parameter. 145 * 146 * mbedtls_aes_init(), and either mbedtls_aes_setkey_enc() or 147 * mbedtls_aes_setkey_dec() must be called before the first 148 * call to this API with the same context. 149 * 150 * \param ctx The AES context to use for encryption or decryption. 151 * \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or 152 * #MBEDTLS_AES_DECRYPT. 153 * \param input The 16-Byte buffer holding the input data. 154 * \param output The 16-Byte buffer holding the output data. 155 156 * \return \c 0 on success. 157 */ 158 int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx, 159 int mode, 160 const unsigned char input[16], 161 unsigned char output[16] ); 162 163 #if defined(MBEDTLS_CIPHER_MODE_CBC) 164 /** 165 * \brief This function performs an AES-CBC encryption or decryption operation 166 * on full blocks. 167 * 168 * It performs the operation defined in the \p mode 169 * parameter (encrypt/decrypt), on the input data buffer defined in 170 * the \p input parameter. 171 * 172 * It can be called as many times as needed, until all the input 173 * data is processed. mbedtls_aes_init(), and either 174 * mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called 175 * before the first call to this API with the same context. 176 * 177 * \note This function operates on aligned blocks, that is, the input size 178 * must be a multiple of the AES block size of 16 Bytes. 179 * 180 * \note Upon exit, the content of the IV is updated so that you can 181 * call the same function again on the next 182 * block(s) of data and get the same result as if it was 183 * encrypted in one call. This allows a "streaming" usage. 184 * If you need to retain the contents of the IV, you should 185 * either save it manually or use the cipher module instead. 186 * 187 * 188 * \param ctx The AES context to use for encryption or decryption. 189 * \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or 190 * #MBEDTLS_AES_DECRYPT. 191 * \param length The length of the input data in Bytes. This must be a 192 * multiple of the block size (16 Bytes). 193 * \param iv Initialization vector (updated after use). 194 * \param input The buffer holding the input data. 195 * \param output The buffer holding the output data. 196 * 197 * \return \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH 198 * on failure. 199 */ 200 int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx, 201 int mode, 202 size_t length, 203 unsigned char iv[16], 204 const unsigned char *input, 205 unsigned char *output ); 206 #endif /* MBEDTLS_CIPHER_MODE_CBC */ 207 208 #if defined(MBEDTLS_CIPHER_MODE_CFB) 209 /** 210 * \brief This function performs an AES-CFB128 encryption or decryption 211 * operation. 212 * 213 * It performs the operation defined in the \p mode 214 * parameter (encrypt or decrypt), on the input data buffer 215 * defined in the \p input parameter. 216 * 217 * For CFB, you must set up the context with mbedtls_aes_setkey_enc(), 218 * regardless of whether you are performing an encryption or decryption 219 * operation, that is, regardless of the \p mode parameter. This is 220 * because CFB mode uses the same key schedule for encryption and 221 * decryption. 222 * 223 * \note Upon exit, the content of the IV is updated so that you can 224 * call the same function again on the next 225 * block(s) of data and get the same result as if it was 226 * encrypted in one call. This allows a "streaming" usage. 227 * If you need to retain the contents of the 228 * IV, you must either save it manually or use the cipher 229 * module instead. 230 * 231 * 232 * \param ctx The AES context to use for encryption or decryption. 233 * \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or 234 * #MBEDTLS_AES_DECRYPT. 235 * \param length The length of the input data. 236 * \param iv_off The offset in IV (updated after use). 237 * \param iv The initialization vector (updated after use). 238 * \param input The buffer holding the input data. 239 * \param output The buffer holding the output data. 240 * 241 * \return \c 0 on success. 242 */ 243 int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx, 244 int mode, 245 size_t length, 246 size_t *iv_off, 247 unsigned char iv[16], 248 const unsigned char *input, 249 unsigned char *output ); 250 251 /** 252 * \brief This function performs an AES-CFB8 encryption or decryption 253 * operation. 254 * 255 * It performs the operation defined in the \p mode 256 * parameter (encrypt/decrypt), on the input data buffer defined 257 * in the \p input parameter. 258 * 259 * Due to the nature of CFB, you must use the same key schedule for 260 * both encryption and decryption operations. Therefore, you must 261 * use the context initialized with mbedtls_aes_setkey_enc() for 262 * both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT. 263 * 264 * \note Upon exit, the content of the IV is updated so that you can 265 * call the same function again on the next 266 * block(s) of data and get the same result as if it was 267 * encrypted in one call. This allows a "streaming" usage. 268 * If you need to retain the contents of the 269 * IV, you should either save it manually or use the cipher 270 * module instead. 271 * 272 * 273 * \param ctx The AES context to use for encryption or decryption. 274 * \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or 275 * #MBEDTLS_AES_DECRYPT 276 * \param length The length of the input data. 277 * \param iv The initialization vector (updated after use). 278 * \param input The buffer holding the input data. 279 * \param output The buffer holding the output data. 280 * 281 * \return \c 0 on success. 282 */ 283 int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx, 284 int mode, 285 size_t length, 286 unsigned char iv[16], 287 const unsigned char *input, 288 unsigned char *output ); 289 #endif /*MBEDTLS_CIPHER_MODE_CFB */ 290 291 #if defined(MBEDTLS_CIPHER_MODE_CTR) 292 /** 293 * \brief This function performs an AES-CTR encryption or decryption 294 * operation. 295 * 296 * This function performs the operation defined in the \p mode 297 * parameter (encrypt/decrypt), on the input data buffer 298 * defined in the \p input parameter. 299 * 300 * Due to the nature of CTR, you must use the same key schedule 301 * for both encryption and decryption operations. Therefore, you 302 * must use the context initialized with mbedtls_aes_setkey_enc() 303 * for both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT. 304 * 305 * \warning You must keep the maximum use of your counter in mind. 306 * 307 * \param ctx The AES context to use for encryption or decryption. 308 * \param length The length of the input data. 309 * \param nc_off The offset in the current \p stream_block, for 310 * resuming within the current cipher stream. The 311 * offset pointer should be 0 at the start of a stream. 312 * \param nonce_counter The 128-bit nonce and counter. 313 * \param stream_block The saved stream block for resuming. This is 314 * overwritten by the function. 315 * \param input The buffer holding the input data. 316 * \param output The buffer holding the output data. 317 * 318 * \return \c 0 on success. 319 */ 320 int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx, 321 size_t length, 322 size_t *nc_off, 323 unsigned char nonce_counter[16], 324 unsigned char stream_block[16], 325 const unsigned char *input, 326 unsigned char *output ); 327 #endif /* MBEDTLS_CIPHER_MODE_CTR */ 328 329 /** 330 * \brief Internal AES block encryption function. This is only 331 * exposed to allow overriding it using 332 * \c MBEDTLS_AES_ENCRYPT_ALT. 333 * 334 * \param ctx The AES context to use for encryption. 335 * \param input The plaintext block. 336 * \param output The output (ciphertext) block. 337 * 338 * \return \c 0 on success. 339 */ 340 int mbedtls_internal_aes_encrypt( mbedtls_aes_context *ctx, 341 const unsigned char input[16], 342 unsigned char output[16] ); 343 344 /** 345 * \brief Internal AES block decryption function. This is only 346 * exposed to allow overriding it using see 347 * \c MBEDTLS_AES_DECRYPT_ALT. 348 * 349 * \param ctx The AES context to use for decryption. 350 * \param input The ciphertext block. 351 * \param output The output (plaintext) block. 352 * 353 * \return \c 0 on success. 354 */ 355 int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx, 356 const unsigned char input[16], 357 unsigned char output[16] ); 358 359 #if !defined(MBEDTLS_DEPRECATED_REMOVED) 360 #if defined(MBEDTLS_DEPRECATED_WARNING) 361 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 362 #else 363 #define MBEDTLS_DEPRECATED 364 #endif 365 /** 366 * \brief Deprecated internal AES block encryption function 367 * without return value. 368 * 369 * \deprecated Superseded by mbedtls_aes_encrypt_ext() in 2.5.0. 370 * 371 * \param ctx The AES context to use for encryption. 372 * \param input Plaintext block. 373 * \param output Output (ciphertext) block. 374 */ 375 MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx, 376 const unsigned char input[16], 377 unsigned char output[16] ); 378 379 /** 380 * \brief Deprecated internal AES block decryption function 381 * without return value. 382 * 383 * \deprecated Superseded by mbedtls_aes_decrypt_ext() in 2.5.0. 384 * 385 * \param ctx The AES context to use for decryption. 386 * \param input Ciphertext block. 387 * \param output Output (plaintext) block. 388 */ 389 MBEDTLS_DEPRECATED void mbedtls_aes_decrypt( mbedtls_aes_context *ctx, 390 const unsigned char input[16], 391 unsigned char output[16] ); 392 393 #undef MBEDTLS_DEPRECATED 394 #endif /* !MBEDTLS_DEPRECATED_REMOVED */ 395 396 #ifdef __cplusplus 397 } 398 #endif 399 400 #else /* MBEDTLS_AES_ALT */ 401 #include "aes_alt.h" 402 #endif /* MBEDTLS_AES_ALT */ 403 404 #ifdef __cplusplus 405 extern "C" { 406 #endif 407 408 /** 409 * \brief Checkup routine. 410 * 411 * \return \c 0 on success, or \c 1 on failure. 412 */ 413 int mbedtls_aes_self_test( int verbose ); 414 415 #ifdef __cplusplus 416 } 417 #endif 418 419 #endif /* aes.h */ 420