yuzu-emu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-11-29 10:24:18 +01:00
Code Issues Packages Projects Releases Wiki Activity

Improve AES documentation

Browse Source 
- Separate "\file" blocks from copyright, so that Doxygen doesn't repeat
  the copyright information in all the Detailed Descriptions.
- Improve phrasing and clarity of functions, parameters, defines and enums.

GitHub PR: #1292
This commit is contained in:
Rose Zadik 2018-01-22 11:48:23 +00:00 committed by Jaeden Amero
parent 3b8fbaab87
commit 7f44127c71
2 changed files with 199 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

302
include/mbedtls/aes.h
View File

@ -1,10 +1,18 @@
/** /**
* \file aes.h * \file aes.h
* *
* \brief AES block cipher * \brief The Advanced Encryption Standard (AES) specifies a FIPS-approved
* cryptographic algorithm that can be used to protect electronic
* data.
*
* The AES algorithm is a symmetric block cipher that can
* encrypt and decrypt information. For more information, see
* <em>FIPS Publication 197: Advanced Encryption Standard</em> and
* <em>ISO/IEC 18033-2:2006: Information technology -- Security
* techniques -- Encryption algorithms -- Part 2: Asymmetric
* ciphers</em>.
*/ */
/* /* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
* Licensed under the Apache License, Version 2.0 (the "License"); you may * Licensed under the Apache License, Version 2.0 (the "License"); you may
@ -19,8 +27,9 @@
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * limitations under the License.
* *
* This file is part of mbed TLS (https://tls.mbed.org) * This file is part of Mbed TLS (https://tls.mbed.org)
*/ */
#ifndef MBEDTLS_AES_H #ifndef MBEDTLS_AES_H
#define MBEDTLS_AES_H #define MBEDTLS_AES_H
@ -34,15 +43,15 @@
#include <stdint.h> #include <stdint.h>
/* padlock.c and aesni.c rely on these values! */ /* padlock.c and aesni.c rely on these values! */
#define MBEDTLS_AES_ENCRYPT 1 #define MBEDTLS_AES_ENCRYPT 1 /**< AES encryption. */
#define MBEDTLS_AES_DECRYPT 0 #define MBEDTLS_AES_DECRYPT 0 /**< AES decryption. */
/* Error codes in range 0x0020-0x0022 */ /* Error codes in range 0x0020-0x0022 */
#define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH -0x0020 /**< Invalid key length. */ #define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH -0x0020 /**< Invalid key length. */
#define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH -0x0022 /**< Invalid data input length. */ #define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH -0x0022 /**< Invalid data input length. */
/* Error codes in range 0x0023-0x0025 */ /* Error codes in range 0x0023-0x0025 */
#define MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE -0x0023 /**< Feature not available, e.g. unsupported AES key size. */ #define MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE -0x0023 /**< Feature not available. For example, an unsupported AES key size. */
#define MBEDTLS_ERR_AES_HW_ACCEL_FAILED -0x0025 /**< AES hardware accelerator failed. */ #define MBEDTLS_ERR_AES_HW_ACCEL_FAILED -0x0025 /**< AES hardware accelerator failed. */
#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \ #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
@ -59,68 +68,90 @@ extern "C" {
#endif #endif
/** /**
* \brief AES context structure * \brief The AES context-type definition.
*
* \note buf is able to hold 32 extra bytes, which can be used:
* - for alignment purposes if VIA padlock is used, and/or
* - to simplify key expansion in the 256-bit case by
* generating an extra round key
*/ */
typedef struct typedef struct
{ {
int nr; /*!< number of rounds */ int nr; /*!< The number of rounds. */
uint32_t *rk; /*!< AES round keys */ uint32_t *rk; /*!< AES round keys. */
uint32_t buf[68]; /*!< unaligned data */ uint32_t buf[68]; /*!< Unaligned data buffer. This buffer can
hold 32 extra Bytes, which can be used for
one of the following purposes:
<ul><li>Alignment if VIA padlock is
used.</li>
<li>Simplifying key expansion in the 256-bit
case by generating an extra round key.
</li></ul> */
} }
mbedtls_aes_context; mbedtls_aes_context;
/** /**
* \brief Initialize AES context * \brief This function initializes the specified AES context.
* *
* \param ctx AES context to be initialized * It must be the first API called before using
* the context.
*
* \param ctx The AES context to initialize.
*/ */
void mbedtls_aes_init( mbedtls_aes_context *ctx ); void mbedtls_aes_init( mbedtls_aes_context *ctx );
/** /**
* \brief Clear AES context * \brief This function releases and clears the specified AES context.
* *
* \param ctx AES context to be cleared * \param ctx The AES context to clear.
*/ */
void mbedtls_aes_free( mbedtls_aes_context *ctx ); void mbedtls_aes_free( mbedtls_aes_context *ctx );
/** /**
* \brief AES key schedule (encryption) * \brief This function sets the encryption key.
* *
* \param ctx AES context to be initialized * \param ctx The AES context to which the key should be bound.
* \param key encryption key * \param key The encryption key.
* \param keybits must be 128, 192 or 256 * \param keybits The size of data passed in bits. Valid options are:
* <ul><li>128 bits</li>
* <li>192 bits</li>
* <li>256 bits</li></ul>
* *
* \return 0 if successful, or MBEDTLS_ERR_AES_INVALID_KEY_LENGTH * \return \c 0 on success or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH
* on failure.
*/ */
int mbedtls_aes_setkey_enc( mbedtls_aes_context *ctx, const unsigned char *key, int mbedtls_aes_setkey_enc( mbedtls_aes_context *ctx, const unsigned char *key,
unsigned int keybits ); unsigned int keybits );
/** /**
* \brief AES key schedule (decryption) * \brief This function sets the decryption key.
* *
* \param ctx AES context to be initialized * \param ctx The AES context to which the key should be bound.
* \param key decryption key * \param key The decryption key.
* \param keybits must be 128, 192 or 256 * \param keybits The size of data passed. Valid options are:
* <ul><li>128 bits</li>
* <li>192 bits</li>
* <li>256 bits</li></ul>
* *
* \return 0 if successful, or MBEDTLS_ERR_AES_INVALID_KEY_LENGTH * \return \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
*/ */
int mbedtls_aes_setkey_dec( mbedtls_aes_context *ctx, const unsigned char *key, int mbedtls_aes_setkey_dec( mbedtls_aes_context *ctx, const unsigned char *key,
unsigned int keybits ); unsigned int keybits );
/** /**
* \brief AES-ECB block encryption/decryption * \brief This function performs an AES single-block encryption or
* decryption operation.
* *
* \param ctx AES context * It performs the operation defined in the \p mode parameter
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT * (encrypt or decrypt), on the input data buffer defined in
* \param input 16-byte input block * the \p input parameter.
* \param output 16-byte output block
* *
* \return 0 if successful * mbedtls_aes_init(), and either mbedtls_aes_setkey_enc() or
* mbedtls_aes_setkey_dec() must be called before the first
* call to this API with the same context.
*
* \param ctx The AES context to use for encryption or decryption.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT.
* \param input The 16-Byte buffer holding the input data.
* \param output The 16-Byte buffer holding the output data.
* \return \c 0 on success.
*/ */
int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx, int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx,
int mode, int mode,
@ -129,26 +160,40 @@ int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx,
#if defined(MBEDTLS_CIPHER_MODE_CBC) #if defined(MBEDTLS_CIPHER_MODE_CBC)
/** /**
* \brief AES-CBC buffer encryption/decryption * \brief This function performs an AES-CBC encryption or decryption operation
* Length should be a multiple of the block * on full blocks.
* size (16 bytes) *
* It performs the operation defined in the \p mode
* parameter (encrypt/decrypt), on the input data buffer defined in
* the \p input parameter.
*
* It can be called as many times as needed, until all the input
* data is processed. mbedtls_aes_init(), and either
* mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called
* before the first call to this API with the same context.
*
* \note This function operates on aligned blocks, that is, the input size
* must be a multiple of the AES block size of 16 Bytes.
* *
* \note Upon exit, the content of the IV is updated so that you can * \note Upon exit, the content of the IV is updated so that you can
* call the function same function again on the following * call the same function again on the next
* block(s) of data and get the same result as if it was * block(s) of data and get the same result as if it was
* encrypted in one call. This allows a "streaming" usage. * encrypted in one call. This allows a "streaming" usage.
* If on the other hand you need to retain the contents of the * If you need to retain the contents of the IV, you should
* IV, you should either save it manually or use the cipher * either save it manually or use the cipher module instead.
* module instead.
* *
* \param ctx AES context
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
* \param length length of the input data
* \param iv initialization vector (updated after use)
* \param input buffer holding the input data
* \param output buffer holding the output data
* *
* \return 0 if successful, or MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH * \param ctx The AES context to use for encryption or decryption.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT.
* \param length The length of the input data in Bytes. This must be a
* multiple of the block size (16 Bytes).
* \param iv Initialization vector (updated after use).
* \param input The buffer holding the input data.
* \param output The buffer holding the output data.
*
* \return \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
* on failure.
*/ */
int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx, int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx,
int mode, int mode,
@ -160,29 +205,38 @@ int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx,
#if defined(MBEDTLS_CIPHER_MODE_CFB) #if defined(MBEDTLS_CIPHER_MODE_CFB)
/** /**
* \brief AES-CFB128 buffer encryption/decryption. * \brief This function performs an AES-CFB128 encryption or decryption
* operation.
* *
* Note: Due to the nature of CFB you should use the same key schedule for * It performs the operation defined in the \p mode
* both encryption and decryption. So a context initialized with * parameter (encrypt or decrypt), on the input data buffer
* mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. * defined in the \p input parameter.
*
* For CFB, you must set up the context with mbedtls_aes_setkey_enc(),
* regardless of whether you are performing an encryption or decryption
* operation, that is, regardless of the \p mode parameter. This is
* because CFB mode uses the same key schedule for encryption and
* decryption.
* *
* \note Upon exit, the content of the IV is updated so that you can * \note Upon exit, the content of the IV is updated so that you can
* call the function same function again on the following * call the same function again on the next
* block(s) of data and get the same result as if it was * block(s) of data and get the same result as if it was
* encrypted in one call. This allows a "streaming" usage. * encrypted in one call. This allows a "streaming" usage.
* If on the other hand you need to retain the contents of the * If you need to retain the contents of the
* IV, you should either save it manually or use the cipher * IV, you must either save it manually or use the cipher
* module instead. * module instead.
* *
* \param ctx AES context
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
* \param length length of the input data
* \param iv_off offset in IV (updated after use)
* \param iv initialization vector (updated after use)
* \param input buffer holding the input data
* \param output buffer holding the output data
* *
* \return 0 if successful * \param ctx The AES context to use for encryption or decryption.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT.
* \param length The length of the input data.
* \param iv_off The offset in IV (updated after use).
* \param iv The initialization vector (updated after use).
* \param input The buffer holding the input data.
* \param output The buffer holding the output data.
*
* \return \c 0 on success.
*/ */
int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx, int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx,
int mode, int mode,
@ -193,28 +247,36 @@ int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx,
unsigned char *output ); unsigned char *output );
/** /**
* \brief AES-CFB8 buffer encryption/decryption. * \brief This function performs an AES-CFB8 encryption or decryption
* operation.
* *
* Note: Due to the nature of CFB you should use the same key schedule for * It performs the operation defined in the \p mode
* both encryption and decryption. So a context initialized with * parameter (encrypt/decrypt), on the input data buffer defined
* mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. * in the \p input parameter.
*
* Due to the nature of CFB, you must use the same key schedule for
* both encryption and decryption operations. Therefore, you must
* use the context initialized with mbedtls_aes_setkey_enc() for
* both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
* *
* \note Upon exit, the content of the IV is updated so that you can * \note Upon exit, the content of the IV is updated so that you can
* call the function same function again on the following * call the same function again on the next
* block(s) of data and get the same result as if it was * block(s) of data and get the same result as if it was
* encrypted in one call. This allows a "streaming" usage. * encrypted in one call. This allows a "streaming" usage.
* If on the other hand you need to retain the contents of the * If you need to retain the contents of the
* IV, you should either save it manually or use the cipher * IV, you should either save it manually or use the cipher
* module instead. * module instead.
* *
* \param ctx AES context
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
* \param length length of the input data
* \param iv initialization vector (updated after use)
* \param input buffer holding the input data
* \param output buffer holding the output data
* *
* \return 0 if successful * \param ctx The AES context to use for encryption or decryption.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT
* \param length The length of the input data.
* \param iv The initialization vector (updated after use).
* \param input The buffer holding the input data.
* \param output The buffer holding the output data.
*
* \return \c 0 on success.
*/ */
int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx, int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx,
int mode, int mode,
@ -226,26 +288,32 @@ int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx,
#if defined(MBEDTLS_CIPHER_MODE_CTR) #if defined(MBEDTLS_CIPHER_MODE_CTR)
/** /**
* \brief AES-CTR buffer encryption/decryption * \brief This function performs an AES-CTR encryption or decryption
* operation.
* *
* Warning: You have to keep the maximum use of your counter in mind! * This function performs the operation defined in the \p mode
* parameter (encrypt/decrypt), on the input data buffer
* defined in the \p input parameter.
* *
* Note: Due to the nature of CTR you should use the same key schedule for * Due to the nature of CTR, you must use the same key schedule
* both encryption and decryption. So a context initialized with * for both encryption and decryption operations. Therefore, you
* mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. * must use the context initialized with mbedtls_aes_setkey_enc()
* for both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
* *
* \param ctx AES context * \warning You must keep the maximum use of your counter in mind.
* \param length The length of the data *
* \param nc_off The offset in the current stream_block (for resuming * \param ctx The AES context to use for encryption or decryption.
* within current cipher stream). The offset pointer to * \param length The length of the input data.
* should be 0 at the start of a stream. * \param nc_off The offset in the current \p stream_block, for
* resuming within the current cipher stream. The
* offset pointer should be 0 at the start of a stream.
* \param nonce_counter The 128-bit nonce and counter. * \param nonce_counter The 128-bit nonce and counter.
* \param stream_block The saved stream-block for resuming. Is overwritten * \param stream_block The saved stream block for resuming. This is
* by the function. * overwritten by the function.
* \param input The input data stream * \param input The buffer holding the input data.
* \param output The output data stream * \param output The buffer holding the output data.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx, int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx,
size_t length, size_t length,
@ -257,30 +325,30 @@ int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx,
#endif /* MBEDTLS_CIPHER_MODE_CTR */ #endif /* MBEDTLS_CIPHER_MODE_CTR */
/** /**
* \brief Internal AES block encryption function * \brief Internal AES block encryption function. This is only
* (Only exposed to allow overriding it, * exposed to allow overriding it using
* see MBEDTLS_AES_ENCRYPT_ALT) * \c MBEDTLS_AES_ENCRYPT_ALT.
* *
* \param ctx AES context * \param ctx The AES context to use for encryption.
* \param input Plaintext block * \param input The plaintext block.
* \param output Output (ciphertext) block * \param output The output (ciphertext) block.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_internal_aes_encrypt( mbedtls_aes_context *ctx, int mbedtls_internal_aes_encrypt( mbedtls_aes_context *ctx,
const unsigned char input[16], const unsigned char input[16],
unsigned char output[16] ); unsigned char output[16] );
/** /**
* \brief Internal AES block decryption function * \brief Internal AES block decryption function. This is only
* (Only exposed to allow overriding it, * exposed to allow overriding it using see
* see MBEDTLS_AES_DECRYPT_ALT) * \c MBEDTLS_AES_DECRYPT_ALT.
* *
* \param ctx AES context * \param ctx The AES context to use for decryption.
* \param input Ciphertext block * \param input The ciphertext block.
* \param output Output (plaintext) block * \param output The output (plaintext) block.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx, int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx,
const unsigned char input[16], const unsigned char input[16],
@ -296,11 +364,11 @@ int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx,
* \brief Deprecated internal AES block encryption function * \brief Deprecated internal AES block encryption function
* without return value. * without return value.
* *
* \deprecated Superseded by mbedtls_aes_encrypt_ext() in 2.5.0 * \deprecated Superseded by mbedtls_aes_encrypt_ext() in 2.5.0.
* *
* \param ctx AES context * \param ctx The AES context to use for encryption.
* \param input Plaintext block * \param input Plaintext block.
* \param output Output (ciphertext) block * \param output Output (ciphertext) block.
*/ */
MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx, MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx,
const unsigned char input[16], const unsigned char input[16],
@ -310,11 +378,11 @@ MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx,
* \brief Deprecated internal AES block decryption function * \brief Deprecated internal AES block decryption function
* without return value. * without return value.
* *
* \deprecated Superseded by mbedtls_aes_decrypt_ext() in 2.5.0 * \deprecated Superseded by mbedtls_aes_decrypt_ext() in 2.5.0.
* *
* \param ctx AES context * \param ctx The AES context to use for decryption.
* \param input Ciphertext block * \param input Ciphertext block.
* \param output Output (plaintext) block * \param output Output (plaintext) block.
*/ */
MBEDTLS_DEPRECATED void mbedtls_aes_decrypt( mbedtls_aes_context *ctx, MBEDTLS_DEPRECATED void mbedtls_aes_decrypt( mbedtls_aes_context *ctx,
const unsigned char input[16], const unsigned char input[16],
@ -336,9 +404,9 @@ extern "C" {
#endif #endif
/** /**
* \brief Checkup routine * \brief Checkup routine.
* *
* \return 0 if successful, or 1 if the test failed * \return \c 0 on success, or \c 1 on failure.
*/ */
int mbedtls_aes_self_test( int verbose ); int mbedtls_aes_self_test( int verbose );

2
library/error.c
View File

@ -569,7 +569,7 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen )
if( use_ret == -(MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH) ) if( use_ret == -(MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH) )
mbedtls_snprintf( buf, buflen, "AES - Invalid data input length" ); mbedtls_snprintf( buf, buflen, "AES - Invalid data input length" );
if( use_ret == -(MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE) ) if( use_ret == -(MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE) )
mbedtls_snprintf( buf, buflen, "AES - Feature not available, e.g. unsupported AES key size" ); mbedtls_snprintf( buf, buflen, "AES - Feature not available. For example, an unsupported AES key size" );
if( use_ret == -(MBEDTLS_ERR_AES_HW_ACCEL_FAILED) ) if( use_ret == -(MBEDTLS_ERR_AES_HW_ACCEL_FAILED) )
mbedtls_snprintf( buf, buflen, "AES - AES hardware accelerator failed" ); mbedtls_snprintf( buf, buflen, "AES - AES hardware accelerator failed" );
#endif /* MBEDTLS_AES_C */ #endif /* MBEDTLS_AES_C */