blob: eecf76cc358ab3f677444c83866f59f6549f12d6 [file] [log] [blame]
Jaeden Ameroe54e6932018-08-06 16:19:58 +01001/**
2 * \file aes.h
3 *
4 * \brief This file contains AES definitions and functions.
5 *
6 * The Advanced Encryption Standard (AES) specifies a FIPS-approved
7 * 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>.
16 */
17
18/* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
19 * 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.
32 *
33 * This file is part of Mbed Crypto (https://tls.mbed.org)
34 */
35
36#ifndef MBEDCRYPTO_AES_H
37#define MBEDCRYPTO_AES_H
38
39#if !defined(MBEDCRYPTO_CONFIG_FILE)
40#include "config.h"
41#else
42#include MBEDCRYPTO_CONFIG_FILE
43#endif
44
45#include <stddef.h>
46#include <stdint.h>
47
48/* padlock.c and aesni.c rely on these values! */
49#define MBEDCRYPTO_AES_ENCRYPT 1 /**< AES encryption. */
50#define MBEDCRYPTO_AES_DECRYPT 0 /**< AES decryption. */
51
52/* Error codes in range 0x0020-0x0022 */
53#define MBEDCRYPTO_ERR_AES_INVALID_KEY_LENGTH -0x0020 /**< Invalid key length. */
54#define MBEDCRYPTO_ERR_AES_INVALID_INPUT_LENGTH -0x0022 /**< Invalid data input length. */
55
56/* Error codes in range 0x0023-0x0025 */
57#define MBEDCRYPTO_ERR_AES_FEATURE_UNAVAILABLE -0x0023 /**< Feature not available. For example, an unsupported AES key size. */
58#define MBEDCRYPTO_ERR_AES_HW_ACCEL_FAILED -0x0025 /**< AES hardware accelerator failed. */
59
60#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
61 !defined(inline) && !defined(__cplusplus)
62#define inline __inline
63#endif
64
65#ifdef __cplusplus
66extern "C" {
67#endif
68
69#if !defined(MBEDCRYPTO_AES_ALT)
70// Regular implementation
71//
72
73/**
74 * \brief The AES context-type definition.
75 */
76typedef struct
77{
78 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> */
88}
89mbedcrypto_aes_context;
90
91#else /* MBEDCRYPTO_AES_ALT */
92#include "aes_alt.h"
93#endif /* MBEDCRYPTO_AES_ALT */
94
95/**
96 * \brief This function initializes the specified AES context.
97 *
98 * It must be the first API called before using
99 * the context.
100 *
101 * \param ctx The AES context to initialize.
102 */
103void mbedcrypto_aes_init( mbedcrypto_aes_context *ctx );
104
105/**
106 * \brief This function releases and clears the specified AES context.
107 *
108 * \param ctx The AES context to clear.
109 */
110void mbedcrypto_aes_free( mbedcrypto_aes_context *ctx );
111
112/**
113 * \brief This function sets the encryption key.
114 *
115 * \param ctx The AES context to which the key should be bound.
116 * \param key The encryption key.
117 * \param keybits The size of data passed in bits. Valid options are:
118 * <ul><li>128 bits</li>
119 * <li>192 bits</li>
120 * <li>256 bits</li></ul>
121 *
122 * \return \c 0 on success.
123 * \return #MBEDCRYPTO_ERR_AES_INVALID_KEY_LENGTH on failure.
124 */
125int mbedcrypto_aes_setkey_enc( mbedcrypto_aes_context *ctx, const unsigned char *key,
126 unsigned int keybits );
127
128/**
129 * \brief This function sets the decryption key.
130 *
131 * \param ctx The AES context to which the key should be bound.
132 * \param key The decryption key.
133 * \param keybits The size of data passed. Valid options are:
134 * <ul><li>128 bits</li>
135 * <li>192 bits</li>
136 * <li>256 bits</li></ul>
137 *
138 * \return \c 0 on success.
139 * \return #MBEDCRYPTO_ERR_AES_INVALID_KEY_LENGTH on failure.
140 */
141int mbedcrypto_aes_setkey_dec( mbedcrypto_aes_context *ctx, const unsigned char *key,
142 unsigned int keybits );
143
144/**
145 * \brief This function performs an AES single-block encryption or
146 * decryption operation.
147 *
148 * It performs the operation defined in the \p mode parameter
149 * (encrypt or decrypt), on the input data buffer defined in
150 * the \p input parameter.
151 *
152 * mbedcrypto_aes_init(), and either mbedcrypto_aes_setkey_enc() or
153 * mbedcrypto_aes_setkey_dec() must be called before the first
154 * call to this API with the same context.
155 *
156 * \param ctx The AES context to use for encryption or decryption.
157 * \param mode The AES operation: #MBEDCRYPTO_AES_ENCRYPT or
158 * #MBEDCRYPTO_AES_DECRYPT.
159 * \param input The 16-Byte buffer holding the input data.
160 * \param output The 16-Byte buffer holding the output data.
161
162 * \return \c 0 on success.
163 */
164int mbedcrypto_aes_crypt_ecb( mbedcrypto_aes_context *ctx,
165 int mode,
166 const unsigned char input[16],
167 unsigned char output[16] );
168
169#if defined(MBEDCRYPTO_CIPHER_MODE_CBC)
170/**
171 * \brief This function performs an AES-CBC encryption or decryption operation
172 * on full blocks.
173 *
174 * It performs the operation defined in the \p mode
175 * parameter (encrypt/decrypt), on the input data buffer defined in
176 * the \p input parameter.
177 *
178 * It can be called as many times as needed, until all the input
179 * data is processed. mbedcrypto_aes_init(), and either
180 * mbedcrypto_aes_setkey_enc() or mbedcrypto_aes_setkey_dec() must be called
181 * before the first call to this API with the same context.
182 *
183 * \note This function operates on aligned blocks, that is, the input size
184 * must be a multiple of the AES block size of 16 Bytes.
185 *
186 * \note Upon exit, the content of the IV is updated so that you can
187 * call the same function again on the next
188 * block(s) of data and get the same result as if it was
189 * encrypted in one call. This allows a "streaming" usage.
190 * If you need to retain the contents of the IV, you should
191 * either save it manually or use the cipher module instead.
192 *
193 *
194 * \param ctx The AES context to use for encryption or decryption.
195 * \param mode The AES operation: #MBEDCRYPTO_AES_ENCRYPT or
196 * #MBEDCRYPTO_AES_DECRYPT.
197 * \param length The length of the input data in Bytes. This must be a
198 * multiple of the block size (16 Bytes).
199 * \param iv Initialization vector (updated after use).
200 * \param input The buffer holding the input data.
201 * \param output The buffer holding the output data.
202 *
203 * \return \c 0 on success.
204 * \return #MBEDCRYPTO_ERR_AES_INVALID_INPUT_LENGTH
205 * on failure.
206 */
207int mbedcrypto_aes_crypt_cbc( mbedcrypto_aes_context *ctx,
208 int mode,
209 size_t length,
210 unsigned char iv[16],
211 const unsigned char *input,
212 unsigned char *output );
213#endif /* MBEDCRYPTO_CIPHER_MODE_CBC */
214
215#if defined(MBEDCRYPTO_CIPHER_MODE_CFB)
216/**
217 * \brief This function performs an AES-CFB128 encryption or decryption
218 * operation.
219 *
220 * It performs the operation defined in the \p mode
221 * parameter (encrypt or decrypt), on the input data buffer
222 * defined in the \p input parameter.
223 *
224 * For CFB, you must set up the context with mbedcrypto_aes_setkey_enc(),
225 * regardless of whether you are performing an encryption or decryption
226 * operation, that is, regardless of the \p mode parameter. This is
227 * because CFB mode uses the same key schedule for encryption and
228 * decryption.
229 *
230 * \note Upon exit, the content of the IV is updated so that you can
231 * call the same function again on the next
232 * block(s) of data and get the same result as if it was
233 * encrypted in one call. This allows a "streaming" usage.
234 * If you need to retain the contents of the
235 * IV, you must either save it manually or use the cipher
236 * module instead.
237 *
238 *
239 * \param ctx The AES context to use for encryption or decryption.
240 * \param mode The AES operation: #MBEDCRYPTO_AES_ENCRYPT or
241 * #MBEDCRYPTO_AES_DECRYPT.
242 * \param length The length of the input data.
243 * \param iv_off The offset in IV (updated after use).
244 * \param iv The initialization vector (updated after use).
245 * \param input The buffer holding the input data.
246 * \param output The buffer holding the output data.
247 *
248 * \return \c 0 on success.
249 */
250int mbedcrypto_aes_crypt_cfb128( mbedcrypto_aes_context *ctx,
251 int mode,
252 size_t length,
253 size_t *iv_off,
254 unsigned char iv[16],
255 const unsigned char *input,
256 unsigned char *output );
257
258/**
259 * \brief This function performs an AES-CFB8 encryption or decryption
260 * operation.
261 *
262 * It performs the operation defined in the \p mode
263 * parameter (encrypt/decrypt), on the input data buffer defined
264 * in the \p input parameter.
265 *
266 * Due to the nature of CFB, you must use the same key schedule for
267 * both encryption and decryption operations. Therefore, you must
268 * use the context initialized with mbedcrypto_aes_setkey_enc() for
269 * both #MBEDCRYPTO_AES_ENCRYPT and #MBEDCRYPTO_AES_DECRYPT.
270 *
271 * \note Upon exit, the content of the IV is updated so that you can
272 * call the same function again on the next
273 * block(s) of data and get the same result as if it was
274 * encrypted in one call. This allows a "streaming" usage.
275 * If you need to retain the contents of the
276 * IV, you should either save it manually or use the cipher
277 * module instead.
278 *
279 *
280 * \param ctx The AES context to use for encryption or decryption.
281 * \param mode The AES operation: #MBEDCRYPTO_AES_ENCRYPT or
282 * #MBEDCRYPTO_AES_DECRYPT
283 * \param length The length of the input data.
284 * \param iv The initialization vector (updated after use).
285 * \param input The buffer holding the input data.
286 * \param output The buffer holding the output data.
287 *
288 * \return \c 0 on success.
289 */
290int mbedcrypto_aes_crypt_cfb8( mbedcrypto_aes_context *ctx,
291 int mode,
292 size_t length,
293 unsigned char iv[16],
294 const unsigned char *input,
295 unsigned char *output );
296#endif /*MBEDCRYPTO_CIPHER_MODE_CFB */
297
298#if defined(MBEDCRYPTO_CIPHER_MODE_CTR)
299/**
300 * \brief This function performs an AES-CTR encryption or decryption
301 * operation.
302 *
303 * This function performs the operation defined in the \p mode
304 * parameter (encrypt/decrypt), on the input data buffer
305 * defined in the \p input parameter.
306 *
307 * Due to the nature of CTR, you must use the same key schedule
308 * for both encryption and decryption operations. Therefore, you
309 * must use the context initialized with mbedcrypto_aes_setkey_enc()
310 * for both #MBEDCRYPTO_AES_ENCRYPT and #MBEDCRYPTO_AES_DECRYPT.
311 *
312 * \warning You must keep the maximum use of your counter in mind.
313 *
314 * \param ctx The AES context to use for encryption or decryption.
315 * \param length The length of the input data.
316 * \param nc_off The offset in the current \p stream_block, for
317 * resuming within the current cipher stream. The
318 * offset pointer should be 0 at the start of a stream.
319 * \param nonce_counter The 128-bit nonce and counter.
320 * \param stream_block The saved stream block for resuming. This is
321 * overwritten by the function.
322 * \param input The buffer holding the input data.
323 * \param output The buffer holding the output data.
324 *
325 * \return \c 0 on success.
326 */
327int mbedcrypto_aes_crypt_ctr( mbedcrypto_aes_context *ctx,
328 size_t length,
329 size_t *nc_off,
330 unsigned char nonce_counter[16],
331 unsigned char stream_block[16],
332 const unsigned char *input,
333 unsigned char *output );
334#endif /* MBEDCRYPTO_CIPHER_MODE_CTR */
335
336/**
337 * \brief Internal AES block encryption function. This is only
338 * exposed to allow overriding it using
339 * \c MBEDCRYPTO_AES_ENCRYPT_ALT.
340 *
341 * \param ctx The AES context to use for encryption.
342 * \param input The plaintext block.
343 * \param output The output (ciphertext) block.
344 *
345 * \return \c 0 on success.
346 */
347int mbedcrypto_internal_aes_encrypt( mbedcrypto_aes_context *ctx,
348 const unsigned char input[16],
349 unsigned char output[16] );
350
351/**
352 * \brief Internal AES block decryption function. This is only
353 * exposed to allow overriding it using see
354 * \c MBEDCRYPTO_AES_DECRYPT_ALT.
355 *
356 * \param ctx The AES context to use for decryption.
357 * \param input The ciphertext block.
358 * \param output The output (plaintext) block.
359 *
360 * \return \c 0 on success.
361 */
362int mbedcrypto_internal_aes_decrypt( mbedcrypto_aes_context *ctx,
363 const unsigned char input[16],
364 unsigned char output[16] );
365
366#if !defined(MBEDCRYPTO_DEPRECATED_REMOVED)
367#if defined(MBEDCRYPTO_DEPRECATED_WARNING)
368#define MBEDCRYPTO_DEPRECATED __attribute__((deprecated))
369#else
370#define MBEDCRYPTO_DEPRECATED
371#endif
372/**
373 * \brief Deprecated internal AES block encryption function
374 * without return value.
375 *
376 * \deprecated Superseded by mbedcrypto_aes_encrypt_ext() in 2.5.0.
377 *
378 * \param ctx The AES context to use for encryption.
379 * \param input Plaintext block.
380 * \param output Output (ciphertext) block.
381 */
382MBEDCRYPTO_DEPRECATED void mbedcrypto_aes_encrypt( mbedcrypto_aes_context *ctx,
383 const unsigned char input[16],
384 unsigned char output[16] );
385
386/**
387 * \brief Deprecated internal AES block decryption function
388 * without return value.
389 *
390 * \deprecated Superseded by mbedcrypto_aes_decrypt_ext() in 2.5.0.
391 *
392 * \param ctx The AES context to use for decryption.
393 * \param input Ciphertext block.
394 * \param output Output (plaintext) block.
395 */
396MBEDCRYPTO_DEPRECATED void mbedcrypto_aes_decrypt( mbedcrypto_aes_context *ctx,
397 const unsigned char input[16],
398 unsigned char output[16] );
399
400#undef MBEDCRYPTO_DEPRECATED
401#endif /* !MBEDCRYPTO_DEPRECATED_REMOVED */
402
403/**
404 * \brief Checkup routine.
405 *
406 * \return \c 0 on success.
407 * \return \c 1 on failure.
408 */
409int mbedcrypto_aes_self_test( int verbose );
410
411#ifdef __cplusplus
412}
413#endif
414
415#endif /* aes.h */