Improve AES documentation
- 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
diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h
index 541fa93..46016dc 100644
--- a/include/mbedtls/aes.h
+++ b/include/mbedtls/aes.h
@@ -1,10 +1,18 @@
/**
* \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-2015, ARM Limited, All Rights Reserved
+/* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
* SPDX-License-Identifier: Apache-2.0
*
* 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
* 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
#define MBEDTLS_AES_H
@@ -34,15 +43,15 @@
#include <stdint.h>
/* padlock.c and aesni.c rely on these values! */
-#define MBEDTLS_AES_ENCRYPT 1
-#define MBEDTLS_AES_DECRYPT 0
+#define MBEDTLS_AES_ENCRYPT 1 /**< AES encryption. */
+#define MBEDTLS_AES_DECRYPT 0 /**< AES decryption. */
/* Error codes in range 0x0020-0x0022 */
#define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH -0x0020 /**< Invalid key length. */
#define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH -0x0022 /**< Invalid data input length. */
/* 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. */
#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
@@ -59,68 +68,90 @@
#endif
/**
- * \brief AES context structure
- *
- * \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
+ * \brief The AES context-type definition.
*/
typedef struct
{
- int nr; /*!< number of rounds */
- uint32_t *rk; /*!< AES round keys */
- uint32_t buf[68]; /*!< unaligned data */
+ int nr; /*!< The number of rounds. */
+ uint32_t *rk; /*!< AES round keys. */
+ 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;
/**
- * \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 );
/**
- * \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 );
/**
- * \brief AES key schedule (encryption)
+ * \brief This function sets the encryption key.
*
- * \param ctx AES context to be initialized
- * \param key encryption key
- * \param keybits must be 128, 192 or 256
+ * \param ctx The AES context to which the key should be bound.
+ * \param key The encryption key.
+ * \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,
unsigned int keybits );
/**
- * \brief AES key schedule (decryption)
+ * \brief This function sets the decryption key.
*
- * \param ctx AES context to be initialized
- * \param key decryption key
- * \param keybits must be 128, 192 or 256
+ * \param ctx The AES context to which the key should be bound.
+ * \param key The decryption key.
+ * \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,
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
- * \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
- * \param input 16-byte input block
- * \param output 16-byte output block
+ * It performs the operation defined in the \p mode parameter
+ * (encrypt or decrypt), on the input data buffer defined in
+ * the \p input parameter.
*
- * \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 mode,
@@ -129,26 +160,40 @@
#if defined(MBEDTLS_CIPHER_MODE_CBC)
/**
- * \brief AES-CBC buffer encryption/decryption
- * Length should be a multiple of the block
- * size (16 bytes)
+ * \brief This function performs an AES-CBC encryption or decryption operation
+ * on full blocks.
*
- * \note Upon exit, the content of the IV is updated so that you can
- * call the function same function again on the following
- * block(s) of data and get the same result as if it was
- * encrypted in one call. This allows a "streaming" usage.
- * If on the other hand you need to retain the contents of the
- * IV, you should either save it manually or use the cipher
- * module instead.
+ * It performs the operation defined in the \p mode
+ * parameter (encrypt/decrypt), on the input data buffer defined in
+ * the \p input parameter.
*
- * \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
+ * 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.
*
- * \return 0 if successful, or MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
+ * \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
+ * call the same function again on the next
+ * block(s) of data and get the same result as if it was
+ * encrypted in one call. This allows a "streaming" usage.
+ * If you need to retain the contents of the IV, you should
+ * either save it manually or use the cipher module instead.
+ *
+ *
+ * \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 mode,
@@ -160,29 +205,38 @@
#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
- * both encryption and decryption. So a context initialized with
- * mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT.
+ * It performs the operation defined in the \p mode
+ * parameter (encrypt or decrypt), on the input data buffer
+ * defined in the \p input parameter.
*
- * \note Upon exit, the content of the IV is updated so that you can
- * call the function same function again on the following
- * block(s) of data and get the same result as if it was
- * encrypted in one call. This allows a "streaming" usage.
- * If on the other hand you need to retain the contents of the
- * IV, you should either save it manually or use the cipher
- * module instead.
+ * 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.
*
- * \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
+ * \note Upon exit, the content of the IV is updated so that you can
+ * call the same function again on the next
+ * block(s) of data and get the same result as if it was
+ * encrypted in one call. This allows a "streaming" usage.
+ * If you need to retain the contents of the
+ * IV, you must either save it manually or use the cipher
+ * module instead.
*
- * \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 mode,
@@ -193,28 +247,36 @@
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
- * both encryption and decryption. So a context initialized with
- * mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT.
+ * It performs the operation defined in the \p mode
+ * parameter (encrypt/decrypt), on the input data buffer defined
+ * in the \p input parameter.
*
- * \note Upon exit, the content of the IV is updated so that you can
- * call the function same function again on the following
- * block(s) of data and get the same result as if it was
- * encrypted in one call. This allows a "streaming" usage.
- * If on the other hand you need to retain the contents of the
- * IV, you should either save it manually or use the cipher
- * module instead.
+ * 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.
*
- * \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
+ * \note Upon exit, the content of the IV is updated so that you can
+ * call the same function again on the next
+ * block(s) of data and get the same result as if it was
+ * encrypted in one call. This allows a "streaming" usage.
+ * If you need to retain the contents of the
+ * IV, you should either save it manually or use the cipher
+ * module instead.
*
- * \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 mode,
@@ -226,26 +288,32 @@
#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
- * both encryption and decryption. So a context initialized with
- * mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT.
+ * Due to the nature of CTR, 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.
*
- * \param ctx AES context
- * \param length The length of the data
- * \param nc_off The offset in the current stream_block (for resuming
- * within current cipher stream). The offset pointer to
- * should be 0 at the start of a stream.
- * \param nonce_counter The 128-bit nonce and counter.
- * \param stream_block The saved stream-block for resuming. Is overwritten
- * by the function.
- * \param input The input data stream
- * \param output The output data stream
+ * \warning You must keep the maximum use of your counter in mind.
*
- * \return 0 if successful
+ * \param ctx The AES context to use for encryption or decryption.
+ * \param length The length of the input data.
+ * \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 stream_block The saved stream block for resuming. This is
+ * overwritten by the function.
+ * \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_ctr( mbedtls_aes_context *ctx,
size_t length,
@@ -257,30 +325,30 @@
#endif /* MBEDTLS_CIPHER_MODE_CTR */
/**
- * \brief Internal AES block encryption function
- * (Only exposed to allow overriding it,
- * see MBEDTLS_AES_ENCRYPT_ALT)
+ * \brief Internal AES block encryption function. This is only
+ * exposed to allow overriding it using
+ * \c MBEDTLS_AES_ENCRYPT_ALT.
*
- * \param ctx AES context
- * \param input Plaintext block
- * \param output Output (ciphertext) block
+ * \param ctx The AES context to use for encryption.
+ * \param input The plaintext 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,
const unsigned char input[16],
unsigned char output[16] );
/**
- * \brief Internal AES block decryption function
- * (Only exposed to allow overriding it,
- * see MBEDTLS_AES_DECRYPT_ALT)
+ * \brief Internal AES block decryption function. This is only
+ * exposed to allow overriding it using see
+ * \c MBEDTLS_AES_DECRYPT_ALT.
*
- * \param ctx AES context
- * \param input Ciphertext block
- * \param output Output (plaintext) block
+ * \param ctx The AES context to use for decryption.
+ * \param input The ciphertext 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,
const unsigned char input[16],
@@ -296,11 +364,11 @@
* \brief Deprecated internal AES block encryption function
* 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 input Plaintext block
- * \param output Output (ciphertext) block
+ * \param ctx The AES context to use for encryption.
+ * \param input Plaintext block.
+ * \param output Output (ciphertext) block.
*/
MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx,
const unsigned char input[16],
@@ -310,11 +378,11 @@
* \brief Deprecated internal AES block decryption function
* 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 input Ciphertext block
- * \param output Output (plaintext) block
+ * \param ctx The AES context to use for decryption.
+ * \param input Ciphertext block.
+ * \param output Output (plaintext) block.
*/
MBEDTLS_DEPRECATED void mbedtls_aes_decrypt( mbedtls_aes_context *ctx,
const unsigned char input[16],
@@ -336,9 +404,9 @@
#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 );
diff --git a/library/error.c b/library/error.c
index 4f5e446..e39fb09 100644
--- a/library/error.c
+++ b/library/error.c
@@ -569,7 +569,7 @@
if( use_ret == -(MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH) )
mbedtls_snprintf( buf, buflen, "AES - Invalid data input length" );
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) )
mbedtls_snprintf( buf, buflen, "AES - AES hardware accelerator failed" );
#endif /* MBEDTLS_AES_C */