aes.h

00001 /**
00002  * \file aes.h
00003  *
00004  * \brief   The Advanced Encryption Standard (AES) specifies a FIPS-approved
00005  *          cryptographic algorithm that can be used to protect electronic
00006  *          data.
00007  *
00008  *          The AES algorithm is a symmetric block cipher that can
00009  *          encrypt and decrypt information. For more information, see
00010  *          <em>FIPS Publication 197: Advanced Encryption Standard</em> and
00011  *          <em>ISO/IEC 18033-2:2006: Information technology -- Security
00012  *          techniques -- Encryption algorithms -- Part 2: Asymmetric
00013  *          ciphers</em>.
00014  */
00015 /*  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
00016  *  SPDX-License-Identifier: Apache-2.0
00017  *
00018  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00019  *  not use this file except in compliance with the License.
00020  *  You may obtain a copy of the License at
00021  *
00022  *  http://www.apache.org/licenses/LICENSE-2.0
00023  *
00024  *  Unless required by applicable law or agreed to in writing, software
00025  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00026  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00027  *  See the License for the specific language governing permissions and
00028  *  limitations under the License.
00029  *
00030  *  This file is part of Mbed TLS (https://tls.mbed.org)
00031  */
00032 
00033 #ifndef MBEDTLS_AES_H
00034 #define MBEDTLS_AES_H
00035 
00036 #if !defined(MBEDTLS_CONFIG_FILE)
00037 #include "config.h"
00038 #else
00039 #include MBEDTLS_CONFIG_FILE
00040 #endif
00041 
00042 #include <stddef.h>
00043 #include <stdint.h>
00044 
00045 /* padlock.c and aesni.c rely on these values! */
00046 #define MBEDTLS_AES_ENCRYPT     1 /**< AES encryption. */
00047 #define MBEDTLS_AES_DECRYPT     0 /**< AES decryption. */
00048 
00049 /* Error codes in range 0x0020-0x0022 */
00050 #define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH                -0x0020  /**< Invalid key length. */
00051 #define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH              -0x0022  /**< Invalid data input length. */
00052 
00053 /* Error codes in range 0x0023-0x0025 */
00054 #define MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE               -0x0023  /**< Feature not available. For example, an unsupported AES key size. */
00055 #define MBEDTLS_ERR_AES_HW_ACCEL_FAILED                   -0x0025  /**< AES hardware accelerator failed. */
00056 
00057 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
00058     !defined(inline) && !defined(__cplusplus)
00059 #define inline __inline
00060 #endif
00061 
00062 #if !defined(MBEDTLS_AES_ALT)
00063 // Regular implementation
00064 //
00065 
00066 #ifdef __cplusplus
00067 extern "C" {
00068 #endif
00069 
00070 /**
00071  * \brief The AES context-type definition.
00072  */
00073 typedef struct
00074 {
00075     int nr ;                     /*!< The number of rounds. */
00076     uint32_t *rk ;               /*!< AES round keys. */
00077     uint32_t buf[68];           /*!< Unaligned data buffer. This buffer can
00078                                      hold 32 extra Bytes, which can be used for
00079                                      one of the following purposes:
00080                                      <ul><li>Alignment if VIA padlock is
00081                                              used.</li>
00082                                      <li>Simplifying key expansion in the 256-bit
00083                                          case by generating an extra round key.
00084                                          </li></ul> */
00085 }
00086 mbedtls_aes_context;
00087 
00088 /**
00089  * \brief          This function initializes the specified AES context.
00090  *
00091  *                 It must be the first API called before using
00092  *                 the context.
00093  *
00094  * \param ctx      The AES context to initialize.
00095  */
00096 void mbedtls_aes_init( mbedtls_aes_context *ctx );
00097 
00098 /**
00099  * \brief          This function releases and clears the specified AES context.
00100  *
00101  * \param ctx      The AES context to clear.
00102  */
00103 void mbedtls_aes_free( mbedtls_aes_context *ctx );
00104 
00105 /**
00106  * \brief          This function sets the encryption key.
00107  *
00108  * \param ctx      The AES context to which the key should be bound.
00109  * \param key      The encryption key.
00110  * \param keybits  The size of data passed in bits. Valid options are:
00111  *                 <ul><li>128 bits</li>
00112  *                 <li>192 bits</li>
00113  *                 <li>256 bits</li></ul>
00114  *
00115  * \return         \c 0 on success or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH
00116  *                 on failure.
00117  */
00118 int mbedtls_aes_setkey_enc( mbedtls_aes_context *ctx, const unsigned char *key,
00119                     unsigned int keybits );
00120 
00121 /**
00122  * \brief          This function sets the decryption key.
00123  *
00124  * \param ctx      The AES context to which the key should be bound.
00125  * \param key      The decryption key.
00126  * \param keybits  The size of data passed. Valid options are:
00127  *                 <ul><li>128 bits</li>
00128  *                 <li>192 bits</li>
00129  *                 <li>256 bits</li></ul>
00130  *
00131  * \return         \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
00132  */
00133 int mbedtls_aes_setkey_dec( mbedtls_aes_context *ctx, const unsigned char *key,
00134                     unsigned int keybits );
00135 
00136 /**
00137  * \brief          This function performs an AES single-block encryption or
00138  *                 decryption operation.
00139  *
00140  *                 It performs the operation defined in the \p mode parameter
00141  *                 (encrypt or decrypt), on the input data buffer defined in
00142  *                 the \p input parameter.
00143  *
00144  *                 mbedtls_aes_init(), and either mbedtls_aes_setkey_enc() or
00145  *                 mbedtls_aes_setkey_dec() must be called before the first
00146  *                 call to this API with the same context.
00147  *
00148  * \param ctx      The AES context to use for encryption or decryption.
00149  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or
00150  *                 #MBEDTLS_AES_DECRYPT.
00151  * \param input    The 16-Byte buffer holding the input data.
00152  * \param output   The 16-Byte buffer holding the output data.
00153 
00154  * \return         \c 0 on success.
00155  */
00156 int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx,
00157                     int mode,
00158                     const unsigned char input[16],
00159                     unsigned char output[16] );
00160 
00161 #if defined(MBEDTLS_CIPHER_MODE_CBC)
00162 /**
00163  * \brief  This function performs an AES-CBC encryption or decryption operation
00164  *         on full blocks.
00165  *
00166  *         It performs the operation defined in the \p mode
00167  *         parameter (encrypt/decrypt), on the input data buffer defined in
00168  *         the \p input parameter.
00169  *
00170  *         It can be called as many times as needed, until all the input
00171  *         data is processed. mbedtls_aes_init(), and either
00172  *         mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called
00173  *         before the first call to this API with the same context.
00174  *
00175  * \note   This function operates on aligned blocks, that is, the input size
00176  *         must be a multiple of the AES block size of 16 Bytes.
00177  *
00178  * \note   Upon exit, the content of the IV is updated so that you can
00179  *         call the same function again on the next
00180  *         block(s) of data and get the same result as if it was
00181  *         encrypted in one call. This allows a "streaming" usage.
00182  *         If you need to retain the contents of the IV, you should
00183  *         either save it manually or use the cipher module instead.
00184  *
00185  *
00186  * \param ctx      The AES context to use for encryption or decryption.
00187  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or
00188  *                 #MBEDTLS_AES_DECRYPT.
00189  * \param length   The length of the input data in Bytes. This must be a
00190  *                 multiple of the block size (16 Bytes).
00191  * \param iv       Initialization vector (updated after use).
00192  * \param input    The buffer holding the input data.
00193  * \param output   The buffer holding the output data.
00194  *
00195  * \return         \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
00196  *                 on failure.
00197  */
00198 int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx,
00199                     int mode,
00200                     size_t length,
00201                     unsigned char iv[16],
00202                     const unsigned char *input,
00203                     unsigned char *output );
00204 #endif /* MBEDTLS_CIPHER_MODE_CBC */
00205 
00206 #if defined(MBEDTLS_CIPHER_MODE_CFB)
00207 /**
00208  * \brief This function performs an AES-CFB128 encryption or decryption
00209  *        operation.
00210  *
00211  *        It performs the operation defined in the \p mode
00212  *        parameter (encrypt or decrypt), on the input data buffer
00213  *        defined in the \p input parameter.
00214  *
00215  *        For CFB, you must set up the context with mbedtls_aes_setkey_enc(),
00216  *        regardless of whether you are performing an encryption or decryption
00217  *        operation, that is, regardless of the \p mode parameter. This is
00218  *        because CFB mode uses the same key schedule for encryption and
00219  *        decryption.
00220  *
00221  * \note  Upon exit, the content of the IV is updated so that you can
00222  *        call the same function again on the next
00223  *        block(s) of data and get the same result as if it was
00224  *        encrypted in one call. This allows a "streaming" usage.
00225  *        If you need to retain the contents of the
00226  *        IV, you must either save it manually or use the cipher
00227  *        module instead.
00228  *
00229  *
00230  * \param ctx      The AES context to use for encryption or decryption.
00231  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or
00232  *                 #MBEDTLS_AES_DECRYPT.
00233  * \param length   The length of the input data.
00234  * \param iv_off   The offset in IV (updated after use).
00235  * \param iv       The initialization vector (updated after use).
00236  * \param input    The buffer holding the input data.
00237  * \param output   The buffer holding the output data.
00238  *
00239  * \return         \c 0 on success.
00240  */
00241 int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx,
00242                        int mode,
00243                        size_t length,
00244                        size_t *iv_off,
00245                        unsigned char iv[16],
00246                        const unsigned char *input,
00247                        unsigned char *output );
00248 
00249 /**
00250  * \brief This function performs an AES-CFB8 encryption or decryption
00251  *        operation.
00252  *
00253  *        It performs the operation defined in the \p mode
00254  *        parameter (encrypt/decrypt), on the input data buffer defined
00255  *        in the \p input parameter.
00256  *
00257  *        Due to the nature of CFB, you must use the same key schedule for
00258  *        both encryption and decryption operations. Therefore, you must
00259  *        use the context initialized with mbedtls_aes_setkey_enc() for
00260  *        both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
00261  *
00262  * \note  Upon exit, the content of the IV is updated so that you can
00263  *        call the same function again on the next
00264  *        block(s) of data and get the same result as if it was
00265  *        encrypted in one call. This allows a "streaming" usage.
00266  *        If you need to retain the contents of the
00267  *        IV, you should either save it manually or use the cipher
00268  *        module instead.
00269  *
00270  *
00271  * \param ctx      The AES context to use for encryption or decryption.
00272  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or
00273  *                 #MBEDTLS_AES_DECRYPT
00274  * \param length   The length of the input data.
00275  * \param iv       The initialization vector (updated after use).
00276  * \param input    The buffer holding the input data.
00277  * \param output   The buffer holding the output data.
00278  *
00279  * \return         \c 0 on success.
00280  */
00281 int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx,
00282                     int mode,
00283                     size_t length,
00284                     unsigned char iv[16],
00285                     const unsigned char *input,
00286                     unsigned char *output );
00287 #endif /*MBEDTLS_CIPHER_MODE_CFB */
00288 
00289 #if defined(MBEDTLS_CIPHER_MODE_CTR)
00290 /**
00291  * \brief      This function performs an AES-CTR encryption or decryption
00292  *             operation.
00293  *
00294  *             This function performs the operation defined in the \p mode
00295  *             parameter (encrypt/decrypt), on the input data buffer
00296  *             defined in the \p input parameter.
00297  *
00298  *             Due to the nature of CTR, you must use the same key schedule
00299  *             for both encryption and decryption operations. Therefore, you
00300  *             must use the context initialized with mbedtls_aes_setkey_enc()
00301  *             for both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
00302  *
00303  * \warning    You must keep the maximum use of your counter in mind.
00304  *
00305  * \param ctx              The AES context to use for encryption or decryption.
00306  * \param length           The length of the input data.
00307  * \param nc_off           The offset in the current \p stream_block, for
00308  *                         resuming within the current cipher stream. The
00309  *                         offset pointer should be 0 at the start of a stream.
00310  * \param nonce_counter    The 128-bit nonce and counter.
00311  * \param stream_block     The saved stream block for resuming. This is
00312  *                         overwritten by the function.
00313  * \param input            The buffer holding the input data.
00314  * \param output           The buffer holding the output data.
00315  *
00316  * \return     \c 0 on success.
00317  */
00318 int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx,
00319                        size_t length,
00320                        size_t *nc_off,
00321                        unsigned char nonce_counter[16],
00322                        unsigned char stream_block[16],
00323                        const unsigned char *input,
00324                        unsigned char *output );
00325 #endif /* MBEDTLS_CIPHER_MODE_CTR */
00326 
00327 /**
00328  * \brief           Internal AES block encryption function. This is only
00329  *                  exposed to allow overriding it using
00330  *                  \c MBEDTLS_AES_ENCRYPT_ALT.
00331  *
00332  * \param ctx       The AES context to use for encryption.
00333  * \param input     The plaintext block.
00334  * \param output    The output (ciphertext) block.
00335  *
00336  * \return          \c 0 on success.
00337  */
00338 int mbedtls_internal_aes_encrypt( mbedtls_aes_context *ctx,
00339                                   const unsigned char input[16],
00340                                   unsigned char output[16] );
00341 
00342 /**
00343  * \brief           Internal AES block decryption function. This is only
00344  *                  exposed to allow overriding it using see
00345  *                  \c MBEDTLS_AES_DECRYPT_ALT.
00346  *
00347  * \param ctx       The AES context to use for decryption.
00348  * \param input     The ciphertext block.
00349  * \param output    The output (plaintext) block.
00350  *
00351  * \return          \c 0 on success.
00352  */
00353 int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx,
00354                                   const unsigned char input[16],
00355                                   unsigned char output[16] );
00356 
00357 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
00358 #if defined(MBEDTLS_DEPRECATED_WARNING)
00359 #define MBEDTLS_DEPRECATED      __attribute__((deprecated))
00360 #else
00361 #define MBEDTLS_DEPRECATED
00362 #endif
00363 /**
00364  * \brief           Deprecated internal AES block encryption function
00365  *                  without return value.
00366  *
00367  * \deprecated      Superseded by mbedtls_aes_encrypt_ext() in 2.5.0.
00368  *
00369  * \param ctx       The AES context to use for encryption.
00370  * \param input     Plaintext block.
00371  * \param output    Output (ciphertext) block.
00372  */
00373 MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx,
00374                                              const unsigned char input[16],
00375                                              unsigned char output[16] );
00376 
00377 /**
00378  * \brief           Deprecated internal AES block decryption function
00379  *                  without return value.
00380  *
00381  * \deprecated      Superseded by mbedtls_aes_decrypt_ext() in 2.5.0.
00382  *
00383  * \param ctx       The AES context to use for decryption.
00384  * \param input     Ciphertext block.
00385  * \param output    Output (plaintext) block.
00386  */
00387 MBEDTLS_DEPRECATED void mbedtls_aes_decrypt( mbedtls_aes_context *ctx,
00388                                              const unsigned char input[16],
00389                                              unsigned char output[16] );
00390 
00391 #undef MBEDTLS_DEPRECATED
00392 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
00393 
00394 #ifdef __cplusplus
00395 }
00396 #endif
00397 
00398 #else  /* MBEDTLS_AES_ALT */
00399 #include "aes_alt.h"
00400 #endif /* MBEDTLS_AES_ALT */
00401 
00402 #ifdef __cplusplus
00403 extern "C" {
00404 #endif
00405 
00406 /**
00407  * \brief          Checkup routine.
00408  *
00409  * \return         \c 0 on success, or \c 1 on failure.
00410  */
00411 int mbedtls_aes_self_test( int verbose );
00412 
00413 #ifdef __cplusplus
00414 }
00415 #endif
00416 
00417 #endif /* aes.h */