|
|
|||
File indexing completed on 2026-05-10 08:44:49
0001 /** 0002 * \file aes.h 0003 * 0004 * \brief This file contains AES definitions and functions. 0005 * 0006 * The Advanced Encryption Standard (AES) specifies a FIPS-approved 0007 * cryptographic algorithm that can be used to protect electronic 0008 * data. 0009 * 0010 * The AES algorithm is a symmetric block cipher that can 0011 * encrypt and decrypt information. For more information, see 0012 * <em>FIPS Publication 197: Advanced Encryption Standard</em> and 0013 * <em>ISO/IEC 18033-2:2006: Information technology -- Security 0014 * techniques -- Encryption algorithms -- Part 2: Asymmetric 0015 * ciphers</em>. 0016 * 0017 * The AES-XTS block mode is standardized by NIST SP 800-38E 0018 * <https://nvlpubs.nist.gov/nistpubs/legacy/sp/nistspecialpublication800-38e.pdf> 0019 * and described in detail by IEEE P1619 0020 * <https://ieeexplore.ieee.org/servlet/opac?punumber=4375278>. 0021 */ 0022 0023 /* 0024 * Copyright The Mbed TLS Contributors 0025 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 0026 */ 0027 0028 #ifndef MBEDTLS_AES_H 0029 #define MBEDTLS_AES_H 0030 #include "mbedtls/private_access.h" 0031 0032 #include "tf-psa-crypto/build_info.h" 0033 #include "mbedtls/platform_util.h" 0034 0035 #include <stddef.h> 0036 #include <stdint.h> 0037 0038 #if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS) 0039 /* aesni.c relies on these values! */ 0040 #define MBEDTLS_AES_ENCRYPT 1 /**< AES encryption. */ 0041 #define MBEDTLS_AES_DECRYPT 0 /**< AES decryption. */ 0042 #endif /* MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS */ 0043 0044 /* Error codes in range 0x0020-0x0022 */ 0045 /** Invalid key length. */ 0046 #define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH -0x0020 0047 /** Invalid data input length. */ 0048 #define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH -0x0022 0049 0050 /** Invalid input data. */ 0051 #define MBEDTLS_ERR_AES_BAD_INPUT_DATA PSA_ERROR_INVALID_ARGUMENT 0052 0053 #ifdef __cplusplus 0054 extern "C" { 0055 #endif 0056 0057 /** 0058 * \brief The AES context-type definition. 0059 */ 0060 typedef struct mbedtls_aes_context { 0061 int MBEDTLS_PRIVATE(nr); /*!< The number of rounds. */ 0062 size_t MBEDTLS_PRIVATE(rk_offset); /*!< The offset in array elements to AES 0063 round keys in the buffer. */ 0064 #if defined(MBEDTLS_AES_ONLY_128_BIT_KEY_LENGTH) 0065 uint32_t MBEDTLS_PRIVATE(buf)[44]; /*!< Aligned data buffer to hold 0066 10 round keys for 128-bit case. */ 0067 #else 0068 uint32_t MBEDTLS_PRIVATE(buf)[68]; /*!< Unaligned data buffer. This buffer can 0069 hold 32 extra Bytes, which can be used for 0070 simplifying key expansion in the 256-bit 0071 case by generating an extra round key. */ 0072 #endif /* MBEDTLS_AES_ONLY_128_BIT_KEY_LENGTH */ 0073 } 0074 mbedtls_aes_context; 0075 0076 #if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS) 0077 #if defined(MBEDTLS_CIPHER_MODE_XTS) 0078 /** 0079 * \brief The AES XTS context-type definition. 0080 */ 0081 typedef struct mbedtls_aes_xts_context { 0082 mbedtls_aes_context MBEDTLS_PRIVATE(crypt); /*!< The AES context to use for AES block 0083 encryption or decryption. */ 0084 mbedtls_aes_context MBEDTLS_PRIVATE(tweak); /*!< The AES context used for tweak 0085 computation. */ 0086 } mbedtls_aes_xts_context; 0087 #endif /* MBEDTLS_CIPHER_MODE_XTS */ 0088 0089 typedef enum { 0090 MBEDTLS_AES_IMP_UNKNOWN = -1, 0091 MBEDTLS_AES_IMP_SOFTWARE, 0092 MBEDTLS_AES_IMP_AESCE, 0093 MBEDTLS_AES_IMP_AESNI_ASM, 0094 MBEDTLS_AES_IMP_AESNI_INTRINSICS, 0095 } mbedtls_aes_implementation; 0096 0097 /** 0098 * \brief This function initializes the specified AES context. 0099 * 0100 * It must be the first API called before using 0101 * the context. 0102 * 0103 * \param ctx The AES context to initialize. This must not be \c NULL. 0104 */ 0105 void mbedtls_aes_init(mbedtls_aes_context *ctx); 0106 0107 /** 0108 * \brief This function releases and clears the specified AES context. 0109 * 0110 * \param ctx The AES context to clear. 0111 * If this is \c NULL, this function does nothing. 0112 * Otherwise, the context must have been at least initialized. 0113 */ 0114 void mbedtls_aes_free(mbedtls_aes_context *ctx); 0115 0116 /** 0117 * \brief This function returns the AES implementation. 0118 * 0119 * The options are: unknown, software AES, AESCE, AESNI 0120 * assembly, and AESNI intrinsics. 0121 * 0122 * \return The enum corresponding to the AES implementation. 0123 */ 0124 mbedtls_aes_implementation mbedtls_aes_get_implementation(void); 0125 0126 #if defined(MBEDTLS_CIPHER_MODE_XTS) 0127 /** 0128 * \brief This function initializes the specified AES XTS context. 0129 * 0130 * It must be the first API called before using 0131 * the context. 0132 * 0133 * \param ctx The AES XTS context to initialize. This must not be \c NULL. 0134 */ 0135 void mbedtls_aes_xts_init(mbedtls_aes_xts_context *ctx); 0136 0137 /** 0138 * \brief This function releases and clears the specified AES XTS context. 0139 * 0140 * \param ctx The AES XTS context to clear. 0141 * If this is \c NULL, this function does nothing. 0142 * Otherwise, the context must have been at least initialized. 0143 */ 0144 void mbedtls_aes_xts_free(mbedtls_aes_xts_context *ctx); 0145 #endif /* MBEDTLS_CIPHER_MODE_XTS */ 0146 0147 /** 0148 * \brief This function sets the encryption key. 0149 * 0150 * \param ctx The AES context to which the key should be bound. 0151 * It must be initialized. 0152 * \param key The encryption key. 0153 * This must be a readable buffer of size \p keybits bits. 0154 * \param keybits The size of data passed in bits. Valid options are: 0155 * <ul><li>128 bits</li> 0156 * <li>192 bits</li> 0157 * <li>256 bits</li></ul> 0158 * 0159 * \return \c 0 on success. 0160 * \return #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure. 0161 */ 0162 MBEDTLS_CHECK_RETURN_TYPICAL 0163 int mbedtls_aes_setkey_enc(mbedtls_aes_context *ctx, const unsigned char *key, 0164 unsigned int keybits); 0165 0166 #if !defined(MBEDTLS_BLOCK_CIPHER_NO_DECRYPT) 0167 /** 0168 * \brief This function sets the decryption key. 0169 * 0170 * \param ctx The AES context to which the key should be bound. 0171 * It must be initialized. 0172 * \param key The decryption key. 0173 * This must be a readable buffer of size \p keybits bits. 0174 * \param keybits The size of data passed. Valid options are: 0175 * <ul><li>128 bits</li> 0176 * <li>192 bits</li> 0177 * <li>256 bits</li></ul> 0178 * 0179 * \return \c 0 on success. 0180 * \return #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure. 0181 */ 0182 MBEDTLS_CHECK_RETURN_TYPICAL 0183 int mbedtls_aes_setkey_dec(mbedtls_aes_context *ctx, const unsigned char *key, 0184 unsigned int keybits); 0185 #endif /* !MBEDTLS_BLOCK_CIPHER_NO_DECRYPT */ 0186 0187 #if defined(MBEDTLS_CIPHER_MODE_XTS) 0188 /** 0189 * \brief This function prepares an XTS context for encryption and 0190 * sets the encryption key. 0191 * 0192 * \param ctx The AES XTS context to which the key should be bound. 0193 * It must be initialized. 0194 * \param key The encryption key. This is comprised of the XTS key1 0195 * concatenated with the XTS key2. 0196 * This must be a readable buffer of size \p keybits bits. 0197 * \param keybits The size of \p key passed in bits. Valid options are: 0198 * <ul><li>256 bits (each of key1 and key2 is a 128-bit key)</li> 0199 * <li>512 bits (each of key1 and key2 is a 256-bit key)</li></ul> 0200 * 0201 * \return \c 0 on success. 0202 * \return #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure. 0203 */ 0204 MBEDTLS_CHECK_RETURN_TYPICAL 0205 int mbedtls_aes_xts_setkey_enc(mbedtls_aes_xts_context *ctx, 0206 const unsigned char *key, 0207 unsigned int keybits); 0208 0209 /** 0210 * \brief This function prepares an XTS context for decryption and 0211 * sets the decryption key. 0212 * 0213 * \param ctx The AES XTS context to which the key should be bound. 0214 * It must be initialized. 0215 * \param key The decryption key. This is comprised of the XTS key1 0216 * concatenated with the XTS key2. 0217 * This must be a readable buffer of size \p keybits bits. 0218 * \param keybits The size of \p key passed in bits. Valid options are: 0219 * <ul><li>256 bits (each of key1 and key2 is a 128-bit key)</li> 0220 * <li>512 bits (each of key1 and key2 is a 256-bit key)</li></ul> 0221 * 0222 * \return \c 0 on success. 0223 * \return #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure. 0224 */ 0225 MBEDTLS_CHECK_RETURN_TYPICAL 0226 int mbedtls_aes_xts_setkey_dec(mbedtls_aes_xts_context *ctx, 0227 const unsigned char *key, 0228 unsigned int keybits); 0229 #endif /* MBEDTLS_CIPHER_MODE_XTS */ 0230 0231 /** 0232 * \brief This function performs an AES single-block encryption or 0233 * decryption operation. 0234 * 0235 * It performs the operation defined in the \p mode parameter 0236 * (encrypt or decrypt), on the input data buffer defined in 0237 * the \p input parameter. 0238 * 0239 * mbedtls_aes_init(), and either mbedtls_aes_setkey_enc() or 0240 * mbedtls_aes_setkey_dec() must be called before the first 0241 * call to this API with the same context. 0242 * 0243 * \param ctx The AES context to use for encryption or decryption. 0244 * It must be initialized and bound to a key. 0245 * \param mode The AES operation: MBEDTLS_AES_ENCRYPT or 0246 * MBEDTLS_AES_DECRYPT. 0247 * \param input The buffer holding the input data. 0248 * It must be readable and at least \c 16 Bytes long. 0249 * \param output The buffer where the output data will be written. 0250 * It must be writeable and at least \c 16 Bytes long. 0251 0252 * \return \c 0 on success. 0253 */ 0254 MBEDTLS_CHECK_RETURN_TYPICAL 0255 int mbedtls_aes_crypt_ecb(mbedtls_aes_context *ctx, 0256 int mode, 0257 const unsigned char input[16], 0258 unsigned char output[16]); 0259 0260 #if defined(MBEDTLS_CIPHER_MODE_CBC) 0261 /** 0262 * \brief This function performs an AES-CBC encryption or decryption operation 0263 * on full blocks. 0264 * 0265 * It performs the operation defined in the \p mode 0266 * parameter (encrypt/decrypt), on the input data buffer defined in 0267 * the \p input parameter. 0268 * 0269 * It can be called as many times as needed, until all the input 0270 * data is processed. mbedtls_aes_init(), and either 0271 * mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called 0272 * before the first call to this API with the same context. 0273 * 0274 * \note This function operates on full blocks, that is, the input size 0275 * must be a multiple of the AES block size of \c 16 Bytes. 0276 * 0277 * \note Upon exit, the content of the IV is updated so that you can 0278 * call the same function again on the next 0279 * block(s) of data and get the same result as if it was 0280 * encrypted in one call. This allows a "streaming" usage. 0281 * If you need to retain the contents of the IV, you should 0282 * either save it manually or use the cipher module instead. 0283 * 0284 * 0285 * \param ctx The AES context to use for encryption or decryption. 0286 * It must be initialized and bound to a key. 0287 * \param mode The AES operation: MBEDTLS_AES_ENCRYPT or 0288 * MBEDTLS_AES_DECRYPT. 0289 * \param length The length of the input data in Bytes. This must be a 0290 * multiple of the block size (\c 16 Bytes). 0291 * \param iv Initialization vector (updated after use). 0292 * It must be a readable and writeable buffer of \c 16 Bytes. 0293 * \param input The buffer holding the input data. 0294 * It must be readable and of size \p length Bytes. 0295 * \param output The buffer holding the output data. 0296 * It must be writeable and of size \p length Bytes. 0297 * 0298 * \return \c 0 on success. 0299 * \return #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH 0300 * on failure. 0301 */ 0302 MBEDTLS_CHECK_RETURN_TYPICAL 0303 int mbedtls_aes_crypt_cbc(mbedtls_aes_context *ctx, 0304 int mode, 0305 size_t length, 0306 unsigned char iv[16], 0307 const unsigned char *input, 0308 unsigned char *output); 0309 #endif /* MBEDTLS_CIPHER_MODE_CBC */ 0310 0311 #if defined(MBEDTLS_CIPHER_MODE_XTS) 0312 /** 0313 * \brief This function performs an AES-XTS encryption or decryption 0314 * operation for an entire XTS data unit. 0315 * 0316 * AES-XTS encrypts or decrypts blocks based on their location as 0317 * defined by a data unit number. The data unit number must be 0318 * provided by \p data_unit. 0319 * 0320 * NIST SP 800-38E limits the maximum size of a data unit to 2^20 0321 * AES blocks. If the data unit is larger than this, this function 0322 * returns #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH. 0323 * 0324 * \param ctx The AES XTS context to use for AES XTS operations. 0325 * It must be initialized and bound to a key. 0326 * \param mode The AES operation: MBEDTLS_AES_ENCRYPT or 0327 * MBEDTLS_AES_DECRYPT. 0328 * \param length The length of a data unit in Bytes. This can be any 0329 * length between 16 bytes and 2^24 bytes inclusive 0330 * (between 1 and 2^20 block cipher blocks). 0331 * \param data_unit The address of the data unit encoded as an array of 16 0332 * bytes in little-endian format. For disk encryption, this 0333 * is typically the index of the block device sector that 0334 * contains the data. 0335 * \param input The buffer holding the input data (which is an entire 0336 * data unit). This function reads \p length Bytes from \p 0337 * input. 0338 * \param output The buffer holding the output data (which is an entire 0339 * data unit). This function writes \p length Bytes to \p 0340 * output. 0341 * 0342 * \return \c 0 on success. 0343 * \return #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH if \p length is 0344 * smaller than an AES block in size (16 Bytes) or if \p 0345 * length is larger than 2^20 blocks (16 MiB). 0346 */ 0347 MBEDTLS_CHECK_RETURN_TYPICAL 0348 int mbedtls_aes_crypt_xts(mbedtls_aes_xts_context *ctx, 0349 int mode, 0350 size_t length, 0351 const unsigned char data_unit[16], 0352 const unsigned char *input, 0353 unsigned char *output); 0354 #endif /* MBEDTLS_CIPHER_MODE_XTS */ 0355 0356 #if defined(MBEDTLS_CIPHER_MODE_CFB) 0357 /** 0358 * \brief This function performs an AES-CFB128 encryption or decryption 0359 * operation. 0360 * 0361 * It performs the operation defined in the \p mode 0362 * parameter (encrypt or decrypt), on the input data buffer 0363 * defined in the \p input parameter. 0364 * 0365 * For CFB, you must set up the context with mbedtls_aes_setkey_enc(), 0366 * regardless of whether you are performing an encryption or decryption 0367 * operation, that is, regardless of the \p mode parameter. This is 0368 * because CFB mode uses the same key schedule for encryption and 0369 * decryption. 0370 * 0371 * \note Upon exit, the content of the IV is updated so that you can 0372 * call the same function again on the next 0373 * block(s) of data and get the same result as if it was 0374 * encrypted in one call. This allows a "streaming" usage. 0375 * If you need to retain the contents of the 0376 * IV, you must either save it manually or use the cipher 0377 * module instead. 0378 * 0379 * 0380 * \param ctx The AES context to use for encryption or decryption. 0381 * It must be initialized and bound to a key. 0382 * \param mode The AES operation: MBEDTLS_AES_ENCRYPT or 0383 * MBEDTLS_AES_DECRYPT. 0384 * \param length The length of the input data in Bytes. 0385 * \param iv_off The offset in IV (updated after use). 0386 * It must point to a valid \c size_t. 0387 * \param iv The initialization vector (updated after use). 0388 * It must be a readable and writeable buffer of \c 16 Bytes. 0389 * \param input The buffer holding the input data. 0390 * It must be readable and of size \p length Bytes. 0391 * \param output The buffer holding the output data. 0392 * It must be writeable and of size \p length Bytes. 0393 * 0394 * \return \c 0 on success. 0395 */ 0396 MBEDTLS_CHECK_RETURN_TYPICAL 0397 int mbedtls_aes_crypt_cfb128(mbedtls_aes_context *ctx, 0398 int mode, 0399 size_t length, 0400 size_t *iv_off, 0401 unsigned char iv[16], 0402 const unsigned char *input, 0403 unsigned char *output); 0404 0405 /** 0406 * \brief This function performs an AES-CFB8 encryption or decryption 0407 * operation. 0408 * 0409 * It performs the operation defined in the \p mode 0410 * parameter (encrypt/decrypt), on the input data buffer defined 0411 * in the \p input parameter. 0412 * 0413 * Due to the nature of CFB, you must use the same key schedule for 0414 * both encryption and decryption operations. Therefore, you must 0415 * use the context initialized with mbedtls_aes_setkey_enc() for 0416 * both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. 0417 * 0418 * \note Upon exit, the content of the IV is updated so that you can 0419 * call the same function again on the next 0420 * block(s) of data and get the same result as if it was 0421 * encrypted in one call. This allows a "streaming" usage. 0422 * If you need to retain the contents of the 0423 * IV, you should either save it manually or use the cipher 0424 * module instead. 0425 * 0426 * 0427 * \param ctx The AES context to use for encryption or decryption. 0428 * It must be initialized and bound to a key. 0429 * \param mode The AES operation: MBEDTLS_AES_ENCRYPT or 0430 * MBEDTLS_AES_DECRYPT 0431 * \param length The length of the input data. 0432 * \param iv The initialization vector (updated after use). 0433 * It must be a readable and writeable buffer of \c 16 Bytes. 0434 * \param input The buffer holding the input data. 0435 * It must be readable and of size \p length Bytes. 0436 * \param output The buffer holding the output data. 0437 * It must be writeable and of size \p length Bytes. 0438 * 0439 * \return \c 0 on success. 0440 */ 0441 MBEDTLS_CHECK_RETURN_TYPICAL 0442 int mbedtls_aes_crypt_cfb8(mbedtls_aes_context *ctx, 0443 int mode, 0444 size_t length, 0445 unsigned char iv[16], 0446 const unsigned char *input, 0447 unsigned char *output); 0448 #endif /*MBEDTLS_CIPHER_MODE_CFB */ 0449 0450 #if defined(MBEDTLS_CIPHER_MODE_OFB) 0451 /** 0452 * \brief This function performs an AES-OFB (Output Feedback Mode) 0453 * encryption or decryption operation. 0454 * 0455 * For OFB, you must set up the context with 0456 * mbedtls_aes_setkey_enc(), regardless of whether you are 0457 * performing an encryption or decryption operation. This is 0458 * because OFB mode uses the same key schedule for encryption and 0459 * decryption. 0460 * 0461 * The OFB operation is identical for encryption or decryption, 0462 * therefore no operation mode needs to be specified. 0463 * 0464 * \note Upon exit, the content of iv, the Initialisation Vector, is 0465 * updated so that you can call the same function again on the next 0466 * block(s) of data and get the same result as if it was encrypted 0467 * in one call. This allows a "streaming" usage, by initialising 0468 * iv_off to 0 before the first call, and preserving its value 0469 * between calls. 0470 * 0471 * For non-streaming use, the iv should be initialised on each call 0472 * to a unique value, and iv_off set to 0 on each call. 0473 * 0474 * If you need to retain the contents of the initialisation vector, 0475 * you must either save it manually or use the cipher module 0476 * instead. 0477 * 0478 * \warning For the OFB mode, the initialisation vector must be unique 0479 * every encryption operation. Reuse of an initialisation vector 0480 * will compromise security. 0481 * 0482 * \param ctx The AES context to use for encryption or decryption. 0483 * It must be initialized and bound to a key. 0484 * \param length The length of the input data. 0485 * \param iv_off The offset in IV (updated after use). 0486 * It must point to a valid \c size_t. 0487 * \param iv The initialization vector (updated after use). 0488 * It must be a readable and writeable buffer of \c 16 Bytes. 0489 * \param input The buffer holding the input data. 0490 * It must be readable and of size \p length Bytes. 0491 * \param output The buffer holding the output data. 0492 * It must be writeable and of size \p length Bytes. 0493 * 0494 * \return \c 0 on success. 0495 */ 0496 MBEDTLS_CHECK_RETURN_TYPICAL 0497 int mbedtls_aes_crypt_ofb(mbedtls_aes_context *ctx, 0498 size_t length, 0499 size_t *iv_off, 0500 unsigned char iv[16], 0501 const unsigned char *input, 0502 unsigned char *output); 0503 0504 #endif /* MBEDTLS_CIPHER_MODE_OFB */ 0505 0506 #if defined(MBEDTLS_CIPHER_MODE_CTR) 0507 /** 0508 * \brief This function performs an AES-CTR encryption or decryption 0509 * operation. 0510 * 0511 * Due to the nature of CTR, you must use the same key schedule 0512 * for both encryption and decryption operations. Therefore, you 0513 * must use the context initialized with mbedtls_aes_setkey_enc() 0514 * for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. 0515 * 0516 * \warning You must never reuse a nonce value with the same key. Doing so 0517 * would void the encryption for the two messages encrypted with 0518 * the same nonce and key. 0519 * 0520 * There are two common strategies for managing nonces with CTR: 0521 * 0522 * 1. You can handle everything as a single message processed over 0523 * successive calls to this function. In that case, you want to 0524 * set \p nonce_counter and \p nc_off to 0 for the first call, and 0525 * then preserve the values of \p nonce_counter, \p nc_off and \p 0526 * stream_block across calls to this function as they will be 0527 * updated by this function. 0528 * 0529 * With this strategy, you must not encrypt more than 2**128 0530 * blocks of data with the same key. 0531 * 0532 * 2. You can encrypt separate messages by dividing the \p 0533 * nonce_counter buffer in two areas: the first one used for a 0534 * per-message nonce, handled by yourself, and the second one 0535 * updated by this function internally. 0536 * 0537 * For example, you might reserve the first 12 bytes for the 0538 * per-message nonce, and the last 4 bytes for internal use. In that 0539 * case, before calling this function on a new message you need to 0540 * set the first 12 bytes of \p nonce_counter to your chosen nonce 0541 * value, the last 4 to 0, and \p nc_off to 0 (which will cause \p 0542 * stream_block to be ignored). That way, you can encrypt at most 0543 * 2**96 messages of up to 2**32 blocks each with the same key. 0544 * 0545 * The per-message nonce (or information sufficient to reconstruct 0546 * it) needs to be communicated with the ciphertext and must be unique. 0547 * The recommended way to ensure uniqueness is to use a message 0548 * counter. An alternative is to generate random nonces, but this 0549 * limits the number of messages that can be securely encrypted: 0550 * for example, with 96-bit random nonces, you should not encrypt 0551 * more than 2**32 messages with the same key. 0552 * 0553 * Note that for both strategies, sizes are measured in blocks and 0554 * that an AES block is 16 bytes. 0555 * 0556 * \warning Upon return, \p stream_block contains sensitive data. Its 0557 * content must not be written to insecure storage and should be 0558 * securely discarded as soon as it's no longer needed. 0559 * 0560 * \param ctx The AES context to use for encryption or decryption. 0561 * It must be initialized and bound to a key. 0562 * \param length The length of the input data. 0563 * \param nc_off The offset in the current \p stream_block, for 0564 * resuming within the current cipher stream. The 0565 * offset pointer should be 0 at the start of a stream. 0566 * It must point to a valid \c size_t. 0567 * \param nonce_counter The 128-bit nonce and counter. 0568 * It must be a readable-writeable buffer of \c 16 Bytes. 0569 * \param stream_block The saved stream block for resuming. This is 0570 * overwritten by the function. 0571 * It must be a readable-writeable buffer of \c 16 Bytes. 0572 * \param input The buffer holding the input data. 0573 * It must be readable and of size \p length Bytes. 0574 * \param output The buffer holding the output data. 0575 * It must be writeable and of size \p length Bytes. 0576 * 0577 * \return \c 0 on success. 0578 */ 0579 MBEDTLS_CHECK_RETURN_TYPICAL 0580 int mbedtls_aes_crypt_ctr(mbedtls_aes_context *ctx, 0581 size_t length, 0582 size_t *nc_off, 0583 unsigned char nonce_counter[16], 0584 unsigned char stream_block[16], 0585 const unsigned char *input, 0586 unsigned char *output); 0587 #endif /* MBEDTLS_CIPHER_MODE_CTR */ 0588 0589 #if defined(MBEDTLS_SELF_TEST) 0590 /** 0591 * \brief Checkup routine. 0592 * 0593 * \return \c 0 on success. 0594 * \return \c 1 on failure. 0595 */ 0596 MBEDTLS_CHECK_RETURN_CRITICAL 0597 int mbedtls_aes_self_test(int verbose); 0598 0599 #endif /* MBEDTLS_SELF_TEST */ 0600 0601 #endif /* MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS */ 0602 0603 #ifdef __cplusplus 0604 } 0605 #endif 0606 0607 #endif /* aes.h */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|