git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/aes.h

   1 /**\r
   2  * \file aes.h\r
   3  *\r
   4  * \brief   This file contains AES definitions and functions.\r
   5  *\r
   6  *          The Advanced Encryption Standard (AES) specifies a FIPS-approved\r
   7  *          cryptographic algorithm that can be used to protect electronic\r
   8  *          data.\r
   9  *\r
  10  *          The AES algorithm is a symmetric block cipher that can\r
  11  *          encrypt and decrypt information. For more information, see\r
  12  *          <em>FIPS Publication 197: Advanced Encryption Standard</em> and\r
  13  *          <em>ISO/IEC 18033-2:2006: Information technology -- Security\r
  14  *          techniques -- Encryption algorithms -- Part 2: Asymmetric\r
  15  *          ciphers</em>.\r
  16  *\r
  17  *          The AES-XTS block mode is standardized by NIST SP 800-38E\r
  18  *          <https://nvlpubs.nist.gov/nistpubs/legacy/sp/nistspecialpublication800-38e.pdf>\r
  19  *          and described in detail by IEEE P1619\r
  20  *          <https://ieeexplore.ieee.org/servlet/opac?punumber=4375278>.\r
  21  */\r
  22 \r
  23 /*  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.\r
  24  *  SPDX-License-Identifier: Apache-2.0\r
  25  *\r
  26  *  Licensed under the Apache License, Version 2.0 (the "License"); you may\r
  27  *  not use this file except in compliance with the License.\r
  28  *  You may obtain a copy of the License at\r
  29  *\r
  30  *  http://www.apache.org/licenses/LICENSE-2.0\r
  31  *\r
  32  *  Unless required by applicable law or agreed to in writing, software\r
  33  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT\r
  34  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  35  *  See the License for the specific language governing permissions and\r
  36  *  limitations under the License.\r
  37  *\r
  38  *  This file is part of Mbed TLS (https://tls.mbed.org)\r
  39  */\r
  40 \r
  41 #ifndef MBEDTLS_AES_H\r
  42 #define MBEDTLS_AES_H\r
  43 \r
  44 #if !defined(MBEDTLS_CONFIG_FILE)\r
  45 #include "config.h"\r
  46 #else\r
  47 #include MBEDTLS_CONFIG_FILE\r
  48 #endif\r
  49 \r
  50 #include <stddef.h>\r
  51 #include <stdint.h>\r
  52 \r
  53 /* padlock.c and aesni.c rely on these values! */\r
  54 #define MBEDTLS_AES_ENCRYPT     1 /**< AES encryption. */\r
  55 #define MBEDTLS_AES_DECRYPT     0 /**< AES decryption. */\r
  56 \r
  57 /* Error codes in range 0x0020-0x0022 */\r
  58 #define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH                -0x0020  /**< Invalid key length. */\r
  59 #define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH              -0x0022  /**< Invalid data input length. */\r
  60 \r
  61 /* Error codes in range 0x0021-0x0025 */\r
  62 #define MBEDTLS_ERR_AES_BAD_INPUT_DATA                    -0x0021  /**< Invalid input data. */\r
  63 \r
  64 /* MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE is deprecated and should not be used. */\r
  65 #define MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE               -0x0023  /**< Feature not available. For example, an unsupported AES key size. */\r
  66 \r
  67 /* MBEDTLS_ERR_AES_HW_ACCEL_FAILED is deprecated and should not be used. */\r
  68 #define MBEDTLS_ERR_AES_HW_ACCEL_FAILED                   -0x0025  /**< AES hardware accelerator failed. */\r
  69 \r
  70 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \\r
  71     !defined(inline) && !defined(__cplusplus)\r
  72 #define inline __inline\r
  73 #endif\r
  74 \r
  75 #ifdef __cplusplus\r
  76 extern "C" {\r
  77 #endif\r
  78 \r
  79 #if !defined(MBEDTLS_AES_ALT)\r
  80 // Regular implementation\r
  81 //\r
  82 \r
  83 /**\r
  84  * \brief The AES context-type definition.\r
  85  */\r
  86 typedef struct mbedtls_aes_context\r
  87 {\r
  88     int nr;                     /*!< The number of rounds. */\r
  89     uint32_t *rk;               /*!< AES round keys. */\r
  90     uint32_t buf[68];           /*!< Unaligned data buffer. This buffer can\r
  91                                      hold 32 extra Bytes, which can be used for\r
  92                                      one of the following purposes:\r
  93                                      <ul><li>Alignment if VIA padlock is\r
  94                                              used.</li>\r
  95                                      <li>Simplifying key expansion in the 256-bit\r
  96                                          case by generating an extra round key.\r
  97                                          </li></ul> */\r
  98 }\r
  99 mbedtls_aes_context;\r
 100 \r
 101 #if defined(MBEDTLS_CIPHER_MODE_XTS)\r
 102 /**\r
 103  * \brief The AES XTS context-type definition.\r
 104  */\r
 105 typedef struct mbedtls_aes_xts_context\r
 106 {\r
 107     mbedtls_aes_context crypt; /*!< The AES context to use for AES block\r
 108                                         encryption or decryption. */\r
 109     mbedtls_aes_context tweak; /*!< The AES context used for tweak\r
 110                                         computation. */\r
 111 } mbedtls_aes_xts_context;\r
 112 #endif /* MBEDTLS_CIPHER_MODE_XTS */\r
 113 \r
 114 #else  /* MBEDTLS_AES_ALT */\r
 115 #include "aes_alt.h"\r
 116 #endif /* MBEDTLS_AES_ALT */\r
 117 \r
 118 /**\r
 119  * \brief          This function initializes the specified AES context.\r
 120  *\r
 121  *                 It must be the first API called before using\r
 122  *                 the context.\r
 123  *\r
 124  * \param ctx      The AES context to initialize. This must not be \c NULL.\r
 125  */\r
 126 void mbedtls_aes_init( mbedtls_aes_context *ctx );\r
 127 \r
 128 /**\r
 129  * \brief          This function releases and clears the specified AES context.\r
 130  *\r
 131  * \param ctx      The AES context to clear.\r
 132  *                 If this is \c NULL, this function does nothing.\r
 133  *                 Otherwise, the context must have been at least initialized.\r
 134  */\r
 135 void mbedtls_aes_free( mbedtls_aes_context *ctx );\r
 136 \r
 137 #if defined(MBEDTLS_CIPHER_MODE_XTS)\r
 138 /**\r
 139  * \brief          This function initializes the specified AES XTS context.\r
 140  *\r
 141  *                 It must be the first API called before using\r
 142  *                 the context.\r
 143  *\r
 144  * \param ctx      The AES XTS context to initialize. This must not be \c NULL.\r
 145  */\r
 146 void mbedtls_aes_xts_init( mbedtls_aes_xts_context *ctx );\r
 147 \r
 148 /**\r
 149  * \brief          This function releases and clears the specified AES XTS context.\r
 150  *\r
 151  * \param ctx      The AES XTS context to clear.\r
 152  *                 If this is \c NULL, this function does nothing.\r
 153  *                 Otherwise, the context must have been at least initialized.\r
 154  */\r
 155 void mbedtls_aes_xts_free( mbedtls_aes_xts_context *ctx );\r
 156 #endif /* MBEDTLS_CIPHER_MODE_XTS */\r
 157 \r
 158 /**\r
 159  * \brief          This function sets the encryption key.\r
 160  *\r
 161  * \param ctx      The AES context to which the key should be bound.\r
 162  *                 It must be initialized.\r
 163  * \param key      The encryption key.\r
 164  *                 This must be a readable buffer of size \p keybits bits.\r
 165  * \param keybits  The size of data passed in bits. Valid options are:\r
 166  *                 <ul><li>128 bits</li>\r
 167  *                 <li>192 bits</li>\r
 168  *                 <li>256 bits</li></ul>\r
 169  *\r
 170  * \return         \c 0 on success.\r
 171  * \return         #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.\r
 172  */\r
 173 int mbedtls_aes_setkey_enc( mbedtls_aes_context *ctx, const unsigned char *key,\r
 174                     unsigned int keybits );\r
 175 \r
 176 /**\r
 177  * \brief          This function sets the decryption key.\r
 178  *\r
 179  * \param ctx      The AES context to which the key should be bound.\r
 180  *                 It must be initialized.\r
 181  * \param key      The decryption key.\r
 182  *                 This must be a readable buffer of size \p keybits bits.\r
 183  * \param keybits  The size of data passed. Valid options are:\r
 184  *                 <ul><li>128 bits</li>\r
 185  *                 <li>192 bits</li>\r
 186  *                 <li>256 bits</li></ul>\r
 187  *\r
 188  * \return         \c 0 on success.\r
 189  * \return         #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.\r
 190  */\r
 191 int mbedtls_aes_setkey_dec( mbedtls_aes_context *ctx, const unsigned char *key,\r
 192                     unsigned int keybits );\r
 193 \r
 194 #if defined(MBEDTLS_CIPHER_MODE_XTS)\r
 195 /**\r
 196  * \brief          This function prepares an XTS context for encryption and\r
 197  *                 sets the encryption key.\r
 198  *\r
 199  * \param ctx      The AES XTS context to which the key should be bound.\r
 200  *                 It must be initialized.\r
 201  * \param key      The encryption key. This is comprised of the XTS key1\r
 202  *                 concatenated with the XTS key2.\r
 203  *                 This must be a readable buffer of size \p keybits bits.\r
 204  * \param keybits  The size of \p key passed in bits. Valid options are:\r
 205  *                 <ul><li>256 bits (each of key1 and key2 is a 128-bit key)</li>\r
 206  *                 <li>512 bits (each of key1 and key2 is a 256-bit key)</li></ul>\r
 207  *\r
 208  * \return         \c 0 on success.\r
 209  * \return         #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.\r
 210  */\r
 211 int mbedtls_aes_xts_setkey_enc( mbedtls_aes_xts_context *ctx,\r
 212                                 const unsigned char *key,\r
 213                                 unsigned int keybits );\r
 214 \r
 215 /**\r
 216  * \brief          This function prepares an XTS context for decryption and\r
 217  *                 sets the decryption key.\r
 218  *\r
 219  * \param ctx      The AES XTS context to which the key should be bound.\r
 220  *                 It must be initialized.\r
 221  * \param key      The decryption key. This is comprised of the XTS key1\r
 222  *                 concatenated with the XTS key2.\r
 223  *                 This must be a readable buffer of size \p keybits bits.\r
 224  * \param keybits  The size of \p key passed in bits. Valid options are:\r
 225  *                 <ul><li>256 bits (each of key1 and key2 is a 128-bit key)</li>\r
 226  *                 <li>512 bits (each of key1 and key2 is a 256-bit key)</li></ul>\r
 227  *\r
 228  * \return         \c 0 on success.\r
 229  * \return         #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.\r
 230  */\r
 231 int mbedtls_aes_xts_setkey_dec( mbedtls_aes_xts_context *ctx,\r
 232                                 const unsigned char *key,\r
 233                                 unsigned int keybits );\r
 234 #endif /* MBEDTLS_CIPHER_MODE_XTS */\r
 235 \r
 236 /**\r
 237  * \brief          This function performs an AES single-block encryption or\r
 238  *                 decryption operation.\r
 239  *\r
 240  *                 It performs the operation defined in the \p mode parameter\r
 241  *                 (encrypt or decrypt), on the input data buffer defined in\r
 242  *                 the \p input parameter.\r
 243  *\r
 244  *                 mbedtls_aes_init(), and either mbedtls_aes_setkey_enc() or\r
 245  *                 mbedtls_aes_setkey_dec() must be called before the first\r
 246  *                 call to this API with the same context.\r
 247  *\r
 248  * \param ctx      The AES context to use for encryption or decryption.\r
 249  *                 It must be initialized and bound to a key.\r
 250  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or\r
 251  *                 #MBEDTLS_AES_DECRYPT.\r
 252  * \param input    The buffer holding the input data.\r
 253  *                 It must be readable and at least \c 16 Bytes long.\r
 254  * \param output   The buffer where the output data will be written.\r
 255  *                 It must be writeable and at least \c 16 Bytes long.\r
 256 \r
 257  * \return         \c 0 on success.\r
 258  */\r
 259 int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx,\r
 260                     int mode,\r
 261                     const unsigned char input[16],\r
 262                     unsigned char output[16] );\r
 263 \r
 264 #if defined(MBEDTLS_CIPHER_MODE_CBC)\r
 265 /**\r
 266  * \brief  This function performs an AES-CBC encryption or decryption operation\r
 267  *         on full blocks.\r
 268  *\r
 269  *         It performs the operation defined in the \p mode\r
 270  *         parameter (encrypt/decrypt), on the input data buffer defined in\r
 271  *         the \p input parameter.\r
 272  *\r
 273  *         It can be called as many times as needed, until all the input\r
 274  *         data is processed. mbedtls_aes_init(), and either\r
 275  *         mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called\r
 276  *         before the first call to this API with the same context.\r
 277  *\r
 278  * \note   This function operates on full blocks, that is, the input size\r
 279  *         must be a multiple of the AES block size of \c 16 Bytes.\r
 280  *\r
 281  * \note   Upon exit, the content of the IV is updated so that you can\r
 282  *         call the same function again on the next\r
 283  *         block(s) of data and get the same result as if it was\r
 284  *         encrypted in one call. This allows a "streaming" usage.\r
 285  *         If you need to retain the contents of the IV, you should\r
 286  *         either save it manually or use the cipher module instead.\r
 287  *\r
 288  *\r
 289  * \param ctx      The AES context to use for encryption or decryption.\r
 290  *                 It must be initialized and bound to a key.\r
 291  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or\r
 292  *                 #MBEDTLS_AES_DECRYPT.\r
 293  * \param length   The length of the input data in Bytes. This must be a\r
 294  *                 multiple of the block size (\c 16 Bytes).\r
 295  * \param iv       Initialization vector (updated after use).\r
 296  *                 It must be a readable and writeable buffer of \c 16 Bytes.\r
 297  * \param input    The buffer holding the input data.\r
 298  *                 It must be readable and of size \p length Bytes.\r
 299  * \param output   The buffer holding the output data.\r
 300  *                 It must be writeable and of size \p length Bytes.\r
 301  *\r
 302  * \return         \c 0 on success.\r
 303  * \return         #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH\r
 304  *                 on failure.\r
 305  */\r
 306 int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx,\r
 307                     int mode,\r
 308                     size_t length,\r
 309                     unsigned char iv[16],\r
 310                     const unsigned char *input,\r
 311                     unsigned char *output );\r
 312 #endif /* MBEDTLS_CIPHER_MODE_CBC */\r
 313 \r
 314 #if defined(MBEDTLS_CIPHER_MODE_XTS)\r
 315 /**\r
 316  * \brief      This function performs an AES-XTS encryption or decryption\r
 317  *             operation for an entire XTS data unit.\r
 318  *\r
 319  *             AES-XTS encrypts or decrypts blocks based on their location as\r
 320  *             defined by a data unit number. The data unit number must be\r
 321  *             provided by \p data_unit.\r
 322  *\r
 323  *             NIST SP 800-38E limits the maximum size of a data unit to 2^20\r
 324  *             AES blocks. If the data unit is larger than this, this function\r
 325  *             returns #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH.\r
 326  *\r
 327  * \param ctx          The AES XTS context to use for AES XTS operations.\r
 328  *                     It must be initialized and bound to a key.\r
 329  * \param mode         The AES operation: #MBEDTLS_AES_ENCRYPT or\r
 330  *                     #MBEDTLS_AES_DECRYPT.\r
 331  * \param length       The length of a data unit in Bytes. This can be any\r
 332  *                     length between 16 bytes and 2^24 bytes inclusive\r
 333  *                     (between 1 and 2^20 block cipher blocks).\r
 334  * \param data_unit    The address of the data unit encoded as an array of 16\r
 335  *                     bytes in little-endian format. For disk encryption, this\r
 336  *                     is typically the index of the block device sector that\r
 337  *                     contains the data.\r
 338  * \param input        The buffer holding the input data (which is an entire\r
 339  *                     data unit). This function reads \p length Bytes from \p\r
 340  *                     input.\r
 341  * \param output       The buffer holding the output data (which is an entire\r
 342  *                     data unit). This function writes \p length Bytes to \p\r
 343  *                     output.\r
 344  *\r
 345  * \return             \c 0 on success.\r
 346  * \return             #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH if \p length is\r
 347  *                     smaller than an AES block in size (16 Bytes) or if \p\r
 348  *                     length is larger than 2^20 blocks (16 MiB).\r
 349  */\r
 350 int mbedtls_aes_crypt_xts( mbedtls_aes_xts_context *ctx,\r
 351                            int mode,\r
 352                            size_t length,\r
 353                            const unsigned char data_unit[16],\r
 354                            const unsigned char *input,\r
 355                            unsigned char *output );\r
 356 #endif /* MBEDTLS_CIPHER_MODE_XTS */\r
 357 \r
 358 #if defined(MBEDTLS_CIPHER_MODE_CFB)\r
 359 /**\r
 360  * \brief This function performs an AES-CFB128 encryption or decryption\r
 361  *        operation.\r
 362  *\r
 363  *        It performs the operation defined in the \p mode\r
 364  *        parameter (encrypt or decrypt), on the input data buffer\r
 365  *        defined in the \p input parameter.\r
 366  *\r
 367  *        For CFB, you must set up the context with mbedtls_aes_setkey_enc(),\r
 368  *        regardless of whether you are performing an encryption or decryption\r
 369  *        operation, that is, regardless of the \p mode parameter. This is\r
 370  *        because CFB mode uses the same key schedule for encryption and\r
 371  *        decryption.\r
 372  *\r
 373  * \note  Upon exit, the content of the IV is updated so that you can\r
 374  *        call the same function again on the next\r
 375  *        block(s) of data and get the same result as if it was\r
 376  *        encrypted in one call. This allows a "streaming" usage.\r
 377  *        If you need to retain the contents of the\r
 378  *        IV, you must either save it manually or use the cipher\r
 379  *        module instead.\r
 380  *\r
 381  *\r
 382  * \param ctx      The AES context to use for encryption or decryption.\r
 383  *                 It must be initialized and bound to a key.\r
 384  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or\r
 385  *                 #MBEDTLS_AES_DECRYPT.\r
 386  * \param length   The length of the input data in Bytes.\r
 387  * \param iv_off   The offset in IV (updated after use).\r
 388  *                 It must point to a valid \c size_t.\r
 389  * \param iv       The initialization vector (updated after use).\r
 390  *                 It must be a readable and writeable buffer of \c 16 Bytes.\r
 391  * \param input    The buffer holding the input data.\r
 392  *                 It must be readable and of size \p length Bytes.\r
 393  * \param output   The buffer holding the output data.\r
 394  *                 It must be writeable and of size \p length Bytes.\r
 395  *\r
 396  * \return         \c 0 on success.\r
 397  */\r
 398 int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx,\r
 399                        int mode,\r
 400                        size_t length,\r
 401                        size_t *iv_off,\r
 402                        unsigned char iv[16],\r
 403                        const unsigned char *input,\r
 404                        unsigned char *output );\r
 405 \r
 406 /**\r
 407  * \brief This function performs an AES-CFB8 encryption or decryption\r
 408  *        operation.\r
 409  *\r
 410  *        It performs the operation defined in the \p mode\r
 411  *        parameter (encrypt/decrypt), on the input data buffer defined\r
 412  *        in the \p input parameter.\r
 413  *\r
 414  *        Due to the nature of CFB, you must use the same key schedule for\r
 415  *        both encryption and decryption operations. Therefore, you must\r
 416  *        use the context initialized with mbedtls_aes_setkey_enc() for\r
 417  *        both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.\r
 418  *\r
 419  * \note  Upon exit, the content of the IV is updated so that you can\r
 420  *        call the same function again on the next\r
 421  *        block(s) of data and get the same result as if it was\r
 422  *        encrypted in one call. This allows a "streaming" usage.\r
 423  *        If you need to retain the contents of the\r
 424  *        IV, you should either save it manually or use the cipher\r
 425  *        module instead.\r
 426  *\r
 427  *\r
 428  * \param ctx      The AES context to use for encryption or decryption.\r
 429  *                 It must be initialized and bound to a key.\r
 430  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or\r
 431  *                 #MBEDTLS_AES_DECRYPT\r
 432  * \param length   The length of the input data.\r
 433  * \param iv       The initialization vector (updated after use).\r
 434  *                 It must be a readable and writeable buffer of \c 16 Bytes.\r
 435  * \param input    The buffer holding the input data.\r
 436  *                 It must be readable and of size \p length Bytes.\r
 437  * \param output   The buffer holding the output data.\r
 438  *                 It must be writeable and of size \p length Bytes.\r
 439  *\r
 440  * \return         \c 0 on success.\r
 441  */\r
 442 int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx,\r
 443                     int mode,\r
 444                     size_t length,\r
 445                     unsigned char iv[16],\r
 446                     const unsigned char *input,\r
 447                     unsigned char *output );\r
 448 #endif /*MBEDTLS_CIPHER_MODE_CFB */\r
 449 \r
 450 #if defined(MBEDTLS_CIPHER_MODE_OFB)\r
 451 /**\r
 452  * \brief       This function performs an AES-OFB (Output Feedback Mode)\r
 453  *              encryption or decryption operation.\r
 454  *\r
 455  *              For OFB, you must set up the context with\r
 456  *              mbedtls_aes_setkey_enc(), regardless of whether you are\r
 457  *              performing an encryption or decryption operation. This is\r
 458  *              because OFB mode uses the same key schedule for encryption and\r
 459  *              decryption.\r
 460  *\r
 461  *              The OFB operation is identical for encryption or decryption,\r
 462  *              therefore no operation mode needs to be specified.\r
 463  *\r
 464  * \note        Upon exit, the content of iv, the Initialisation Vector, is\r
 465  *              updated so that you can call the same function again on the next\r
 466  *              block(s) of data and get the same result as if it was encrypted\r
 467  *              in one call. This allows a "streaming" usage, by initialising\r
 468  *              iv_off to 0 before the first call, and preserving its value\r
 469  *              between calls.\r
 470  *\r
 471  *              For non-streaming use, the iv should be initialised on each call\r
 472  *              to a unique value, and iv_off set to 0 on each call.\r
 473  *\r
 474  *              If you need to retain the contents of the initialisation vector,\r
 475  *              you must either save it manually or use the cipher module\r
 476  *              instead.\r
 477  *\r
 478  * \warning     For the OFB mode, the initialisation vector must be unique\r
 479  *              every encryption operation. Reuse of an initialisation vector\r
 480  *              will compromise security.\r
 481  *\r
 482  * \param ctx      The AES context to use for encryption or decryption.\r
 483  *                 It must be initialized and bound to a key.\r
 484  * \param length   The length of the input data.\r
 485  * \param iv_off   The offset in IV (updated after use).\r
 486  *                 It must point to a valid \c size_t.\r
 487  * \param iv       The initialization vector (updated after use).\r
 488  *                 It must be a readable and writeable buffer of \c 16 Bytes.\r
 489  * \param input    The buffer holding the input data.\r
 490  *                 It must be readable and of size \p length Bytes.\r
 491  * \param output   The buffer holding the output data.\r
 492  *                 It must be writeable and of size \p length Bytes.\r
 493  *\r
 494  * \return         \c 0 on success.\r
 495  */\r
 496 int mbedtls_aes_crypt_ofb( mbedtls_aes_context *ctx,\r
 497                        size_t length,\r
 498                        size_t *iv_off,\r
 499                        unsigned char iv[16],\r
 500                        const unsigned char *input,\r
 501                        unsigned char *output );\r
 502 \r
 503 #endif /* MBEDTLS_CIPHER_MODE_OFB */\r
 504 \r
 505 #if defined(MBEDTLS_CIPHER_MODE_CTR)\r
 506 /**\r
 507  * \brief      This function performs an AES-CTR encryption or decryption\r
 508  *             operation.\r
 509  *\r
 510  *             This function performs the operation defined in the \p mode\r
 511  *             parameter (encrypt/decrypt), on the input data buffer\r
 512  *             defined in the \p input parameter.\r
 513  *\r
 514  *             Due to the nature of CTR, you must use the same key schedule\r
 515  *             for both encryption and decryption operations. Therefore, you\r
 516  *             must use the context initialized with mbedtls_aes_setkey_enc()\r
 517  *             for both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.\r
 518  *\r
 519  * \warning    You must never reuse a nonce value with the same key. Doing so\r
 520  *             would void the encryption for the two messages encrypted with\r
 521  *             the same nonce and key.\r
 522  *\r
 523  *             There are two common strategies for managing nonces with CTR:\r
 524  *\r
 525  *             1. You can handle everything as a single message processed over\r
 526  *             successive calls to this function. In that case, you want to\r
 527  *             set \p nonce_counter and \p nc_off to 0 for the first call, and\r
 528  *             then preserve the values of \p nonce_counter, \p nc_off and \p\r
 529  *             stream_block across calls to this function as they will be\r
 530  *             updated by this function.\r
 531  *\r
 532  *             With this strategy, you must not encrypt more than 2**128\r
 533  *             blocks of data with the same key.\r
 534  *\r
 535  *             2. You can encrypt separate messages by dividing the \p\r
 536  *             nonce_counter buffer in two areas: the first one used for a\r
 537  *             per-message nonce, handled by yourself, and the second one\r
 538  *             updated by this function internally.\r
 539  *\r
 540  *             For example, you might reserve the first 12 bytes for the\r
 541  *             per-message nonce, and the last 4 bytes for internal use. In that\r
 542  *             case, before calling this function on a new message you need to\r
 543  *             set the first 12 bytes of \p nonce_counter to your chosen nonce\r
 544  *             value, the last 4 to 0, and \p nc_off to 0 (which will cause \p\r
 545  *             stream_block to be ignored). That way, you can encrypt at most\r
 546  *             2**96 messages of up to 2**32 blocks each with the same key.\r
 547  *\r
 548  *             The per-message nonce (or information sufficient to reconstruct\r
 549  *             it) needs to be communicated with the ciphertext and must be unique.\r
 550  *             The recommended way to ensure uniqueness is to use a message\r
 551  *             counter. An alternative is to generate random nonces, but this\r
 552  *             limits the number of messages that can be securely encrypted:\r
 553  *             for example, with 96-bit random nonces, you should not encrypt\r
 554  *             more than 2**32 messages with the same key.\r
 555  *\r
 556  *             Note that for both stategies, sizes are measured in blocks and\r
 557  *             that an AES block is 16 bytes.\r
 558  *\r
 559  * \warning    Upon return, \p stream_block contains sensitive data. Its\r
 560  *             content must not be written to insecure storage and should be\r
 561  *             securely discarded as soon as it's no longer needed.\r
 562  *\r
 563  * \param ctx              The AES context to use for encryption or decryption.\r
 564  *                         It must be initialized and bound to a key.\r
 565  * \param length           The length of the input data.\r
 566  * \param nc_off           The offset in the current \p stream_block, for\r
 567  *                         resuming within the current cipher stream. The\r
 568  *                         offset pointer should be 0 at the start of a stream.\r
 569  *                         It must point to a valid \c size_t.\r
 570  * \param nonce_counter    The 128-bit nonce and counter.\r
 571  *                         It must be a readable-writeable buffer of \c 16 Bytes.\r
 572  * \param stream_block     The saved stream block for resuming. This is\r
 573  *                         overwritten by the function.\r
 574  *                         It must be a readable-writeable buffer of \c 16 Bytes.\r
 575  * \param input            The buffer holding the input data.\r
 576  *                         It must be readable and of size \p length Bytes.\r
 577  * \param output           The buffer holding the output data.\r
 578  *                         It must be writeable and of size \p length Bytes.\r
 579  *\r
 580  * \return                 \c 0 on success.\r
 581  */\r
 582 int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx,\r
 583                        size_t length,\r
 584                        size_t *nc_off,\r
 585                        unsigned char nonce_counter[16],\r
 586                        unsigned char stream_block[16],\r
 587                        const unsigned char *input,\r
 588                        unsigned char *output );\r
 589 #endif /* MBEDTLS_CIPHER_MODE_CTR */\r
 590 \r
 591 /**\r
 592  * \brief           Internal AES block encryption function. This is only\r
 593  *                  exposed to allow overriding it using\r
 594  *                  \c MBEDTLS_AES_ENCRYPT_ALT.\r
 595  *\r
 596  * \param ctx       The AES context to use for encryption.\r
 597  * \param input     The plaintext block.\r
 598  * \param output    The output (ciphertext) block.\r
 599  *\r
 600  * \return          \c 0 on success.\r
 601  */\r
 602 int mbedtls_internal_aes_encrypt( mbedtls_aes_context *ctx,\r
 603                                   const unsigned char input[16],\r
 604                                   unsigned char output[16] );\r
 605 \r
 606 /**\r
 607  * \brief           Internal AES block decryption function. This is only\r
 608  *                  exposed to allow overriding it using see\r
 609  *                  \c MBEDTLS_AES_DECRYPT_ALT.\r
 610  *\r
 611  * \param ctx       The AES context to use for decryption.\r
 612  * \param input     The ciphertext block.\r
 613  * \param output    The output (plaintext) block.\r
 614  *\r
 615  * \return          \c 0 on success.\r
 616  */\r
 617 int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx,\r
 618                                   const unsigned char input[16],\r
 619                                   unsigned char output[16] );\r
 620 \r
 621 #if !defined(MBEDTLS_DEPRECATED_REMOVED)\r
 622 #if defined(MBEDTLS_DEPRECATED_WARNING)\r
 623 #define MBEDTLS_DEPRECATED      __attribute__((deprecated))\r
 624 #else\r
 625 #define MBEDTLS_DEPRECATED\r
 626 #endif\r
 627 /**\r
 628  * \brief           Deprecated internal AES block encryption function\r
 629  *                  without return value.\r
 630  *\r
 631  * \deprecated      Superseded by mbedtls_internal_aes_encrypt()\r
 632  *\r
 633  * \param ctx       The AES context to use for encryption.\r
 634  * \param input     Plaintext block.\r
 635  * \param output    Output (ciphertext) block.\r
 636  */\r
 637 MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx,\r
 638                                              const unsigned char input[16],\r
 639                                              unsigned char output[16] );\r
 640 \r
 641 /**\r
 642  * \brief           Deprecated internal AES block decryption function\r
 643  *                  without return value.\r
 644  *\r
 645  * \deprecated      Superseded by mbedtls_internal_aes_decrypt()\r
 646  *\r
 647  * \param ctx       The AES context to use for decryption.\r
 648  * \param input     Ciphertext block.\r
 649  * \param output    Output (plaintext) block.\r
 650  */\r
 651 MBEDTLS_DEPRECATED void mbedtls_aes_decrypt( mbedtls_aes_context *ctx,\r
 652                                              const unsigned char input[16],\r
 653                                              unsigned char output[16] );\r
 654 \r
 655 #undef MBEDTLS_DEPRECATED\r
 656 #endif /* !MBEDTLS_DEPRECATED_REMOVED */\r
 657 \r
 658 \r
 659 #if defined(MBEDTLS_SELF_TEST)\r
 660 /**\r
 661  * \brief          Checkup routine.\r
 662  *\r
 663  * \return         \c 0 on success.\r
 664  * \return         \c 1 on failure.\r
 665  */\r
 666 int mbedtls_aes_self_test( int verbose );\r
 667 \r
 668 #endif /* MBEDTLS_SELF_TEST */\r
 669 \r
 670 #ifdef __cplusplus\r
 671 }\r
 672 #endif\r
 673 \r
 674 #endif /* aes.h */\r