aes.h

00001 /**
00002  * \file aes.h
00003  *
00004  * \brief   This file contains AES definitions and functions.
00005  *
00006  *          The Advanced Encryption Standard (AES) specifies a FIPS-approved
00007  *          cryptographic algorithm that can be used to protect electronic
00008  *          data.
00009  *
00010  *          The AES algorithm is a symmetric block cipher that can
00011  *          encrypt and decrypt information. For more information, see
00012  *          <em>FIPS Publication 197: Advanced Encryption Standard</em> and
00013  *          <em>ISO/IEC 18033-2:2006: Information technology -- Security
00014  *          techniques -- Encryption algorithms -- Part 2: Asymmetric
00015  *          ciphers</em>.
00016  *
00017  *          The AES-XTS block mode is standardized by NIST SP 800-38E
00018  *          <https://nvlpubs.nist.gov/nistpubs/legacy/sp/nistspecialpublication800-38e.pdf>
00019  *          and described in detail by IEEE P1619
00020  *          <https://ieeexplore.ieee.org/servlet/opac?punumber=4375278>.
00021  */
00022 
00023 /*  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
00024  *  SPDX-License-Identifier: Apache-2.0
00025  *
00026  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00027  *  not use this file except in compliance with the License.
00028  *  You may obtain a copy of the License at
00029  *
00030  *  http://www.apache.org/licenses/LICENSE-2.0
00031  *
00032  *  Unless required by applicable law or agreed to in writing, software
00033  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00034  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00035  *  See the License for the specific language governing permissions and
00036  *  limitations under the License.
00037  *
00038  *  This file is part of Mbed TLS (https://tls.mbed.org)
00039  */
00040 
00041 #ifndef MBEDTLS_AES_H
00042 #define MBEDTLS_AES_H
00043 
00044 #if !defined(MBEDTLS_CONFIG_FILE)
00045 #include "mbedtls/config.h"
00046 #else
00047 #include MBEDTLS_CONFIG_FILE
00048 #endif
00049 
00050 #include <stddef.h>
00051 #include <stdint.h>
00052 
00053 /* padlock.c and aesni.c rely on these values! */
00054 #define MBEDTLS_AES_ENCRYPT     1 /**< AES encryption. */
00055 #define MBEDTLS_AES_DECRYPT     0 /**< AES decryption. */
00056 
00057 /* Error codes in range 0x0020-0x0022 */
00058 #define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH                -0x0020  /**< Invalid key length. */
00059 #define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH              -0x0022  /**< Invalid data input length. */
00060 
00061 /* Error codes in range 0x0021-0x0025 */
00062 #define MBEDTLS_ERR_AES_BAD_INPUT_DATA                    -0x0021  /**< Invalid input data. */
00063 
00064 /* MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE is deprecated and should not be used. */
00065 #define MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE               -0x0023  /**< Feature not available. For example, an unsupported AES key size. */
00066 
00067 /* MBEDTLS_ERR_AES_HW_ACCEL_FAILED is deprecated and should not be used. */
00068 #define MBEDTLS_ERR_AES_HW_ACCEL_FAILED                   -0x0025  /**< AES hardware accelerator failed. */
00069 
00070 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
00071     !defined(inline) && !defined(__cplusplus)
00072 #define inline __inline
00073 #endif
00074 
00075 #ifdef __cplusplus
00076 extern "C" {
00077 #endif
00078 
00079 #if !defined(MBEDTLS_AES_ALT)
00080 // Regular implementation
00081 //
00082 
00083 /**
00084  * \brief The AES context-type definition.
00085  */
00086 typedef struct mbedtls_aes_context
00087 {
00088     int nr ;                     /*!< The number of rounds. */
00089     uint32_t *rk ;               /*!< AES round keys. */
00090     uint32_t buf [68];           /*!< Unaligned data buffer. This buffer can
00091                                      hold 32 extra Bytes, which can be used for
00092                                      one of the following purposes:
00093                                      <ul><li>Alignment if VIA padlock is
00094                                              used.</li>
00095                                      <li>Simplifying key expansion in the 256-bit
00096                                          case by generating an extra round key.
00097                                          </li></ul> */
00098 }
00099 mbedtls_aes_context;
00100 
00101 #if defined(MBEDTLS_CIPHER_MODE_XTS)
00102 /**
00103  * \brief The AES XTS context-type definition.
00104  */
00105 typedef struct mbedtls_aes_xts_context
00106 {
00107     mbedtls_aes_context crypt ; /*!< The AES context to use for AES block
00108                                         encryption or decryption. */
00109     mbedtls_aes_context tweak ; /*!< The AES context used for tweak
00110                                         computation. */
00111 } mbedtls_aes_xts_context;
00112 #endif /* MBEDTLS_CIPHER_MODE_XTS */
00113 
00114 #else  /* MBEDTLS_AES_ALT */
00115 #include "aes_alt.h"
00116 #endif /* MBEDTLS_AES_ALT */
00117 
00118 /**
00119  * \brief          This function initializes the specified AES context.
00120  *
00121  *                 It must be the first API called before using
00122  *                 the context.
00123  *
00124  * \param ctx      The AES context to initialize. This must not be \c NULL.
00125  */
00126 void mbedtls_aes_init( mbedtls_aes_context *ctx );
00127 
00128 /**
00129  * \brief          This function releases and clears the specified AES context.
00130  *
00131  * \param ctx      The AES context to clear.
00132  *                 If this is \c NULL, this function does nothing.
00133  *                 Otherwise, the context must have been at least initialized.
00134  */
00135 void mbedtls_aes_free( mbedtls_aes_context *ctx );
00136 
00137 #if defined(MBEDTLS_CIPHER_MODE_XTS)
00138 /**
00139  * \brief          This function initializes the specified AES XTS context.
00140  *
00141  *                 It must be the first API called before using
00142  *                 the context.
00143  *
00144  * \param ctx      The AES XTS context to initialize. This must not be \c NULL.
00145  */
00146 void mbedtls_aes_xts_init( mbedtls_aes_xts_context *ctx );
00147 
00148 /**
00149  * \brief          This function releases and clears the specified AES XTS context.
00150  *
00151  * \param ctx      The AES XTS context to clear.
00152  *                 If this is \c NULL, this function does nothing.
00153  *                 Otherwise, the context must have been at least initialized.
00154  */
00155 void mbedtls_aes_xts_free( mbedtls_aes_xts_context *ctx );
00156 #endif /* MBEDTLS_CIPHER_MODE_XTS */
00157 
00158 /**
00159  * \brief          This function sets the encryption key.
00160  *
00161  * \param ctx      The AES context to which the key should be bound.
00162  *                 It must be initialized.
00163  * \param key      The encryption key.
00164  *                 This must be a readable buffer of size \p keybits bits.
00165  * \param keybits  The size of data passed in bits. Valid options are:
00166  *                 <ul><li>128 bits</li>
00167  *                 <li>192 bits</li>
00168  *                 <li>256 bits</li></ul>
00169  *
00170  * \return         \c 0 on success.
00171  * \return         #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
00172  */
00173 int mbedtls_aes_setkey_enc( mbedtls_aes_context *ctx, const unsigned char *key,
00174                     unsigned int keybits );
00175 
00176 /**
00177  * \brief          This function sets the decryption key.
00178  *
00179  * \param ctx      The AES context to which the key should be bound.
00180  *                 It must be initialized.
00181  * \param key      The decryption key.
00182  *                 This must be a readable buffer of size \p keybits bits.
00183  * \param keybits  The size of data passed. Valid options are:
00184  *                 <ul><li>128 bits</li>
00185  *                 <li>192 bits</li>
00186  *                 <li>256 bits</li></ul>
00187  *
00188  * \return         \c 0 on success.
00189  * \return         #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
00190  */
00191 int mbedtls_aes_setkey_dec( mbedtls_aes_context *ctx, const unsigned char *key,
00192                     unsigned int keybits );
00193 
00194 #if defined(MBEDTLS_CIPHER_MODE_XTS)
00195 /**
00196  * \brief          This function prepares an XTS context for encryption and
00197  *                 sets the encryption key.
00198  *
00199  * \param ctx      The AES XTS context to which the key should be bound.
00200  *                 It must be initialized.
00201  * \param key      The encryption key. This is comprised of the XTS key1
00202  *                 concatenated with the XTS key2.
00203  *                 This must be a readable buffer of size \p keybits bits.
00204  * \param keybits  The size of \p key passed in bits. Valid options are:
00205  *                 <ul><li>256 bits (each of key1 and key2 is a 128-bit key)</li>
00206  *                 <li>512 bits (each of key1 and key2 is a 256-bit key)</li></ul>
00207  *
00208  * \return         \c 0 on success.
00209  * \return         #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
00210  */
00211 int mbedtls_aes_xts_setkey_enc( mbedtls_aes_xts_context *ctx,
00212                                 const unsigned char *key,
00213                                 unsigned int keybits );
00214 
00215 /**
00216  * \brief          This function prepares an XTS context for decryption and
00217  *                 sets the decryption key.
00218  *
00219  * \param ctx      The AES XTS context to which the key should be bound.
00220  *                 It must be initialized.
00221  * \param key      The decryption key. This is comprised of the XTS key1
00222  *                 concatenated with the XTS key2.
00223  *                 This must be a readable buffer of size \p keybits bits.
00224  * \param keybits  The size of \p key passed in bits. Valid options are:
00225  *                 <ul><li>256 bits (each of key1 and key2 is a 128-bit key)</li>
00226  *                 <li>512 bits (each of key1 and key2 is a 256-bit key)</li></ul>
00227  *
00228  * \return         \c 0 on success.
00229  * \return         #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
00230  */
00231 int mbedtls_aes_xts_setkey_dec( mbedtls_aes_xts_context *ctx,
00232                                 const unsigned char *key,
00233                                 unsigned int keybits );
00234 #endif /* MBEDTLS_CIPHER_MODE_XTS */
00235 
00236 /**
00237  * \brief          This function performs an AES single-block encryption or
00238  *                 decryption operation.
00239  *
00240  *                 It performs the operation defined in the \p mode parameter
00241  *                 (encrypt or decrypt), on the input data buffer defined in
00242  *                 the \p input parameter.
00243  *
00244  *                 mbedtls_aes_init(), and either mbedtls_aes_setkey_enc() or
00245  *                 mbedtls_aes_setkey_dec() must be called before the first
00246  *                 call to this API with the same context.
00247  *
00248  * \param ctx      The AES context to use for encryption or decryption.
00249  *                 It must be initialized and bound to a key.
00250  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or
00251  *                 #MBEDTLS_AES_DECRYPT.
00252  * \param input    The buffer holding the input data.
00253  *                 It must be readable and at least \c 16 Bytes long.
00254  * \param output   The buffer where the output data will be written.
00255  *                 It must be writeable and at least \c 16 Bytes long.
00256 
00257  * \return         \c 0 on success.
00258  */
00259 int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx,
00260                     int mode,
00261                     const unsigned char input[16],
00262                     unsigned char output[16] );
00263 
00264 #if defined(MBEDTLS_CIPHER_MODE_CBC)
00265 /**
00266  * \brief  This function performs an AES-CBC encryption or decryption operation
00267  *         on full blocks.
00268  *
00269  *         It performs the operation defined in the \p mode
00270  *         parameter (encrypt/decrypt), on the input data buffer defined in
00271  *         the \p input parameter.
00272  *
00273  *         It can be called as many times as needed, until all the input
00274  *         data is processed. mbedtls_aes_init(), and either
00275  *         mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called
00276  *         before the first call to this API with the same context.
00277  *
00278  * \note   This function operates on full blocks, that is, the input size
00279  *         must be a multiple of the AES block size of \c 16 Bytes.
00280  *
00281  * \note   Upon exit, the content of the IV is updated so that you can
00282  *         call the same function again on the next
00283  *         block(s) of data and get the same result as if it was
00284  *         encrypted in one call. This allows a "streaming" usage.
00285  *         If you need to retain the contents of the IV, you should
00286  *         either save it manually or use the cipher module instead.
00287  *
00288  *
00289  * \param ctx      The AES context to use for encryption or decryption.
00290  *                 It must be initialized and bound to a key.
00291  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or
00292  *                 #MBEDTLS_AES_DECRYPT.
00293  * \param length   The length of the input data in Bytes. This must be a
00294  *                 multiple of the block size (\c 16 Bytes).
00295  * \param iv       Initialization vector (updated after use).
00296  *                 It must be a readable and writeable buffer of \c 16 Bytes.
00297  * \param input    The buffer holding the input data.
00298  *                 It must be readable and of size \p length Bytes.
00299  * \param output   The buffer holding the output data.
00300  *                 It must be writeable and of size \p length Bytes.
00301  *
00302  * \return         \c 0 on success.
00303  * \return         #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
00304  *                 on failure.
00305  */
00306 int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx,
00307                     int mode,
00308                     size_t length,
00309                     unsigned char iv[16],
00310                     const unsigned char *input,
00311                     unsigned char *output );
00312 #endif /* MBEDTLS_CIPHER_MODE_CBC */
00313 
00314 #if defined(MBEDTLS_CIPHER_MODE_XTS)
00315 /**
00316  * \brief      This function performs an AES-XTS encryption or decryption
00317  *             operation for an entire XTS data unit.
00318  *
00319  *             AES-XTS encrypts or decrypts blocks based on their location as
00320  *             defined by a data unit number. The data unit number must be
00321  *             provided by \p data_unit.
00322  *
00323  *             NIST SP 800-38E limits the maximum size of a data unit to 2^20
00324  *             AES blocks. If the data unit is larger than this, this function
00325  *             returns #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH.
00326  *
00327  * \param ctx          The AES XTS context to use for AES XTS operations.
00328  *                     It must be initialized and bound to a key.
00329  * \param mode         The AES operation: #MBEDTLS_AES_ENCRYPT or
00330  *                     #MBEDTLS_AES_DECRYPT.
00331  * \param length       The length of a data unit in Bytes. This can be any
00332  *                     length between 16 bytes and 2^24 bytes inclusive
00333  *                     (between 1 and 2^20 block cipher blocks).
00334  * \param data_unit    The address of the data unit encoded as an array of 16
00335  *                     bytes in little-endian format. For disk encryption, this
00336  *                     is typically the index of the block device sector that
00337  *                     contains the data.
00338  * \param input        The buffer holding the input data (which is an entire
00339  *                     data unit). This function reads \p length Bytes from \p
00340  *                     input.
00341  * \param output       The buffer holding the output data (which is an entire
00342  *                     data unit). This function writes \p length Bytes to \p
00343  *                     output.
00344  *
00345  * \return             \c 0 on success.
00346  * \return             #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH if \p length is
00347  *                     smaller than an AES block in size (16 Bytes) or if \p
00348  *                     length is larger than 2^20 blocks (16 MiB).
00349  */
00350 int mbedtls_aes_crypt_xts( mbedtls_aes_xts_context *ctx,
00351                            int mode,
00352                            size_t length,
00353                            const unsigned char data_unit[16],
00354                            const unsigned char *input,
00355                            unsigned char *output );
00356 #endif /* MBEDTLS_CIPHER_MODE_XTS */
00357 
00358 #if defined(MBEDTLS_CIPHER_MODE_CFB)
00359 /**
00360  * \brief This function performs an AES-CFB128 encryption or decryption
00361  *        operation.
00362  *
00363  *        It performs the operation defined in the \p mode
00364  *        parameter (encrypt or decrypt), on the input data buffer
00365  *        defined in the \p input parameter.
00366  *
00367  *        For CFB, you must set up the context with mbedtls_aes_setkey_enc(),
00368  *        regardless of whether you are performing an encryption or decryption
00369  *        operation, that is, regardless of the \p mode parameter. This is
00370  *        because CFB mode uses the same key schedule for encryption and
00371  *        decryption.
00372  *
00373  * \note  Upon exit, the content of the IV is updated so that you can
00374  *        call the same function again on the next
00375  *        block(s) of data and get the same result as if it was
00376  *        encrypted in one call. This allows a "streaming" usage.
00377  *        If you need to retain the contents of the
00378  *        IV, you must either save it manually or use the cipher
00379  *        module instead.
00380  *
00381  *
00382  * \param ctx      The AES context to use for encryption or decryption.
00383  *                 It must be initialized and bound to a key.
00384  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or
00385  *                 #MBEDTLS_AES_DECRYPT.
00386  * \param length   The length of the input data in Bytes.
00387  * \param iv_off   The offset in IV (updated after use).
00388  *                 It must point to a valid \c size_t.
00389  * \param iv       The initialization vector (updated after use).
00390  *                 It must be a readable and writeable buffer of \c 16 Bytes.
00391  * \param input    The buffer holding the input data.
00392  *                 It must be readable and of size \p length Bytes.
00393  * \param output   The buffer holding the output data.
00394  *                 It must be writeable and of size \p length Bytes.
00395  *
00396  * \return         \c 0 on success.
00397  */
00398 int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx,
00399                        int mode,
00400                        size_t length,
00401                        size_t *iv_off,
00402                        unsigned char iv[16],
00403                        const unsigned char *input,
00404                        unsigned char *output );
00405 
00406 /**
00407  * \brief This function performs an AES-CFB8 encryption or decryption
00408  *        operation.
00409  *
00410  *        It performs the operation defined in the \p mode
00411  *        parameter (encrypt/decrypt), on the input data buffer defined
00412  *        in the \p input parameter.
00413  *
00414  *        Due to the nature of CFB, you must use the same key schedule for
00415  *        both encryption and decryption operations. Therefore, you must
00416  *        use the context initialized with mbedtls_aes_setkey_enc() for
00417  *        both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
00418  *
00419  * \note  Upon exit, the content of the IV is updated so that you can
00420  *        call the same function again on the next
00421  *        block(s) of data and get the same result as if it was
00422  *        encrypted in one call. This allows a "streaming" usage.
00423  *        If you need to retain the contents of the
00424  *        IV, you should either save it manually or use the cipher
00425  *        module instead.
00426  *
00427  *
00428  * \param ctx      The AES context to use for encryption or decryption.
00429  *                 It must be initialized and bound to a key.
00430  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or
00431  *                 #MBEDTLS_AES_DECRYPT
00432  * \param length   The length of the input data.
00433  * \param iv       The initialization vector (updated after use).
00434  *                 It must be a readable and writeable buffer of \c 16 Bytes.
00435  * \param input    The buffer holding the input data.
00436  *                 It must be readable and of size \p length Bytes.
00437  * \param output   The buffer holding the output data.
00438  *                 It must be writeable and of size \p length Bytes.
00439  *
00440  * \return         \c 0 on success.
00441  */
00442 int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx,
00443                     int mode,
00444                     size_t length,
00445                     unsigned char iv[16],
00446                     const unsigned char *input,
00447                     unsigned char *output );
00448 #endif /*MBEDTLS_CIPHER_MODE_CFB */
00449 
00450 #if defined(MBEDTLS_CIPHER_MODE_OFB)
00451 /**
00452  * \brief       This function performs an AES-OFB (Output Feedback Mode)
00453  *              encryption or decryption operation.
00454  *
00455  *              For OFB, you must set up the context with
00456  *              mbedtls_aes_setkey_enc(), regardless of whether you are
00457  *              performing an encryption or decryption operation. This is
00458  *              because OFB mode uses the same key schedule for encryption and
00459  *              decryption.
00460  *
00461  *              The OFB operation is identical for encryption or decryption,
00462  *              therefore no operation mode needs to be specified.
00463  *
00464  * \note        Upon exit, the content of iv, the Initialisation Vector, is
00465  *              updated so that you can call the same function again on the next
00466  *              block(s) of data and get the same result as if it was encrypted
00467  *              in one call. This allows a "streaming" usage, by initialising
00468  *              iv_off to 0 before the first call, and preserving its value
00469  *              between calls.
00470  *
00471  *              For non-streaming use, the iv should be initialised on each call
00472  *              to a unique value, and iv_off set to 0 on each call.
00473  *
00474  *              If you need to retain the contents of the initialisation vector,
00475  *              you must either save it manually or use the cipher module
00476  *              instead.
00477  *
00478  * \warning     For the OFB mode, the initialisation vector must be unique
00479  *              every encryption operation. Reuse of an initialisation vector
00480  *              will compromise security.
00481  *
00482  * \param ctx      The AES context to use for encryption or decryption.
00483  *                 It must be initialized and bound to a key.
00484  * \param length   The length of the input data.
00485  * \param iv_off   The offset in IV (updated after use).
00486  *                 It must point to a valid \c size_t.
00487  * \param iv       The initialization vector (updated after use).
00488  *                 It must be a readable and writeable buffer of \c 16 Bytes.
00489  * \param input    The buffer holding the input data.
00490  *                 It must be readable and of size \p length Bytes.
00491  * \param output   The buffer holding the output data.
00492  *                 It must be writeable and of size \p length Bytes.
00493  *
00494  * \return         \c 0 on success.
00495  */
00496 int mbedtls_aes_crypt_ofb( mbedtls_aes_context *ctx,
00497                        size_t length,
00498                        size_t *iv_off,
00499                        unsigned char iv[16],
00500                        const unsigned char *input,
00501                        unsigned char *output );
00502 
00503 #endif /* MBEDTLS_CIPHER_MODE_OFB */
00504 
00505 #if defined(MBEDTLS_CIPHER_MODE_CTR)
00506 /**
00507  * \brief      This function performs an AES-CTR encryption or decryption
00508  *             operation.
00509  *
00510  *             This function performs the operation defined in the \p mode
00511  *             parameter (encrypt/decrypt), on the input data buffer
00512  *             defined in the \p input parameter.
00513  *
00514  *             Due to the nature of CTR, you must use the same key schedule
00515  *             for both encryption and decryption operations. Therefore, you
00516  *             must use the context initialized with mbedtls_aes_setkey_enc()
00517  *             for both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
00518  *
00519  * \warning    You must never reuse a nonce value with the same key. Doing so
00520  *             would void the encryption for the two messages encrypted with
00521  *             the same nonce and key.
00522  *
00523  *             There are two common strategies for managing nonces with CTR:
00524  *
00525  *             1. You can handle everything as a single message processed over
00526  *             successive calls to this function. In that case, you want to
00527  *             set \p nonce_counter and \p nc_off to 0 for the first call, and
00528  *             then preserve the values of \p nonce_counter, \p nc_off and \p
00529  *             stream_block across calls to this function as they will be
00530  *             updated by this function.
00531  *
00532  *             With this strategy, you must not encrypt more than 2**128
00533  *             blocks of data with the same key.
00534  *
00535  *             2. You can encrypt separate messages by dividing the \p
00536  *             nonce_counter buffer in two areas: the first one used for a
00537  *             per-message nonce, handled by yourself, and the second one
00538  *             updated by this function internally.
00539  *
00540  *             For example, you might reserve the first 12 bytes for the
00541  *             per-message nonce, and the last 4 bytes for internal use. In that
00542  *             case, before calling this function on a new message you need to
00543  *             set the first 12 bytes of \p nonce_counter to your chosen nonce
00544  *             value, the last 4 to 0, and \p nc_off to 0 (which will cause \p
00545  *             stream_block to be ignored). That way, you can encrypt at most
00546  *             2**96 messages of up to 2**32 blocks each with the same key.
00547  *
00548  *             The per-message nonce (or information sufficient to reconstruct
00549  *             it) needs to be communicated with the ciphertext and must be unique.
00550  *             The recommended way to ensure uniqueness is to use a message
00551  *             counter. An alternative is to generate random nonces, but this
00552  *             limits the number of messages that can be securely encrypted:
00553  *             for example, with 96-bit random nonces, you should not encrypt
00554  *             more than 2**32 messages with the same key.
00555  *
00556  *             Note that for both stategies, sizes are measured in blocks and
00557  *             that an AES block is 16 bytes.
00558  *
00559  * \warning    Upon return, \p stream_block contains sensitive data. Its
00560  *             content must not be written to insecure storage and should be
00561  *             securely discarded as soon as it's no longer needed.
00562  *
00563  * \param ctx              The AES context to use for encryption or decryption.
00564  *                         It must be initialized and bound to a key.
00565  * \param length           The length of the input data.
00566  * \param nc_off           The offset in the current \p stream_block, for
00567  *                         resuming within the current cipher stream. The
00568  *                         offset pointer should be 0 at the start of a stream.
00569  *                         It must point to a valid \c size_t.
00570  * \param nonce_counter    The 128-bit nonce and counter.
00571  *                         It must be a readable-writeable buffer of \c 16 Bytes.
00572  * \param stream_block     The saved stream block for resuming. This is
00573  *                         overwritten by the function.
00574  *                         It must be a readable-writeable buffer of \c 16 Bytes.
00575  * \param input            The buffer holding the input data.
00576  *                         It must be readable and of size \p length Bytes.
00577  * \param output           The buffer holding the output data.
00578  *                         It must be writeable and of size \p length Bytes.
00579  *
00580  * \return                 \c 0 on success.
00581  */
00582 int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx,
00583                        size_t length,
00584                        size_t *nc_off,
00585                        unsigned char nonce_counter[16],
00586                        unsigned char stream_block[16],
00587                        const unsigned char *input,
00588                        unsigned char *output );
00589 #endif /* MBEDTLS_CIPHER_MODE_CTR */
00590 
00591 /**
00592  * \brief           Internal AES block encryption function. This is only
00593  *                  exposed to allow overriding it using
00594  *                  \c MBEDTLS_AES_ENCRYPT_ALT.
00595  *
00596  * \param ctx       The AES context to use for encryption.
00597  * \param input     The plaintext block.
00598  * \param output    The output (ciphertext) block.
00599  *
00600  * \return          \c 0 on success.
00601  */
00602 int mbedtls_internal_aes_encrypt( mbedtls_aes_context *ctx,
00603                                   const unsigned char input[16],
00604                                   unsigned char output[16] );
00605 
00606 /**
00607  * \brief           Internal AES block decryption function. This is only
00608  *                  exposed to allow overriding it using see
00609  *                  \c MBEDTLS_AES_DECRYPT_ALT.
00610  *
00611  * \param ctx       The AES context to use for decryption.
00612  * \param input     The ciphertext block.
00613  * \param output    The output (plaintext) block.
00614  *
00615  * \return          \c 0 on success.
00616  */
00617 int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx,
00618                                   const unsigned char input[16],
00619                                   unsigned char output[16] );
00620 
00621 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
00622 #if defined(MBEDTLS_DEPRECATED_WARNING)
00623 #define MBEDTLS_DEPRECATED      __attribute__((deprecated))
00624 #else
00625 #define MBEDTLS_DEPRECATED
00626 #endif
00627 /**
00628  * \brief           Deprecated internal AES block encryption function
00629  *                  without return value.
00630  *
00631  * \deprecated      Superseded by mbedtls_internal_aes_encrypt()
00632  *
00633  * \param ctx       The AES context to use for encryption.
00634  * \param input     Plaintext block.
00635  * \param output    Output (ciphertext) block.
00636  */
00637 MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx,
00638                                              const unsigned char input[16],
00639                                              unsigned char output[16] );
00640 
00641 /**
00642  * \brief           Deprecated internal AES block decryption function
00643  *                  without return value.
00644  *
00645  * \deprecated      Superseded by mbedtls_internal_aes_decrypt()
00646  *
00647  * \param ctx       The AES context to use for decryption.
00648  * \param input     Ciphertext block.
00649  * \param output    Output (plaintext) block.
00650  */
00651 MBEDTLS_DEPRECATED void mbedtls_aes_decrypt( mbedtls_aes_context *ctx,
00652                                              const unsigned char input[16],
00653                                              unsigned char output[16] );
00654 
00655 #undef MBEDTLS_DEPRECATED
00656 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
00657 
00658 
00659 #if defined(MBEDTLS_SELF_TEST)
00660 /**
00661  * \brief          Checkup routine.
00662  *
00663  * \return         \c 0 on success.
00664  * \return         \c 1 on failure.
00665  */
00666 int mbedtls_aes_self_test( int verbose );
00667 
00668 #endif /* MBEDTLS_SELF_TEST */
00669 
00670 #ifdef __cplusplus
00671 }
00672 #endif
00673 
00674 #endif /* aes.h */