Back to home page

EIC code displayed by LXR

 
 

    


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 */