1 /** 2 * \file aes.h 3 * 4 * \brief AES block cipher 5 * 6 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved 7 * SPDX-License-Identifier: Apache-2.0 8 * 9 * Licensed under the Apache License, Version 2.0 (the "License"); you may 10 * not use this file except in compliance with the License. 11 * You may obtain a copy of the License at 12 * 13 * http://www.apache.org/licenses/LICENSE-2.0 14 * 15 * Unless required by applicable law or agreed to in writing, software 16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 18 * See the License for the specific language governing permissions and 19 * limitations under the License. 20 * 21 * This file is part of mbed TLS (https://tls.mbed.org) 22 */ 23 #ifndef MBEDTLS_AES_H 24 #define MBEDTLS_AES_H 25 26 #if !defined(MBEDTLS_CONFIG_FILE) 27 #include "config.h" 28 #else 29 #include MBEDTLS_CONFIG_FILE 30 #endif 31 32 #include <stddef.h> 33 #include <stdint.h> 34 35 /* padlock.c and aesni.c rely on these values! */ 36 #define MBEDTLS_AES_ENCRYPT 1 37 #define MBEDTLS_AES_DECRYPT 0 38 39 #define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH -0x0020 /**< Invalid key length. */ 40 #define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH -0x0022 /**< Invalid data input length. */ 41 42 #if !defined(MBEDTLS_AES_ALT) 43 // Regular implementation 44 // 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** 51 * \brief AES context structure 52 * 53 * \note buf is able to hold 32 extra bytes, which can be used: 54 * - for alignment purposes if VIA padlock is used, and/or 55 * - to simplify key expansion in the 256-bit case by 56 * generating an extra round key 57 */ 58 typedef struct 59 { 60 int nr; /*!< number of rounds */ 61 uint32_t *rk; /*!< AES round keys */ 62 uint32_t buf[68]; /*!< unaligned data */ 63 } 64 mbedtls_aes_context; 65 66 /** 67 * \brief Initialize AES context 68 * 69 * \param ctx AES context to be initialized 70 */ 71 void mbedtls_aes_init( mbedtls_aes_context *ctx ); 72 73 /** 74 * \brief Clear AES context 75 * 76 * \param ctx AES context to be cleared 77 */ 78 void mbedtls_aes_free( mbedtls_aes_context *ctx ); 79 80 /** 81 * \brief AES key schedule (encryption) 82 * 83 * \param ctx AES context to be initialized 84 * \param key encryption key 85 * \param keybits must be 128, 192 or 256 86 * 87 * \return 0 if successful, or MBEDTLS_ERR_AES_INVALID_KEY_LENGTH 88 */ 89 int mbedtls_aes_setkey_enc( mbedtls_aes_context *ctx, const unsigned char *key, 90 unsigned int keybits ); 91 92 /** 93 * \brief AES key schedule (decryption) 94 * 95 * \param ctx AES context to be initialized 96 * \param key decryption key 97 * \param keybits must be 128, 192 or 256 98 * 99 * \return 0 if successful, or MBEDTLS_ERR_AES_INVALID_KEY_LENGTH 100 */ 101 int mbedtls_aes_setkey_dec( mbedtls_aes_context *ctx, const unsigned char *key, 102 unsigned int keybits ); 103 104 /** 105 * \brief AES-ECB block encryption/decryption 106 * 107 * \param ctx AES context 108 * \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT 109 * \param input 16-byte input block 110 * \param output 16-byte output block 111 * 112 * \return 0 if successful 113 */ 114 int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx, 115 int mode, 116 const unsigned char input[16], 117 unsigned char output[16] ); 118 119 #if defined(MBEDTLS_CIPHER_MODE_CBC) 120 /** 121 * \brief AES-CBC buffer encryption/decryption 122 * Length should be a multiple of the block 123 * size (16 bytes) 124 * 125 * \note Upon exit, the content of the IV is updated so that you can 126 * call the function same function again on the following 127 * block(s) of data and get the same result as if it was 128 * encrypted in one call. This allows a "streaming" usage. 129 * If on the other hand you need to retain the contents of the 130 * IV, you should either save it manually or use the cipher 131 * module instead. 132 * 133 * \param ctx AES context 134 * \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT 135 * \param length length of the input data 136 * \param iv initialization vector (updated after use) 137 * \param input buffer holding the input data 138 * \param output buffer holding the output data 139 * 140 * \return 0 if successful, or MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH 141 */ 142 int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx, 143 int mode, 144 size_t length, 145 unsigned char iv[16], 146 const unsigned char *input, 147 unsigned char *output ); 148 #endif /* MBEDTLS_CIPHER_MODE_CBC */ 149 150 #if defined(MBEDTLS_CIPHER_MODE_CFB) 151 /** 152 * \brief AES-CFB128 buffer encryption/decryption. 153 * 154 * Note: Due to the nature of CFB you should use the same key schedule for 155 * both encryption and decryption. So a context initialized with 156 * mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. 157 * 158 * \note Upon exit, the content of the IV is updated so that you can 159 * call the function same function again on the following 160 * block(s) of data and get the same result as if it was 161 * encrypted in one call. This allows a "streaming" usage. 162 * If on the other hand you need to retain the contents of the 163 * IV, you should either save it manually or use the cipher 164 * module instead. 165 * 166 * \param ctx AES context 167 * \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT 168 * \param length length of the input data 169 * \param iv_off offset in IV (updated after use) 170 * \param iv initialization vector (updated after use) 171 * \param input buffer holding the input data 172 * \param output buffer holding the output data 173 * 174 * \return 0 if successful 175 */ 176 int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx, 177 int mode, 178 size_t length, 179 size_t *iv_off, 180 unsigned char iv[16], 181 const unsigned char *input, 182 unsigned char *output ); 183 184 /** 185 * \brief AES-CFB8 buffer encryption/decryption. 186 * 187 * Note: Due to the nature of CFB you should use the same key schedule for 188 * both encryption and decryption. So a context initialized with 189 * mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. 190 * 191 * \note Upon exit, the content of the IV is updated so that you can 192 * call the function same function again on the following 193 * block(s) of data and get the same result as if it was 194 * encrypted in one call. This allows a "streaming" usage. 195 * If on the other hand you need to retain the contents of the 196 * IV, you should either save it manually or use the cipher 197 * module instead. 198 * 199 * \param ctx AES context 200 * \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT 201 * \param length length of the input data 202 * \param iv initialization vector (updated after use) 203 * \param input buffer holding the input data 204 * \param output buffer holding the output data 205 * 206 * \return 0 if successful 207 */ 208 int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx, 209 int mode, 210 size_t length, 211 unsigned char iv[16], 212 const unsigned char *input, 213 unsigned char *output ); 214 #endif /*MBEDTLS_CIPHER_MODE_CFB */ 215 216 #if defined(MBEDTLS_CIPHER_MODE_CTR) 217 /** 218 * \brief AES-CTR buffer encryption/decryption 219 * 220 * Warning: You have to keep the maximum use of your counter in mind! 221 * 222 * Note: Due to the nature of CTR you should use the same key schedule for 223 * both encryption and decryption. So a context initialized with 224 * mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. 225 * 226 * \param ctx AES context 227 * \param length The length of the data 228 * \param nc_off The offset in the current stream_block (for resuming 229 * within current cipher stream). The offset pointer to 230 * should be 0 at the start of a stream. 231 * \param nonce_counter The 128-bit nonce and counter. 232 * \param stream_block The saved stream-block for resuming. Is overwritten 233 * by the function. 234 * \param input The input data stream 235 * \param output The output data stream 236 * 237 * \return 0 if successful 238 */ 239 int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx, 240 size_t length, 241 size_t *nc_off, 242 unsigned char nonce_counter[16], 243 unsigned char stream_block[16], 244 const unsigned char *input, 245 unsigned char *output ); 246 #endif /* MBEDTLS_CIPHER_MODE_CTR */ 247 248 /** 249 * \brief Internal AES block encryption function 250 * (Only exposed to allow overriding it, 251 * see MBEDTLS_AES_ENCRYPT_ALT) 252 * 253 * \param ctx AES context 254 * \param input Plaintext block 255 * \param output Output (ciphertext) block 256 */ 257 void mbedtls_aes_encrypt( mbedtls_aes_context *ctx, 258 const unsigned char input[16], 259 unsigned char output[16] ); 260 261 /** 262 * \brief Internal AES block decryption function 263 * (Only exposed to allow overriding it, 264 * see MBEDTLS_AES_DECRYPT_ALT) 265 * 266 * \param ctx AES context 267 * \param input Ciphertext block 268 * \param output Output (plaintext) block 269 */ 270 void mbedtls_aes_decrypt( mbedtls_aes_context *ctx, 271 const unsigned char input[16], 272 unsigned char output[16] ); 273 274 #ifdef __cplusplus 275 } 276 #endif 277 278 #else /* MBEDTLS_AES_ALT */ 279 #include "aes_alt.h" 280 #endif /* MBEDTLS_AES_ALT */ 281 282 #ifdef __cplusplus 283 extern "C" { 284 #endif 285 286 /** 287 * \brief Checkup routine 288 * 289 * \return 0 if successful, or 1 if the test failed 290 */ 291 int mbedtls_aes_self_test( int verbose ); 292 293 #ifdef __cplusplus 294 } 295 #endif 296 297 #endif /* aes.h */ 298
