blob: ea697811d2b5691e5c529e82cdf1381fe58acb29 [file] [log] [blame]
Paul Bakker5121ce52009-01-03 21:22:43 +00001/**
2 * \file aes.h
Paul Bakkere0ccd0a2009-01-04 16:27:10 +00003 *
Rose Zadik5ad7aea2018-03-26 12:00:09 +01004 * \brief This file contains AES definitions and functions.
5 *
6 * The Advanced Encryption Standard (AES) specifies a FIPS-approved
Rose Zadik7f441272018-01-22 11:48:23 +00007 * cryptographic algorithm that can be used to protect electronic
8 * data.
9 *
10 * The AES algorithm is a symmetric block cipher that can
11 * encrypt and decrypt information. For more information, see
12 * <em>FIPS Publication 197: Advanced Encryption Standard</em> and
13 * <em>ISO/IEC 18033-2:2006: Information technology -- Security
14 * techniques -- Encryption algorithms -- Part 2: Asymmetric
15 * ciphers</em>.
Darryl Greena40a1012018-01-05 15:33:17 +000016 */
Rose Zadik5ad7aea2018-03-26 12:00:09 +010017
Rose Zadik7f441272018-01-22 11:48:23 +000018/* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +020019 * SPDX-License-Identifier: Apache-2.0
20 *
21 * Licensed under the Apache License, Version 2.0 (the "License"); you may
22 * not use this file except in compliance with the License.
23 * You may obtain a copy of the License at
24 *
25 * http://www.apache.org/licenses/LICENSE-2.0
26 *
27 * Unless required by applicable law or agreed to in writing, software
28 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
29 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
30 * See the License for the specific language governing permissions and
31 * limitations under the License.
Paul Bakkerb96f1542010-07-18 20:36:00 +000032 *
Rose Zadik7f441272018-01-22 11:48:23 +000033 * This file is part of Mbed TLS (https://tls.mbed.org)
Paul Bakker5121ce52009-01-03 21:22:43 +000034 */
Rose Zadik7f441272018-01-22 11:48:23 +000035
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020036#ifndef MBEDTLS_AES_H
37#define MBEDTLS_AES_H
Paul Bakker5121ce52009-01-03 21:22:43 +000038
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020039#if !defined(MBEDTLS_CONFIG_FILE)
Paul Bakker90995b52013-06-24 19:20:35 +020040#include "config.h"
Manuel Pégourié-Gonnardcef4ad22014-04-29 12:39:06 +020041#else
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020042#include MBEDTLS_CONFIG_FILE
Manuel Pégourié-Gonnardcef4ad22014-04-29 12:39:06 +020043#endif
Paul Bakker90995b52013-06-24 19:20:35 +020044
Rich Evans00ab4702015-02-06 13:43:58 +000045#include <stddef.h>
Manuel Pégourié-Gonnardab229102015-04-15 11:53:16 +020046#include <stdint.h>
Paul Bakker5c2364c2012-10-01 14:41:15 +000047
Manuel Pégourié-Gonnard5b685652013-12-18 11:45:21 +010048/* padlock.c and aesni.c rely on these values! */
Rose Zadik7f441272018-01-22 11:48:23 +000049#define MBEDTLS_AES_ENCRYPT 1 /**< AES encryption. */
50#define MBEDTLS_AES_DECRYPT 0 /**< AES decryption. */
Paul Bakker5121ce52009-01-03 21:22:43 +000051
Andres Amaya Garciac5380642017-11-28 19:57:51 +000052/* Error codes in range 0x0020-0x0022 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020053#define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH -0x0020 /**< Invalid key length. */
54#define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH -0x0022 /**< Invalid data input length. */
Paul Bakker2b222c82009-07-27 21:03:45 +000055
Gilles Peskine7ecab3d2018-01-26 17:56:38 +010056/* Error codes in range 0x0023-0x0025 */
Rose Zadik7f441272018-01-22 11:48:23 +000057#define MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE -0x0023 /**< Feature not available. For example, an unsupported AES key size. */
Gilles Peskine7ecab3d2018-01-26 17:56:38 +010058#define MBEDTLS_ERR_AES_HW_ACCEL_FAILED -0x0025 /**< AES hardware accelerator failed. */
Paul Bakker5121ce52009-01-03 21:22:43 +000059
Andres AGf5bf7182017-03-03 14:09:56 +000060#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
61 !defined(inline) && !defined(__cplusplus)
62#define inline __inline
63#endif
64
Paul Bakker407a0da2013-06-27 14:29:21 +020065#ifdef __cplusplus
66extern "C" {
67#endif
68
Ron Eldorb2aacec2017-05-18 16:53:08 +030069#if !defined(MBEDTLS_AES_ALT)
70// Regular implementation
71//
72
Paul Bakker5121ce52009-01-03 21:22:43 +000073/**
Rose Zadik7f441272018-01-22 11:48:23 +000074 * \brief The AES context-type definition.
Paul Bakker5121ce52009-01-03 21:22:43 +000075 */
76typedef struct
77{
Rose Zadik7f441272018-01-22 11:48:23 +000078 int nr; /*!< The number of rounds. */
79 uint32_t *rk; /*!< AES round keys. */
80 uint32_t buf[68]; /*!< Unaligned data buffer. This buffer can
81 hold 32 extra Bytes, which can be used for
82 one of the following purposes:
83 <ul><li>Alignment if VIA padlock is
84 used.</li>
85 <li>Simplifying key expansion in the 256-bit
86 case by generating an extra round key.
87 </li></ul> */
Paul Bakker5121ce52009-01-03 21:22:43 +000088}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020089mbedtls_aes_context;
Paul Bakker5121ce52009-01-03 21:22:43 +000090
Jaeden Amero9d3eba42018-04-28 15:02:45 +010091#if defined(MBEDTLS_CIPHER_MODE_XTS)
92/**
93 * \brief The AES XTS context-type definition.
94 */
95typedef struct
96{
97 mbedtls_aes_context crypt; /*!< The AES context to use for AES block
98 encryption or decryption. */
99 mbedtls_aes_context tweak; /*!< The AES context used for tweak computation. */
100} mbedtls_aes_xts_context;
101#endif /* MBEDTLS_CIPHER_MODE_XTS */
102
Ron Eldorb2aacec2017-05-18 16:53:08 +0300103#else /* MBEDTLS_AES_ALT */
104#include "aes_alt.h"
105#endif /* MBEDTLS_AES_ALT */
106
Paul Bakker5121ce52009-01-03 21:22:43 +0000107/**
Rose Zadik7f441272018-01-22 11:48:23 +0000108 * \brief This function initializes the specified AES context.
Paul Bakkerc7ea99a2014-06-18 11:12:03 +0200109 *
Rose Zadik7f441272018-01-22 11:48:23 +0000110 * It must be the first API called before using
111 * the context.
112 *
113 * \param ctx The AES context to initialize.
Paul Bakkerc7ea99a2014-06-18 11:12:03 +0200114 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200115void mbedtls_aes_init( mbedtls_aes_context *ctx );
Paul Bakkerc7ea99a2014-06-18 11:12:03 +0200116
117/**
Rose Zadik7f441272018-01-22 11:48:23 +0000118 * \brief This function releases and clears the specified AES context.
Paul Bakkerc7ea99a2014-06-18 11:12:03 +0200119 *
Rose Zadik7f441272018-01-22 11:48:23 +0000120 * \param ctx The AES context to clear.
Paul Bakkerc7ea99a2014-06-18 11:12:03 +0200121 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200122void mbedtls_aes_free( mbedtls_aes_context *ctx );
Paul Bakkerc7ea99a2014-06-18 11:12:03 +0200123
Jaeden Amero9d3eba42018-04-28 15:02:45 +0100124#if defined(MBEDTLS_CIPHER_MODE_XTS)
125/**
126 * \brief This function initializes the specified AES XTS context.
127 *
128 * It must be the first API called before using
129 * the context.
130 *
131 * \param ctx The AES XTS context to initialize.
132 */
133void mbedtls_aes_xts_init( mbedtls_aes_xts_context *ctx );
134
135/**
136 * \brief This function releases and clears the specified AES XTS context.
137 *
138 * \param ctx The AES XTS context to clear.
139 */
140void mbedtls_aes_xts_free( mbedtls_aes_xts_context *ctx );
141#endif /* MBEDTLS_CIPHER_MODE_XTS */
142
Paul Bakkerc7ea99a2014-06-18 11:12:03 +0200143/**
Rose Zadik7f441272018-01-22 11:48:23 +0000144 * \brief This function sets the encryption key.
Paul Bakker5121ce52009-01-03 21:22:43 +0000145 *
Rose Zadik7f441272018-01-22 11:48:23 +0000146 * \param ctx The AES context to which the key should be bound.
147 * \param key The encryption key.
148 * \param keybits The size of data passed in bits. Valid options are:
149 * <ul><li>128 bits</li>
150 * <li>192 bits</li>
151 * <li>256 bits</li></ul>
Paul Bakker2b222c82009-07-27 21:03:45 +0000152 *
Rose Zadik5ad7aea2018-03-26 12:00:09 +0100153 * \return \c 0 on success.
Rose Zadik819d13d2018-04-16 09:35:15 +0100154 * \return #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000155 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200156int mbedtls_aes_setkey_enc( mbedtls_aes_context *ctx, const unsigned char *key,
Manuel Pégourié-Gonnardb8186a52015-06-18 14:58:58 +0200157 unsigned int keybits );
Paul Bakker5121ce52009-01-03 21:22:43 +0000158
159/**
Rose Zadik7f441272018-01-22 11:48:23 +0000160 * \brief This function sets the decryption key.
Paul Bakker5121ce52009-01-03 21:22:43 +0000161 *
Rose Zadik7f441272018-01-22 11:48:23 +0000162 * \param ctx The AES context to which the key should be bound.
163 * \param key The decryption key.
164 * \param keybits The size of data passed. Valid options are:
165 * <ul><li>128 bits</li>
166 * <li>192 bits</li>
167 * <li>256 bits</li></ul>
Paul Bakker2b222c82009-07-27 21:03:45 +0000168 *
Rose Zadik5ad7aea2018-03-26 12:00:09 +0100169 * \return \c 0 on success.
170 * \return #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000171 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200172int mbedtls_aes_setkey_dec( mbedtls_aes_context *ctx, const unsigned char *key,
Manuel Pégourié-Gonnardb8186a52015-06-18 14:58:58 +0200173 unsigned int keybits );
Paul Bakker5121ce52009-01-03 21:22:43 +0000174
Jaeden Amero9d3eba42018-04-28 15:02:45 +0100175#if defined(MBEDTLS_CIPHER_MODE_XTS)
176/**
177 * \brief This function sets the encryption key.
178 *
179 * \param ctx The AES XTS context to which the key should be bound.
180 * \param key The encryption key. This is comprised of the XTS key1
181 * concatenated with the XTS key2.
182 * \param keybits The size of data passed in bits. Valid options are:
183 * <ul><li>256 bits</li>
184 * <li>384 bits</li>
185 * <li>512 bits</li></ul>
186 *
187 * \return \c 0 on success.
188 * \return #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
189 */
190int mbedtls_aes_xts_setkey_enc( mbedtls_aes_xts_context *ctx,
191 const unsigned char *key,
192 unsigned int keybits );
193
194/**
195 * \brief This function sets the decryption key.
196 *
197 * \param ctx The AES XTS context to which the key should be bound.
198 * \param key The decryption key. This is comprised of the XTS key1
199 * concatenated with the XTS key2.
200 * \param keybits The size of data passed. Valid options are:
201 * <ul><li>256 bits</li>
202 * <li>384 bits</li>
203 * <li>512 bits</li></ul>
204 *
205 * \return \c 0 on success.
206 * \return #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
207 */
208int mbedtls_aes_xts_setkey_dec( mbedtls_aes_xts_context *ctx,
209 const unsigned char *key,
210 unsigned int keybits );
211#endif /* MBEDTLS_CIPHER_MODE_XTS */
212
Paul Bakker5121ce52009-01-03 21:22:43 +0000213/**
Rose Zadik7f441272018-01-22 11:48:23 +0000214 * \brief This function performs an AES single-block encryption or
215 * decryption operation.
Paul Bakker5121ce52009-01-03 21:22:43 +0000216 *
Rose Zadik7f441272018-01-22 11:48:23 +0000217 * It performs the operation defined in the \p mode parameter
218 * (encrypt or decrypt), on the input data buffer defined in
219 * the \p input parameter.
Paul Bakkerf3ccc682010-03-18 21:21:02 +0000220 *
Rose Zadik7f441272018-01-22 11:48:23 +0000221 * mbedtls_aes_init(), and either mbedtls_aes_setkey_enc() or
222 * mbedtls_aes_setkey_dec() must be called before the first
223 * call to this API with the same context.
224 *
225 * \param ctx The AES context to use for encryption or decryption.
226 * \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
227 * #MBEDTLS_AES_DECRYPT.
228 * \param input The 16-Byte buffer holding the input data.
229 * \param output The 16-Byte buffer holding the output data.
230
231 * \return \c 0 on success.
Paul Bakker5121ce52009-01-03 21:22:43 +0000232 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200233int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx,
Paul Bakker5121ce52009-01-03 21:22:43 +0000234 int mode,
Paul Bakkerff60ee62010-03-16 21:09:09 +0000235 const unsigned char input[16],
Paul Bakker5121ce52009-01-03 21:22:43 +0000236 unsigned char output[16] );
237
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200238#if defined(MBEDTLS_CIPHER_MODE_CBC)
Paul Bakker5121ce52009-01-03 21:22:43 +0000239/**
Rose Zadik7f441272018-01-22 11:48:23 +0000240 * \brief This function performs an AES-CBC encryption or decryption operation
241 * on full blocks.
Paul Bakker5121ce52009-01-03 21:22:43 +0000242 *
Rose Zadik7f441272018-01-22 11:48:23 +0000243 * It performs the operation defined in the \p mode
244 * parameter (encrypt/decrypt), on the input data buffer defined in
245 * the \p input parameter.
Manuel Pégourié-Gonnard2be147a2015-01-23 16:19:47 +0000246 *
Rose Zadik7f441272018-01-22 11:48:23 +0000247 * It can be called as many times as needed, until all the input
248 * data is processed. mbedtls_aes_init(), and either
249 * mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called
250 * before the first call to this API with the same context.
Paul Bakkerf3ccc682010-03-18 21:21:02 +0000251 *
Rose Zadik7f441272018-01-22 11:48:23 +0000252 * \note This function operates on aligned blocks, that is, the input size
253 * must be a multiple of the AES block size of 16 Bytes.
254 *
255 * \note Upon exit, the content of the IV is updated so that you can
256 * call the same function again on the next
257 * block(s) of data and get the same result as if it was
258 * encrypted in one call. This allows a "streaming" usage.
259 * If you need to retain the contents of the IV, you should
260 * either save it manually or use the cipher module instead.
261 *
262 *
263 * \param ctx The AES context to use for encryption or decryption.
264 * \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
265 * #MBEDTLS_AES_DECRYPT.
266 * \param length The length of the input data in Bytes. This must be a
267 * multiple of the block size (16 Bytes).
268 * \param iv Initialization vector (updated after use).
269 * \param input The buffer holding the input data.
270 * \param output The buffer holding the output data.
271 *
Rose Zadik5ad7aea2018-03-26 12:00:09 +0100272 * \return \c 0 on success.
273 * \return #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
Rose Zadik7f441272018-01-22 11:48:23 +0000274 * on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000275 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200276int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx,
Paul Bakker5121ce52009-01-03 21:22:43 +0000277 int mode,
Paul Bakker23986e52011-04-24 08:57:21 +0000278 size_t length,
Paul Bakker5121ce52009-01-03 21:22:43 +0000279 unsigned char iv[16],
Paul Bakkerff60ee62010-03-16 21:09:09 +0000280 const unsigned char *input,
Paul Bakker5121ce52009-01-03 21:22:43 +0000281 unsigned char *output );
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200282#endif /* MBEDTLS_CIPHER_MODE_CBC */
Paul Bakker5121ce52009-01-03 21:22:43 +0000283
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200284#if defined(MBEDTLS_CIPHER_MODE_CFB)
Paul Bakker5121ce52009-01-03 21:22:43 +0000285/**
Rose Zadik7f441272018-01-22 11:48:23 +0000286 * \brief This function performs an AES-CFB128 encryption or decryption
287 * operation.
Paul Bakker5121ce52009-01-03 21:22:43 +0000288 *
Rose Zadik7f441272018-01-22 11:48:23 +0000289 * It performs the operation defined in the \p mode
290 * parameter (encrypt or decrypt), on the input data buffer
291 * defined in the \p input parameter.
Paul Bakkerca6f3e22011-10-06 13:11:08 +0000292 *
Rose Zadik7f441272018-01-22 11:48:23 +0000293 * For CFB, you must set up the context with mbedtls_aes_setkey_enc(),
294 * regardless of whether you are performing an encryption or decryption
295 * operation, that is, regardless of the \p mode parameter. This is
296 * because CFB mode uses the same key schedule for encryption and
297 * decryption.
Manuel Pégourié-Gonnard2be147a2015-01-23 16:19:47 +0000298 *
Rose Zadik7f441272018-01-22 11:48:23 +0000299 * \note Upon exit, the content of the IV is updated so that you can
300 * call the same function again on the next
301 * block(s) of data and get the same result as if it was
302 * encrypted in one call. This allows a "streaming" usage.
303 * If you need to retain the contents of the
304 * IV, you must either save it manually or use the cipher
305 * module instead.
Paul Bakkerf3ccc682010-03-18 21:21:02 +0000306 *
Rose Zadik7f441272018-01-22 11:48:23 +0000307 *
308 * \param ctx The AES context to use for encryption or decryption.
309 * \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
310 * #MBEDTLS_AES_DECRYPT.
311 * \param length The length of the input data.
312 * \param iv_off The offset in IV (updated after use).
313 * \param iv The initialization vector (updated after use).
314 * \param input The buffer holding the input data.
315 * \param output The buffer holding the output data.
316 *
317 * \return \c 0 on success.
Paul Bakker5121ce52009-01-03 21:22:43 +0000318 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200319int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx,
Paul Bakker5121ce52009-01-03 21:22:43 +0000320 int mode,
Paul Bakker23986e52011-04-24 08:57:21 +0000321 size_t length,
Paul Bakker1ef71df2011-06-09 14:14:58 +0000322 size_t *iv_off,
Paul Bakker5121ce52009-01-03 21:22:43 +0000323 unsigned char iv[16],
Paul Bakkerff60ee62010-03-16 21:09:09 +0000324 const unsigned char *input,
Paul Bakker5121ce52009-01-03 21:22:43 +0000325 unsigned char *output );
326
Paul Bakker9a736322012-11-14 12:39:52 +0000327/**
Rose Zadik7f441272018-01-22 11:48:23 +0000328 * \brief This function performs an AES-CFB8 encryption or decryption
329 * operation.
Paul Bakker556efba2014-01-24 15:38:12 +0100330 *
Rose Zadik7f441272018-01-22 11:48:23 +0000331 * It performs the operation defined in the \p mode
332 * parameter (encrypt/decrypt), on the input data buffer defined
333 * in the \p input parameter.
Paul Bakker556efba2014-01-24 15:38:12 +0100334 *
Rose Zadik7f441272018-01-22 11:48:23 +0000335 * Due to the nature of CFB, you must use the same key schedule for
336 * both encryption and decryption operations. Therefore, you must
337 * use the context initialized with mbedtls_aes_setkey_enc() for
338 * both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
Manuel Pégourié-Gonnard2be147a2015-01-23 16:19:47 +0000339 *
Rose Zadik7f441272018-01-22 11:48:23 +0000340 * \note Upon exit, the content of the IV is updated so that you can
341 * call the same function again on the next
342 * block(s) of data and get the same result as if it was
343 * encrypted in one call. This allows a "streaming" usage.
344 * If you need to retain the contents of the
345 * IV, you should either save it manually or use the cipher
346 * module instead.
Paul Bakker556efba2014-01-24 15:38:12 +0100347 *
Rose Zadik7f441272018-01-22 11:48:23 +0000348 *
349 * \param ctx The AES context to use for encryption or decryption.
350 * \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
351 * #MBEDTLS_AES_DECRYPT
352 * \param length The length of the input data.
353 * \param iv The initialization vector (updated after use).
354 * \param input The buffer holding the input data.
355 * \param output The buffer holding the output data.
356 *
357 * \return \c 0 on success.
Paul Bakker556efba2014-01-24 15:38:12 +0100358 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200359int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx,
Paul Bakker556efba2014-01-24 15:38:12 +0100360 int mode,
361 size_t length,
362 unsigned char iv[16],
363 const unsigned char *input,
364 unsigned char *output );
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200365#endif /*MBEDTLS_CIPHER_MODE_CFB */
Paul Bakker556efba2014-01-24 15:38:12 +0100366
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200367#if defined(MBEDTLS_CIPHER_MODE_CTR)
Paul Bakker556efba2014-01-24 15:38:12 +0100368/**
Rose Zadik7f441272018-01-22 11:48:23 +0000369 * \brief This function performs an AES-CTR encryption or decryption
370 * operation.
Paul Bakkerb6ecaf52011-04-19 14:29:23 +0000371 *
Rose Zadik7f441272018-01-22 11:48:23 +0000372 * This function performs the operation defined in the \p mode
373 * parameter (encrypt/decrypt), on the input data buffer
374 * defined in the \p input parameter.
Paul Bakkerb6ecaf52011-04-19 14:29:23 +0000375 *
Rose Zadik7f441272018-01-22 11:48:23 +0000376 * Due to the nature of CTR, you must use the same key schedule
377 * for both encryption and decryption operations. Therefore, you
378 * must use the context initialized with mbedtls_aes_setkey_enc()
379 * for both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
Paul Bakkerca6f3e22011-10-06 13:11:08 +0000380 *
Rose Zadik7f441272018-01-22 11:48:23 +0000381 * \warning You must keep the maximum use of your counter in mind.
Paul Bakkerb6ecaf52011-04-19 14:29:23 +0000382 *
Rose Zadik7f441272018-01-22 11:48:23 +0000383 * \param ctx The AES context to use for encryption or decryption.
384 * \param length The length of the input data.
385 * \param nc_off The offset in the current \p stream_block, for
386 * resuming within the current cipher stream. The
387 * offset pointer should be 0 at the start of a stream.
388 * \param nonce_counter The 128-bit nonce and counter.
389 * \param stream_block The saved stream block for resuming. This is
390 * overwritten by the function.
391 * \param input The buffer holding the input data.
392 * \param output The buffer holding the output data.
393 *
Rose Zadik5ad7aea2018-03-26 12:00:09 +0100394 * \return \c 0 on success.
Paul Bakkerb6ecaf52011-04-19 14:29:23 +0000395 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200396int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx,
Paul Bakker1ef71df2011-06-09 14:14:58 +0000397 size_t length,
398 size_t *nc_off,
Paul Bakkerb6ecaf52011-04-19 14:29:23 +0000399 unsigned char nonce_counter[16],
400 unsigned char stream_block[16],
401 const unsigned char *input,
402 unsigned char *output );
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200403#endif /* MBEDTLS_CIPHER_MODE_CTR */
Paul Bakker90995b52013-06-24 19:20:35 +0200404
Jaeden Amero9d3eba42018-04-28 15:02:45 +0100405#if defined(MBEDTLS_CIPHER_MODE_XTS)
406/**
407 * \brief This function performs an AES-XTS encryption or decryption
408 * operation for an entire XTS sector.
409 *
410 * AES-XTS encrypts or decrypts blocks based on their location as
411 * defined by a sector number. These must be provided by \p sector.
412 *
413 * NIST SP 800-38E limits the maximum size of a data unit to 2**20
414 * AES blocks. If the data unit is larger than this, this function
415 * returns #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH.
416 *
417 * \param ctx The AES XTS context to use for AES XTS operations.
418 * \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
419 * #MBEDTLS_AES_DECRYPT.
420 * \param length The length of both an entire sector and the input data
421 * in bytes. The length must be at least 16 bytes. The
422 * length does not need to be a multiple of 16 bytes.
423 * \param data_unit The data unit (commonly a block device sector) address
424 * in byte array form. The least significant byte must be
425 * at sector[0]. The most significant byte must be at
426 * sector[15]. Array must be 16 bytes in length.
427 * \param input The buffer holding the input data.
428 * \param output The buffer holding the output data.
429 *
430 * \return \c 0 on success.
431 * \return #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH if length smaller
432 * than an AES block in size (16 bytes) or if the length is
433 * larger than 2**20 blocks.
434 */
435int mbedtls_aes_crypt_xts( mbedtls_aes_xts_context *ctx,
436 int mode,
437 size_t length,
438 const unsigned char data_unit[16],
439 const unsigned char *input,
440 unsigned char *output );
441#endif /* MBEDTLS_CIPHER_MODE_XTS */
442
Manuel Pégourié-Gonnard31993f22015-05-12 15:41:08 +0200443/**
Rose Zadik7f441272018-01-22 11:48:23 +0000444 * \brief Internal AES block encryption function. This is only
445 * exposed to allow overriding it using
446 * \c MBEDTLS_AES_ENCRYPT_ALT.
Manuel Pégourié-Gonnard31993f22015-05-12 15:41:08 +0200447 *
Rose Zadik7f441272018-01-22 11:48:23 +0000448 * \param ctx The AES context to use for encryption.
449 * \param input The plaintext block.
450 * \param output The output (ciphertext) block.
Andres AGf5bf7182017-03-03 14:09:56 +0000451 *
Rose Zadik7f441272018-01-22 11:48:23 +0000452 * \return \c 0 on success.
Manuel Pégourié-Gonnard31993f22015-05-12 15:41:08 +0200453 */
Andres AGf5bf7182017-03-03 14:09:56 +0000454int mbedtls_internal_aes_encrypt( mbedtls_aes_context *ctx,
455 const unsigned char input[16],
456 unsigned char output[16] );
Manuel Pégourié-Gonnard31993f22015-05-12 15:41:08 +0200457
458/**
Rose Zadik7f441272018-01-22 11:48:23 +0000459 * \brief Internal AES block decryption function. This is only
460 * exposed to allow overriding it using see
461 * \c MBEDTLS_AES_DECRYPT_ALT.
Manuel Pégourié-Gonnard31993f22015-05-12 15:41:08 +0200462 *
Rose Zadik7f441272018-01-22 11:48:23 +0000463 * \param ctx The AES context to use for decryption.
464 * \param input The ciphertext block.
465 * \param output The output (plaintext) block.
Andres AGf5bf7182017-03-03 14:09:56 +0000466 *
Rose Zadik7f441272018-01-22 11:48:23 +0000467 * \return \c 0 on success.
Manuel Pégourié-Gonnard31993f22015-05-12 15:41:08 +0200468 */
Andres AGf5bf7182017-03-03 14:09:56 +0000469int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx,
470 const unsigned char input[16],
471 unsigned char output[16] );
472
473#if !defined(MBEDTLS_DEPRECATED_REMOVED)
474#if defined(MBEDTLS_DEPRECATED_WARNING)
475#define MBEDTLS_DEPRECATED __attribute__((deprecated))
476#else
477#define MBEDTLS_DEPRECATED
478#endif
479/**
Hanno Beckerca1cdb22017-07-20 09:50:59 +0100480 * \brief Deprecated internal AES block encryption function
481 * without return value.
Andres AGf5bf7182017-03-03 14:09:56 +0000482 *
Rose Zadik7f441272018-01-22 11:48:23 +0000483 * \deprecated Superseded by mbedtls_aes_encrypt_ext() in 2.5.0.
Andres AGf5bf7182017-03-03 14:09:56 +0000484 *
Rose Zadik7f441272018-01-22 11:48:23 +0000485 * \param ctx The AES context to use for encryption.
486 * \param input Plaintext block.
487 * \param output Output (ciphertext) block.
Andres AGf5bf7182017-03-03 14:09:56 +0000488 */
Hanno Beckerbedc2052017-06-26 12:46:56 +0100489MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx,
490 const unsigned char input[16],
491 unsigned char output[16] );
Andres AGf5bf7182017-03-03 14:09:56 +0000492
493/**
Hanno Beckerca1cdb22017-07-20 09:50:59 +0100494 * \brief Deprecated internal AES block decryption function
495 * without return value.
Andres AGf5bf7182017-03-03 14:09:56 +0000496 *
Rose Zadik7f441272018-01-22 11:48:23 +0000497 * \deprecated Superseded by mbedtls_aes_decrypt_ext() in 2.5.0.
Andres AGf5bf7182017-03-03 14:09:56 +0000498 *
Rose Zadik7f441272018-01-22 11:48:23 +0000499 * \param ctx The AES context to use for decryption.
500 * \param input Ciphertext block.
501 * \param output Output (plaintext) block.
Andres AGf5bf7182017-03-03 14:09:56 +0000502 */
Hanno Beckerbedc2052017-06-26 12:46:56 +0100503MBEDTLS_DEPRECATED void mbedtls_aes_decrypt( mbedtls_aes_context *ctx,
504 const unsigned char input[16],
505 unsigned char output[16] );
Andres AGf5bf7182017-03-03 14:09:56 +0000506
507#undef MBEDTLS_DEPRECATED
508#endif /* !MBEDTLS_DEPRECATED_REMOVED */
Manuel Pégourié-Gonnard31993f22015-05-12 15:41:08 +0200509
Paul Bakker5121ce52009-01-03 21:22:43 +0000510/**
Rose Zadik7f441272018-01-22 11:48:23 +0000511 * \brief Checkup routine.
Paul Bakker5121ce52009-01-03 21:22:43 +0000512 *
Rose Zadik5ad7aea2018-03-26 12:00:09 +0100513 * \return \c 0 on success.
514 * \return \c 1 on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000515 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200516int mbedtls_aes_self_test( int verbose );
Paul Bakker5121ce52009-01-03 21:22:43 +0000517
518#ifdef __cplusplus
519}
520#endif
521
522#endif /* aes.h */