Merge branch 'development' into development-restricted
diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile
index d5b3abe..40fa056 100644
--- a/doxygen/mbedtls.doxyfile
+++ b/doxygen/mbedtls.doxyfile
@@ -165,7 +165,7 @@
# comments will behave just like regular Qt-style comments
# (thus requiring an explicit @brief command for a brief description.)
-JAVADOC_AUTOBRIEF = YES
+JAVADOC_AUTOBRIEF = NO
# If the QT_AUTOBRIEF tag is set to YES then Doxygen will
# interpret the first line (until the first dot) of a Qt-style
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/include/mbedtls/ccm.h b/include/mbedtls/ccm.h
index 1459eb8..5a9ee4a 100644
--- a/include/mbedtls/ccm.h
+++ b/include/mbedtls/ccm.h
@@ -1,10 +1,19 @@
/**
* \file ccm.h
*
- * \brief Counter with CBC-MAC (CCM) for 128-bit block ciphers
+ * \brief CCM combines Counter mode encryption with CBC-MAC authentication
+ * for 128-bit block ciphers.
+ *
+ * Input to CCM includes the following elements:
+ * <ul><li>Payload - data that is both authenticated and encrypted.</li>
+ * <li>Associated data (Adata) - data that is authenticated but not
+ * encrypted, For example, a header.</li>
+ * <li>Nonce - A unique value that is assigned to the payload and the
+ * associated data.</li></ul>
+ *
*/
/*
- * 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,16 +28,17 @@
* 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_CCM_H
#define MBEDTLS_CCM_H
#include "cipher.h"
-#define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D /**< Bad input parameters to function. */
-#define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F /**< Authenticated decryption failed. */
-#define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */
+#define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D /**< Bad input parameters to the function. */
+#define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F /**< Authenticated decryption failed. */
+#define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */
#if !defined(MBEDTLS_CCM_ALT)
// Regular implementation
@@ -39,31 +49,33 @@
#endif
/**
- * \brief CCM context structure
+ * \brief The CCM context-type definition. The CCM context is passed
+ * to the APIs called.
*/
typedef struct {
- mbedtls_cipher_context_t cipher_ctx; /*!< cipher context used */
+ mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */
}
mbedtls_ccm_context;
/**
- * \brief Initialize CCM context (just makes references valid)
- * Makes the context ready for mbedtls_ccm_setkey() or
- * mbedtls_ccm_free().
+ * \brief This function initializes the specified CCM context,
+ * to make references valid, and prepare the context
+ * for mbedtls_ccm_setkey() or mbedtls_ccm_free().
*
- * \param ctx CCM context to initialize
+ * \param ctx The CCM context to initialize.
*/
void mbedtls_ccm_init( mbedtls_ccm_context *ctx );
/**
- * \brief CCM initialization (encryption and decryption)
+ * \brief This function initializes the CCM context set in the
+ * \p ctx parameter and sets the encryption key.
*
- * \param ctx CCM context to be initialized
- * \param cipher cipher to use (a 128-bit block cipher)
- * \param key encryption key
- * \param keybits key size in bits (must be acceptable by the cipher)
+ * \param ctx The CCM context to initialize.
+ * \param cipher The 128-bit block cipher to use.
+ * \param key The encryption key.
+ * \param keybits The key size in bits. This must be acceptable by the cipher.
*
- * \return 0 if successful, or a cipher specific error code
+ * \return \c 0 on success, or a cipher-specific error code.
*/
int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx,
mbedtls_cipher_id_t cipher,
@@ -71,36 +83,37 @@
unsigned int keybits );
/**
- * \brief Free a CCM context and underlying cipher sub-context
+ * \brief This function releases and clears the specified CCM context
+ * and underlying cipher sub-context.
*
- * \param ctx CCM context to free
+ * \param ctx The CCM context to clear.
*/
void mbedtls_ccm_free( mbedtls_ccm_context *ctx );
/**
- * \brief CCM buffer encryption
+ * \brief This function encrypts a buffer using CCM.
*
- * \param ctx CCM context
- * \param length length of the input data in bytes
- * \param iv nonce (initialization vector)
- * \param iv_len length of IV in bytes
- * must be 2, 3, 4, 5, 6, 7 or 8
- * \param add additional data
- * \param add_len length of additional data in bytes
- * must be less than 2^16 - 2^8
- * \param input buffer holding the input data
- * \param output buffer for holding the output data
- * must be at least 'length' bytes wide
- * \param tag buffer for holding the tag
- * \param tag_len length of the tag to generate in bytes
- * must be 4, 6, 8, 10, 14 or 16
+ * \param ctx The CCM context to use for encryption.
+ * \param length The length of the input data in Bytes.
+ * \param iv Initialization vector (nonce).
+ * \param iv_len The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.
+ * \param add The additional data field.
+ * \param add_len The length of additional data in Bytes.
+ * Must be less than 2^16 - 2^8.
+ * \param input The buffer holding the input data.
+ * \param output The buffer holding the output data.
+ * Must be at least \p length Bytes wide.
+ * \param tag The buffer holding the tag.
+ * \param tag_len The length of the tag to generate in Bytes:
+ * 4, 6, 8, 10, 14 or 16.
*
- * \note The tag is written to a separate buffer. To get the tag
- * concatenated with the output as in the CCM spec, use
- * tag = output + length and make sure the output buffer is
- * at least length + tag_len wide.
+ * \note The tag is written to a separate buffer. To concatenate
+ * the \p tag with the \p output, as done in <em>RFC-3610:
+ * Counter with CBC-MAC (CCM)</em>, use
+ * \p tag = \p output + \p length, and make sure that the
+ * output buffer is at least \p length + \p tag_len wide.
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
const unsigned char *iv, size_t iv_len,
@@ -109,21 +122,22 @@
unsigned char *tag, size_t tag_len );
/**
- * \brief CCM buffer authenticated decryption
+ * \brief This function performs a CCM authenticated decryption of a
+ * buffer.
*
- * \param ctx CCM context
- * \param length length of the input data
- * \param iv initialization vector
- * \param iv_len length of IV
- * \param add additional data
- * \param add_len length of additional data
- * \param input buffer holding the input data
- * \param output buffer for holding the output data
- * \param tag buffer holding the tag
- * \param tag_len length of the tag
+ * \param ctx The CCM context to use for decryption.
+ * \param length The length of the input data in Bytes.
+ * \param iv Initialization vector.
+ * \param iv_len The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.
+ * \param add The additional data field.
+ * \param add_len The length of additional data in Bytes.
+ * \param input The buffer holding the input data.
+ * \param output The buffer holding the output data.
+ * \param tag The buffer holding the tag.
+ * \param tag_len The length of the tag in Bytes.
*
- * \return 0 if successful and authenticated,
- * MBEDTLS_ERR_CCM_AUTH_FAILED if tag does not match
+ * \return 0 if successful and authenticated, or
+ * #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
*/
int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
const unsigned char *iv, size_t iv_len,
@@ -135,9 +149,9 @@
}
#endif
-#else /* !MBEDTLS_CCM_ALT */
+#else /* MBEDTLS_CCM_ALT */
#include "ccm_alt.h"
-#endif /* !MBEDTLS_CCM_ALT */
+#endif /* MBEDTLS_CCM_ALT */
#ifdef __cplusplus
extern "C" {
@@ -145,9 +159,9 @@
#if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
/**
- * \brief Checkup routine
+ * \brief The CCM checkup routine.
*
- * \return 0 if successful, or 1 if the test failed
+ * \return \c 0 on success, or \c 1 on failure.
*/
int mbedtls_ccm_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h
index 97b9226..dc1bc56 100644
--- a/include/mbedtls/cipher.h
+++ b/include/mbedtls/cipher.h
@@ -1,12 +1,12 @@
/**
* \file cipher.h
*
- * \brief Generic cipher wrapper.
+ * \brief The generic cipher wrapper.
*
* \author Adriaan de Jong <dejong@fox-it.com>
*/
/*
- * 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
@@ -21,7 +21,7 @@
* 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_CIPHER_H
@@ -52,22 +52,23 @@
#define inline __inline
#endif
-#define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080 /**< The selected feature is not available. */
-#define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA -0x6100 /**< Bad input parameters to function. */
-#define MBEDTLS_ERR_CIPHER_ALLOC_FAILED -0x6180 /**< Failed to allocate memory. */
-#define MBEDTLS_ERR_CIPHER_INVALID_PADDING -0x6200 /**< Input data contains invalid padding and is rejected. */
-#define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280 /**< Decryption of block requires a full block. */
-#define MBEDTLS_ERR_CIPHER_AUTH_FAILED -0x6300 /**< Authentication failed (for AEAD modes). */
-#define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT -0x6380 /**< The context is invalid, eg because it was free()ed. */
-#define MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED -0x6400 /**< Cipher hardware accelerator failed. */
+#define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080 /**< The selected feature is not available. */
+#define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA -0x6100 /**< Bad input parameters. */
+#define MBEDTLS_ERR_CIPHER_ALLOC_FAILED -0x6180 /**< Failed to allocate memory. */
+#define MBEDTLS_ERR_CIPHER_INVALID_PADDING -0x6200 /**< Input data contains invalid padding and is rejected. */
+#define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280 /**< Decryption of block requires a full block. */
+#define MBEDTLS_ERR_CIPHER_AUTH_FAILED -0x6300 /**< Authentication failed (for AEAD modes). */
+#define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT -0x6380 /**< The context is invalid. For example, because it was freed. */
+#define MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED -0x6400 /**< Cipher hardware accelerator failed. */
-#define MBEDTLS_CIPHER_VARIABLE_IV_LEN 0x01 /**< Cipher accepts IVs of variable length */
-#define MBEDTLS_CIPHER_VARIABLE_KEY_LEN 0x02 /**< Cipher accepts keys of variable length */
+#define MBEDTLS_CIPHER_VARIABLE_IV_LEN 0x01 /**< Cipher accepts IVs of variable length. */
+#define MBEDTLS_CIPHER_VARIABLE_KEY_LEN 0x02 /**< Cipher accepts keys of variable length. */
#ifdef __cplusplus
extern "C" {
#endif
+/** Supported cipher IDs. */
typedef enum {
MBEDTLS_CIPHER_ID_NONE = 0,
MBEDTLS_CIPHER_ID_NULL,
@@ -79,6 +80,7 @@
MBEDTLS_CIPHER_ID_ARC4,
} mbedtls_cipher_id_t;
+/** Supported cipher types. */
typedef enum {
MBEDTLS_CIPHER_NONE = 0,
MBEDTLS_CIPHER_NULL,
@@ -131,6 +133,7 @@
MBEDTLS_CIPHER_CAMELLIA_256_CCM,
} mbedtls_cipher_type_t;
+/** Supported cipher modes. */
typedef enum {
MBEDTLS_MODE_NONE = 0,
MBEDTLS_MODE_ECB,
@@ -143,14 +146,16 @@
MBEDTLS_MODE_CCM,
} mbedtls_cipher_mode_t;
+/** Supported cipher padding types. */
typedef enum {
- MBEDTLS_PADDING_PKCS7 = 0, /**< PKCS7 padding (default) */
- MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding */
- MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding */
- MBEDTLS_PADDING_ZEROS, /**< zero padding (not reversible!) */
- MBEDTLS_PADDING_NONE, /**< never pad (full blocks only) */
+ MBEDTLS_PADDING_PKCS7 = 0, /**< PKCS7 padding (default). */
+ MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding. */
+ MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding. */
+ MBEDTLS_PADDING_ZEROS, /**< zero padding (not reversible). */
+ MBEDTLS_PADDING_NONE, /**< never pad (full blocks only). */
} mbedtls_cipher_padding_t;
+/** Type of operation. */
typedef enum {
MBEDTLS_OPERATION_NONE = -1,
MBEDTLS_DECRYPT = 0,
@@ -158,19 +163,19 @@
} mbedtls_operation_t;
enum {
- /** Undefined key length */
+ /** Undefined key length. */
MBEDTLS_KEY_LENGTH_NONE = 0,
- /** Key length, in bits (including parity), for DES keys */
+ /** Key length, in bits (including parity), for DES keys. */
MBEDTLS_KEY_LENGTH_DES = 64,
- /** Key length, in bits (including parity), for DES in two key EDE */
+ /** Key length in bits, including parity, for DES in two-key EDE. */
MBEDTLS_KEY_LENGTH_DES_EDE = 128,
- /** Key length, in bits (including parity), for DES in three-key EDE */
+ /** Key length in bits, including parity, for DES in three-key EDE. */
MBEDTLS_KEY_LENGTH_DES_EDE3 = 192,
};
-/** Maximum length of any IV, in bytes */
+/** Maximum length of any IV, in Bytes. */
#define MBEDTLS_MAX_IV_LENGTH 16
-/** Maximum block size of any cipher, in bytes */
+/** Maximum block size of any cipher, in Bytes. */
#define MBEDTLS_MAX_BLOCK_LENGTH 16
/**
@@ -184,33 +189,40 @@
typedef struct mbedtls_cmac_context_t mbedtls_cmac_context_t;
/**
- * Cipher information. Allows cipher functions to be called in a generic way.
+ * Cipher information. Allows calling cipher functions
+ * in a generic way.
*/
typedef struct {
- /** Full cipher identifier (e.g. MBEDTLS_CIPHER_AES_256_CBC) */
+ /** Full cipher identifier. For example,
+ * MBEDTLS_CIPHER_AES_256_CBC.
+ */
mbedtls_cipher_type_t type;
- /** Cipher mode (e.g. MBEDTLS_MODE_CBC) */
+ /** The cipher mode. For example, MBEDTLS_MODE_CBC. */
mbedtls_cipher_mode_t mode;
- /** Cipher key length, in bits (default length for variable sized ciphers)
- * (Includes parity bits for ciphers like DES) */
+ /** The cipher key length, in bits. This is the
+ * default length for variable sized ciphers.
+ * Includes parity bits for ciphers like DES.
+ */
unsigned int key_bitlen;
- /** Name of the cipher */
+ /** Name of the cipher. */
const char * name;
- /** IV/NONCE size, in bytes.
- * For cipher that accept many sizes: recommended size */
+ /** IV or nonce size, in Bytes.
+ * For ciphers that accept variable IV sizes,
+ * this is the recommended size.
+ */
unsigned int iv_size;
- /** Flags for variable IV size, variable key size, etc. */
+ /** Flags to set. For example, if the cipher supports variable IV sizes or variable key sizes. */
int flags;
- /** block size, in bytes */
+ /** The block size, in Bytes. */
unsigned int block_size;
- /** Base cipher information and functions */
+ /** Struct for base cipher information and functions. */
const mbedtls_cipher_base_t *base;
} mbedtls_cipher_info_t;
@@ -219,125 +231,133 @@
* Generic cipher context.
*/
typedef struct {
- /** Information about the associated cipher */
+ /** Information about the associated cipher. */
const mbedtls_cipher_info_t *cipher_info;
- /** Key length to use */
+ /** Key length to use. */
int key_bitlen;
- /** Operation that the context's key has been initialised for */
+ /** Operation that the key of the context has been
+ * initialized for.
+ */
mbedtls_operation_t operation;
#if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
- /** Padding functions to use, if relevant for cipher mode */
+ /** Padding functions to use, if relevant for
+ * the specific cipher mode.
+ */
void (*add_padding)( unsigned char *output, size_t olen, size_t data_len );
int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len );
#endif
- /** Buffer for data that hasn't been encrypted yet */
+ /** Buffer for input that has not been processed yet. */
unsigned char unprocessed_data[MBEDTLS_MAX_BLOCK_LENGTH];
- /** Number of bytes that still need processing */
+ /** Number of Bytes that have not been processed yet. */
size_t unprocessed_len;
- /** Current IV or NONCE_COUNTER for CTR-mode */
+ /** Current IV or NONCE_COUNTER for CTR-mode. */
unsigned char iv[MBEDTLS_MAX_IV_LENGTH];
- /** IV size in bytes (for ciphers with variable-length IVs) */
+ /** IV size in Bytes, for ciphers with variable-length IVs. */
size_t iv_size;
- /** Cipher-specific context */
+ /** The cipher-specific context. */
void *cipher_ctx;
#if defined(MBEDTLS_CMAC_C)
- /** CMAC Specific context */
+ /** CMAC-specific context. */
mbedtls_cmac_context_t *cmac_ctx;
#endif
} mbedtls_cipher_context_t;
/**
- * \brief Returns the list of ciphers supported by the generic cipher module.
+ * \brief This function retrieves the list of ciphers supported by the generic
+ * cipher module.
*
- * \return a statically allocated array of ciphers, the last entry
- * is 0.
+ * \return A statically-allocated array of ciphers. The last entry
+ * is zero.
*/
const int *mbedtls_cipher_list( void );
/**
- * \brief Returns the cipher information structure associated
- * with the given cipher name.
+ * \brief This function retrieves the cipher-information
+ * structure associated with the given cipher name.
*
* \param cipher_name Name of the cipher to search for.
*
- * \return the cipher information structure associated with the
- * given cipher_name, or NULL if not found.
+ * \return The cipher information structure associated with the
+ * given \p cipher_name, or NULL if not found.
*/
const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name );
/**
- * \brief Returns the cipher information structure associated
- * with the given cipher type.
+ * \brief This function retrieves the cipher-information
+ * structure associated with the given cipher type.
*
* \param cipher_type Type of the cipher to search for.
*
- * \return the cipher information structure associated with the
- * given cipher_type, or NULL if not found.
+ * \return The cipher information structure associated with the
+ * given \p cipher_type, or NULL if not found.
*/
const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type( const mbedtls_cipher_type_t cipher_type );
/**
- * \brief Returns the cipher information structure associated
- * with the given cipher id, key size and mode.
+ * \brief This function retrieves the cipher-information
+ * structure associated with the given cipher ID,
+ * key size and mode.
*
- * \param cipher_id Id of the cipher to search for
- * (e.g. MBEDTLS_CIPHER_ID_AES)
- * \param key_bitlen Length of the key in bits
- * \param mode Cipher mode (e.g. MBEDTLS_MODE_CBC)
+ * \param cipher_id The ID of the cipher to search for. For example,
+ * #MBEDTLS_CIPHER_ID_AES.
+ * \param key_bitlen The length of the key in bits.
+ * \param mode The cipher mode. For example, #MBEDTLS_MODE_CBC.
*
- * \return the cipher information structure associated with the
- * given cipher_type, or NULL if not found.
+ * \return The cipher information structure associated with the
+ * given \p cipher_id, or NULL if not found.
*/
const mbedtls_cipher_info_t *mbedtls_cipher_info_from_values( const mbedtls_cipher_id_t cipher_id,
int key_bitlen,
const mbedtls_cipher_mode_t mode );
/**
- * \brief Initialize a cipher_context (as NONE)
+ * \brief This function initializes a \p cipher_context as NONE.
*/
void mbedtls_cipher_init( mbedtls_cipher_context_t *ctx );
/**
- * \brief Free and clear the cipher-specific context of ctx.
- * Freeing ctx itself remains the responsibility of the
- * caller.
+ * \brief This function frees and clears the cipher-specific
+ * context of \p ctx. Freeing \p ctx itself remains the
+ * responsibility of the caller.
*/
void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx );
+
/**
- * \brief Initialises and fills the cipher context structure with
- * the appropriate values.
+ * \brief This function initializes and fills the cipher-context
+ * structure with the appropriate values. It also clears
+ * the structure.
*
- * \note Currently also clears structure. In future versions you
- * will be required to call mbedtls_cipher_init() on the structure
- * first.
+ * \param ctx The context to initialize. May not be NULL.
+ * \param cipher_info The cipher to use.
*
- * \param ctx context to initialise. May not be NULL.
- * \param cipher_info cipher to use.
- *
- * \return 0 on success,
- * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure,
- * MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
+ * \return \c 0 on success,
+ * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure,
+ * #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
* cipher-specific context failed.
+ *
+ * \internal Currently, the function also clears the structure.
+ * In future versions, the caller will be required to call
+ * mbedtls_cipher_init() on the structure first.
*/
int mbedtls_cipher_setup( mbedtls_cipher_context_t *ctx, const mbedtls_cipher_info_t *cipher_info );
/**
- * \brief Returns the block size of the given cipher.
+ * \brief This function returns the block size of the given cipher.
*
- * \param ctx cipher's context. Must have been initialised.
+ * \param ctx The context of the cipher. Must be initialized.
*
- * \return size of the cipher's blocks, or 0 if ctx has not been
- * initialised.
+ * \return The size of the blocks of the cipher, or zero if \p ctx
+ * has not been initialized.
*/
static inline unsigned int mbedtls_cipher_get_block_size( const mbedtls_cipher_context_t *ctx )
{
@@ -348,13 +368,13 @@
}
/**
- * \brief Returns the mode of operation for the cipher.
- * (e.g. MBEDTLS_MODE_CBC)
+ * \brief This function returns the mode of operation for
+ * the cipher. For example, MBEDTLS_MODE_CBC.
*
- * \param ctx cipher's context. Must have been initialised.
+ * \param ctx The context of the cipher. Must be initialized.
*
- * \return mode of operation, or MBEDTLS_MODE_NONE if ctx
- * has not been initialised.
+ * \return The mode of operation, or #MBEDTLS_MODE_NONE if
+ * \p ctx has not been initialized.
*/
static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtls_cipher_context_t *ctx )
{
@@ -365,13 +385,14 @@
}
/**
- * \brief Returns the size of the cipher's IV/NONCE in bytes.
+ * \brief This function returns the size of the IV or nonce
+ * of the cipher, in Bytes.
*
- * \param ctx cipher's context. Must have been initialised.
+ * \param ctx The context of the cipher. Must be initialized.
*
- * \return If IV has not been set yet: (recommended) IV size
- * (0 for ciphers not using IV/NONCE).
- * If IV has already been set: actual size.
+ * \return <ul><li>If no IV has been set: the recommended IV size.
+ * 0 for ciphers not using IV or nonce.</li>
+ * <li>If IV has already been set: the actual size.</li></ul>
*/
static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ctx )
{
@@ -385,12 +406,12 @@
}
/**
- * \brief Returns the type of the given cipher.
+ * \brief This function returns the type of the given cipher.
*
- * \param ctx cipher's context. Must have been initialised.
+ * \param ctx The context of the cipher. Must be initialized.
*
- * \return type of the cipher, or MBEDTLS_CIPHER_NONE if ctx has
- * not been initialised.
+ * \return The type of the cipher, or #MBEDTLS_CIPHER_NONE if
+ * \p ctx has not been initialized.
*/
static inline mbedtls_cipher_type_t mbedtls_cipher_get_type( const mbedtls_cipher_context_t *ctx )
{
@@ -401,11 +422,13 @@
}
/**
- * \brief Returns the name of the given cipher, as a string.
+ * \brief This function returns the name of the given cipher
+ * as a string.
*
- * \param ctx cipher's context. Must have been initialised.
+ * \param ctx The context of the cipher. Must be initialized.
*
- * \return name of the cipher, or NULL if ctx was not initialised.
+ * \return The name of the cipher, or NULL if \p ctx has not
+ * been not initialized.
*/
static inline const char *mbedtls_cipher_get_name( const mbedtls_cipher_context_t *ctx )
{
@@ -416,13 +439,13 @@
}
/**
- * \brief Returns the key length of the cipher.
+ * \brief This function returns the key length of the cipher.
*
- * \param ctx cipher's context. Must have been initialised.
+ * \param ctx The context of the cipher. Must be initialized.
*
- * \return cipher's key length, in bits, or
- * MBEDTLS_KEY_LENGTH_NONE if ctx has not been
- * initialised.
+ * \return The key length of the cipher in bits, or
+ * #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been
+ * initialized.
*/
static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t *ctx )
{
@@ -433,13 +456,13 @@
}
/**
- * \brief Returns the operation of the given cipher.
+ * \brief This function returns the operation of the given cipher.
*
- * \param ctx cipher's context. Must have been initialised.
+ * \param ctx The context of the cipher. Must be initialized.
*
- * \return operation (MBEDTLS_ENCRYPT or MBEDTLS_DECRYPT),
- * or MBEDTLS_OPERATION_NONE if ctx has not been
- * initialised.
+ * \return The type of operation: #MBEDTLS_ENCRYPT or
+ * #MBEDTLS_DECRYPT, or #MBEDTLS_OPERATION_NONE if \p ctx
+ * has not been initialized.
*/
static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_cipher_context_t *ctx )
{
@@ -450,18 +473,18 @@
}
/**
- * \brief Set the key to use with the given context.
+ * \brief This function sets the key to use with the given context.
*
- * \param ctx generic cipher context. May not be NULL. Must have been
- * initialised using cipher_context_from_type or
- * cipher_context_from_string.
+ * \param ctx The generic cipher context. May not be NULL. Must have
+ * been initialized using mbedtls_cipher_info_from_type()
+ * or mbedtls_cipher_info_from_string().
* \param key The key to use.
- * \param key_bitlen key length to use, in bits.
- * \param operation Operation that the key will be used for, either
- * MBEDTLS_ENCRYPT or MBEDTLS_DECRYPT.
+ * \param key_bitlen The key length to use, in bits.
+ * \param operation The operation that the key will be used for:
+ * #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
*
- * \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
- * parameter verification fails or a cipher specific
+ * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
+ * parameter verification fails, or a cipher-specific
* error code.
*/
int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *key,
@@ -469,170 +492,176 @@
#if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
/**
- * \brief Set padding mode, for cipher modes that use padding.
- * (Default: PKCS7 padding.)
+ * \brief This function sets the padding mode, for cipher modes
+ * that use padding.
*
- * \param ctx generic cipher context
- * \param mode padding mode
+ * The default passing mode is PKCS7 padding.
*
- * \returns 0 on success, MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
- * if selected padding mode is not supported, or
- * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
+ * \param ctx The generic cipher context.
+ * \param mode The padding mode.
+ *
+ * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
+ * if the selected padding mode is not supported, or
+ * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
* does not support padding.
*/
int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_cipher_padding_t mode );
#endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */
/**
- * \brief Set the initialization vector (IV) or nonce
+ * \brief This function sets the initialization vector (IV)
+ * or nonce.
*
- * \param ctx generic cipher context
- * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
- * \param iv_len IV length for ciphers with variable-size IV;
- * discarded by ciphers with fixed-size IV.
+ * \param ctx The generic cipher context.
+ * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
+ * \param iv_len The IV length for ciphers with variable-size IV.
+ * This parameter is discarded by ciphers with fixed-size IV.
*
- * \returns 0 on success, or MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
+ * \returns \c 0 on success, or #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
*
- * \note Some ciphers don't use IVs nor NONCE. For these
- * ciphers, this function has no effect.
+ * \note Some ciphers do not use IVs nor nonce. For these
+ * ciphers, this function has no effect.
*/
int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx,
const unsigned char *iv, size_t iv_len );
/**
- * \brief Finish preparation of the given context
+ * \brief This function resets the cipher state.
*
- * \param ctx generic cipher context
+ * \param ctx The generic cipher context.
*
- * \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
- * if parameter verification fails.
+ * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
+ * if parameter verification fails.
*/
int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx );
#if defined(MBEDTLS_GCM_C)
/**
- * \brief Add additional data (for AEAD ciphers).
- * Currently only supported with GCM.
- * Must be called exactly once, after mbedtls_cipher_reset().
+ * \brief This function adds additional data for AEAD ciphers.
+ * Only supported with GCM. Must be called
+ * exactly once, after mbedtls_cipher_reset().
*
- * \param ctx generic cipher context
- * \param ad Additional data to use.
- * \param ad_len Length of ad.
+ * \param ctx The generic cipher context.
+ * \param ad The additional data to use.
+ * \param ad_len the Length of \p ad.
*
- * \return 0 on success, or a specific error code.
+ * \return \c 0 on success, or a specific error code on failure.
*/
int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx,
const unsigned char *ad, size_t ad_len );
#endif /* MBEDTLS_GCM_C */
/**
- * \brief Generic cipher update function. Encrypts/decrypts
- * using the given cipher context. Writes as many block
- * size'd blocks of data as possible to output. Any data
- * that cannot be written immediately will either be added
- * to the next block, or flushed when cipher_final is
- * called.
- * Exception: for MBEDTLS_MODE_ECB, expects single block
- * in size (e.g. 16 bytes for AES)
+ * \brief The generic cipher update function. It encrypts or
+ * decrypts using the given cipher context. Writes as
+ * many block-sized blocks of data as possible to output.
+ * Any data that cannot be written immediately is either
+ * added to the next block, or flushed when
+ * mbedtls_cipher_finish() is called.
+ * Exception: For MBEDTLS_MODE_ECB, expects a single block
+ * in size. For example, 16 Bytes for AES.
*
- * \param ctx generic cipher context
- * \param input buffer holding the input data
- * \param ilen length of the input data
- * \param output buffer for the output data. Should be able to hold at
- * least ilen + block_size. Cannot be the same buffer as
- * input!
- * \param olen length of the output data, will be filled with the
- * actual number of bytes written.
+ * \param ctx The generic cipher context.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ * \param output The buffer for the output data. Must be able to hold at
+ * least \p ilen + block_size. Must not be the same buffer
+ * as input.
+ * \param olen The length of the output data, to be updated with the
+ * actual number of Bytes written.
*
- * \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
+ * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
* parameter verification fails,
- * MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an
- * unsupported mode for a cipher or a cipher specific
+ * #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an
+ * unsupported mode for a cipher, or a cipher-specific
* error code.
*
* \note If the underlying cipher is GCM, all calls to this
- * function, except the last one before mbedtls_cipher_finish(),
- * must have ilen a multiple of the block size.
+ * function, except the last one before
+ * mbedtls_cipher_finish(). Must have \p ilen as a
+ * multiple of the block_size.
*/
int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input,
size_t ilen, unsigned char *output, size_t *olen );
/**
- * \brief Generic cipher finalisation function. If data still
- * needs to be flushed from an incomplete block, data
- * contained within it will be padded with the size of
- * the last block, and written to the output buffer.
+ * \brief The generic cipher finalization function. If data still
+ * needs to be flushed from an incomplete block, the data
+ * contained in it is padded to the size of
+ * the last block, and written to the \p output buffer.
*
- * \param ctx Generic cipher context
- * \param output buffer to write data to. Needs block_size available.
- * \param olen length of the data written to the output buffer.
+ * \param ctx The generic cipher context.
+ * \param output The buffer to write data to. Needs block_size available.
+ * \param olen The length of the data written to the \p output buffer.
*
- * \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
+ * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
* parameter verification fails,
- * MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
+ * #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
* expected a full block but was not provided one,
- * MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
- * while decrypting or a cipher specific error code.
+ * #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
+ * while decrypting, or a cipher-specific error code
+ * on failure for any other reason.
*/
int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx,
unsigned char *output, size_t *olen );
#if defined(MBEDTLS_GCM_C)
/**
- * \brief Write tag for AEAD ciphers.
- * Currently only supported with GCM.
+ * \brief This function writes a tag for AEAD ciphers.
+ * Only supported with GCM.
* Must be called after mbedtls_cipher_finish().
*
- * \param ctx Generic cipher context
- * \param tag buffer to write the tag
- * \param tag_len Length of the tag to write
+ * \param ctx The generic cipher context.
+ * \param tag The buffer to write the tag to.
+ * \param tag_len The length of the tag to write.
*
- * \return 0 on success, or a specific error code.
+ * \return \c 0 on success, or a specific error code on failure.
*/
int mbedtls_cipher_write_tag( mbedtls_cipher_context_t *ctx,
unsigned char *tag, size_t tag_len );
/**
- * \brief Check tag for AEAD ciphers.
- * Currently only supported with GCM.
+ * \brief This function checks the tag for AEAD ciphers.
+ * Only supported with GCM.
* Must be called after mbedtls_cipher_finish().
*
- * \param ctx Generic cipher context
- * \param tag Buffer holding the tag
- * \param tag_len Length of the tag to check
+ * \param ctx The generic cipher context.
+ * \param tag The buffer holding the tag.
+ * \param tag_len The length of the tag to check.
*
- * \return 0 on success, or a specific error code.
+ * \return \c 0 on success, or a specific error code on failure.
*/
int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx,
const unsigned char *tag, size_t tag_len );
#endif /* MBEDTLS_GCM_C */
/**
- * \brief Generic all-in-one encryption/decryption
- * (for all ciphers except AEAD constructs).
+ * \brief The generic all-in-one encryption/decryption function,
+ * for all ciphers except AEAD constructs.
*
- * \param ctx generic cipher context
- * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
- * \param iv_len IV length for ciphers with variable-size IV;
- * discarded by ciphers with fixed-size IV.
- * \param input buffer holding the input data
- * \param ilen length of the input data
- * \param output buffer for the output data. Should be able to hold at
- * least ilen + block_size. Cannot be the same buffer as
- * input!
- * \param olen length of the output data, will be filled with the
- * actual number of bytes written.
+ * \param ctx The generic cipher context.
+ * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
+ * \param iv_len The IV length for ciphers with variable-size IV.
+ * This parameter is discarded by ciphers with fixed-size
+ * IV.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ * \param output The buffer for the output data. Must be able to hold at
+ * least \p ilen + block_size. Must not be the same buffer
+ * as input.
+ * \param olen The length of the output data, to be updated with the
+ * actual number of Bytes written.
*
- * \note Some ciphers don't use IVs nor NONCE. For these
- * ciphers, use iv = NULL and iv_len = 0.
+ * \note Some ciphers do not use IVs nor nonce. For these
+ * ciphers, use \p iv = NULL and \p iv_len = 0.
*
- * \returns 0 on success, or
- * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
- * MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
+ * \returns \c 0 on success, or
+ * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
+ * #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
* expected a full block but was not provided one, or
- * MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
- * while decrypting, or
- * a cipher specific error code.
+ * #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
+ * while decrypting, or a cipher-specific error code on
+ * failure for any other reason.
*/
int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx,
const unsigned char *iv, size_t iv_len,
@@ -641,26 +670,26 @@
#if defined(MBEDTLS_CIPHER_MODE_AEAD)
/**
- * \brief Generic autenticated encryption (AEAD ciphers).
+ * \brief The generic autenticated encryption (AEAD) function.
*
- * \param ctx generic cipher context
- * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
- * \param iv_len IV length for ciphers with variable-size IV;
- * discarded by ciphers with fixed-size IV.
- * \param ad Additional data to authenticate.
- * \param ad_len Length of ad.
- * \param input buffer holding the input data
- * \param ilen length of the input data
- * \param output buffer for the output data.
- * Should be able to hold at least ilen.
- * \param olen length of the output data, will be filled with the
- * actual number of bytes written.
- * \param tag buffer for the authentication tag
- * \param tag_len desired tag length
+ * \param ctx The generic cipher context.
+ * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
+ * \param iv_len The IV length for ciphers with variable-size IV.
+ * This parameter is discarded by ciphers with fixed-size IV.
+ * \param ad The additional data to authenticate.
+ * \param ad_len The length of \p ad.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ * \param output The buffer for the output data.
+ * Must be able to hold at least \p ilen.
+ * \param olen The length of the output data, to be updated with the
+ * actual number of Bytes written.
+ * \param tag The buffer for the authentication tag.
+ * \param tag_len The desired length of the authentication tag.
*
- * \returns 0 on success, or
- * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
- * a cipher specific error code.
+ * \returns \c 0 on success, or
+ * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
+ * a cipher-specific error code.
*/
int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx,
const unsigned char *iv, size_t iv_len,
@@ -670,31 +699,31 @@
unsigned char *tag, size_t tag_len );
/**
- * \brief Generic autenticated decryption (AEAD ciphers).
+ * \brief The generic autenticated decryption (AEAD) function.
*
- * \param ctx generic cipher context
- * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
- * \param iv_len IV length for ciphers with variable-size IV;
- * discarded by ciphers with fixed-size IV.
- * \param ad Additional data to be authenticated.
- * \param ad_len Length of ad.
- * \param input buffer holding the input data
- * \param ilen length of the input data
- * \param output buffer for the output data.
- * Should be able to hold at least ilen.
- * \param olen length of the output data, will be filled with the
- * actual number of bytes written.
- * \param tag buffer holding the authentication tag
- * \param tag_len length of the authentication tag
+ * \param ctx The generic cipher context.
+ * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
+ * \param iv_len The IV length for ciphers with variable-size IV.
+ * This parameter is discarded by ciphers with fixed-size IV.
+ * \param ad The additional data to be authenticated.
+ * \param ad_len The length of \p ad.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ * \param output The buffer for the output data.
+ * Must be able to hold at least \p ilen.
+ * \param olen The length of the output data, to be updated with the
+ * actual number of Bytes written.
+ * \param tag The buffer holding the authentication tag.
+ * \param tag_len The length of the authentication tag.
*
- * \returns 0 on success, or
- * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
- * MBEDTLS_ERR_CIPHER_AUTH_FAILED if data isn't authentic,
- * or a cipher specific error code.
+ * \returns \c 0 on success, or
+ * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
+ * #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic,
+ * or a cipher-specific error code on failure for any other reason.
*
* \note If the data is not authentic, then the output buffer
- * is zeroed out to prevent the unauthentic plaintext to
- * be used by mistake, making this interface safer.
+ * is zeroed out to prevent the unauthentic plaintext being
+ * used, making this interface safer.
*/
int mbedtls_cipher_auth_decrypt( mbedtls_cipher_context_t *ctx,
const unsigned char *iv, size_t iv_len,
diff --git a/include/mbedtls/cmac.h b/include/mbedtls/cmac.h
index 1cac948..628c9da 100644
--- a/include/mbedtls/cmac.h
+++ b/include/mbedtls/cmac.h
@@ -1,11 +1,11 @@
/**
* \file cmac.h
*
- * \brief Cipher-based Message Authentication Code (CMAC) Mode for
- * Authentication
+ * \brief The Cipher-based Message Authentication Code (CMAC) Mode for
+ * Authentication.
*/
/*
- * Copyright (C) 2015-2016, ARM Limited, All Rights Reserved
+ * Copyright (C) 2015-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
@@ -20,8 +20,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_CMAC_H
#define MBEDTLS_CMAC_H
@@ -31,110 +32,125 @@
extern "C" {
#endif
-#define MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED -0x007A /**< CMAC hardware accelerator failed. */
+#define MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED -0x007A /**< CMAC hardware accelerator failed. */
#define MBEDTLS_AES_BLOCK_SIZE 16
#define MBEDTLS_DES3_BLOCK_SIZE 8
#if defined(MBEDTLS_AES_C)
-#define MBEDTLS_CIPHER_BLKSIZE_MAX 16 /* longest used by CMAC is AES */
+#define MBEDTLS_CIPHER_BLKSIZE_MAX 16 /* The longest block used by CMAC is that of AES. */
#else
-#define MBEDTLS_CIPHER_BLKSIZE_MAX 8 /* longest used by CMAC is 3DES */
+#define MBEDTLS_CIPHER_BLKSIZE_MAX 8 /* The longest block used by CMAC is that of 3DES. */
#endif
#if !defined(MBEDTLS_CMAC_ALT)
/**
- * CMAC context structure - Contains internal state information only
+ * The CMAC context structure.
*/
struct mbedtls_cmac_context_t
{
- /** Internal state of the CMAC algorithm */
+ /** The internal state of the CMAC algorithm. */
unsigned char state[MBEDTLS_CIPHER_BLKSIZE_MAX];
/** Unprocessed data - either data that was not block aligned and is still
- * pending to be processed, or the final block */
+ * pending processing, or the final block. */
unsigned char unprocessed_block[MBEDTLS_CIPHER_BLKSIZE_MAX];
- /** Length of data pending to be processed */
+ /** The length of data pending processing. */
size_t unprocessed_len;
};
/**
- * \brief Set the CMAC key and prepare to authenticate the input
- * data.
- * Should be called with an initialized cipher context.
+ * \brief This function sets the CMAC key, and prepares to authenticate
+ * the input data.
+ * Must be called with an initialized cipher context.
*
- * \param ctx Cipher context. This should be a cipher context,
- * initialized to be one of the following types:
- * MBEDTLS_CIPHER_AES_128_ECB, MBEDTLS_CIPHER_AES_192_ECB,
- * MBEDTLS_CIPHER_AES_256_ECB or
- * MBEDTLS_CIPHER_DES_EDE3_ECB.
- * \param key CMAC key
- * \param keybits length of the CMAC key in bits
- * (must be acceptable by the cipher)
+ * \param ctx The cipher context used for the CMAC operation, initialized
+ * as one of the following types:<ul>
+ * <li>MBEDTLS_CIPHER_AES_128_ECB</li>
+ * <li>MBEDTLS_CIPHER_AES_192_ECB</li>
+ * <li>MBEDTLS_CIPHER_AES_256_ECB</li>
+ * <li>MBEDTLS_CIPHER_DES_EDE3_ECB</li></ul>
+ * \param key The CMAC key.
+ * \param keybits The length of the CMAC key in bits.
+ * Must be supported by the cipher.
*
- * \return 0 if successful, or a cipher specific error code
+ * \return \c 0 on success, or a cipher-specific error code.
*/
int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx,
const unsigned char *key, size_t keybits );
/**
- * \brief Generic CMAC process buffer.
- * Called between mbedtls_cipher_cmac_starts() or
- * mbedtls_cipher_cmac_reset() and
- * mbedtls_cipher_cmac_finish().
- * May be called repeatedly.
+ * \brief This function feeds an input buffer into an ongoing CMAC
+ * computation.
*
- * \param ctx CMAC context
- * \param input buffer holding the data
- * \param ilen length of the input data
+ * It is called between mbedtls_cipher_cmac_starts() or
+ * mbedtls_cipher_cmac_reset(), and mbedtls_cipher_cmac_finish().
+ * Can be called repeatedly.
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * \param ctx The cipher context used for the CMAC operation.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ *
+ * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * if parameter verification fails.
*/
int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx,
const unsigned char *input, size_t ilen );
/**
- * \brief Output CMAC.
- * Called after mbedtls_cipher_cmac_update().
- * Usually followed by mbedtls_cipher_cmac_reset(), then
- * mbedtls_cipher_cmac_starts(), or mbedtls_cipher_free().
+ * \brief This function finishes the CMAC operation, and writes
+ * the result to the output buffer.
*
- * \param ctx CMAC context
- * \param output Generic CMAC checksum result
+ * It is called after mbedtls_cipher_cmac_update().
+ * It can be followed by mbedtls_cipher_cmac_reset() and
+ * mbedtls_cipher_cmac_update(), or mbedtls_cipher_free().
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * \param ctx The cipher context used for the CMAC operation.
+ * \param output The output buffer for the CMAC checksum result.
+ *
+ * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * if parameter verification fails.
*/
int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx,
unsigned char *output );
/**
- * \brief Prepare to authenticate a new message with the same key.
- * Called after mbedtls_cipher_cmac_finish() and before
- * mbedtls_cipher_cmac_update().
+ * \brief This function prepares the authentication of another
+ * message with the same key as the previous CMAC
+ * operation.
*
- * \param ctx CMAC context to be reset
+ * It is called after mbedtls_cipher_cmac_finish()
+ * and before mbedtls_cipher_cmac_update().
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * \param ctx The cipher context used for the CMAC operation.
+ *
+ * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * if parameter verification fails.
*/
int mbedtls_cipher_cmac_reset( mbedtls_cipher_context_t *ctx );
/**
- * \brief Output = Generic_CMAC( cmac key, input buffer )
+ * \brief This function calculates the full generic CMAC
+ * on the input buffer with the provided key.
*
- * \param cipher_info message digest info
- * \param key CMAC key
- * \param keylen length of the CMAC key in bits
- * \param input buffer holding the data
- * \param ilen length of the input data
- * \param output Generic CMAC-result
+ * The function allocates the context, performs the
+ * calculation, and frees the context.
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * The CMAC result is calculated as
+ * output = generic CMAC(cmac key, input buffer).
+ *
+ *
+ * \param cipher_info The cipher information.
+ * \param key The CMAC key.
+ * \param keylen The length of the CMAC key in bits.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ * \param output The buffer for the generic CMAC result.
+ *
+ * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * if parameter verification fails.
*/
int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info,
const unsigned char *key, size_t keylen,
@@ -143,16 +159,21 @@
#if defined(MBEDTLS_AES_C)
/**
- * \brief AES-CMAC-128-PRF
- * Implementation of (AES-CMAC-PRF-128), as defined in RFC 4615
+ * \brief This function implements the AES-CMAC-PRF-128 pseudorandom
+ * function, as defined in
+ * <em>RFC-4615: The Advanced Encryption Standard-Cipher-based
+ * Message Authentication Code-Pseudo-Random Function-128
+ * (AES-CMAC-PRF-128) Algorithm for the Internet Key
+ * Exchange Protocol (IKE).</em>
*
- * \param key PRF key
- * \param key_len PRF key length in bytes
- * \param input buffer holding the input data
- * \param in_len length of the input data in bytes
- * \param output buffer holding the generated pseudorandom output (16 bytes)
+ * \param key The key to use.
+ * \param key_len The key length in Bytes.
+ * \param input The buffer holding the input data.
+ * \param in_len The length of the input data in Bytes.
+ * \param output The buffer holding the generated 16 Bytes of
+ * pseudorandom output.
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_aes_cmac_prf_128( const unsigned char *key, size_t key_len,
const unsigned char *input, size_t in_len,
@@ -173,9 +194,9 @@
#if defined(MBEDTLS_SELF_TEST) && ( defined(MBEDTLS_AES_C) || defined(MBEDTLS_DES_C) )
/**
- * \brief Checkup routine
+ * \brief The CMAC checkup routine.
*
- * \return 0 if successful, or 1 if the test failed
+ * \return \c 0 on success, or \c 1 on failure.
*/
int mbedtls_cmac_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */
diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h
index 01cd826..121575a 100644
--- a/include/mbedtls/ctr_drbg.h
+++ b/include/mbedtls/ctr_drbg.h
@@ -1,10 +1,13 @@
/**
* \file ctr_drbg.h
*
- * \brief CTR_DRBG based on AES-256 (NIST SP 800-90)
+ * \brief CTR_DRBG is based on AES-256, as defined in <em>NIST SP 800-90A:
+ * Recommendation for Random Number Generation Using Deterministic
+ * Random Bit Generators</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 +22,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_CTR_DRBG_H
#define MBEDTLS_CTR_DRBG_H
@@ -31,78 +35,95 @@
#endif
#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034 /**< The entropy source failed. */
-#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036 /**< Too many random requested in single call. */
-#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038 /**< Input too large (Entropy + additional). */
-#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A /**< Read/write error in file. */
+#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036 /**< The requested random buffer length is too big. */
+#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038 /**< The input (entropy + additional data) is too large. */
+#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A /**< Read or write error in file. */
-#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 /**< Block size used by the cipher */
-#define MBEDTLS_CTR_DRBG_KEYSIZE 32 /**< Key size used by the cipher */
-#define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )
-#define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )
- /**< The seed length (counter + AES key) */
+#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 /**< The block size used by the cipher. */
+#define MBEDTLS_CTR_DRBG_KEYSIZE 32 /**< The key size used by the cipher. */
+#define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) /**< The key size for the DRBG operation, in bits. */
+#define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE ) /**< The seed length, calculated as (counter + AES key). */
/**
* \name SECTION: Module settings
*
* The configuration options you can set for this module are in this section.
- * Either change them in config.h or define them on the compiler command line.
+ * Either change them in config.h or define them using the compiler command
+ * line.
* \{
*/
#if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN)
#if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
-#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48 /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */
+#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48
+/**< The amount of entropy used per seed by default:
+ * <ul><li>48 with SHA-512.</li>
+ * <li>32 with SHA-256.</li></ul>
+ */
#else
-#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32 /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */
+#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32
+/**< Amount of entropy used per seed by default:
+ * <ul><li>48 with SHA-512.</li>
+ * <li>32 with SHA-256.</li></ul>
+ */
#endif
#endif
#if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
-#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000 /**< Interval before reseed is performed by default */
+#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000
+/**< The interval before reseed is performed by default. */
#endif
#if !defined(MBEDTLS_CTR_DRBG_MAX_INPUT)
-#define MBEDTLS_CTR_DRBG_MAX_INPUT 256 /**< Maximum number of additional input bytes */
+#define MBEDTLS_CTR_DRBG_MAX_INPUT 256
+/**< The maximum number of additional input Bytes. */
#endif
#if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST)
-#define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024 /**< Maximum number of requested bytes per call */
+#define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024
+/**< The maximum number of requested Bytes per call. */
#endif
#if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT)
-#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384 /**< Maximum size of (re)seed buffer */
+#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384
+/**< The maximum size of seed or reseed buffer. */
#endif
/* \} name SECTION: Module settings */
-#define MBEDTLS_CTR_DRBG_PR_OFF 0 /**< No prediction resistance */
-#define MBEDTLS_CTR_DRBG_PR_ON 1 /**< Prediction resistance enabled */
+#define MBEDTLS_CTR_DRBG_PR_OFF 0
+/**< Prediction resistance is disabled. */
+#define MBEDTLS_CTR_DRBG_PR_ON 1
+/**< Prediction resistance is enabled. */
#ifdef __cplusplus
extern "C" {
#endif
/**
- * \brief CTR_DRBG context structure
+ * \brief The CTR_DRBG context structure.
*/
typedef struct
{
- unsigned char counter[16]; /*!< counter (V) */
- int reseed_counter; /*!< reseed counter */
- int prediction_resistance; /*!< enable prediction resistance (Automatic
- reseed before every random generation) */
- size_t entropy_len; /*!< amount of entropy grabbed on each
- (re)seed */
- int reseed_interval; /*!< reseed interval */
+ unsigned char counter[16]; /*!< The counter (V). */
+ int reseed_counter; /*!< The reseed counter. */
+ int prediction_resistance; /*!< This determines whether prediction
+ resistance is enabled, that is
+ whether to systematically reseed before
+ each random generation. */
+ size_t entropy_len; /*!< The amount of entropy grabbed on each
+ seed or reseed operation. */
+ int reseed_interval; /*!< The reseed interval. */
- mbedtls_aes_context aes_ctx; /*!< AES context */
+ mbedtls_aes_context aes_ctx; /*!< The AES context. */
/*
* Callbacks (Entropy)
*/
int (*f_entropy)(void *, unsigned char *, size_t);
+ /*!< The entropy callback function. */
- void *p_entropy; /*!< context for the entropy function */
+ void *p_entropy; /*!< The context for the entropy function. */
#if defined(MBEDTLS_THREADING_C)
mbedtls_threading_mutex_t mutex;
@@ -111,31 +132,32 @@
mbedtls_ctr_drbg_context;
/**
- * \brief CTR_DRBG context initialization
- * Makes the context ready for mbedtls_ctr_drbg_seed() or
- * mbedtls_ctr_drbg_free().
+ * \brief This function initializes the CTR_DRBG context,
+ * and prepares it for mbedtls_ctr_drbg_seed()
+ * or mbedtls_ctr_drbg_free().
*
- * \param ctx CTR_DRBG context to be initialized
+ * \param ctx The CTR_DRBG context to initialize.
*/
void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
/**
- * \brief CTR_DRBG initial seeding
- * Seed and setup entropy source for future reseeds.
+ * \brief This function seeds and sets up the CTR_DRBG
+ * entropy source for future reseeds.
*
- * Note: Personalization data can be provided in addition to the more generic
- * entropy source to make this instantiation as unique as possible.
+ * \note Personalization data can be provided in addition to the more generic
+ * entropy source, to make this instantiation as unique as possible.
*
- * \param ctx CTR_DRBG context to be seeded
- * \param f_entropy Entropy callback (p_entropy, buffer to fill, buffer
- * length)
- * \param p_entropy Entropy context
- * \param custom Personalization data (Device specific identifiers)
- * (Can be NULL)
- * \param len Length of personalization data
+ * \param ctx The CTR_DRBG context to seed.
+ * \param f_entropy The entropy callback, taking as arguments the
+ * \p p_entropy context, the buffer to fill, and the
+ length of the buffer.
+ * \param p_entropy The entropy context.
+ * \param custom Personalization data, that is device-specific
+ identifiers. Can be NULL.
+ * \param len The length of the personalization data.
*
- * \return 0 if successful, or
- * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
+ * \return \c 0 on success, or
+ * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
*/
int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
int (*f_entropy)(void *, unsigned char *, size_t),
@@ -144,138 +166,147 @@
size_t len );
/**
- * \brief Clear CTR_CRBG context data
+ * \brief This function clears CTR_CRBG context data.
*
- * \param ctx CTR_DRBG context to clear
+ * \param ctx The CTR_DRBG context to clear.
*/
void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx );
/**
- * \brief Enable / disable prediction resistance (Default: Off)
+ * \brief This function turns prediction resistance on or off.
+ * The default value is off.
*
- * Note: If enabled, entropy is used for ctx->entropy_len before each call!
- * Only use this if you have ample supply of good entropy!
+ * \note If enabled, entropy is gathered at the beginning of
+ * every call to mbedtls_ctr_drbg_random_with_add().
+ * Only use this if your entropy source has sufficient
+ * throughput.
*
- * \param ctx CTR_DRBG context
- * \param resistance MBEDTLS_CTR_DRBG_PR_ON or MBEDTLS_CTR_DRBG_PR_OFF
+ * \param ctx The CTR_DRBG context.
+ * \param resistance #MBEDTLS_CTR_DRBG_PR_ON or #MBEDTLS_CTR_DRBG_PR_OFF.
*/
void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
int resistance );
/**
- * \brief Set the amount of entropy grabbed on each (re)seed
- * (Default: MBEDTLS_CTR_DRBG_ENTROPY_LEN)
+ * \brief This function sets the amount of entropy grabbed on each
+ * seed or reseed. The default value is
+ * #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
*
- * \param ctx CTR_DRBG context
- * \param len Amount of entropy to grab
+ * \param ctx The CTR_DRBG context.
+ * \param len The amount of entropy to grab.
*/
void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx,
size_t len );
/**
- * \brief Set the reseed interval
- * (Default: MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
+ * \brief This function sets the reseed interval.
+ * The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL.
*
- * \param ctx CTR_DRBG context
- * \param interval Reseed interval
+ * \param ctx The CTR_DRBG context.
+ * \param interval The reseed interval.
*/
void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx,
int interval );
/**
- * \brief CTR_DRBG reseeding (extracts data from entropy source)
+ * \brief This function reseeds the CTR_DRBG context, that is
+ * extracts data from the entropy source.
*
- * \param ctx CTR_DRBG context
- * \param additional Additional data to add to state (Can be NULL)
- * \param len Length of additional data
+ * \param ctx The CTR_DRBG context.
+ * \param additional Additional data to add to the state. Can be NULL.
+ * \param len The length of the additional data.
*
- * \return 0 if successful, or
- * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
+ * \return \c 0 on success, or
+ * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
*/
int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
const unsigned char *additional, size_t len );
/**
- * \brief CTR_DRBG update state
+ * \brief This function updates the state of the CTR_DRBG context.
*
- * \param ctx CTR_DRBG context
- * \param additional Additional data to update state with
- * \param add_len Length of additional data
+ * \param ctx The CTR_DRBG context.
+ * \param additional The data to update the state with.
+ * \param add_len Length of \p additional data.
*
- * \note If add_len is greater than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT,
- * only the first MBEDTLS_CTR_DRBG_MAX_SEED_INPUT bytes are used,
- * the remaining ones are silently discarded.
+ * \note If \p add_len is greater than #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT,
+ * only the first #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
+ * The remaining Bytes are silently discarded.
*/
void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx,
const unsigned char *additional, size_t add_len );
/**
- * \brief CTR_DRBG generate random with additional update input
+ * \brief This function updates a CTR_DRBG instance with additional
+ * data and uses it to generate random data.
*
- * Note: Automatically reseeds if reseed_counter is reached.
+ * \note The function automatically reseeds if the reseed counter is exceeded.
*
- * \param p_rng CTR_DRBG context
- * \param output Buffer to fill
- * \param output_len Length of the buffer
- * \param additional Additional data to update with (Can be NULL)
- * \param add_len Length of additional data
+ * \param p_rng The CTR_DRBG context. This must be a pointer to a
+ * #mbedtls_ctr_drbg_context structure.
+ * \param output The buffer to fill.
+ * \param output_len The length of the buffer.
+ * \param additional Additional data to update. Can be NULL.
+ * \param add_len The length of the additional data.
*
- * \return 0 if successful, or
- * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or
- * MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG
+ * \return \c 0 on success, or
+ * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
+ * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
*/
int mbedtls_ctr_drbg_random_with_add( void *p_rng,
unsigned char *output, size_t output_len,
const unsigned char *additional, size_t add_len );
/**
- * \brief CTR_DRBG generate random
+ * \brief This function uses CTR_DRBG to generate random data.
*
- * Note: Automatically reseeds if reseed_counter is reached.
+ * \note The function automatically reseeds if the reseed counter is exceeded.
*
- * \param p_rng CTR_DRBG context
- * \param output Buffer to fill
- * \param output_len Length of the buffer
+ * \param p_rng The CTR_DRBG context. This must be a pointer to a
+ * #mbedtls_ctr_drbg_context structure.
+ * \param output The buffer to fill.
+ * \param output_len The length of the buffer.
*
- * \return 0 if successful, or
- * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or
- * MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG
+ * \return \c 0 on success, or
+ * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
+ * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
*/
int mbedtls_ctr_drbg_random( void *p_rng,
unsigned char *output, size_t output_len );
#if defined(MBEDTLS_FS_IO)
/**
- * \brief Write a seed file
+ * \brief This function writes a seed file.
*
- * \param ctx CTR_DRBG context
- * \param path Name of the file
+ * \param ctx The CTR_DRBG context.
+ * \param path The name of the file.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or
- * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
+ * \return \c 0 on success,
+ * #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or
+ * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
+ * failure.
*/
int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
/**
- * \brief Read and update a seed file. Seed is added to this
- * instance
+ * \brief This function reads and updates a seed file. The seed
+ * is added to this instance.
*
- * \param ctx CTR_DRBG context
- * \param path Name of the file
+ * \param ctx The CTR_DRBG context.
+ * \param path The name of the file.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error,
- * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
- * MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG
+ * \return \c 0 on success,
+ * #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error,
+ * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
+ * #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG on failure.
*/
int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
#endif /* MBEDTLS_FS_IO */
/**
- * \brief Checkup routine
+ * \brief The CTR_DRBG checkup routine.
*
- * \return 0 if successful, or 1 if the test failed
+ * \return \c 0 on success, or \c 1 on failure.
*/
int mbedtls_ctr_drbg_self_test( int verbose );
diff --git a/include/mbedtls/dhm.h b/include/mbedtls/dhm.h
index 8a953b9..da2e66b 100644
--- a/include/mbedtls/dhm.h
+++ b/include/mbedtls/dhm.h
@@ -1,7 +1,15 @@
/**
* \file dhm.h
*
- * \brief Diffie-Hellman-Merkle key exchange
+ * \brief Diffie-Hellman-Merkle key exchange.
+ *
+ * <em>RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for
+ * Internet Key Exchange (IKE)</em> defines a number of standardized
+ * Diffie-Hellman groups for IKE.
+ *
+ * <em>RFC-5114: Additional Diffie-Hellman Groups for Use with IETF
+ * Standards</em> defines a number of standardized Diffie-Hellman
+ * groups that can be used.
*
* \warning The security of the DHM key exchange relies on the proper choice
* of prime modulus - optimally, it should be a safe prime. The usage
@@ -30,7 +38,7 @@
*
*/
/*
- * 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
@@ -45,9 +53,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_DHM_H
#define MBEDTLS_DHM_H
@@ -62,7 +70,7 @@
/*
* DHM Error codes
*/
-#define MBEDTLS_ERR_DHM_BAD_INPUT_DATA -0x3080 /**< Bad input parameters to function. */
+#define MBEDTLS_ERR_DHM_BAD_INPUT_DATA -0x3080 /**< Bad input parameters. */
#define MBEDTLS_ERR_DHM_READ_PARAMS_FAILED -0x3100 /**< Reading of the DHM parameters failed. */
#define MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED -0x3180 /**< Making of the DHM parameters failed. */
#define MBEDTLS_ERR_DHM_READ_PUBLIC_FAILED -0x3200 /**< Reading of the public values failed. */
@@ -70,7 +78,7 @@
#define MBEDTLS_ERR_DHM_CALC_SECRET_FAILED -0x3300 /**< Calculation of the DHM secret failed. */
#define MBEDTLS_ERR_DHM_INVALID_FORMAT -0x3380 /**< The ASN.1 data is not formatted correctly. */
#define MBEDTLS_ERR_DHM_ALLOC_FAILED -0x3400 /**< Allocation of memory failed. */
-#define MBEDTLS_ERR_DHM_FILE_IO_ERROR -0x3480 /**< Read/write of file failed. */
+#define MBEDTLS_ERR_DHM_FILE_IO_ERROR -0x3480 /**< Read or write of file failed. */
#define MBEDTLS_ERR_DHM_HW_ACCEL_FAILED -0x3500 /**< DHM hardware accelerator failed. */
#define MBEDTLS_ERR_DHM_SET_GROUP_FAILED -0x3580 /**< Setting the modulus and generator failed. */
@@ -79,35 +87,35 @@
#endif
/**
- * \brief DHM context structure
+ * \brief The DHM context structure.
*/
typedef struct
{
- size_t len; /*!< size(P) in chars */
- mbedtls_mpi P; /*!< prime modulus */
- mbedtls_mpi G; /*!< generator */
- mbedtls_mpi X; /*!< secret value */
- mbedtls_mpi GX; /*!< self = G^X mod P */
- mbedtls_mpi GY; /*!< peer = G^Y mod P */
- mbedtls_mpi K; /*!< key = GY^X mod P */
- mbedtls_mpi RP; /*!< cached R^2 mod P */
- mbedtls_mpi Vi; /*!< blinding value */
- mbedtls_mpi Vf; /*!< un-blinding value */
- mbedtls_mpi pX; /*!< previous X */
+ size_t len; /*!< The size of \p P in Bytes. */
+ mbedtls_mpi P; /*!< The prime modulus. */
+ mbedtls_mpi G; /*!< The generator. */
+ mbedtls_mpi X; /*!< Our secret value. */
+ mbedtls_mpi GX; /*!< Our public key = \c G^X mod \c P. */
+ mbedtls_mpi GY; /*!< The public key of the peer = \c G^Y mod \c P. */
+ mbedtls_mpi K; /*!< The shared secret = \c G^(XY) mod \c P. */
+ mbedtls_mpi RP; /*!< The cached value = \c R^2 mod \c P. */
+ mbedtls_mpi Vi; /*!< The blinding value. */
+ mbedtls_mpi Vf; /*!< The unblinding value. */
+ mbedtls_mpi pX; /*!< The previous \c X. */
}
mbedtls_dhm_context;
/**
- * \brief Initialize DHM context
+ * \brief This function initializes the DHM context.
*
- * \param ctx DHM context to be initialized
+ * \param ctx The DHM context to initialize.
*/
void mbedtls_dhm_init( mbedtls_dhm_context *ctx );
/**
- * \brief Parse the ServerKeyExchange parameters
+ * \brief This function parses the ServerKeyExchange parameters.
*
- * \param ctx DHM context
+ * \param ctx The DHM context.
* \param p On input, *p must be the start of the input buffer.
* On output, *p is updated to point to the end of the data
* that has been read. On success, this is the first byte
@@ -115,23 +123,25 @@
* On error, this is the point at which an error has been
* detected, which is usually not useful except to debug
* failures.
- * \param end end of buffer
+ * \param end The end of the input buffer.
*
- * \return 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
+ * on failure.
*/
int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx,
unsigned char **p,
const unsigned char *end );
/**
- * \brief Setup and write the ServerKeyExchange parameters
+ * \brief This function sets up and writes the ServerKeyExchange
+ * parameters.
*
- * \param ctx DHM context
- * \param x_size private value size in bytes
- * \param output destination buffer
- * \param olen number of chars written
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \param ctx The DHM context.
+ * \param x_size The private value size in Bytes.
+ * \param olen The number of characters written.
+ * \param output The destination buffer.
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG parameter.
*
* \note The destination buffer must be large enough to hold
* the reduced binary presentation of the modulus, the generator
@@ -140,12 +150,13 @@
* space is available. Refer to \c mbedtls_mpi_size to computing
* the byte-size of an MPI.
*
- * \note This function assumes that ctx->P and ctx->G
+ * \note This function assumes that \c ctx->P and \c ctx->G
* have already been properly set. For that, use
- * \c mbedtls_dhm_set_group below in conjunction with
- * \c mbedtls_mpi_read_binary and \c mbedtls_mpi_read_string.
+ * mbedtls_dhm_set_group() below in conjunction with
+ * mbedtls_mpi_read_binary() and mbedtls_mpi_read_string().
*
- * \return 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
+ * on failure.
*/
int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size,
unsigned char *output, size_t *olen,
@@ -155,48 +166,52 @@
/**
* \brief Set prime modulus and generator
*
- * \param ctx DHM context
- * \param P MPI holding DHM prime modulus
- * \param G MPI holding DHM generator
+ * \param ctx The DHM context.
+ * \param P The MPI holding DHM prime modulus.
+ * \param G The MPI holding DHM generator.
*
* \note This function can be used to set P, G
* in preparation for \c mbedtls_dhm_make_params.
*
- * \return 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
+ * \return \c 0 if successful, or an \c MBEDTLS_ERR_DHM_XXX error code
+ * on failure.
*/
int mbedtls_dhm_set_group( mbedtls_dhm_context *ctx,
const mbedtls_mpi *P,
const mbedtls_mpi *G );
/**
- * \brief Import the peer's public value G^Y
+ * \brief This function imports the public value G^Y of the peer.
*
- * \param ctx DHM context
- * \param input input buffer
- * \param ilen size of buffer
+ * \param ctx The DHM context.
+ * \param input The input buffer.
+ * \param ilen The size of the input buffer.
*
- * \return 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
+ * on failure.
*/
int mbedtls_dhm_read_public( mbedtls_dhm_context *ctx,
const unsigned char *input, size_t ilen );
/**
- * \brief Create own private value X and export G^X
+ * \brief This function creates its own private value \c X and
+ * exports \c G^X.
*
- * \param ctx DHM context
- * \param x_size private value size in bytes
- * \param output destination buffer
- * \param olen size of the destination buffer;
- * must be at least equal to the size of P, ctx->len
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \param ctx The DHM context.
+ * \param x_size The private value size in Bytes.
+ * \param output The destination buffer.
+ * \param olen The length of the destination buffer. Must be at least
+ equal to ctx->len (the size of \c P).
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG parameter.
*
* \note The destination buffer will always be fully written
* so as to contain a big-endian presentation of G^X mod P.
* If it is larger than ctx->len, it will accordingly be
* padded with zero-bytes in the beginning.
*
- * \return 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
+ * on failure.
*/
int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size,
unsigned char *output, size_t olen,
@@ -204,23 +219,25 @@
void *p_rng );
/**
- * \brief Derive and export the shared secret (G^Y)^X mod P
+ * \brief This function derives and exports the shared secret
+ * \c (G^Y)^X mod \c P.
*
- * \param ctx DHM context
- * \param output destination buffer
- * \param output_size size of the destination buffer, must be at
- * at least the size of ctx->len
- * \param olen on exit, holds the actual number of bytes written
- * \param f_rng RNG function, for blinding purposes
- * \param p_rng RNG parameter
+ * \param ctx The DHM context.
+ * \param output The destination buffer.
+ * \param output_size The size of the destination buffer. Must be at least
+ * the size of ctx->len.
+ * \param olen On exit, holds the actual number of Bytes written.
+ * \param f_rng The RNG function, for blinding purposes.
+ * \param p_rng The RNG parameter.
*
- * \return 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
+ * on failure.
*
- * \note If non-NULL, f_rng is used to blind the input as
- * countermeasure against timing attacks. Blinding is
- * automatically used if and only if our secret value X is
- * re-used and costs nothing otherwise, so it is recommended
- * to always pass a non-NULL f_rng argument.
+ * \note If non-NULL, \p f_rng is used to blind the input as
+ * a countermeasure against timing attacks. Blinding is used
+ * only if our secret value \p X is re-used and omitted
+ * otherwise. Therefore, we recommend always passing a
+ * non-NULL \p f_rng argument.
*/
int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx,
unsigned char *output, size_t output_size, size_t *olen,
@@ -228,23 +245,24 @@
void *p_rng );
/**
- * \brief Free and clear the components of a DHM key
+ * \brief This function frees and clears the components of a DHM key.
*
- * \param ctx DHM context to free and clear
+ * \param ctx The DHM context to free and clear.
*/
void mbedtls_dhm_free( mbedtls_dhm_context *ctx );
#if defined(MBEDTLS_ASN1_PARSE_C)
/** \ingroup x509_module */
/**
- * \brief Parse DHM parameters in PEM or DER format
+ * \brief This function parses DHM parameters in PEM or DER format.
*
- * \param dhm DHM context to be initialized
- * \param dhmin input buffer
- * \param dhminlen size of the buffer
- * (including the terminating null byte for PEM data)
+ * \param dhm The DHM context to initialize.
+ * \param dhmin The input buffer.
+ * \param dhminlen The size of the buffer, including the terminating null
+ * Byte for PEM data.
*
- * \return 0 if successful, or a specific DHM or PEM error code
+ * \return \c 0 on success, or a specific DHM or PEM error code
+ * on failure.
*/
int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
size_t dhminlen );
@@ -252,12 +270,13 @@
#if defined(MBEDTLS_FS_IO)
/** \ingroup x509_module */
/**
- * \brief Load and parse DHM parameters
+ * \brief This function loads and parses DHM parameters from a file.
*
- * \param dhm DHM context to be initialized
- * \param path filename to read the DHM Parameters from
+ * \param dhm The DHM context to load the parameters to.
+ * \param path The filename to read the DHM parameters from.
*
- * \return 0 if successful, or a specific DHM or PEM error code
+ * \return \c 0 on success, or a specific DHM or PEM error code
+ * on failure.
*/
int mbedtls_dhm_parse_dhmfile( mbedtls_dhm_context *dhm, const char *path );
#endif /* MBEDTLS_FS_IO */
@@ -276,9 +295,9 @@
#endif
/**
- * \brief Checkup routine
+ * \brief The DMH checkup routine.
*
- * \return 0 if successful, or 1 if the test failed
+ * \return \c 0 on success, or \c 1 on failure.
*/
int mbedtls_dhm_self_test( int verbose );
@@ -293,16 +312,16 @@
* when configuring the Diffie-Hellman parameters by hand
* through \c mbedtls_ssl_conf_dh_param.
*
- * Included are:
- * RFC 5114 2.2. 2048-bit MODP Group with 224-bit Prime Order Subgroup
- * RFC 3526 3. 2048-bit MODP Group
- * RFC 3526 4. 3072-bit MODP Group
- * RFC 3526 5. 4096-bit MODP Group
- * RFC 7919 A.1 ffdhe2048
- * RFC 7919 A.2 ffdhe3072
- * RFC 7919 A.3 ffdhe4096
- * RFC 7919 A.4 ffdhe6144
- * RFC 7919 A.5 ffdhe8192
+ * The following lists the source of the above groups in the standards:
+ * - RFC 5114 section 2.2: 2048-bit MODP Group with 224-bit Prime Order Subgroup
+ * - RFC 3526 section 3: 2048-bit MODP Group
+ * - RFC 3526 section 4: 3072-bit MODP Group
+ * - RFC 3526 section 5: 4096-bit MODP Group
+ * - RFC 7919 section A.1: ffdhe2048
+ * - RFC 7919 section A.2: ffdhe3072
+ * - RFC 7919 section A.3: ffdhe4096
+ * - RFC 7919 section A.4: ffdhe6144
+ * - RFC 7919 section A.5: ffdhe8192
*
* The constants with suffix "_p" denote the chosen prime moduli, while
* the constants with suffix "_g" denote the chosen generator
@@ -347,6 +366,12 @@
* replacement.
*/
+/**
+ * The hexadecimal presentation of the prime underlying the
+ * 2048-bit MODP Group with 224-bit Prime Order Subgroup, as defined
+ * in <em>RFC-5114: Additional Diffie-Hellman Groups for Use with
+ * IETF Standards</em>.
+ */
#define MBEDTLS_DHM_RFC5114_MODP_P \
MBEDTLS_DEPRECATED_STRING_CONSTANT( \
"AD107E1E9123A9D0D660FAA79559C51FA20D64E5683B9FD1" \
@@ -361,6 +386,11 @@
"C9B53DCF4BA80A29E3FB73C16B8E75B97EF363E2FFA31F71" \
"CF9DE5384E71B81C0AC4DFFE0C10E64F" )
+/**
+ * The hexadecimal presentation of the chosen generator of the 2048-bit MODP
+ * Group with 224-bit Prime Order Subgroup, as defined in <em>RFC-5114:
+ * Additional Diffie-Hellman Groups for Use with IETF Standards</em>.
+ */
#define MBEDTLS_DHM_RFC5114_MODP_2048_G \
MBEDTLS_DEPRECATED_STRING_CONSTANT( \
"AC4032EF4F2D9AE39DF30B5C8FFDAC506CDEBE7B89998CAF" \
@@ -376,13 +406,16 @@
"81BC087F2A7065B384B890D3191F2BFA" )
/**
+ * The hexadecimal presentation of the prime underlying the 2048-bit MODP
+ * Group, as defined in <em>RFC-3526: More Modular Exponential (MODP)
+ * Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
+ *
* \deprecated The hex-encoded primes from RFC 3625 are deprecated and
* superseded by the corresponding macros providing them as
* binary constants. Their hex-encoded constants are likely
* to be removed in a future version of the library.
*
*/
-
#define MBEDTLS_DHM_RFC3526_MODP_2048_P \
MBEDTLS_DEPRECATED_STRING_CONSTANT( \
"FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
@@ -397,9 +430,19 @@
"DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
"15728E5A8AACAA68FFFFFFFFFFFFFFFF" )
+/**
+ * The hexadecimal presentation of the chosen generator of the 2048-bit MODP
+ * Group, as defined in <em>RFC-3526: More Modular Exponential (MODP)
+ * Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
+ */
#define MBEDTLS_DHM_RFC3526_MODP_2048_G \
MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" )
+/**
+ * The hexadecimal presentation of the prime underlying the 3072-bit MODP
+ * Group, as defined in <em>RFC-3072: More Modular Exponential (MODP)
+ * Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
+ */
#define MBEDTLS_DHM_RFC3526_MODP_3072_P \
MBEDTLS_DEPRECATED_STRING_CONSTANT( \
"FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
@@ -419,9 +462,19 @@
"BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \
"43DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF" )
+/**
+ * The hexadecimal presentation of the chosen generator of the 3072-bit MODP
+ * Group, as defined in <em>RFC-3526: More Modular Exponential (MODP)
+ * Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
+ */
#define MBEDTLS_DHM_RFC3526_MODP_3072_G \
MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" )
+/**
+ * The hexadecimal presentation of the prime underlying the 4096-bit MODP
+ * Group, as defined in <em>RFC-3526: More Modular Exponential (MODP)
+ * Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
+ */
#define MBEDTLS_DHM_RFC3526_MODP_4096_P \
MBEDTLS_DEPRECATED_STRING_CONSTANT( \
"FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
@@ -447,6 +500,11 @@
"93B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934063199" \
"FFFFFFFFFFFFFFFF" )
+/**
+ * The hexadecimal presentation of the chosen generator of the 4096-bit MODP
+ * Group, as defined in <em>RFC-3526: More Modular Exponential (MODP)
+ * Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
+ */
#define MBEDTLS_DHM_RFC3526_MODP_4096_G \
MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" )
diff --git a/include/mbedtls/ecdh.h b/include/mbedtls/ecdh.h
index 14a362b..99cfde0 100644
--- a/include/mbedtls/ecdh.h
+++ b/include/mbedtls/ecdh.h
@@ -1,10 +1,18 @@
/**
* \file ecdh.h
*
- * \brief Elliptic curve Diffie-Hellman
+ * \brief The Elliptic Curve Diffie-Hellman (ECDH) protocol APIs.
+ *
+ * ECDH is an anonymous key agreement protocol allowing two parties to
+ * establish a shared secret over an insecure channel. Each party must have an
+ * elliptic-curve public–private key pair.
+ *
+ * For more information, see <em>NIST SP 800-56A Rev. 2: Recommendation for
+ * Pair-Wise Key Establishment Schemes Using Discrete Logarithm
+ * Cryptography</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_ECDH_H
#define MBEDTLS_ECDH_H
@@ -31,7 +40,9 @@
#endif
/**
- * When importing from an EC key, select if it is our key or the peer's key
+ * Defines the source of the imported EC key:
+ * <ul><li>Our key.</li>
+ * <li>The key of the peer.</li></ul>
*/
typedef enum
{
@@ -40,56 +51,67 @@
} mbedtls_ecdh_side;
/**
- * \brief ECDH context structure
+ * \brief The ECDH context structure.
*/
typedef struct
{
- mbedtls_ecp_group grp; /*!< elliptic curve used */
- mbedtls_mpi d; /*!< our secret value (private key) */
- mbedtls_ecp_point Q; /*!< our public value (public key) */
- mbedtls_ecp_point Qp; /*!< peer's public value (public key) */
- mbedtls_mpi z; /*!< shared secret */
- int point_format; /*!< format for point export in TLS messages */
- mbedtls_ecp_point Vi; /*!< blinding value (for later) */
- mbedtls_ecp_point Vf; /*!< un-blinding value (for later) */
- mbedtls_mpi _d; /*!< previous d (for later) */
+ mbedtls_ecp_group grp; /*!< The elliptic curve used. */
+ mbedtls_mpi d; /*!< The private key. */
+ mbedtls_ecp_point Q; /*!< The public key. */
+ mbedtls_ecp_point Qp; /*!< The value of the public key of the peer. */
+ mbedtls_mpi z; /*!< The shared secret. */
+ int point_format; /*!< The format of point export in TLS messages. */
+ mbedtls_ecp_point Vi; /*!< The blinding value. */
+ mbedtls_ecp_point Vf; /*!< The unblinding value. */
+ mbedtls_mpi _d; /*!< The previous \p d. */
}
mbedtls_ecdh_context;
/**
- * \brief Generate a public key.
- * Raw function that only does the core computation.
+ * \brief This function generates an ECDH keypair on an elliptic
+ * curve.
*
- * \param grp ECP group
- * \param d Destination MPI (secret exponent, aka private key)
- * \param Q Destination point (public key)
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * This function performs the first of two core computations
+ * implemented during the ECDH key exchange. The second core
+ * computation is performed by mbedtls_ecdh_compute_shared().
*
- * \return 0 if successful,
- * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \param grp The ECP group.
+ * \param d The destination MPI (private key).
+ * \param Q The destination point (public key).
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG parameter.
+ *
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
+ * \c MBEDTLS_MPI_XXX error code on failure.
+ *
+ * \see ecp.h
*/
int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng );
/**
- * \brief Compute shared secret
- * Raw function that only does the core computation.
+ * \brief This function computes the shared secret.
*
- * \param grp ECP group
- * \param z Destination MPI (shared secret)
- * \param Q Public key from other party
- * \param d Our secret exponent (private key)
- * \param f_rng RNG function (see notes)
- * \param p_rng RNG parameter
+ * This function performs the second of two core computations
+ * implemented during the ECDH key exchange. The first core
+ * computation is performed by mbedtls_ecdh_gen_public().
*
- * \return 0 if successful,
- * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \param grp The ECP group.
+ * \param z The destination MPI (shared secret).
+ * \param Q The public key from another party.
+ * \param d Our secret exponent (private key).
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG parameter.
*
- * \note If f_rng is not NULL, it is used to implement
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
+ * \c MBEDTLS_MPI_XXX error code on failure.
+ *
+ * \see ecp.h
+ *
+ * \note If \p f_rng is not NULL, it is used to implement
* countermeasures against potential elaborate timing
- * attacks, see \c mbedtls_ecp_mul() for details.
+ * attacks. For more information, see mbedtls_ecp_mul().
*/
int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
@@ -97,34 +119,41 @@
void *p_rng );
/**
- * \brief Initialize context
+ * \brief This function initializes an ECDH context.
*
- * \param ctx Context to initialize
+ * \param ctx The ECDH context to initialize.
*/
void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
/**
- * \brief Free context
+ * \brief This function frees a context.
*
- * \param ctx Context to free
+ * \param ctx The context to free.
*/
void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
/**
- * \brief Generate a public key and a TLS ServerKeyExchange payload.
- * (First function used by a TLS server for ECDHE.)
+ * \brief This function generates a public key and a TLS
+ * ServerKeyExchange payload.
*
- * \param ctx ECDH context
- * \param olen number of chars written
- * \param buf destination buffer
- * \param blen length of buffer
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * This is the first function used by a TLS server for ECDHE
+ * ciphersuites.
*
- * \note This function assumes that ctx->grp has already been
- * properly set (for example using mbedtls_ecp_group_load).
+ * \param ctx The ECDH context.
+ * \param olen The number of characters written.
+ * \param buf The destination buffer.
+ * \param blen The length of the destination buffer.
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG parameter.
*
- * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
+ * \note This function assumes that the ECP group (grp) of the
+ * \p ctx context has already been properly set,
+ * for example, using mbedtls_ecp_group_load().
+ *
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
+ * on failure.
+ *
+ * \see ecp.h
*/
int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
unsigned char *buf, size_t blen,
@@ -132,45 +161,63 @@
void *p_rng );
/**
- * \brief Parse and procress a TLS ServerKeyExhange payload.
- * (First function used by a TLS client for ECDHE.)
+ * \brief This function parses and processes a TLS ServerKeyExhange
+ * payload.
*
- * \param ctx ECDH context
- * \param buf pointer to start of input buffer
- * \param end one past end of buffer
+ * This is the first function used by a TLS client for ECDHE
+ * ciphersuites.
*
- * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
+ * \param ctx The ECDH context.
+ * \param buf The pointer to the start of the input buffer.
+ * \param end The address for one Byte past the end of the buffer.
+ *
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
+ * on failure.
+ *
+ * \see ecp.h
*/
int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
const unsigned char **buf, const unsigned char *end );
/**
- * \brief Setup an ECDH context from an EC key.
- * (Used by clients and servers in place of the
- * ServerKeyEchange for static ECDH: import ECDH parameters
- * from a certificate's EC key information.)
+ * \brief This function sets up an ECDH context from an EC key.
*
- * \param ctx ECDH constext to set
- * \param key EC key to use
- * \param side Is it our key (1) or the peer's key (0) ?
+ * It is used by clients and servers in place of the
+ * ServerKeyEchange for static ECDH, and imports ECDH
+ * parameters from the EC key information of a certificate.
*
- * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
+ * \param ctx The ECDH context to set up.
+ * \param key The EC key to use.
+ * \param side Defines the source of the key:
+ * <ul><li>1: Our key.</li>
+ <li>0: The key of the peer.</li></ul>
+ *
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
+ * on failure.
+ *
+ * \see ecp.h
*/
int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
mbedtls_ecdh_side side );
/**
- * \brief Generate a public key and a TLS ClientKeyExchange payload.
- * (Second function used by a TLS client for ECDH(E).)
+ * \brief This function generates a public key and a TLS
+ * ClientKeyExchange payload.
*
- * \param ctx ECDH context
- * \param olen number of bytes actually written
- * \param buf destination buffer
- * \param blen size of destination buffer
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * This is the second function used by a TLS client for ECDH(E)
+ * ciphersuites.
*
- * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
+ * \param ctx The ECDH context.
+ * \param olen The number of Bytes written.
+ * \param buf The destination buffer.
+ * \param blen The size of the destination buffer.
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG parameter.
+ *
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
+ * on failure.
+ *
+ * \see ecp.h
*/
int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
unsigned char *buf, size_t blen,
@@ -178,30 +225,45 @@
void *p_rng );
/**
- * \brief Parse and process a TLS ClientKeyExchange payload.
- * (Second function used by a TLS server for ECDH(E).)
+ * \brief This function parses and processes a TLS ClientKeyExchange
+ * payload.
*
- * \param ctx ECDH context
- * \param buf start of input buffer
- * \param blen length of input buffer
+ * This is the second function used by a TLS server for ECDH(E)
+ * ciphersuites.
*
- * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
+ * \param ctx The ECDH context.
+ * \param buf The start of the input buffer.
+ * \param blen The length of the input buffer.
+ *
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
+ * on failure.
+ *
+ * \see ecp.h
*/
int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
const unsigned char *buf, size_t blen );
/**
- * \brief Derive and export the shared secret.
- * (Last function used by both TLS client en servers.)
+ * \brief This function derives and exports the shared secret.
*
- * \param ctx ECDH context
- * \param olen number of bytes written
- * \param buf destination buffer
- * \param blen buffer length
- * \param f_rng RNG function, see notes for \c mbedtls_ecdh_compute_shared()
- * \param p_rng RNG parameter
+ * This is the last function used by both TLS client
+ * and servers.
*
- * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
+ * \param ctx The ECDH context.
+ * \param olen The number of Bytes written.
+ * \param buf The destination buffer.
+ * \param blen The length of the destination buffer.
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG parameter.
+ *
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
+ * on failure.
+ *
+ * \see ecp.h
+ *
+ * \note If \p f_rng is not NULL, it is used to implement
+ * countermeasures against potential elaborate timing
+ * attacks. For more information, see mbedtls_ecp_mul().
*/
int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
unsigned char *buf, size_t blen,
diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h
index 6c6ae29..aa23d67 100644
--- a/include/mbedtls/ecdsa.h
+++ b/include/mbedtls/ecdsa.h
@@ -1,10 +1,16 @@
/**
* \file ecdsa.h
*
- * \brief Elliptic curve DSA
+ * \brief The Elliptic Curve Digital Signature Algorithm (ECDSA).
+ *
+ * ECDSA is defined in <em>Standards for Efficient Cryptography Group (SECG):
+ * SEC1 Elliptic Curve Cryptography</em>.
+ * The use of ECDSA for TLS is defined in <em>RFC-4492: Elliptic Curve
+ * Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)</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 +25,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_ECDSA_H
#define MBEDTLS_ECDSA_H
@@ -28,7 +35,7 @@
#include "md.h"
/*
- * RFC 4492 page 20:
+ * RFC-4492 page 20:
*
* Ecdsa-Sig-Value ::= SEQUENCE {
* r INTEGER,
@@ -44,11 +51,11 @@
#if MBEDTLS_ECP_MAX_BYTES > 124
#error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN"
#endif
-/** Maximum size of an ECDSA signature in bytes */
+/** The maximal size of an ECDSA signature in Bytes. */
#define MBEDTLS_ECDSA_MAX_LEN ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) )
/**
- * \brief ECDSA context structure
+ * \brief The ECDSA context structure.
*/
typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
@@ -57,25 +64,30 @@
#endif
/**
- * \brief Compute ECDSA signature of a previously hashed message
+ * \brief This function computes the ECDSA signature of a
+ * previously-hashed message.
*
- * \note The deterministic version is usually prefered.
+ * \note The deterministic version is usually preferred.
*
- * \param grp ECP group
- * \param r First output integer
- * \param s Second output integer
- * \param d Private signing key
- * \param buf Message hash
- * \param blen Length of buf
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \param grp The ECP group.
+ * \param r The first output integer.
+ * \param s The second output integer.
+ * \param d The private signing key.
+ * \param buf The message hash.
+ * \param blen The length of \p buf.
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG parameter.
*
* \note If the bitlength of the message hash is larger than the
- * bitlength of the group order, then the hash is truncated as
- * prescribed by SEC1 4.1.3 step 5.
+ * bitlength of the group order, then the hash is truncated
+ * as defined in <em>Standards for Efficient Cryptography Group
+ * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ * 4.1.3, step 5.
*
- * \return 0 if successful,
- * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX
+ * or \c MBEDTLS_MPI_XXX error code on failure.
+ *
+ * \see ecp.h
*/
int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
@@ -83,23 +95,31 @@
#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
/**
- * \brief Compute ECDSA signature of a previously hashed message,
- * deterministic version (RFC 6979).
+ * \brief This function computes the ECDSA signature of a
+ * previously-hashed message, deterministic version.
+ * For more information, see <em>RFC-6979: Deterministic
+ * Usage of the Digital Signature Algorithm (DSA) and Elliptic
+ * Curve Digital Signature Algorithm (ECDSA)</em>.
*
- * \param grp ECP group
- * \param r First output integer
- * \param s Second output integer
- * \param d Private signing key
- * \param buf Message hash
- * \param blen Length of buf
- * \param md_alg MD algorithm used to hash the message
+ * \param grp The ECP group.
+ * \param r The first output integer.
+ * \param s The second output integer.
+ * \param d The private signing key.
+ * \param buf The message hash.
+ * \param blen The length of \p buf.
+ * \param md_alg The MD algorithm used to hash the message.
*
* \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as
- * prescribed by SEC1 4.1.3 step 5.
+ * defined in <em>Standards for Efficient Cryptography Group
+ * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ * 4.1.3, step 5.
*
- * \return 0 if successful,
- * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \return \c 0 on success,
+ * or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
+ * error code on failure.
+ *
+ * \see ecp.h
*/
int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
@@ -107,55 +127,73 @@
#endif /* MBEDTLS_ECDSA_DETERMINISTIC */
/**
- * \brief Verify ECDSA signature of a previously hashed message
+ * \brief This function verifies the ECDSA signature of a
+ * previously-hashed message.
*
- * \param grp ECP group
- * \param buf Message hash
- * \param blen Length of buf
- * \param Q Public key to use for verification
- * \param r First integer of the signature
- * \param s Second integer of the signature
+ * \param grp The ECP group.
+ * \param buf The message hash.
+ * \param blen The length of \p buf.
+ * \param Q The public key to use for verification.
+ * \param r The first integer of the signature.
+ * \param s The second integer of the signature.
*
* \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as
- * prescribed by SEC1 4.1.4 step 3.
+ * defined in <em>Standards for Efficient Cryptography Group
+ * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ * 4.1.4, step 3.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid
- * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \return \c 0 on success,
+ * #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
+ * or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
+ * error code on failure for any other reason.
+ *
+ * \see ecp.h
*/
int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
const unsigned char *buf, size_t blen,
const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s);
/**
- * \brief Compute ECDSA signature and write it to buffer,
- * serialized as defined in RFC 4492 page 20.
- * (Not thread-safe to use same context in multiple threads)
+ * \brief This function computes the ECDSA signature and writes it
+ * to a buffer, serialized as defined in <em>RFC-4492:
+ * Elliptic Curve Cryptography (ECC) Cipher Suites for
+ * Transport Layer Security (TLS)</em>.
*
- * \note The deterministic version (RFC 6979) is used if
- * MBEDTLS_ECDSA_DETERMINISTIC is defined.
+ * \warning It is not thread-safe to use the same context in
+ * multiple threads.
*
- * \param ctx ECDSA context
- * \param md_alg Algorithm that was used to hash the message
- * \param hash Message hash
- * \param hlen Length of hash
- * \param sig Buffer that will hold the signature
- * \param slen Length of the signature written
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \note The deterministic version is used if
+ * #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more
+ * information, see <em>RFC-6979: Deterministic Usage
+ * of the Digital Signature Algorithm (DSA) and Elliptic
+ * Curve Digital Signature Algorithm (ECDSA)</em>.
*
- * \note The "sig" buffer must be at least as large as twice the
- * size of the curve used, plus 9 (eg. 73 bytes if a 256-bit
- * curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe.
+ * \param ctx The ECDSA context.
+ * \param md_alg The message digest that was used to hash the message.
+ * \param hash The message hash.
+ * \param hlen The length of the hash.
+ * \param sig The buffer that holds the signature.
+ * \param slen The length of the signature written.
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG parameter.
+ *
+ * \note The \p sig buffer must be at least twice as large as the
+ * size of the curve used, plus 9. For example, 73 Bytes if
+ * a 256-bit curve is used. A buffer length of
+ * #MBEDTLS_ECDSA_MAX_LEN is always safe.
*
* \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as
- * prescribed by SEC1 4.1.3 step 5.
+ * defined in <em>Standards for Efficient Cryptography Group
+ * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ * 4.1.3, step 5.
*
- * \return 0 if successful,
- * or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or
- * MBEDTLS_ERR_ASN1_XXX error code
+ * \return \c 0 on success,
+ * or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
+ * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
+ *
+ * \see ecp.h
*/
int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hlen,
@@ -171,31 +209,43 @@
#define MBEDTLS_DEPRECATED
#endif
/**
- * \brief Compute ECDSA signature and write it to buffer,
- * serialized as defined in RFC 4492 page 20.
- * Deterministic version, RFC 6979.
- * (Not thread-safe to use same context in multiple threads)
+ * \brief This function computes an ECDSA signature and writes it to a buffer,
+ * serialized as defined in <em>RFC-4492: Elliptic Curve Cryptography
+ * (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
+ *
+ * The deterministic version is defined in <em>RFC-6979:
+ * Deterministic Usage of the Digital Signature Algorithm (DSA) and
+ * Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
+ *
+ * \warning It is not thread-safe to use the same context in
+ * multiple threads.
+
*
* \deprecated Superseded by mbedtls_ecdsa_write_signature() in 2.0.0
*
- * \param ctx ECDSA context
- * \param hash Message hash
- * \param hlen Length of hash
- * \param sig Buffer that will hold the signature
- * \param slen Length of the signature written
- * \param md_alg MD algorithm used to hash the message
+ * \param ctx The ECDSA context.
+ * \param hash The Message hash.
+ * \param hlen The length of the hash.
+ * \param sig The buffer that holds the signature.
+ * \param slen The length of the signature written.
+ * \param md_alg The MD algorithm used to hash the message.
*
- * \note The "sig" buffer must be at least as large as twice the
- * size of the curve used, plus 9 (eg. 73 bytes if a 256-bit
- * curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe.
+ * \note The \p sig buffer must be at least twice as large as the
+ * size of the curve used, plus 9. For example, 73 Bytes if a
+ * 256-bit curve is used. A buffer length of
+ * #MBEDTLS_ECDSA_MAX_LEN is always safe.
*
* \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as
- * prescribed by SEC1 4.1.3 step 5.
+ * defined in <em>Standards for Efficient Cryptography Group
+ * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ * 4.1.3, step 5.
*
- * \return 0 if successful,
- * or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or
- * MBEDTLS_ERR_ASN1_XXX error code
+ * \return \c 0 on success,
+ * or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
+ * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
+ *
+ * \see ecp.h
*/
int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
const unsigned char *hash, size_t hlen,
@@ -206,63 +256,74 @@
#endif /* MBEDTLS_ECDSA_DETERMINISTIC */
/**
- * \brief Read and verify an ECDSA signature
+ * \brief This function reads and verifies an ECDSA signature.
*
- * \param ctx ECDSA context
- * \param hash Message hash
- * \param hlen Size of hash
- * \param sig Signature to read and verify
- * \param slen Size of sig
+ * \param ctx The ECDSA context.
+ * \param hash The message hash.
+ * \param hlen The size of the hash.
+ * \param sig The signature to read and verify.
+ * \param slen The size of \p sig.
*
* \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as
- * prescribed by SEC1 4.1.4 step 3.
+ * defined in <em>Standards for Efficient Cryptography Group
+ * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ * 4.1.4, step 3.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
- * MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is
- * valid but its actual length is less than siglen,
- * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX error code
+ * \return \c 0 on success,
+ * #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
+ * #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is
+ * valid but its actual length is less than \p siglen,
+ * or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
+ * error code on failure for any other reason.
+ *
+ * \see ecp.h
*/
int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
const unsigned char *hash, size_t hlen,
const unsigned char *sig, size_t slen );
/**
- * \brief Generate an ECDSA keypair on the given curve
+ * \brief This function generates an ECDSA keypair on the given curve.
*
- * \param ctx ECDSA context in which the keypair should be stored
- * \param gid Group (elliptic curve) to use. One of the various
- * MBEDTLS_ECP_DP_XXX macros depending on configuration.
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \param ctx The ECDSA context to store the keypair in.
+ * \param gid The elliptic curve to use. One of the various
+ * \c MBEDTLS_ECP_DP_XXX macros depending on configuration.
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG parameter.
*
- * \return 0 on success, or a MBEDTLS_ERR_ECP_XXX code.
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on
+ * failure.
+ *
+ * \see ecp.h
*/
int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
/**
- * \brief Set an ECDSA context from an EC key pair
+ * \brief This function sets an ECDSA context from an EC key pair.
*
- * \param ctx ECDSA context to set
- * \param key EC key to use
+ * \param ctx The ECDSA context to set.
+ * \param key The EC key to use.
*
- * \return 0 on success, or a MBEDTLS_ERR_ECP_XXX code.
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on
+ * failure.
+ *
+ * \see ecp.h
*/
int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key );
/**
- * \brief Initialize context
+ * \brief This function initializes an ECDSA context.
*
- * \param ctx Context to initialize
+ * \param ctx The ECDSA context to initialize.
*/
void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
/**
- * \brief Free context
+ * \brief This function frees an ECDSA context.
*
- * \param ctx Context to free
+ * \param ctx The ECDSA context to free.
*/
void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );
diff --git a/include/mbedtls/gcm.h b/include/mbedtls/gcm.h
index c7f01c3..1e5a507 100644
--- a/include/mbedtls/gcm.h
+++ b/include/mbedtls/gcm.h
@@ -1,10 +1,16 @@
/**
* \file gcm.h
*
- * \brief Galois/Counter mode for 128-bit block ciphers
+ * \brief Galois/Counter Mode (GCM) for 128-bit block ciphers, as defined
+ * in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
+ * (GCM), Natl. Inst. Stand. Technol.</em>
+ *
+ * For more information on GCM, see <em>NIST SP 800-38D: Recommendation for
+ * Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</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 +25,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_GCM_H
#define MBEDTLS_GCM_H
@@ -42,39 +49,49 @@
#endif
/**
- * \brief GCM context structure
+ * \brief The GCM context structure.
*/
typedef struct {
- mbedtls_cipher_context_t cipher_ctx;/*!< cipher context used */
- uint64_t HL[16]; /*!< Precalculated HTable */
- uint64_t HH[16]; /*!< Precalculated HTable */
- uint64_t len; /*!< Total data length */
- uint64_t add_len; /*!< Total add length */
- unsigned char base_ectr[16];/*!< First ECTR for tag */
- unsigned char y[16]; /*!< Y working value */
- unsigned char buf[16]; /*!< buf working value */
- int mode; /*!< Encrypt or Decrypt */
+ mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */
+ uint64_t HL[16]; /*!< Precalculated HTable low. */
+ uint64_t HH[16]; /*!< Precalculated HTable high. */
+ uint64_t len; /*!< The total length of the encrypted data. */
+ uint64_t add_len; /*!< The total length of the additional data. */
+ unsigned char base_ectr[16]; /*!< The first ECTR for tag. */
+ unsigned char y[16]; /*!< The Y working value. */
+ unsigned char buf[16]; /*!< The buf working value. */
+ int mode; /*!< The operation to perform:
+ #MBEDTLS_GCM_ENCRYPT or
+ #MBEDTLS_GCM_DECRYPT. */
}
mbedtls_gcm_context;
/**
- * \brief Initialize GCM context (just makes references valid)
- * Makes the context ready for mbedtls_gcm_setkey() or
- * mbedtls_gcm_free().
+ * \brief This function initializes the specified GCM context,
+ * to make references valid, and prepares the context
+ * for mbedtls_gcm_setkey() or mbedtls_gcm_free().
*
- * \param ctx GCM context to initialize
+ * The function does not bind the GCM context to a particular
+ * cipher, nor set the key. For this purpose, use
+ * mbedtls_gcm_setkey().
+ *
+ * \param ctx The GCM context to initialize.
*/
void mbedtls_gcm_init( mbedtls_gcm_context *ctx );
/**
- * \brief GCM initialization (encryption)
+ * \brief This function associates a GCM context with a
+ * cipher algorithm and a key.
*
- * \param ctx GCM context to be initialized
- * \param cipher cipher to use (a 128-bit block cipher)
- * \param key encryption key
- * \param keybits must be 128, 192 or 256
+ * \param ctx The GCM context to initialize.
+ * \param cipher The 128-bit block cipher to use.
+ * \param key The encryption key.
+ * \param keybits The key size in bits. Valid options are:
+ * <ul><li>128 bits</li>
+ * <li>192 bits</li>
+ * <li>256 bits</li></ul>
*
- * \return 0 if successful, or a cipher specific error code
+ * \return \c 0 on success, or a cipher specific error code.
*/
int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
mbedtls_cipher_id_t cipher,
@@ -82,26 +99,27 @@
unsigned int keybits );
/**
- * \brief GCM buffer encryption/decryption using a block cipher
+ * \brief This function performs GCM encryption or decryption of a buffer.
*
- * \note On encryption, the output buffer can be the same as the input buffer.
- * On decryption, the output buffer cannot be the same as input buffer.
- * If buffers overlap, the output buffer must trail at least 8 bytes
+ * \note For encryption, the output buffer can be the same as the input buffer.
+ * For decryption, the output buffer cannot be the same as input buffer.
+ * If the buffers overlap, the output buffer must trail at least 8 Bytes
* behind the input buffer.
*
- * \param ctx GCM context
- * \param mode MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT
- * \param length length of the input data
- * \param iv initialization vector
- * \param iv_len length of IV
- * \param add additional data
- * \param add_len length of additional data
- * \param input buffer holding the input data
- * \param output buffer for holding the output data
- * \param tag_len length of the tag to generate
- * \param tag buffer for holding the tag
+ * \param ctx The GCM context to use for encryption or decryption.
+ * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or
+ * #MBEDTLS_GCM_DECRYPT.
+ * \param length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
+ * \param iv The initialization vector.
+ * \param iv_len The length of the IV.
+ * \param add The buffer holding the additional data.
+ * \param add_len The length of the additional data.
+ * \param input The buffer holding the input data.
+ * \param output The buffer for holding the output data.
+ * \param tag_len The length of the tag to generate.
+ * \param tag The buffer for holding the tag.
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
int mode,
@@ -116,25 +134,26 @@
unsigned char *tag );
/**
- * \brief GCM buffer authenticated decryption using a block cipher
+ * \brief This function performs a GCM authenticated decryption of a
+ * buffer.
*
- * \note On decryption, the output buffer cannot be the same as input buffer.
- * If buffers overlap, the output buffer must trail at least 8 bytes
+ * \note For decryption, the output buffer cannot be the same as input buffer.
+ * If the buffers overlap, the output buffer must trail at least 8 Bytes
* behind the input buffer.
*
- * \param ctx GCM context
- * \param length length of the input data
- * \param iv initialization vector
- * \param iv_len length of IV
- * \param add additional data
- * \param add_len length of additional data
- * \param tag buffer holding the tag
- * \param tag_len length of the tag
- * \param input buffer holding the input data
- * \param output buffer for holding the output data
+ * \param ctx The GCM context.
+ * \param length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
+ * \param iv The initialization vector.
+ * \param iv_len The length of the IV.
+ * \param add The buffer holding the additional data.
+ * \param add_len The length of the additional data.
+ * \param tag The buffer holding the tag.
+ * \param tag_len The length of the tag.
+ * \param input The buffer holding the input data.
+ * \param output The buffer for holding the output data.
*
- * \return 0 if successful and authenticated,
- * MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match
+ * \return 0 if successful and authenticated, or
+ * #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match.
*/
int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
size_t length,
@@ -148,16 +167,18 @@
unsigned char *output );
/**
- * \brief Generic GCM stream start function
+ * \brief This function starts a GCM encryption or decryption
+ * operation.
*
- * \param ctx GCM context
- * \param mode MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT
- * \param iv initialization vector
- * \param iv_len length of IV
- * \param add additional data (or NULL if length is 0)
- * \param add_len length of additional data
+ * \param ctx The GCM context.
+ * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or
+ * #MBEDTLS_GCM_DECRYPT.
+ * \param iv The initialization vector.
+ * \param iv_len The length of the IV.
+ * \param add The buffer holding the additional data, or NULL if \p add_len is 0.
+ * \param add_len The length of the additional data. If 0, \p add is NULL.
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
int mode,
@@ -167,21 +188,23 @@
size_t add_len );
/**
- * \brief Generic GCM update function. Encrypts/decrypts using the
- * given GCM context. Expects input to be a multiple of 16
- * bytes! Only the last call before mbedtls_gcm_finish() can be less
- * than 16 bytes!
+ * \brief This function feeds an input buffer into an ongoing GCM
+ * encryption or decryption operation.
*
- * \note On decryption, the output buffer cannot be the same as input buffer.
- * If buffers overlap, the output buffer must trail at least 8 bytes
+ * ` The function expects input to be a multiple of 16
+ * Bytes. Only the last call before calling
+ * mbedtls_gcm_finish() can be less than 16 Bytes.
+ *
+ * \note For decryption, the output buffer cannot be the same as input buffer.
+ * If the buffers overlap, the output buffer must trail at least 8 Bytes
* behind the input buffer.
*
- * \param ctx GCM context
- * \param length length of the input data
- * \param input buffer holding the input data
- * \param output buffer for holding the output data
+ * \param ctx The GCM context.
+ * \param length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
+ * \param input The buffer holding the input data.
+ * \param output The buffer for holding the output data.
*
- * \return 0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT
+ * \return \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
*/
int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
size_t length,
@@ -189,24 +212,27 @@
unsigned char *output );
/**
- * \brief Generic GCM finalisation function. Wraps up the GCM stream
- * and generates the tag. The tag can have a maximum length of
- * 16 bytes.
+ * \brief This function finishes the GCM operation and generates
+ * the authentication tag.
*
- * \param ctx GCM context
- * \param tag buffer for holding the tag
- * \param tag_len length of the tag to generate (must be at least 4)
+ * It wraps up the GCM stream, and generates the
+ * tag. The tag can have a maximum length of 16 Bytes.
*
- * \return 0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT
+ * \param ctx The GCM context.
+ * \param tag The buffer for holding the tag.
+ * \param tag_len The length of the tag to generate. Must be at least four.
+ *
+ * \return \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
*/
int mbedtls_gcm_finish( mbedtls_gcm_context *ctx,
unsigned char *tag,
size_t tag_len );
/**
- * \brief Free a GCM context and underlying cipher sub-context
+ * \brief This function clears a GCM context and the underlying
+ * cipher sub-context.
*
- * \param ctx GCM context to free
+ * \param ctx The GCM context to clear.
*/
void mbedtls_gcm_free( mbedtls_gcm_context *ctx );
@@ -223,9 +249,9 @@
#endif
/**
- * \brief Checkup routine
+ * \brief The GCM checkup routine.
*
- * \return 0 if successful, or 1 if the test failed
+ * \return \c 0 on success, or \c 1 on failure.
*/
int mbedtls_gcm_self_test( int verbose );
diff --git a/include/mbedtls/md.h b/include/mbedtls/md.h
index 57c27a6..5e0376c 100644
--- a/include/mbedtls/md.h
+++ b/include/mbedtls/md.h
@@ -1,12 +1,12 @@
-/**
+ /**
* \file md.h
*
- * \brief Generic message digest wrapper
+ * \brief The generic message-digest wrapper.
*
* \author Adriaan de Jong <dejong@fox-it.com>
*/
/*
- * 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
@@ -21,8 +21,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_MD_H
#define MBEDTLS_MD_H
@@ -64,65 +65,79 @@
#endif
/**
- * Opaque struct defined in md_internal.h
+ * Opaque struct defined in md_internal.h.
*/
typedef struct mbedtls_md_info_t mbedtls_md_info_t;
/**
- * Generic message digest context.
+ * The generic message-digest context.
*/
typedef struct {
- /** Information about the associated message digest */
+ /** Information about the associated message digest. */
const mbedtls_md_info_t *md_info;
- /** Digest-specific context */
+ /** The digest-specific context. */
void *md_ctx;
- /** HMAC part of the context */
+ /** The HMAC part of the context. */
void *hmac_ctx;
} mbedtls_md_context_t;
/**
- * \brief Returns the list of digests supported by the generic digest module.
+ * \brief This function returns the list of digests supported by the
+ * generic digest module.
*
- * \return a statically allocated array of digests, the last entry
- * is 0.
+ * \return A statically allocated array of digests. Each element
+ * in the returned list is an integer belonging to the
+ * message-digest enumeration #mbedtls_md_type_t.
+ * The last entry is 0.
*/
const int *mbedtls_md_list( void );
/**
- * \brief Returns the message digest information associated with the
- * given digest name.
+ * \brief This function returns the message-digest information
+ * associated with the given digest name.
*
- * \param md_name Name of the digest to search for.
+ * \param md_name The name of the digest to search for.
*
- * \return The message digest information associated with md_name or
- * NULL if not found.
+ * \return The message-digest information associated with \p md_name,
+ * or NULL if not found.
*/
const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name );
/**
- * \brief Returns the message digest information associated with the
- * given digest type.
+ * \brief This function returns the message-digest information
+ * associated with the given digest type.
*
- * \param md_type type of digest to search for.
+ * \param md_type The type of digest to search for.
*
- * \return The message digest information associated with md_type or
- * NULL if not found.
+ * \return The message-digest information associated with \p md_type,
+ * or NULL if not found.
*/
const mbedtls_md_info_t *mbedtls_md_info_from_type( mbedtls_md_type_t md_type );
/**
- * \brief Initialize a md_context (as NONE)
- * This should always be called first.
- * Prepares the context for mbedtls_md_setup() or mbedtls_md_free().
+ * \brief This function initializes a message-digest context without
+ * binding it to a particular message-digest algorithm.
+ *
+ * This function should always be called first. It prepares the
+ * context for mbedtls_md_setup() for binding it to a
+ * message-digest algorithm.
*/
void mbedtls_md_init( mbedtls_md_context_t *ctx );
/**
- * \brief Free and clear the internal structures of ctx.
- * Can be called at any time after mbedtls_md_init().
- * Mandatory once mbedtls_md_setup() has been called.
+ * \brief This function clears the internal structure of \p ctx and
+ * frees any embedded internal structure, but does not free
+ * \p ctx itself.
+ *
+ * If you have called mbedtls_md_setup() on \p ctx, you must
+ * call mbedtls_md_free() when you are no longer using the
+ * context.
+ * Calling this function if you have previously
+ * called mbedtls_md_init() and nothing else is optional.
+ * You must not call this function if you have not called
+ * mbedtls_md_init().
*/
void mbedtls_md_free( mbedtls_md_context_t *ctx );
@@ -133,220 +148,288 @@
#define MBEDTLS_DEPRECATED
#endif
/**
- * \brief Select MD to use and allocate internal structures.
- * Should be called after mbedtls_md_init() or mbedtls_md_free().
+ * \brief This function selects the message digest algorithm to use,
+ * and allocates internal structures.
+ *
+ * It should be called after mbedtls_md_init() or mbedtls_md_free().
* Makes it necessary to call mbedtls_md_free() later.
*
* \deprecated Superseded by mbedtls_md_setup() in 2.0.0
*
- * \param ctx Context to set up.
- * \param md_info Message digest to use.
+ * \param ctx The context to set up.
+ * \param md_info The information structure of the message-digest algorithm
+ * to use.
*
* \returns \c 0 on success,
- * \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure,
- * \c MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure.
+ * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure,
+ * #MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure.
*/
int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED;
#undef MBEDTLS_DEPRECATED
#endif /* MBEDTLS_DEPRECATED_REMOVED */
/**
- * \brief Select MD to use and allocate internal structures.
- * Should be called after mbedtls_md_init() or mbedtls_md_free().
- * Makes it necessary to call mbedtls_md_free() later.
+ * \brief This function selects the message digest algorithm to use,
+ * and allocates internal structures.
*
- * \param ctx Context to set up.
- * \param md_info Message digest to use.
- * \param hmac 0 to save some memory if HMAC will not be used,
- * non-zero is HMAC is going to be used with this context.
+ * It should be called after mbedtls_md_init() or
+ * mbedtls_md_free(). Makes it necessary to call
+ * mbedtls_md_free() later.
+ *
+ * \param ctx The context to set up.
+ * \param md_info The information structure of the message-digest algorithm
+ * to use.
+ * \param hmac <ul><li>0: HMAC is not used. Saves some memory.</li>
+ * <li>non-zero: HMAC is used with this context.</li></ul>
*
* \returns \c 0 on success,
- * \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure,
- * \c MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure.
+ * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, or
+ * #MBEDTLS_ERR_MD_ALLOC_FAILED on memory allocation failure.
*/
int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac );
/**
- * \brief Clone the state of an MD context
+ * \brief This function clones the state of an message-digest
+ * context.
*
- * \note The two contexts must have been setup to the same type
- * (cloning from SHA-256 to SHA-512 make no sense).
+ * \note You must call mbedtls_md_setup() on \c dst before calling
+ * this function.
*
- * \warning Only clones the MD state, not the HMAC state! (for now)
+ * \note The two contexts must have the same type,
+ * for example, both are SHA-256.
*
- * \param dst The destination context
- * \param src The context to be cloned
+ * \warning This function clones the message-digest state, not the
+ * HMAC state.
+ *
+ * \param dst The destination context.
+ * \param src The context to be cloned.
*
* \return \c 0 on success,
- * \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure.
+ * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure.
*/
int mbedtls_md_clone( mbedtls_md_context_t *dst,
const mbedtls_md_context_t *src );
/**
- * \brief Returns the size of the message digest output.
+ * \brief This function extracts the message-digest size from the
+ * message-digest information structure.
*
- * \param md_info message digest info
+ * \param md_info The information structure of the message-digest algorithm
+ * to use.
*
- * \return size of the message digest output in bytes.
+ * \return The size of the message-digest output in Bytes.
*/
unsigned char mbedtls_md_get_size( const mbedtls_md_info_t *md_info );
/**
- * \brief Returns the type of the message digest output.
+ * \brief This function extracts the message-digest type from the
+ * message-digest information structure.
*
- * \param md_info message digest info
+ * \param md_info The information structure of the message-digest algorithm
+ * to use.
*
- * \return type of the message digest output.
+ * \return The type of the message digest.
*/
mbedtls_md_type_t mbedtls_md_get_type( const mbedtls_md_info_t *md_info );
/**
- * \brief Returns the name of the message digest output.
+ * \brief This function extracts the message-digest name from the
+ * message-digest information structure.
*
- * \param md_info message digest info
+ * \param md_info The information structure of the message-digest algorithm
+ * to use.
*
- * \return name of the message digest output.
+ * \return The name of the message digest.
*/
const char *mbedtls_md_get_name( const mbedtls_md_info_t *md_info );
/**
- * \brief Prepare the context to digest a new message.
- * Generally called after mbedtls_md_setup() or mbedtls_md_finish().
- * Followed by mbedtls_md_update().
+ * \brief This function starts a message-digest computation.
*
- * \param ctx generic message digest context.
+ * You must call this function after setting up the context
+ * with mbedtls_md_setup(), and before passing data with
+ * mbedtls_md_update().
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * \param ctx The generic message-digest context.
+ *
+ * \returns \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ * parameter verification fails.
*/
int mbedtls_md_starts( mbedtls_md_context_t *ctx );
/**
- * \brief Generic message digest process buffer
- * Called between mbedtls_md_starts() and mbedtls_md_finish().
- * May be called repeatedly.
+ * \brief This function feeds an input buffer into an ongoing
+ * message-digest computation.
*
- * \param ctx Generic message digest context
- * \param input buffer holding the datal
- * \param ilen length of the input data
+ * You must call mbedtls_md_starts() before calling this
+ * function. You may call this function multiple times.
+ * Afterwards, call mbedtls_md_finish().
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * \param ctx The generic message-digest context.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ *
+ * \returns \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ * parameter verification fails.
*/
int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen );
/**
- * \brief Generic message digest final digest
- * Called after mbedtls_md_update().
- * Usually followed by mbedtls_md_free() or mbedtls_md_starts().
+ * \brief This function finishes the digest operation,
+ * and writes the result to the output buffer.
*
- * \param ctx Generic message digest context
- * \param output Generic message digest checksum result
+ * Call this function after a call to mbedtls_md_starts(),
+ * followed by any number of calls to mbedtls_md_update().
+ * Afterwards, you may either clear the context with
+ * mbedtls_md_free(), or call mbedtls_md_starts() to reuse
+ * the context for another digest operation with the same
+ * algorithm.
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * \param ctx The generic message-digest context.
+ * \param output The buffer for the generic message-digest checksum result.
+ *
+ * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ * parameter verification fails.
*/
int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output );
/**
- * \brief Output = message_digest( input buffer )
+ * \brief This function calculates the message-digest of a buffer,
+ * with respect to a configurable message-digest algorithm
+ * in a single call.
*
- * \param md_info message digest info
- * \param input buffer holding the data
- * \param ilen length of the input data
- * \param output Generic message digest checksum result
+ * The result is calculated as
+ * Output = message_digest(input buffer).
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * \param md_info The information structure of the message-digest algorithm
+ * to use.
+ * \param input The buffer holding the data.
+ * \param ilen The length of the input data.
+ * \param output The generic message-digest checksum result.
+ *
+ * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ * parameter verification fails.
*/
int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
unsigned char *output );
#if defined(MBEDTLS_FS_IO)
/**
- * \brief Output = message_digest( file contents )
+ * \brief This function calculates the message-digest checksum
+ * result of the contents of the provided file.
*
- * \param md_info message digest info
- * \param path input file name
- * \param output generic message digest checksum result
+ * The result is calculated as
+ * Output = message_digest(file contents).
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed,
- * MBEDTLS_ERR_MD_BAD_INPUT_DATA if md_info was NULL.
+ * \param md_info The information structure of the message-digest algorithm
+ * to use.
+ * \param path The input file name.
+ * \param output The generic message-digest checksum result.
+ *
+ * \return \c 0 on success,
+ * #MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed, or
+ * #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.
*/
int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path,
unsigned char *output );
#endif /* MBEDTLS_FS_IO */
/**
- * \brief Set HMAC key and prepare to authenticate a new message.
- * Usually called after mbedtls_md_setup() or mbedtls_md_hmac_finish().
+ * \brief This function sets the HMAC key and prepares to
+ * authenticate a new message.
*
- * \param ctx HMAC context
- * \param key HMAC secret key
- * \param keylen length of the HMAC key in bytes
+ * Call this function after mbedtls_md_setup(), to use
+ * the MD context for an HMAC calculation, then call
+ * mbedtls_md_hmac_update() to provide the input data, and
+ * mbedtls_md_hmac_finish() to get the HMAC value.
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * \param ctx The message digest context containing an embedded HMAC
+ * context.
+ * \param key The HMAC secret key.
+ * \param keylen The length of the HMAC key in Bytes.
+ *
+ * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ * parameter verification fails.
*/
int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key,
size_t keylen );
/**
- * \brief Generic HMAC process buffer.
- * Called between mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset()
- * and mbedtls_md_hmac_finish().
- * May be called repeatedly.
+ * \brief This function feeds an input buffer into an ongoing HMAC
+ * computation.
*
- * \param ctx HMAC context
- * \param input buffer holding the data
- * \param ilen length of the input data
+ * Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset()
+ * before calling this function.
+ * You may call this function multiple times to pass the
+ * input piecewise.
+ * Afterwards, call mbedtls_md_hmac_finish().
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * \param ctx The message digest context containing an embedded HMAC
+ * context.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ *
+ * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ * parameter verification fails.
*/
int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input,
size_t ilen );
/**
- * \brief Output HMAC.
- * Called after mbedtls_md_hmac_update().
- * Usually followed by mbedtls_md_hmac_reset(),
- * mbedtls_md_hmac_starts(), or mbedtls_md_free().
+ * \brief This function finishes the HMAC operation, and writes
+ * the result to the output buffer.
*
- * \param ctx HMAC context
- * \param output Generic HMAC checksum result
+ * Call this function after mbedtls_md_hmac_starts() and
+ * mbedtls_md_hmac_update() to get the HMAC value. Afterwards
+ * you may either call mbedtls_md_free() to clear the context,
+ * or call mbedtls_md_hmac_reset() to reuse the context with
+ * the same HMAC key.
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * \param ctx The message digest context containing an embedded HMAC
+ * context.
+ * \param output The generic HMAC checksum result.
+ *
+ * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ * parameter verification fails.
*/
int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output);
/**
- * \brief Prepare to authenticate a new message with the same key.
- * Called after mbedtls_md_hmac_finish() and before
- * mbedtls_md_hmac_update().
+ * \brief This function prepares to authenticate a new message with
+ * the same key as the previous HMAC operation.
*
- * \param ctx HMAC context to be reset
+ * You may call this function after mbedtls_md_hmac_finish().
+ * Afterwards call mbedtls_md_hmac_update() to pass the new
+ * input.
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * \param ctx The message digest context containing an embedded HMAC
+ * context.
+ *
+ * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ * parameter verification fails.
*/
int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx );
/**
- * \brief Output = Generic_HMAC( hmac key, input buffer )
+ * \brief This function calculates the full generic HMAC
+ * on the input buffer with the provided key.
*
- * \param md_info message digest info
- * \param key HMAC secret key
- * \param keylen length of the HMAC key in bytes
- * \param input buffer holding the data
- * \param ilen length of the input data
- * \param output Generic HMAC-result
+ * The function allocates the context, performs the
+ * calculation, and frees the context.
*
- * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- * verification fails.
+ * The HMAC result is calculated as
+ * output = generic HMAC(hmac key, input buffer).
+ *
+ * \param md_info The information structure of the message-digest algorithm
+ * to use.
+ * \param key The HMAC secret key.
+ * \param keylen The length of the HMAC secret key in Bytes.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ * \param output The generic HMAC result.
+ *
+ * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ * parameter verification fails.
*/
int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen,
const unsigned char *input, size_t ilen,
diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h
index e051751..ed10775 100644
--- a/include/mbedtls/platform.h
+++ b/include/mbedtls/platform.h
@@ -1,10 +1,10 @@
/**
* \file platform.h
*
- * \brief mbed TLS Platform abstraction layer
+ * \brief The Mbed TLS platform abstraction layer.
*/
/*
- * Copyright (C) 2006-2016, 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,7 +19,7 @@
* 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_PLATFORM_H
#define MBEDTLS_PLATFORM_H
@@ -52,34 +52,34 @@
#include <time.h>
#if !defined(MBEDTLS_PLATFORM_STD_SNPRINTF)
#if defined(_WIN32)
-#define MBEDTLS_PLATFORM_STD_SNPRINTF mbedtls_platform_win32_snprintf /**< Default snprintf to use */
+#define MBEDTLS_PLATFORM_STD_SNPRINTF mbedtls_platform_win32_snprintf /**< The default \c snprintf function to use. */
#else
-#define MBEDTLS_PLATFORM_STD_SNPRINTF snprintf /**< Default snprintf to use */
+#define MBEDTLS_PLATFORM_STD_SNPRINTF snprintf /**< The default \c snprintf function to use. */
#endif
#endif
#if !defined(MBEDTLS_PLATFORM_STD_PRINTF)
-#define MBEDTLS_PLATFORM_STD_PRINTF printf /**< Default printf to use */
+#define MBEDTLS_PLATFORM_STD_PRINTF printf /**< The default \c printf function to use. */
#endif
#if !defined(MBEDTLS_PLATFORM_STD_FPRINTF)
-#define MBEDTLS_PLATFORM_STD_FPRINTF fprintf /**< Default fprintf to use */
+#define MBEDTLS_PLATFORM_STD_FPRINTF fprintf /**< The default \c fprintf function to use. */
#endif
#if !defined(MBEDTLS_PLATFORM_STD_CALLOC)
-#define MBEDTLS_PLATFORM_STD_CALLOC calloc /**< Default allocator to use */
+#define MBEDTLS_PLATFORM_STD_CALLOC calloc /**< The default \c calloc function to use. */
#endif
#if !defined(MBEDTLS_PLATFORM_STD_FREE)
-#define MBEDTLS_PLATFORM_STD_FREE free /**< Default free to use */
+#define MBEDTLS_PLATFORM_STD_FREE free /**< The default \c free function to use. */
#endif
#if !defined(MBEDTLS_PLATFORM_STD_EXIT)
-#define MBEDTLS_PLATFORM_STD_EXIT exit /**< Default exit to use */
+#define MBEDTLS_PLATFORM_STD_EXIT exit /**< The default \c exit function to use. */
#endif
#if !defined(MBEDTLS_PLATFORM_STD_TIME)
-#define MBEDTLS_PLATFORM_STD_TIME time /**< Default time to use */
+#define MBEDTLS_PLATFORM_STD_TIME time /**< The default \c time function to use. */
#endif
#if !defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS)
-#define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS EXIT_SUCCESS /**< Default exit value to use */
+#define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS EXIT_SUCCESS /**< The default exit value to use. */
#endif
#if !defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE)
-#define MBEDTLS_PLATFORM_STD_EXIT_FAILURE EXIT_FAILURE /**< Default exit value to use */
+#define MBEDTLS_PLATFORM_STD_EXIT_FAILURE EXIT_FAILURE /**< The default exit value to use. */
#endif
#if defined(MBEDTLS_FS_IO)
#if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_READ)
@@ -116,12 +116,12 @@
extern void (*mbedtls_free)( void *ptr );
/**
- * \brief Set your own memory implementation function pointers
+ * \brief This function allows configuring custom memory-management functions.
*
- * \param calloc_func the calloc function implementation
- * \param free_func the free function implementation
+ * \param calloc_func The \c calloc function implementation.
+ * \param free_func The \c free function implementation.
*
- * \return 0 if successful
+ * \return \c 0.
*/
int mbedtls_platform_set_calloc_free( void * (*calloc_func)( size_t, size_t ),
void (*free_func)( void * ) );
@@ -140,11 +140,11 @@
extern int (*mbedtls_fprintf)( FILE *stream, const char *format, ... );
/**
- * \brief Set your own fprintf function pointer
+ * \brief This function allows configuring a custom \p fprintf function pointer.
*
- * \param fprintf_func the fprintf function implementation
+ * \param fprintf_func The \c fprintf function implementation.
*
- * \return 0
+ * \return \c 0.
*/
int mbedtls_platform_set_fprintf( int (*fprintf_func)( FILE *stream, const char *,
... ) );
@@ -163,11 +163,12 @@
extern int (*mbedtls_printf)( const char *format, ... );
/**
- * \brief Set your own printf function pointer
+ * \brief This function allows configuring a custom \c printf function
+ * pointer.
*
- * \param printf_func the printf function implementation
+ * \param printf_func The \c printf function implementation.
*
- * \return 0
+ * \return \c 0 on success.
*/
int mbedtls_platform_set_printf( int (*printf_func)( const char *, ... ) );
#else /* !MBEDTLS_PLATFORM_PRINTF_ALT */
@@ -196,11 +197,12 @@
extern int (*mbedtls_snprintf)( char * s, size_t n, const char * format, ... );
/**
- * \brief Set your own snprintf function pointer
+ * \brief This function allows configuring a custom \c snprintf function
+ * pointer.
*
- * \param snprintf_func the snprintf function implementation
+ * \param snprintf_func The \c snprintf function implementation.
*
- * \return 0
+ * \return \c 0 on success.
*/
int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n,
const char * format, ... ) );
@@ -219,11 +221,12 @@
extern void (*mbedtls_exit)( int status );
/**
- * \brief Set your own exit function pointer
+ * \brief This function allows configuring a custom \c exit function
+ * pointer.
*
- * \param exit_func the exit function implementation
+ * \param exit_func The \c exit function implementation.
*
- * \return 0
+ * \return \c 0 on success.
*/
int mbedtls_platform_set_exit( void (*exit_func)( int status ) );
#else
@@ -266,12 +269,13 @@
extern int (*mbedtls_nv_seed_write)( unsigned char *buf, size_t buf_len );
/**
- * \brief Set your own seed file writing/reading functions
+ * \brief This function allows configuring custom seed file writing and
+ * reading functions.
*
- * \param nv_seed_read_func the seed reading function implementation
- * \param nv_seed_write_func the seed writing function implementation
+ * \param nv_seed_read_func The seed reading function implementation.
+ * \param nv_seed_write_func The seed writing function implementation.
*
- * \return 0
+ * \return \c 0 on success.
*/
int mbedtls_platform_set_nv_seed(
int (*nv_seed_read_func)( unsigned char *buf, size_t buf_len ),
@@ -292,13 +296,13 @@
#if !defined(MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT)
/**
- * \brief Platform context structure
+ * \brief The platform context structure.
*
* \note This structure may be used to assist platform-specific
- * setup/teardown operations.
+ * setup or teardown operations.
*/
typedef struct {
- char dummy; /**< Placeholder member as empty structs are not portable */
+ char dummy; /**< Placeholder member, as empty structs are not portable. */
}
mbedtls_platform_context;
@@ -307,32 +311,32 @@
#endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */
/**
- * \brief Perform any platform initialisation operations
+ * \brief This function performs any platform initialization operations.
*
- * \param ctx mbed TLS context
+ * \param ctx The Mbed TLS context.
*
- * \return 0 if successful
+ * \return \c 0 on success.
*
- * \note This function is intended to allow platform specific initialisation,
+ * \note This function is intended to allow platform-specific initialization,
* and should be called before any other library functions. Its
- * implementation is platform specific, and by default, unless platform
- * specific code is provided, it does nothing.
+ * implementation is platform-specific, and unless
+ * platform-specific code is provided, it does nothing.
*
- * Its use and whether its necessary to be called is dependent on the
+ * Its use and whether it is necessary to call it is dependent on the
* platform.
*/
int mbedtls_platform_setup( mbedtls_platform_context *ctx );
/**
- * \brief Perform any platform teardown operations
+ * \brief This function performs any platform teardown operations.
*
- * \param ctx mbed TLS context
+ * \param ctx The Mbed TLS context.
*
- * \note This function should be called after every other mbed TLS module has
- * been correctly freed using the appropriate free function.
- * Its implementation is platform specific, and by default, unless
- * platform specific code is provided, it does nothing.
+ * \note This function should be called after every other Mbed TLS module
+ * has been correctly freed using the appropriate free function.
+ * Its implementation is platform-specific, and unless
+ * platform-specific code is provided, it does nothing.
*
- * Its use and whether its necessary to be called is dependent on the
+ * Its use and whether it is necessary to call it is dependent on the
* platform.
*/
void mbedtls_platform_teardown( mbedtls_platform_context *ctx );
diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h
index 7521058..fb2f77f 100644
--- a/include/mbedtls/rsa.h
+++ b/include/mbedtls/rsa.h
@@ -1,10 +1,15 @@
/**
* \file rsa.h
*
- * \brief The RSA public-key cryptosystem
+ * \brief The RSA public-key cryptosystem.
+ *
+ * For more information, see <em>Public-Key Cryptography Standards (PKCS)
+ * #1 v1.5: RSA Encryption</em> and <em>Public-Key Cryptography Standards
+ * (PKCS) #1 v2.1: RSA Cryptography Specifications</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,7 +24,7 @@
* 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_RSA_H
#define MBEDTLS_RSA_H
@@ -43,26 +48,26 @@
#define MBEDTLS_ERR_RSA_BAD_INPUT_DATA -0x4080 /**< Bad input parameters to function. */
#define MBEDTLS_ERR_RSA_INVALID_PADDING -0x4100 /**< Input data contains invalid padding and is rejected. */
#define MBEDTLS_ERR_RSA_KEY_GEN_FAILED -0x4180 /**< Something failed during generation of a key. */
-#define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED -0x4200 /**< Key failed to pass the library's validity check. */
+#define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED -0x4200 /**< Key failed to pass the validity check of the library. */
#define MBEDTLS_ERR_RSA_PUBLIC_FAILED -0x4280 /**< The public key operation failed. */
#define MBEDTLS_ERR_RSA_PRIVATE_FAILED -0x4300 /**< The private key operation failed. */
#define MBEDTLS_ERR_RSA_VERIFY_FAILED -0x4380 /**< The PKCS#1 verification failed. */
#define MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE -0x4400 /**< The output buffer for decryption is not large enough. */
#define MBEDTLS_ERR_RSA_RNG_FAILED -0x4480 /**< The random generator failed to generate non-zeros. */
-#define MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION -0x4500 /**< The implementation doesn't offer the requested operation, e.g. because of security violations or lack of functionality */
+#define MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION -0x4500 /**< The implementation does not offer the requested operation, for example, because of security violations or lack of functionality. */
#define MBEDTLS_ERR_RSA_HW_ACCEL_FAILED -0x4580 /**< RSA hardware accelerator failed. */
/*
* RSA constants
*/
-#define MBEDTLS_RSA_PUBLIC 0
-#define MBEDTLS_RSA_PRIVATE 1
+#define MBEDTLS_RSA_PUBLIC 0 /**< Request private key operation. */
+#define MBEDTLS_RSA_PRIVATE 1 /**< Request public key operation. */
-#define MBEDTLS_RSA_PKCS_V15 0
-#define MBEDTLS_RSA_PKCS_V21 1
+#define MBEDTLS_RSA_PKCS_V15 0 /**< Use PKCS-1 v1.5 encoding. */
+#define MBEDTLS_RSA_PKCS_V21 1 /**< Use PKCS-1 v2.1 encoding. */
-#define MBEDTLS_RSA_SIGN 1
-#define MBEDTLS_RSA_CRYPT 2
+#define MBEDTLS_RSA_SIGN 1 /**< Identifier for RSA signature operations. */
+#define MBEDTLS_RSA_CRYPT 2 /**< Identifier for RSA encryption and decryption operations. */
#define MBEDTLS_RSA_SALT_LEN_ANY -1
@@ -80,103 +85,106 @@
#endif
/**
- * \brief RSA context structure
+ * \brief The RSA context structure.
*
* \note Direct manipulation of the members of this structure
- * is deprecated and will no longer be supported starting
- * from the next major release. All manipulation should instead
- * be done through the public interface functions.
- *
+ * is deprecated. All manipulation should instead be done through
+ * the public interface functions.
*/
typedef struct
{
- int ver; /*!< always 0 */
- size_t len; /*!< size(N) in chars */
+ int ver; /*!< Always 0.*/
+ size_t len; /*!< The size of \p N in Bytes. */
- mbedtls_mpi N; /*!< public modulus */
- mbedtls_mpi E; /*!< public exponent */
+ mbedtls_mpi N; /*!< The public modulus. */
+ mbedtls_mpi E; /*!< The public exponent. */
- mbedtls_mpi D; /*!< private exponent */
- mbedtls_mpi P; /*!< 1st prime factor */
- mbedtls_mpi Q; /*!< 2nd prime factor */
+ mbedtls_mpi D; /*!< The private exponent. */
+ mbedtls_mpi P; /*!< The first prime factor. */
+ mbedtls_mpi Q; /*!< The second prime factor. */
- mbedtls_mpi DP; /*!< D % (P - 1) */
- mbedtls_mpi DQ; /*!< D % (Q - 1) */
+ mbedtls_mpi DP; /*!< \p D % (P - 1) */
+ mbedtls_mpi DQ; /*!< \p D % (Q - 1) */
mbedtls_mpi QP; /*!< 1 / (Q % P) */
- mbedtls_mpi RN; /*!< cached R^2 mod N */
+ mbedtls_mpi RN; /*!< cached R^2 mod \p N */
- mbedtls_mpi RP; /*!< cached R^2 mod P */
- mbedtls_mpi RQ; /*!< cached R^2 mod Q */
+ mbedtls_mpi RP; /*!< cached R^2 mod \p P */
+ mbedtls_mpi RQ; /*!< cached R^2 mod \p Q */
- mbedtls_mpi Vi; /*!< cached blinding value */
- mbedtls_mpi Vf; /*!< cached un-blinding value */
+ mbedtls_mpi Vi; /*!< The cached blinding value. */
+ mbedtls_mpi Vf; /*!< The cached un-blinding value. */
- int padding; /*!< \c MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
- \c MBEDTLS_RSA_PKCS_v21 for OAEP/PSS */
- int hash_id; /*!< Hash identifier of mbedtls_md_type_t as
- specified in the mbedtls_md.h header file
- for the EME-OAEP and EMSA-PSS
- encoding */
+ int padding; /*!< Selects padding mode:
+ #MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
+ #MBEDTLS_RSA_PKCS_V21 for OAEP or PSS. */
+ int hash_id; /*!< Hash identifier of mbedtls_md_type_t type,
+ as specified in md.h for use in the MGF
+ mask generating function used in the
+ EME-OAEP and EMSA-PSS encodings. */
#if defined(MBEDTLS_THREADING_C)
- mbedtls_threading_mutex_t mutex; /*!< Thread-safety mutex */
+ mbedtls_threading_mutex_t mutex; /*!< Thread-safety mutex. */
#endif
}
mbedtls_rsa_context;
/**
- * \brief Initialize an RSA context
+ * \brief This function initializes an RSA context.
*
- * Note: Set padding to \c MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP
+ * \note Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP
* encryption scheme and the RSASSA-PSS signature scheme.
*
- * \param ctx RSA context to be initialized
- * \param padding \c MBEDTLS_RSA_PKCS_V15 or \c MBEDTLS_RSA_PKCS_V21
- * \param hash_id \c MBEDTLS_RSA_PKCS_V21 hash identifier
+ * \param ctx The RSA context to initialize.
+ * \param padding Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
+ * #MBEDTLS_RSA_PKCS_V21.
+ * \param hash_id The hash identifier of #mbedtls_md_type_t type, if
+ * \p padding is #MBEDTLS_RSA_PKCS_V21.
*
- * \note The hash_id parameter is actually ignored
- * when using \c MBEDTLS_RSA_PKCS_V15 padding.
+ * \note The \p hash_id parameter is ignored when using
+ * #MBEDTLS_RSA_PKCS_V15 padding.
*
- * \note Choice of padding mode is strictly enforced for private key
+ * \note The choice of padding mode is strictly enforced for private key
* operations, since there might be security concerns in
- * mixing padding modes. For public key operations it's merely
+ * mixing padding modes. For public key operations it is
* a default value, which can be overriden by calling specific
- * rsa_rsaes_xxx or rsa_rsassa_xxx functions.
+ * \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions.
*
- * \note The chosen hash is always used for OEAP encryption.
- * For PSS signatures, it's always used for making signatures,
- * but can be overriden (and always is, if set to
- * \c MBEDTLS_MD_NONE) for verifying them.
+ * \note The hash selected in \p hash_id is always used for OEAP
+ * encryption. For PSS signatures, it is always used for
+ * making signatures, but can be overriden for verifying them.
+ * If set to #MBEDTLS_MD_NONE, it is always overriden.
*/
void mbedtls_rsa_init( mbedtls_rsa_context *ctx,
int padding,
int hash_id);
/**
- * \brief Import a set of core parameters into an RSA context
+ * \brief This function imports a set of core parameters into an
+ * RSA context.
*
- * \param ctx Initialized RSA context to store parameters
- * \param N RSA modulus, or NULL
- * \param P First prime factor of N, or NULL
- * \param Q Second prime factor of N, or NULL
- * \param D Private exponent, or NULL
- * \param E Public exponent, or NULL
+ * \param ctx The initialized RSA context to store the parameters in.
+ * \param N The RSA modulus, or NULL.
+ * \param P The first prime factor of \p N, or NULL.
+ * \param Q The second prime factor of \p N, or NULL.
+ * \param D The private exponent, or NULL.
+ * \param E The public exponent, or NULL.
*
* \note This function can be called multiple times for successive
- * imports if the parameters are not simultaneously present.
+ * imports, if the parameters are not simultaneously present.
+ *
* Any sequence of calls to this function should be followed
- * by a call to \c mbedtls_rsa_complete which will check
- * and complete the provided information to a ready-for-use
+ * by a call to mbedtls_rsa_complete(), which checks and
+ * completes the provided information to a ready-for-use
* public or private RSA key.
*
- * \note See the documentation of \c mbedtls_rsa_complete for more
- * information on which parameters are necessary to setup
- * a private or public RSA key.
+ * \note See mbedtls_rsa_complete() for more information on which
+ * parameters are necessary to set up a private or public
+ * RSA key.
*
* \note The imported parameters are copied and need not be preserved
* for the lifetime of the RSA context being set up.
*
- * \return 0 if successful, non-zero error code on failure.
+ * \return \c 0 on success, or a non-zero error code on failure.
*/
int mbedtls_rsa_import( mbedtls_rsa_context *ctx,
const mbedtls_mpi *N,
@@ -184,36 +192,37 @@
const mbedtls_mpi *D, const mbedtls_mpi *E );
/**
- * \brief Import core RSA parameters in raw big-endian
- * binary format into an RSA context
+ * \brief This function imports core RSA parameters, in raw big-endian
+ * binary format, into an RSA context.
*
- * \param ctx Initialized RSA context to store parameters
- * \param N RSA modulus, or NULL
- * \param N_len Byte length of N, ignored if N == NULL
- * \param P First prime factor of N, or NULL
- * \param P_len Byte length of P, ignored if P == NULL
- * \param Q Second prime factor of N, or NULL
- * \param Q_len Byte length of Q, ignored if Q == NULL
- * \param D Private exponent, or NULL
- * \param D_len Byte length of D, ignored if D == NULL
- * \param E Public exponent, or NULL
- * \param E_len Byte length of E, ignored if E == NULL
+ * \param ctx The initialized RSA context to store the parameters in.
+ * \param N The RSA modulus, or NULL.
+ * \param N_len The Byte length of \p N, ignored if \p N == NULL.
+ * \param P The first prime factor of \p N, or NULL.
+ * \param P_len The Byte length of \p P, ignored if \p P == NULL.
+ * \param Q The second prime factor of \p N, or NULL.
+ * \param Q_len The Byte length of \p Q, ignored if \p Q == NULL.
+ * \param D The private exponent, or NULL.
+ * \param D_len The Byte length of \p D, ignored if \p D == NULL.
+ * \param E The public exponent, or NULL.
+ * \param E_len The Byte length of \p E, ignored if \p E == NULL.
*
* \note This function can be called multiple times for successive
- * imports if the parameters are not simultaneously present.
+ * imports, if the parameters are not simultaneously present.
+ *
* Any sequence of calls to this function should be followed
- * by a call to \c mbedtls_rsa_complete which will check
- * and complete the provided information to a ready-for-use
+ * by a call to mbedtls_rsa_complete(), which checks and
+ * completes the provided information to a ready-for-use
* public or private RSA key.
*
- * \note See the documentation of \c mbedtls_rsa_complete for more
- * information on which parameters are necessary to setup
- * a private or public RSA key.
+ * \note See mbedtls_rsa_complete() for more information on which
+ * parameters are necessary to set up a private or public
+ * RSA key.
*
* \note The imported parameters are copied and need not be preserved
* for the lifetime of the RSA context being set up.
*
- * \return 0 if successful, non-zero error code on failure.
+ * \return \c 0 on success, or a non-zero error code on failure.
*/
int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx,
unsigned char const *N, size_t N_len,
@@ -223,71 +232,71 @@
unsigned char const *E, size_t E_len );
/**
- * \brief Attempt to complete an RSA context from
+ * \brief This function completes an RSA context from
* a set of imported core parameters.
*
- * \param ctx Initialized RSA context to store parameters
+ * To setup an RSA public key, precisely \p N and \p E
+ * must have been imported.
*
- * \note
- * - To setup an RSA public key, precisely N and E
- * must have been imported.
+ * To setup an RSA private key, sufficient information must
+ * be present for the other parameters to be derivable.
*
- * - To setup an RSA private key, enough information must be
- * present for the other parameters to be derivable.
+ * The default implementation supports the following:
+ * <ul><li>Derive \p P, \p Q from \p N, \p D, \p E.</li>
+ * <li>Derive \p N, \p D from \p P, \p Q, \p E.</li></ul>
+ * Alternative implementations need not support these.
*
- * The default implementation supports the following:
- * - Derive P, Q from N, D, E
- * - Derive N, D from P, Q, E.
+ * If this function runs successfully, it guarantees that
+ * the RSA context can be used for RSA operations without
+ * the risk of failure or crash.
*
- * - Alternative implementations need not support these
- * and may return \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA instead.
+ * \param ctx The initialized RSA context holding imported parameters.
*
- * \return
- * - 0 if successful. In this case, it is guaranteed
- * that the RSA context can be used for RSA operations
- * without the risk of failure or crash.
- * - \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted
- * derivations failed.
+ * \return \c 0 on success, or #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the
+ * attempted derivations failed.
*
* \warning This function need not perform consistency checks
- * for the imported parameters! In particular, parameters that
- * are not needed by the implementation may be silently discarded
- * and left unchecked. For the purpose of checking the consistency
- * of the key material, see \c mbedtls_rsa_check_privkey.
+ * for the imported parameters. In particular, parameters that
+ * are not needed by the implementation might be silently
+ * discarded and left unchecked. To check the consistency
+ * of the key material, see mbedtls_rsa_check_privkey().
*
*/
int mbedtls_rsa_complete( mbedtls_rsa_context *ctx );
/**
- * \brief Export core parameters of an RSA key
+ * \brief This function exports the core parameters of an RSA key.
*
- * \param ctx Initialized RSA context
- * \param N MPI to hold the RSA modulus, or NULL
- * \param P MPI to hold the first prime factor of N, or NULL
- * \param Q MPI to hold the second prime factor of N, or NULL
- * \param D MPI to hold the private exponent, or NULL
- * \param E MPI to hold the public exponent, or NULL
+ * If this function runs successfully, the non-NULL buffers
+ * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully
+ * written, with additional unused space filled leading by
+ * zero Bytes.
*
- * \return
- * - 0 if successful. In this case, the non-NULL buffers
- * pointed to by N, P, Q, D, E are fully written, with
- * additional unused space filled leading by 0-bytes.
- * - Non-zero return code otherwise. In particular, if
- * exporting the requested parameters
- * cannot be done because of a lack of functionality
- * or because of security policies, the error code
- * \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION is returned.
- * In this case, the RSA context stays intact and can
- * be continued to be used.
+ * Possible reasons for returning
+ * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul>
+ * <li>An alternative RSA implementation is in use, which
+ * stores the key externally, and either cannot or should
+ * not export it into RAM.</li>
+ * <li>A SW or HW implementation might not support a certain
+ * deduction. For example, \p P, \p Q from \p N, \p D,
+ * and \p E if the former are not part of the
+ * implementation.</li></ul>
*
- * \note Reasons for returning \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION
- * would be the following: Firstly, it might be that an
- * alternative RSA implementation is in use which stores
- * the key externally, and which either cannot or should not
- * export it into RAM. Alternatively, an implementation
- * (regardless of SW or HW) might not support deducing e.g.
- * P, Q from N, D, E if the former are not part of the
- * implementation.
+ * If the function fails due to an unsupported operation,
+ * the RSA context stays intact and remains usable.
+ *
+ * \param ctx The initialized RSA context.
+ * \param N The MPI to hold the RSA modulus, or NULL.
+ * \param P The MPI to hold the first prime factor of \p N, or NULL.
+ * \param Q The MPI to hold the second prime factor of \p N, or NULL.
+ * \param D The MPI to hold the private exponent, or NULL.
+ * \param E The MPI to hold the public exponent, or NULL.
+ *
+ * \return \c 0 on success,
+ * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
+ * requested parameters cannot be done due to missing
+ * functionality or because of security policies,
+ * or a non-zero return code on any other failure.
*
*/
int mbedtls_rsa_export( const mbedtls_rsa_context *ctx,
@@ -295,46 +304,48 @@
mbedtls_mpi *D, mbedtls_mpi *E );
/**
- * \brief Export core parameters of an RSA key
- * in raw big-endian binary format
+ * \brief This function exports core parameters of an RSA key
+ * in raw big-endian binary format.
*
- * \param ctx Initialized RSA context
- * \param N Byte array to store the RSA modulus, or NULL
- * \param N_len Size of buffer for modulus
- * \param P Byte array to hold the first prime factor of N, or NULL
- * \param P_len Size of buffer for first prime factor
- * \param Q Byte array to hold the second prime factor of N, or NULL
- * \param Q_len Size of buffer for second prime factor
- * \param D Byte array to hold the private exponent, or NULL
- * \param D_len Size of buffer for private exponent
- * \param E Byte array to hold the public exponent, or NULL
- * \param E_len Size of buffer for public exponent
+ * If this function runs successfully, the non-NULL buffers
+ * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully
+ * written, with additional unused space filled leading by
+ * zero Bytes.
+ *
+ * Possible reasons for returning
+ * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul>
+ * <li>An alternative RSA implementation is in use, which
+ * stores the key externally, and either cannot or should
+ * not export it into RAM.</li>
+ * <li>A SW or HW implementation might not support a certain
+ * deduction. For example, \p P, \p Q from \p N, \p D,
+ * and \p E if the former are not part of the
+ * implementation.</li></ul>
+ * If the function fails due to an unsupported operation,
+ * the RSA context stays intact and remains usable.
+ *
+ * \param ctx The initialized RSA context.
+ * \param N The Byte array to store the RSA modulus, or NULL.
+ * \param N_len The size of the buffer for the modulus.
+ * \param P The Byte array to hold the first prime factor of \p N, or
+ * NULL.
+ * \param P_len The size of the buffer for the first prime factor.
+ * \param Q The Byte array to hold the second prime factor of \p N, or
+ NULL.
+ * \param Q_len The size of the buffer for the second prime factor.
+ * \param D The Byte array to hold the private exponent, or NULL.
+ * \param D_len The size of the buffer for the private exponent.
+ * \param E The Byte array to hold the public exponent, or NULL.
+ * \param E_len The size of the buffer for the public exponent.
*
* \note The length fields are ignored if the corresponding
* buffer pointers are NULL.
*
- * \return
- * - 0 if successful. In this case, the non-NULL buffers
- * pointed to by N, P, Q, D, E are fully written, with
- * additional unused space filled leading by 0-bytes.
- * - Non-zero return code otherwise. In particular, if
- * exporting the requested parameters
- * cannot be done because of a lack of functionality
- * or because of security policies, the error code
- * \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION is returned.
- * In this case, the RSA context stays intact and can
- * be continued to be used.
- *
- * \note Reasons for returning \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION
- * would be the following: Firstly, it might be that an
- * alternative RSA implementation is in use which stores
- * the key externally, and which either cannot or should not
- * export it into RAM. Alternatively, an implementation
- * (regardless of SW or HW) might not support deducing e.g.
- * P, Q from N, D, E if the former are not part of the
- * implementation.
- *
- *
+ * \return \c 0 on success,
+ * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
+ * requested parameters cannot be done due to missing
+ * functionality or because of security policies,
+ * or a non-zero return code on any other failure.
*/
int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx,
unsigned char *N, size_t N_len,
@@ -344,57 +355,59 @@
unsigned char *E, size_t E_len );
/**
- * \brief Export CRT parameters of a private RSA key
+ * \brief This function exports CRT parameters of a private RSA key.
*
- * \param ctx Initialized RSA context
- * \param DP MPI to hold D modulo P-1, or NULL
- * \param DQ MPI to hold D modulo Q-1, or NULL
- * \param QP MPI to hold modular inverse of Q modulo P, or NULL
+ * \param ctx The initialized RSA context.
+ * \param DP The MPI to hold D modulo P-1, or NULL.
+ * \param DQ The MPI to hold D modulo Q-1, or NULL.
+ * \param QP The MPI to hold modular inverse of Q modulo P, or NULL.
*
- * \return 0 if successful, non-zero error code otherwise.
+ * \return \c 0 on success, non-zero error code otherwise.
*
* \note Alternative RSA implementations not using CRT-parameters
- * internally can implement this function using based on
- * \c mbedtls_rsa_deduce_opt.
+ * internally can implement this function based on
+ * mbedtls_rsa_deduce_opt().
*
*/
int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx,
mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP );
/**
- * \brief Set padding for an already initialized RSA context
- * See \c mbedtls_rsa_init() for details.
+ * \brief This function sets padding for an already initialized RSA
+ * context. See mbedtls_rsa_init() for details.
*
- * \param ctx RSA context to be set
- * \param padding \c MBEDTLS_RSA_PKCS_V15 or \c MBEDTLS_RSA_PKCS_V21
- * \param hash_id \c MBEDTLS_RSA_PKCS_V21 hash identifier
+ * \param ctx The RSA context to be set.
+ * \param padding Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
+ * #MBEDTLS_RSA_PKCS_V21.
+ * \param hash_id The #MBEDTLS_RSA_PKCS_V21 hash identifier.
*/
void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding,
int hash_id);
/**
- * \brief Get length of RSA modulus in bytes
+ * \brief This function retrieves the length of RSA modulus in Bytes.
*
- * \param ctx Initialized RSA context
+ * \param ctx The initialized RSA context.
*
- * \return Length of RSA modulus, in bytes.
+ * \return The length of the RSA modulus in Bytes.
*
*/
size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx );
/**
- * \brief Generate an RSA keypair
+ * \brief This function generates an RSA keypair.
*
- * \param ctx RSA context that will hold the key
- * \param f_rng RNG function
- * \param p_rng RNG parameter
- * \param nbits size of the public key in bits
- * \param exponent public exponent (e.g., 65537)
+ * \param ctx The RSA context used to hold the key.
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG parameter.
+ * \param nbits The size of the public key in bits.
+ * \param exponent The public exponent. For example, 65537.
*
- * \note mbedtls_rsa_init() must be called beforehand to setup
- * the RSA context.
+ * \note mbedtls_rsa_init() must be called before this function,
+ * to set up the RSA context.
*
- * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ on failure.
*/
int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -402,101 +415,109 @@
unsigned int nbits, int exponent );
/**
- * \brief Check if a context contains (at least) an RSA public key
+ * \brief This function checks if a context contains at least an RSA
+ * public key.
*
- * \param ctx RSA context to be checked
+ * If the function runs successfully, it is guaranteed that
+ * enough information is present to perform an RSA public key
+ * operation using mbedtls_rsa_public().
*
- * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code.
- * On success, it is guaranteed that enough information is
- * present to perform an RSA public key operation
- * \c mbedtls_rsa_public.
+ * \param ctx The RSA context to check.
+ *
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*
*/
int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
/**
- * \brief Check if a context contains an RSA private key
+ * \brief This function checks if a context contains an RSA private key
* and perform basic consistency checks.
*
- * \param ctx RSA context to be checked
+ * \param ctx The RSA context to check.
*
- * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code.
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code on
+ * failure.
*
* \note The consistency checks performed by this function not only
- * ensure that \c mbedtls_rsa_private can be called successfully
+ * ensure that mbedtls_rsa_private() can be called successfully
* on the given context, but that the various parameters are
* mutually consistent with high probability, in the sense that
- * \c mbedtls_rsa_public and \c mbedtls_rsa_private are inverses.
+ * mbedtls_rsa_public() and mbedtls_rsa_private() are inverses.
*
* \warning This function should catch accidental misconfigurations
* like swapping of parameters, but it cannot establish full
* trust in neither the quality nor the consistency of the key
* material that was used to setup the given RSA context:
- * - Regarding consistency, note (see \c mbedtls_rsa_complete)
- * that imported parameters irrelevant for the implementation
- * might be silently dropped, in which case the present
- * function doesn't have access to and hence cannot check them.
- * If you want to check the consistency of the entire
- * content of, say, an PKCS1-encoded RSA private key, you
- * should use \c mbedtls_rsa_validate_params before setting
- * up the RSA context.
- * Further, if the implementation performs empirical checks,
- * these checks will substantiate but not guarantee consistency.
- * - Regarding quality, this function is not expected to perform
- * extended quality assessments like checking that the prime
- * factors are safe. Further, it is the user's responsibility to
- * ensure trustworthiness of the source of his RSA parameters,
- * a question going beyond what's effectively checkable
- * by the library.
- *
+ * <ul><li>Consistency: Imported parameters that are irrelevant
+ * for the implementation might be silently dropped. If dropped,
+ * the current function does not have access to them,
+ * and therefore cannot check them. See mbedtls_rsa_complete().
+ * If you want to check the consistency of the entire
+ * content of an PKCS1-encoded RSA private key, for example, you
+ * should use mbedtls_rsa_validate_params() before setting
+ * up the RSA context.
+ * Additionally, if the implementation performs empirical checks,
+ * these checks substantiate but do not guarantee consistency.</li>
+ * <li>Quality: This function is not expected to perform
+ * extended quality assessments like checking that the prime
+ * factors are safe. Additionally, it is the responsibility of the
+ * user to ensure the trustworthiness of the source of his RSA
+ * parameters, which goes beyond what is effectively checkable
+ * by the library.</li></ul>
*/
int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx );
/**
- * \brief Check a public-private RSA key pair.
- * Check each of the contexts, and make sure they match.
+ * \brief This function checks a public-private RSA key pair.
*
- * \param pub RSA context holding the public key
- * \param prv RSA context holding the private key
+ * It checks each of the contexts, and makes sure they match.
*
- * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \param pub The RSA context holding the public key.
+ * \param prv The RSA context holding the private key.
+ *
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*/
int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub,
const mbedtls_rsa_context *prv );
/**
- * \brief Do an RSA public key operation
+ * \brief This function performs an RSA public key operation.
*
- * \param ctx RSA context
- * \param input input buffer
- * \param output output buffer
+ * \param ctx The RSA context.
+ * \param input The input buffer.
+ * \param output The output buffer.
*
- * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*
- * \note This function does NOT take care of message
- * padding. Also, be sure to set input[0] = 0 or ensure that
- * input is smaller than N.
+ * \note This function does not handle message padding.
+ *
+ * \note Make sure to set \p input[0] = 0 or ensure that
+ * input is smaller than \p N.
*
* \note The input and output buffers must be large
- * enough (eg. 128 bytes if RSA-1024 is used).
+ * enough. For example, 128 Bytes if RSA-1024 is used.
*/
int mbedtls_rsa_public( mbedtls_rsa_context *ctx,
const unsigned char *input,
unsigned char *output );
/**
- * \brief Do an RSA private key operation
+ * \brief This function performs an RSA private key operation.
*
- * \param ctx RSA context
- * \param f_rng RNG function (Needed for blinding)
- * \param p_rng RNG parameter
- * \param input input buffer
- * \param output output buffer
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Needed for blinding.
+ * \param p_rng The RNG parameter.
+ * \param input The input buffer.
+ * \param output The output buffer.
*
- * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*
* \note The input and output buffers must be large
- * enough (eg. 128 bytes if RSA-1024 is used).
+ * enough. For example, 128 Bytes if RSA-1024 is used.
*/
int mbedtls_rsa_private( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -505,32 +526,36 @@
unsigned char *output );
/**
- * \brief Generic wrapper to perform a PKCS#1 encryption using the
- * mode from the context. Add the message padding, then do an
- * RSA operation.
+ * \brief This function adds the message padding, then performs an RSA
+ * operation.
*
- * \param ctx RSA context
- * \param f_rng RNG function (Needed for padding and PKCS#1 v2.1 encoding
- * and \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param ilen contains the plaintext length
- * \param input buffer holding the data to be encrypted
- * \param output buffer that will hold the ciphertext
+ * It is the generic wrapper for performing a PKCS#1 encryption
+ * operation using the \p mode from the context.
+ *
+ *
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Needed for padding, PKCS#1 v2.1
+ * encoding, and #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG parameter.
+ * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ilen The length of the plaintext.
+ * \param input The buffer holding the data to encrypt.
+ * \param output The buffer used to hold the ciphertext.
*
* \deprecated It is deprecated and discouraged to call this function
- * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- * are likely to remove the mode argument and have it implicitly
- * set to MBEDTLS_RSA_PUBLIC.
+ * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ * are likely to remove the \p mode argument and have it
+ * implicitly set to #MBEDTLS_RSA_PUBLIC.
*
* \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PRIVATE and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*
- * \note The output buffer must be as large as the size
- * of ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note The input and output buffers must be as large as the size
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*/
int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -540,29 +565,32 @@
unsigned char *output );
/**
- * \brief Perform a PKCS#1 v1.5 encryption (RSAES-PKCS1-v1_5-ENCRYPT)
+ * \brief This function performs a PKCS#1 v1.5 encryption operation
+ * (RSAES-PKCS1-v1_5-ENCRYPT).
*
- * \param ctx RSA context
- * \param f_rng RNG function (Needed for padding and \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param ilen contains the plaintext length
- * \param input buffer holding the data to be encrypted
- * \param output buffer that will hold the ciphertext
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Needed for padding and
+ * #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG parameter.
+ * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ilen The length of the plaintext.
+ * \param input The buffer holding the data to encrypt.
+ * \param output The buffer used to hold the ciphertext.
*
* \deprecated It is deprecated and discouraged to call this function
- * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- * are likely to remove the mode argument and have it implicitly
- * set to MBEDTLS_RSA_PUBLIC.
+ * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ * are likely to remove the \p mode argument and have it
+ * implicitly set to #MBEDTLS_RSA_PUBLIC.
*
* \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PRIVATE and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*
* \note The output buffer must be as large as the size
- * of ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*/
int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -572,32 +600,34 @@
unsigned char *output );
/**
- * \brief Perform a PKCS#1 v2.1 OAEP encryption (RSAES-OAEP-ENCRYPT)
+ * \brief This function performs a PKCS#1 v2.1 OAEP encryption
+ * operation (RSAES-OAEP-ENCRYPT).
*
- * \param ctx RSA context
- * \param f_rng RNG function (Needed for padding and PKCS#1 v2.1 encoding
- * and \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param label buffer holding the custom label to use
- * \param label_len contains the label length
- * \param ilen contains the plaintext length
- * \param input buffer holding the data to be encrypted
- * \param output buffer that will hold the ciphertext
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Needed for padding and PKCS#1 v2.1
+ * encoding and #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG parameter.
+ * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param label The buffer holding the custom label to use.
+ * \param label_len The length of the label.
+ * \param ilen The length of the plaintext.
+ * \param input The buffer holding the data to encrypt.
+ * \param output The buffer used to hold the ciphertext.
*
* \deprecated It is deprecated and discouraged to call this function
- * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- * are likely to remove the mode argument and have it implicitly
- * set to MBEDTLS_RSA_PUBLIC.
+ * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ * are likely to remove the \p mode argument and have it
+ * implicitly set to #MBEDTLS_RSA_PUBLIC.
*
* \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PRIVATE and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*
* \note The output buffer must be as large as the size
- * of ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * of ctx->N. For example, 128 Bytes if RSA-1024 is used.
*/
int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -609,39 +639,42 @@
unsigned char *output );
/**
- * \brief Generic wrapper to perform a PKCS#1 decryption using the
- * mode from the context. Do an RSA operation, then remove
- * the message padding
+ * \brief This function performs an RSA operation, then removes the
+ * message padding.
*
- * \param ctx RSA context
- * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param olen will contain the plaintext length
- * \param input buffer holding the encrypted data
- * \param output buffer that will hold the plaintext
- * \param output_max_len maximum length of the output buffer
+ * It is the generic wrapper for performing a PKCS#1 decryption
+ * operation using the \p mode from the context.
+ *
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG parameter.
+ * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param olen The length of the plaintext.
+ * \param input The buffer holding the encrypted data.
+ * \param output The buffer used to hold the plaintext.
+ * \param output_max_len The maximum length of the output buffer.
*
* \deprecated It is deprecated and discouraged to call this function
- * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- * are likely to remove the mode argument and have it implicitly
- * set to MBEDTLS_RSA_PRIVATE.
+ * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ * are likely to remove the \p mode argument and have it
+ * implicitly set to #MBEDTLS_RSA_PRIVATE.
*
* \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PUBLIC and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*
* \note The output buffer length \c output_max_len should be
- * as large as the size \c ctx->len of \c ctx->N (eg. 128 bytes
- * if RSA-1024 is used) to be able to hold an arbitrary
- * decrypted message. If it is not large enough to hold
- * the decryption of the particular ciphertext provided,
- * the function will return \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
+ * as large as the size \p ctx->len of \p ctx->N (for example,
+ * 128 Bytes if RSA-1024 is used) to be able to hold an
+ * arbitrary decrypted message. If it is not large enough to
+ * hold the decryption of the particular ciphertext provided,
+ * the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
*
* \note The input buffer must be as large as the size
- * of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*/
int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -652,37 +685,39 @@
size_t output_max_len );
/**
- * \brief Perform a PKCS#1 v1.5 decryption (RSAES-PKCS1-v1_5-DECRYPT)
+ * \brief This function performs a PKCS#1 v1.5 decryption
+ * operation (RSAES-PKCS1-v1_5-DECRYPT).
*
- * \param ctx RSA context
- * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param olen will contain the plaintext length
- * \param input buffer holding the encrypted data
- * \param output buffer that will hold the plaintext
- * \param output_max_len maximum length of the output buffer
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG parameter.
+ * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param olen The length of the plaintext.
+ * \param input The buffer holding the encrypted data.
+ * \param output The buffer to hold the plaintext.
+ * \param output_max_len The maximum length of the output buffer.
*
* \deprecated It is deprecated and discouraged to call this function
- * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- * are likely to remove the mode argument and have it implicitly
- * set to MBEDTLS_RSA_PRIVATE.
+ * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ * are likely to remove the \p mode argument and have it
+ * implicitly set to #MBEDTLS_RSA_PRIVATE.
*
* \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PUBLIC and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*
* \note The output buffer length \c output_max_len should be
- * as large as the size \c ctx->len of \c ctx->N (eg. 128 bytes
- * if RSA-1024 is used) to be able to hold an arbitrary
- * decrypted message. If it is not large enough to hold
- * the decryption of the particular ciphertext provided,
- * the function will return \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
+ * as large as the size \p ctx->len of \p ctx->N, for example,
+ * 128 Bytes if RSA-1024 is used, to be able to hold an
+ * arbitrary decrypted message. If it is not large enough to
+ * hold the decryption of the particular ciphertext provided,
+ * the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
*
* \note The input buffer must be as large as the size
- * of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*/
int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -693,40 +728,42 @@
size_t output_max_len );
/**
- * \brief Perform a PKCS#1 v2.1 OAEP decryption (RSAES-OAEP-DECRYPT)
+ * \brief This function performs a PKCS#1 v2.1 OAEP decryption
+ * operation (RSAES-OAEP-DECRYPT).
*
- * \param ctx RSA context
- * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param label buffer holding the custom label to use
- * \param label_len contains the label length
- * \param olen will contain the plaintext length
- * \param input buffer holding the encrypted data
- * \param output buffer that will hold the plaintext
- * \param output_max_len maximum length of the output buffer
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG parameter.
+ * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param label The buffer holding the custom label to use.
+ * \param label_len The length of the label.
+ * \param olen The length of the plaintext.
+ * \param input The buffer holding the encrypted data.
+ * \param output The buffer to hold the plaintext.
+ * \param output_max_len The maximum length of the output buffer.
*
* \deprecated It is deprecated and discouraged to call this function
- * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- * are likely to remove the mode argument and have it implicitly
- * set to MBEDTLS_RSA_PRIVATE.
+ * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ * are likely to remove the \p mode argument and have it
+ * implicitly set to #MBEDTLS_RSA_PRIVATE.
*
* \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PUBLIC and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*
* \note The output buffer length \c output_max_len should be
- * as large as the size \c ctx->len of \c ctx->N (eg. 128 bytes
- * if RSA-1024 is used) to be able to hold an arbitrary
- * decrypted message. If it is not large enough to hold
- * the decryption of the particular ciphertext provided,
- * the function will return \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
+ * as large as the size \p ctx->len of \p ctx->N, for
+ * example, 128 Bytes if RSA-1024 is used, to be able to
+ * hold an arbitrary decrypted message. If it is not
+ * large enough to hold the decryption of the particular
+ * ciphertext provided, the function returns
+ * #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
*
* \note The input buffer must be as large as the size
- * of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
- *
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*/
int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -739,39 +776,41 @@
size_t output_max_len );
/**
- * \brief Generic wrapper to perform a PKCS#1 signature using the
- * mode from the context. Do a private RSA operation to sign
- * a message digest
+ * \brief This function performs a private RSA operation to sign
+ * a message digest using PKCS#1.
*
- * \param ctx RSA context
- * \param f_rng RNG function (Needed for PKCS#1 v2.1 encoding and for
- * \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for
- * signing raw data)
- * \param hashlen message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash buffer holding the message digest
- * \param sig buffer that will hold the ciphertext
+ * It is the generic wrapper for performing a PKCS#1
+ * signature using the \p mode from the context.
+ *
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for
+ * #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG parameter.
+ * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg The message-digest algorithm used to hash the original data.
+ * Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash The buffer holding the message digest.
+ * \param sig The buffer to hold the ciphertext.
*
* \deprecated It is deprecated and discouraged to call this function
- * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- * are likely to remove the mode argument and have it implicitly
- * set to MBEDTLS_RSA_PRIVATE.
+ * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ * are likely to remove the \p mode argument and have it
+ * implicitly set to #MBEDTLS_RSA_PRIVATE.
*
* \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PUBLIC and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return 0 if the signing operation was successful,
- * or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return \c 0 if the signing operation was successful,
+ * or an \c MBEDTLS_ERR_RSA_XXX error code on failure.
*
- * \note The \c sig buffer must be as large as the size
- * of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note The \p sig buffer must be as large as the size
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*
- * \note In case of PKCS#1 v2.1 encoding, see comments on
- * \c mbedtls_rsa_rsassa_pss_sign() for details on
- * \c md_alg and \c hash_id.
+ * \note For PKCS#1 v2.1 encoding, see comments on
+ * mbedtls_rsa_rsassa_pss_sign() for details on
+ * \p md_alg and \p hash_id.
*/
int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -783,32 +822,34 @@
unsigned char *sig );
/**
- * \brief Perform a PKCS#1 v1.5 signature (RSASSA-PKCS1-v1_5-SIGN)
+ * \brief This function performs a PKCS#1 v1.5 signature
+ * operation (RSASSA-PKCS1-v1_5-SIGN).
*
- * \param ctx RSA context
- * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE
- * for signing raw data)
- * \param hashlen message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash buffer holding the message digest
- * \param sig buffer that will hold the ciphertext
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG parameter.
+ * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg The message-digest algorithm used to hash the original data.
+ * Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash The buffer holding the message digest.
+ * \param sig The buffer to hold the ciphertext.
*
* \deprecated It is deprecated and discouraged to call this function
- * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- * are likely to remove the mode argument and have it implicitly
- * set to MBEDTLS_RSA_PRIVATE.
+ * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ * are likely to remove the \p mode argument and have it
+ * implicitly set to #MBEDTLS_RSA_PRIVATE.
*
* \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PUBLIC and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return 0 if the signing operation was successful,
+ * \return \c 0 if the signing operation was successful,
* or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*
- * \note The \c sig buffer must be as large as the size
- * of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note The \p sig buffer must be as large as the size
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*/
int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -820,38 +861,42 @@
unsigned char *sig );
/**
- * \brief Perform a PKCS#1 v2.1 PSS signature (RSASSA-PSS-SIGN)
+ * \brief This function performs a PKCS#1 v2.1 PSS signature
+ * operation (RSASSA-PSS-SIGN).
*
- * \param ctx RSA context
- * \param f_rng RNG function (Needed for PKCS#1 v2.1 encoding and for
- * \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE
- * for signing raw data)
- * \param hashlen message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash buffer holding the message digest
- * \param sig buffer that will hold the ciphertext
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for
+ * #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG parameter.
+ * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg The message-digest algorithm used to hash the original data.
+ * Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash The buffer holding the message digest.
+ * \param sig The buffer to hold the ciphertext.
*
* \deprecated It is deprecated and discouraged to call this function
- * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- * are likely to remove the mode argument and have it implicitly
- * set to MBEDTLS_RSA_PRIVATE.
+ * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ * are likely to remove the \p mode argument and have it
+ * implicitly set to #MBEDTLS_RSA_PRIVATE.
*
* \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PUBLIC and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return 0 if the signing operation was successful,
+ * \return \c 0 if the signing operation was successful,
* or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*
- * \note The \c sig buffer must be as large as the size
- * of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note The \p sig buffer must be as large as the size
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*
- * \note The \c hash_id in the RSA context is the one used for the
- * encoding. \c md_alg in the function call is the type of hash
- * that is encoded. According to RFC 3447 it is advised to
- * keep both hashes the same.
+ * \note The \p hash_id in the RSA context is the one used for the
+ * encoding. \p md_alg in the function call is the type of hash
+ * that is encoded. According to <em>RFC-3447: Public-Key
+ * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
+ * Specifications</em> it is advised to keep both hashes the
+ * same.
*/
int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -863,36 +908,41 @@
unsigned char *sig );
/**
- * \brief Generic wrapper to perform a PKCS#1 verification using the
- * mode from the context. Do a public RSA operation and check
- * the message digest
+ * \brief This function performs a public RSA operation and checks
+ * the message digest.
*
- * \param ctx points to an RSA public key
- * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash buffer holding the message digest
- * \param sig buffer holding the ciphertext
+ * This is the generic wrapper for performing a PKCS#1
+ * verification using the mode from the context.
+ *
+ * \param ctx The RSA public key context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG parameter.
+ * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg The message-digest algorithm used to hash the original data.
+ * Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash The buffer holding the message digest.
+ * \param sig The buffer holding the ciphertext.
*
* \deprecated It is deprecated and discouraged to call this function
- * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- * are likely to remove the mode argument and have it implicitly
- * set to MBEDTLS_RSA_PUBLIC.
+ * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ * are likely to remove the \p mode argument and have it
+ * set to #MBEDTLS_RSA_PUBLIC.
*
* \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PRIVATE and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return 0 if the verify operation was successful,
+ * \return \c 0 if the verify operation was successful,
* or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*
- * \note The \c sig buffer must be as large as the size
- * of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note The \p sig buffer must be as large as the size
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*
- * \note In case of PKCS#1 v2.1 encoding, see comments on
- * \c mbedtls_rsa_rsassa_pss_verify() about md_alg and hash_id.
+ * \note For PKCS#1 v2.1 encoding, see comments on
+ * mbedtls_rsa_rsassa_pss_verify() about \p md_alg and
+ * \p hash_id.
*/
int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -904,32 +954,34 @@
const unsigned char *sig );
/**
- * \brief Perform a PKCS#1 v1.5 verification (RSASSA-PKCS1-v1_5-VERIFY)
+ * \brief This function performs a PKCS#1 v1.5 verification
+ * operation (RSASSA-PKCS1-v1_5-VERIFY).
*
- * \param ctx points to an RSA public key
- * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE
- * for signing raw data)
- * \param hashlen message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash buffer holding the message digest
- * \param sig buffer holding the ciphertext
+ * \param ctx The RSA public key context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG parameter.
+ * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg The message-digest algorithm used to hash the original data.
+ * Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash The buffer holding the message digest.
+ * \param sig The buffer holding the ciphertext.
*
* \deprecated It is deprecated and discouraged to call this function
- * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- * are likely to remove the mode argument and have it implicitly
- * set to MBEDTLS_RSA_PUBLIC.
+ * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ * are likely to remove the \p mode argument and have it
+ * set to #MBEDTLS_RSA_PUBLIC.
*
* \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PRIVATE and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return 0 if the verify operation was successful,
+ * \return \c 0 if the verify operation was successful,
* or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*
- * \note The \c sig buffer must be as large as the size
- * of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note The \p sig buffer must be as large as the size
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*/
int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -941,38 +993,45 @@
const unsigned char *sig );
/**
- * \brief Perform a PKCS#1 v2.1 PSS verification (RSASSA-PSS-VERIFY)
- * (This is the "simple" version.)
+ * \brief This function performs a PKCS#1 v2.1 PSS verification
+ * operation (RSASSA-PSS-VERIFY).
*
- * \param ctx points to an RSA public key
- * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash buffer holding the message digest
- * \param sig buffer holding the ciphertext
+ * The hash function for the MGF mask generating function
+ * is that specified in the RSA context.
+ *
+ * \param ctx The RSA public key context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG parameter.
+ * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg The message-digest algorithm used to hash the original data.
+ * Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash The buffer holding the message digest.
+ * \param sig The buffer holding the ciphertext.
*
* \deprecated It is deprecated and discouraged to call this function
- * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- * are likely to remove the mode argument and have it implicitly
- * set to MBEDTLS_RSA_PUBLIC.
+ * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ * are likely to remove the \p mode argument and have it
+ * implicitly set to #MBEDTLS_RSA_PUBLIC.
*
* \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PRIVATE and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return 0 if the verify operation was successful,
+ * \return \c 0 if the verify operation was successful,
* or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*
- * \note The \c sig buffer must be as large as the size
- * of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note The \p sig buffer must be as large as the size
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*
- * \note The \c hash_id in the RSA context is the one used for the
- * verification. \c md_alg in the function call is the type of
- * hash that is verified. According to RFC 3447 it is advised to
- * keep both hashes the same. If \c hash_id in the RSA context is
- * unset, the \c md_alg from the function call is used.
+ * \note The \p hash_id in the RSA context is the one used for the
+ * verification. \p md_alg in the function call is the type of
+ * hash that is verified. According to <em>RFC-3447: Public-Key
+ * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
+ * Specifications</em> it is advised to keep both hashes the
+ * same. If \p hash_id in the RSA context is unset,
+ * the \p md_alg from the function call is used.
*/
int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -984,28 +1043,33 @@
const unsigned char *sig );
/**
- * \brief Perform a PKCS#1 v2.1 PSS verification (RSASSA-PSS-VERIFY)
- * (This is the version with "full" options.)
+ * \brief This function performs a PKCS#1 v2.1 PSS verification
+ * operation (RSASSA-PSS-VERIFY).
*
- * \param ctx points to an RSA public key
- * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash buffer holding the message digest
- * \param mgf1_hash_id message digest used for mask generation
- * \param expected_salt_len Length of the salt used in padding, use
- * \c MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length
- * \param sig buffer holding the ciphertext
+ * The hash function for the MGF mask generating function
+ * is that specified in \p mgf1_hash_id.
*
- * \return 0 if the verify operation was successful,
+ * \param ctx The RSA public key context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG parameter.
+ * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg The message-digest algorithm used to hash the original data.
+ * Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash The buffer holding the message digest.
+ * \param mgf1_hash_id The message digest used for mask generation.
+ * \param expected_salt_len The length of the salt used in padding. Use
+ * #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.
+ * \param sig The buffer holding the ciphertext.
+ *
+ * \return \c 0 if the verify operation was successful,
* or an \c MBEDTLS_ERR_RSA_XXX error code
+ * on failure.
*
- * \note The \c sig buffer must be as large as the size
- * of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note The \p sig buffer must be as large as the size
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*
- * \note The \c hash_id in the RSA context is ignored.
+ * \note The \p hash_id in the RSA context is ignored.
*/
int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -1019,20 +1083,20 @@
const unsigned char *sig );
/**
- * \brief Copy the components of an RSA context
+ * \brief This function copies the components of an RSA context.
*
- * \param dst Destination context
- * \param src Source context
+ * \param dst The destination context.
+ * \param src The source context.
*
- * \return 0 on success,
- * \c MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure
+ * \return \c 0 on success,
+ * #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure.
*/
int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src );
/**
- * \brief Free the components of an RSA key
+ * \brief This function frees the components of an RSA key.
*
- * \param ctx RSA Context to free
+ * \param ctx The RSA Context to free.
*/
void mbedtls_rsa_free( mbedtls_rsa_context *ctx );
@@ -1049,9 +1113,9 @@
#endif
/**
- * \brief Checkup routine
+ * \brief The RSA checkup routine.
*
- * \return 0 if successful, or 1 if the test failed
+ * \return \c 0 on success, or \c 1 on failure.
*/
int mbedtls_rsa_self_test( int verbose );
diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h
index 4d3a164..700a348 100644
--- a/include/mbedtls/sha1.h
+++ b/include/mbedtls/sha1.h
@@ -1,10 +1,10 @@
/**
* \file sha1.h
*
- * \brief SHA-1 cryptographic hash function
+ * \brief The SHA-1 cryptographic hash function.
*/
/*
- * 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,7 +19,7 @@
* 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_SHA1_H
#define MBEDTLS_SHA1_H
@@ -49,68 +49,70 @@
#endif
/**
- * \brief SHA-1 context structure
+ * \brief The SHA-1 context structure.
*/
typedef struct
{
- uint32_t total[2]; /*!< number of bytes processed */
- uint32_t state[5]; /*!< intermediate digest state */
- unsigned char buffer[64]; /*!< data block being processed */
+ uint32_t total[2]; /*!< The number of Bytes processed. */
+ uint32_t state[5]; /*!< The intermediate digest state. */
+ unsigned char buffer[64]; /*!< The data block being processed. */
}
mbedtls_sha1_context;
/**
- * \brief Initialize SHA-1 context
+ * \brief This function initializes a SHA-1 context.
*
- * \param ctx SHA-1 context to be initialized
+ * \param ctx The SHA-1 context to initialize.
*/
void mbedtls_sha1_init( mbedtls_sha1_context *ctx );
/**
- * \brief Clear SHA-1 context
+ * \brief This function clears a SHA-1 context.
*
- * \param ctx SHA-1 context to be cleared
+ * \param ctx The SHA-1 context to clear.
*/
void mbedtls_sha1_free( mbedtls_sha1_context *ctx );
/**
- * \brief Clone (the state of) a SHA-1 context
+ * \brief This function clones the state of a SHA-1 context.
*
- * \param dst The destination context
- * \param src The context to be cloned
+ * \param dst The destination context.
+ * \param src The context to clone.
*/
void mbedtls_sha1_clone( mbedtls_sha1_context *dst,
const mbedtls_sha1_context *src );
/**
- * \brief SHA-1 context setup
+ * \brief This function starts a SHA-1 checksum calculation.
*
- * \param ctx context to be initialized
+ * \param ctx The context to initialize.
*
- * \return 0 if successful
+ * \return \c 0 if successful
*/
int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx );
/**
- * \brief SHA-1 process buffer
+ * \brief This function feeds an input buffer into an ongoing SHA-1
+ * checksum calculation.
*
- * \param ctx SHA-1 context
- * \param input buffer holding the data
- * \param ilen length of the input data
+ * \param ctx The SHA-1 context.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
*
- * \return 0 if successful
+ * \return \c 0 if successful
*/
int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx,
const unsigned char *input,
size_t ilen );
/**
- * \brief SHA-1 final digest
+ * \brief This function finishes the SHA-1 operation, and writes
+ * the result to the output buffer.
*
- * \param ctx SHA-1 context
- * \param output SHA-1 checksum result
+ * \param ctx The SHA-1 context.
+ * \param output The SHA-1 checksum result.
*
- * \return 0 if successful
+ * \return \c 0 if successful
*/
int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx,
unsigned char output[20] );
@@ -119,9 +121,9 @@
* \brief SHA-1 process data block (internal use only)
*
* \param ctx SHA-1 context
- * \param data buffer holding one block of data
+ * \param data The data block being processed.
*
- * \return 0 if successful
+ * \return \c 0 if successful
*/
int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
const unsigned char data[64] );
@@ -137,7 +139,7 @@
*
* \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0
*
- * \param ctx context to be initialized
+ * \param ctx The SHA-1 context to be initialized.
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha1_starts(
mbedtls_sha1_context *ctx )
@@ -150,9 +152,9 @@
*
* \deprecated Superseded by mbedtls_sha1_update_ret() in 2.7.0
*
- * \param ctx SHA-1 context
- * \param input buffer holding the data
- * \param ilen length of the input data
+ * \param ctx The SHA-1 context.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha1_update(
mbedtls_sha1_context *ctx,
@@ -167,8 +169,8 @@
*
* \deprecated Superseded by mbedtls_sha1_finish_ret() in 2.7.0
*
- * \param ctx SHA-1 context
- * \param output SHA-1 checksum result
+ * \param ctx The SHA-1 context.
+ * \param output The SHA-1 checksum result.
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha1_finish(
mbedtls_sha1_context *ctx,
@@ -182,8 +184,8 @@
*
* \deprecated Superseded by mbedtls_internal_sha1_process() in 2.7.0
*
- * \param ctx SHA-1 context
- * \param data buffer holding one block of data
+ * \param ctx The SHA-1 context.
+ * \param data The data block being processed.
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha1_process(
mbedtls_sha1_context *ctx,
@@ -208,13 +210,19 @@
#endif
/**
- * \brief Output = SHA-1( input buffer )
+ * \brief This function calculates the SHA-1 checksum of a buffer.
*
- * \param input buffer holding the data
- * \param ilen length of the input data
- * \param output SHA-1 checksum result
+ * The function allocates the context, performs the
+ * calculation, and frees the context.
*
- * \return 0 if successful
+ * The SHA-1 result is calculated as
+ * output = SHA-1(input buffer).
+ *
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ * \param output The SHA-1 checksum result.
+ *
+ * \return \c 0 if successful
*/
int mbedtls_sha1_ret( const unsigned char *input,
size_t ilen,
@@ -231,9 +239,9 @@
*
* \deprecated Superseded by mbedtls_sha1_ret() in 2.7.0
*
- * \param input buffer holding the data
- * \param ilen length of the input data
- * \param output SHA-1 checksum result
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ * \param output The SHA-1 checksum result.
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha1( const unsigned char *input,
size_t ilen,
@@ -246,9 +254,9 @@
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
/**
- * \brief Checkup routine
+ * \brief The SHA-1 checkup routine.
*
- * \return 0 if successful, or 1 if the test failed
+ * \return \c 0 on success, or \c 1 on failure.
*/
int mbedtls_sha1_self_test( int verbose );
diff --git a/include/mbedtls/sha256.h b/include/mbedtls/sha256.h
index 5c5d07a..a2b6e11 100644
--- a/include/mbedtls/sha256.h
+++ b/include/mbedtls/sha256.h
@@ -1,10 +1,10 @@
/**
* \file sha256.h
*
- * \brief SHA-224 and SHA-256 cryptographic hash function
+ * \brief The SHA-224 and SHA-256 cryptographic hash function.
*/
/*
- * 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,7 +19,7 @@
* 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_SHA256_H
#define MBEDTLS_SHA256_H
@@ -39,7 +39,6 @@
!defined(inline) && !defined(__cplusplus)
#define inline __inline
#endif
-
#if !defined(MBEDTLS_SHA256_ALT)
// Regular implementation
//
@@ -49,81 +48,94 @@
#endif
/**
- * \brief SHA-256 context structure
+ * \brief The SHA-256 context structure.
+ *
+ * The structure is used both for SHA-256 and for SHA-224
+ * checksum calculations. The choice between these two is
+ * made in the call to mbedtls_sha256_starts_ret().
*/
typedef struct
{
- uint32_t total[2]; /*!< number of bytes processed */
- uint32_t state[8]; /*!< intermediate digest state */
- unsigned char buffer[64]; /*!< data block being processed */
- int is224; /*!< 0 => SHA-256, else SHA-224 */
+ uint32_t total[2]; /*!< The number of Bytes processed. */
+ uint32_t state[8]; /*!< The intermediate digest state. */
+ unsigned char buffer[64]; /*!< The data block being processed. */
+ int is224; /*!< Determines which function to use.
+ <ul><li>0: Use SHA-256.</li>
+ <li>1: Use SHA-224.</li></ul> */
}
mbedtls_sha256_context;
/**
- * \brief Initialize SHA-256 context
+ * \brief This function initializes a SHA-256 context.
*
- * \param ctx SHA-256 context to be initialized
+ * \param ctx The SHA-256 context to initialize.
*/
void mbedtls_sha256_init( mbedtls_sha256_context *ctx );
/**
- * \brief Clear SHA-256 context
+ * \brief This function clears a SHA-256 context.
*
- * \param ctx SHA-256 context to be cleared
+ * \param ctx The SHA-256 context to clear.
*/
void mbedtls_sha256_free( mbedtls_sha256_context *ctx );
/**
- * \brief Clone (the state of) a SHA-256 context
+ * \brief This function clones the state of a SHA-256 context.
*
- * \param dst The destination context
- * \param src The context to be cloned
+ * \param dst The destination context.
+ * \param src The context to clone.
*/
void mbedtls_sha256_clone( mbedtls_sha256_context *dst,
const mbedtls_sha256_context *src );
/**
- * \brief SHA-256 context setup
+ * \brief This function starts a SHA-224 or SHA-256 checksum
+ * calculation.
*
- * \param ctx context to be initialized
- * \param is224 0 = use SHA256, 1 = use SHA224
+ * \param ctx The context to initialize.
+ * \param is224 Determines which function to use.
+ * <ul><li>0: Use SHA-256.</li>
+ * <li>1: Use SHA-224.</li></ul>
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 );
/**
- * \brief SHA-256 process buffer
+ * \brief This function feeds an input buffer into an ongoing
+ * SHA-256 checksum calculation.
*
* \param ctx SHA-256 context
* \param input buffer holding the data
* \param ilen length of the input data
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_sha256_update_ret( mbedtls_sha256_context *ctx,
const unsigned char *input,
size_t ilen );
/**
- * \brief SHA-256 final digest
+ * \brief This function finishes the SHA-256 operation, and writes
+ * the result to the output buffer.
*
- * \param ctx SHA-256 context
- * \param output SHA-224/256 checksum result
+ * \param ctx The SHA-256 context.
+ * \param output The SHA-224 or SHA-256 checksum result.
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx,
unsigned char output[32] );
/**
- * \brief SHA-256 process data block (internal use only)
+ * \brief This function processes a single data block within
+ * the ongoing SHA-256 computation. This function is for
+ * internal use only.
*
- * \param ctx SHA-256 context
- * \param data buffer holding one block of data
+ * \param ctx The SHA-256 context.
+ * \param data The buffer holding one block of data.
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx,
const unsigned char data[64] );
@@ -135,12 +147,14 @@
#define MBEDTLS_DEPRECATED
#endif
/**
- * \brief SHA-256 context setup
+ * \brief This function starts a SHA-256 checksum calculation.
*
- * \deprecated Superseded by mbedtls_sha256_starts_ret() in 2.7.0
+ * \deprecated Superseded by mbedtls_sha256_starts_ret() in 2.7.0.
*
- * \param ctx context to be initialized
- * \param is224 0 = use SHA256, 1 = use SHA224
+ * \param ctx The SHA-256 context to initialize.
+ * \param is224 Determines which function to use.
+ * <ul><li>0: Use SHA-256.</li>
+ * <li>1: Use SHA-224.</li></ul>
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha256_starts(
mbedtls_sha256_context *ctx,
@@ -150,13 +164,14 @@
}
/**
- * \brief SHA-256 process buffer
+ * \brief This function feeds an input buffer into an ongoing
+ * SHA-256 checksum calculation.
*
- * \deprecated Superseded by mbedtls_sha256_update_ret() in 2.7.0
+ * \deprecated Superseded by mbedtls_sha256_update_ret() in 2.7.0.
*
- * \param ctx SHA-256 context
- * \param input buffer holding the data
- * \param ilen length of the input data
+ * \param ctx The SHA-256 context to initialize.
+ * \param input The buffer holding the data.
+ * \param ilen The length of the input data.
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha256_update(
mbedtls_sha256_context *ctx,
@@ -167,12 +182,13 @@
}
/**
- * \brief SHA-256 final digest
+ * \brief This function finishes the SHA-256 operation, and writes
+ * the result to the output buffer.
*
- * \deprecated Superseded by mbedtls_sha256_finish_ret() in 2.7.0
+ * \deprecated Superseded by mbedtls_sha256_finish_ret() in 2.7.0.
*
- * \param ctx SHA-256 context
- * \param output SHA-224/256 checksum result
+ * \param ctx The SHA-256 context.
+ * \param output The SHA-224or SHA-256 checksum result.
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha256_finish(
mbedtls_sha256_context *ctx,
@@ -182,12 +198,14 @@
}
/**
- * \brief SHA-256 process data block (internal use only)
+ * \brief This function processes a single data block within
+ * the ongoing SHA-256 computation. This function is for
+ * internal use only.
*
- * \deprecated Superseded by mbedtls_internal_sha256_process() in 2.7.0
+ * \deprecated Superseded by mbedtls_internal_sha256_process() in 2.7.0.
*
- * \param ctx SHA-256 context
- * \param data buffer holding one block of data
+ * \param ctx The SHA-256 context.
+ * \param data The buffer holding one block of data.
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha256_process(
mbedtls_sha256_context *ctx,
@@ -198,7 +216,6 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
-
#ifdef __cplusplus
}
#endif
@@ -212,14 +229,21 @@
#endif
/**
- * \brief Output = SHA-256( input buffer )
+ * \brief This function calculates the SHA-224 or SHA-256
+ * checksum of a buffer.
*
- * \param input buffer holding the data
- * \param ilen length of the input data
- * \param output SHA-224/256 checksum result
- * \param is224 0 = use SHA256, 1 = use SHA224
+ * The function allocates the context, performs the
+ * calculation, and frees the context.
*
- * \return 0 if successful
+ * The SHA-256 result is calculated as
+ * output = SHA-256(input buffer).
+ *
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ * \param output The SHA-224 or SHA-256 checksum result.
+ * \param is224 Determines which function to use.
+ * <ul><li>0: Use SHA-256.</li>
+ * <li>1: Use SHA-224.</li></ul>
*/
int mbedtls_sha256_ret( const unsigned char *input,
size_t ilen,
@@ -232,15 +256,25 @@
#else
#define MBEDTLS_DEPRECATED
#endif
+
/**
- * \brief Output = SHA-256( input buffer )
+ * \brief This function calculates the SHA-224 or SHA-256 checksum
+ * of a buffer.
*
- * \deprecated Superseded by mbedtls_sha256_ret() in 2.7.0
+ * The function allocates the context, performs the
+ * calculation, and frees the context.
*
- * \param input buffer holding the data
- * \param ilen length of the input data
- * \param output SHA-224/256 checksum result
- * \param is224 0 = use SHA256, 1 = use SHA224
+ * The SHA-256 result is calculated as
+ * output = SHA-256(input buffer).
+ *
+ * \deprecated Superseded by mbedtls_sha256_ret() in 2.7.0.
+ *
+ * \param input The buffer holding the data.
+ * \param ilen The length of the input data.
+ * \param output The SHA-224 or SHA-256 checksum result.
+ * \param is224 Determines which function to use.
+ * <ul><li>0: Use SHA-256.</li>
+ * <li>1: Use SHA-224.</li></ul>
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha256(
const unsigned char *input,
@@ -255,9 +289,9 @@
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
/**
- * \brief Checkup routine
+ * \brief The SHA-224 and SHA-256 checkup routine.
*
- * \return 0 if successful, or 1 if the test failed
+ * \return \c 0 on success, or \c 1 on failure.
*/
int mbedtls_sha256_self_test( int verbose );
diff --git a/include/mbedtls/sha512.h b/include/mbedtls/sha512.h
index 7453c44..52ae204 100644
--- a/include/mbedtls/sha512.h
+++ b/include/mbedtls/sha512.h
@@ -1,10 +1,10 @@
/**
* \file sha512.h
*
- * \brief SHA-384 and SHA-512 cryptographic hash function
+ * \brief The SHA-384 and SHA-512 cryptographic hash function.
*/
/*
- * 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,7 +19,7 @@
* 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_SHA512_H
#define MBEDTLS_SHA512_H
@@ -39,7 +39,6 @@
!defined(inline) && !defined(__cplusplus)
#define inline __inline
#endif
-
#if !defined(MBEDTLS_SHA512_ALT)
// Regular implementation
//
@@ -49,85 +48,97 @@
#endif
/**
- * \brief SHA-512 context structure
+ * \brief The SHA-512 context structure.
+ *
+ * The structure is used both for SHA-384 and for SHA-512
+ * checksum calculations. The choice between these two is
+ * made in the call to mbedtls_sha512_starts_ret().
*/
typedef struct
{
- uint64_t total[2]; /*!< number of bytes processed */
- uint64_t state[8]; /*!< intermediate digest state */
- unsigned char buffer[128]; /*!< data block being processed */
- int is384; /*!< 0 => SHA-512, else SHA-384 */
+ uint64_t total[2]; /*!< The number of Bytes processed. */
+ uint64_t state[8]; /*!< The intermediate digest state. */
+ unsigned char buffer[128]; /*!< The data block being processed. */
+ int is384; /*!< Determines which function to use.
+ * <ul><li>0: Use SHA-512.</li>
+ * <li>1: Use SHA-384.</li></ul> */
}
mbedtls_sha512_context;
/**
- * \brief Initialize SHA-512 context
+ * \brief This function initializes a SHA-512 context.
*
- * \param ctx SHA-512 context to be initialized
+ * \param ctx The SHA-512 context to initialize.
*/
void mbedtls_sha512_init( mbedtls_sha512_context *ctx );
/**
- * \brief Clear SHA-512 context
+ * \brief This function clears a SHA-512 context.
*
- * \param ctx SHA-512 context to be cleared
+ * \param ctx The SHA-512 context to clear.
*/
void mbedtls_sha512_free( mbedtls_sha512_context *ctx );
/**
- * \brief Clone (the state of) a SHA-512 context
+ * \brief This function clones the state of a SHA-512 context.
*
- * \param dst The destination context
- * \param src The context to be cloned
+ * \param dst The destination context.
+ * \param src The context to clone.
*/
void mbedtls_sha512_clone( mbedtls_sha512_context *dst,
const mbedtls_sha512_context *src );
/**
- * \brief SHA-512 context setup
+ * \brief This function starts a SHA-384 or SHA-512 checksum
+ * calculation.
*
- * \param ctx context to be initialized
- * \param is384 0 = use SHA512, 1 = use SHA384
+ * \param ctx The SHA-512 context to initialize.
+ * \param is384 Determines which function to use.
+ * <ul><li>0: Use SHA-512.</li>
+ * <li>1: Use SHA-384.</li></ul>
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 );
/**
- * \brief SHA-512 process buffer
+ * \brief This function feeds an input buffer into an ongoing
+ * SHA-512 checksum calculation.
*
- * \param ctx SHA-512 context
- * \param input buffer holding the data
- * \param ilen length of the input data
+ * \param ctx The SHA-512 context.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,
- const unsigned char *input,
- size_t ilen );
+ const unsigned char *input,
+ size_t ilen );
/**
- * \brief SHA-512 final digest
+ * \brief This function finishes the SHA-512 operation, and writes
+ * the result to the output buffer. This function is for
+ * internal use only.
*
- * \param ctx SHA-512 context
- * \param output SHA-384/512 checksum result
+ * \param ctx The SHA-512 context.
+ * \param output The SHA-384 or SHA-512 checksum result.
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
unsigned char output[64] );
/**
- * \brief SHA-512 process data block (internal use only)
+ * \brief This function processes a single data block within
+ * the ongoing SHA-512 computation.
*
- * \param ctx SHA-512 context
- * \param data buffer holding one block of data
+ * \param ctx The SHA-512 context.
+ * \param data The buffer holding one block of data.
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
const unsigned char data[128] );
-
#if !defined(MBEDTLS_DEPRECATED_REMOVED)
#if defined(MBEDTLS_DEPRECATED_WARNING)
#define MBEDTLS_DEPRECATED __attribute__((deprecated))
@@ -135,12 +146,15 @@
#define MBEDTLS_DEPRECATED
#endif
/**
- * \brief SHA-512 context setup
+ * \brief This function starts a SHA-384 or SHA-512 checksum
+ * calculation.
*
* \deprecated Superseded by mbedtls_sha512_starts_ret() in 2.7.0
*
- * \param ctx context to be initialized
- * \param is384 0 = use SHA512, 1 = use SHA384
+ * \param ctx The SHA-512 context to initialize.
+ * \param is384 Determines which function to use.
+ * <ul><li>0: Use SHA-512.</li>
+ * <li>1: Use SHA-384.</li></ul>
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha512_starts(
mbedtls_sha512_context *ctx,
@@ -150,13 +164,14 @@
}
/**
- * \brief SHA-512 process buffer
+ * \brief This function feeds an input buffer into an ongoing
+ * SHA-512 checksum calculation.
*
* \deprecated Superseded by mbedtls_sha512_update_ret() in 2.7.0
*
- * \param ctx SHA-512 context
- * \param input buffer holding the data
- * \param ilen length of the input data
+ * \param ctx The SHA-512 context.
+ * \param input The buffer holding the data.
+ * \param ilen The length of the input data.
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha512_update(
mbedtls_sha512_context *ctx,
@@ -167,12 +182,13 @@
}
/**
- * \brief SHA-512 final digest
+ * \brief This function finishes the SHA-512 operation, and writes
+ * the result to the output buffer.
*
* \deprecated Superseded by mbedtls_sha512_finish_ret() in 2.7.0
*
- * \param ctx SHA-512 context
- * \param output SHA-384/512 checksum result
+ * \param ctx The SHA-512 context.
+ * \param output The SHA-384 or SHA-512 checksum result.
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha512_finish(
mbedtls_sha512_context *ctx,
@@ -182,12 +198,14 @@
}
/**
- * \brief SHA-512 process data block (internal use only)
+ * \brief This function processes a single data block within
+ * the ongoing SHA-512 computation. This function is for
+ * internal use only.
*
* \deprecated Superseded by mbedtls_internal_sha512_process() in 2.7.0
*
- * \param ctx SHA-512 context
- * \param data buffer holding one block of data
+ * \param ctx The SHA-512 context.
+ * \param data The buffer holding one block of data.
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha512_process(
mbedtls_sha512_context *ctx,
@@ -212,14 +230,23 @@
#endif
/**
- * \brief Output = SHA-512( input buffer )
+ * \brief This function calculates the SHA-512 or SHA-384
+ * checksum of a buffer.
*
- * \param input buffer holding the data
- * \param ilen length of the input data
- * \param output SHA-384/512 checksum result
- * \param is384 0 = use SHA512, 1 = use SHA384
+ * The function allocates the context, performs the
+ * calculation, and frees the context.
*
- * \return 0 if successful
+ * The SHA-512 result is calculated as
+ * output = SHA-512(input buffer).
+ *
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ * \param output The SHA-384 or SHA-512 checksum result.
+ * \param is384 Determines which function to use.
+ * <ul><li>0: Use SHA-512.</li>
+ * <li>1: Use SHA-384.</li></ul>
+ *
+ * \return \c 0 on success.
*/
int mbedtls_sha512_ret( const unsigned char *input,
size_t ilen,
@@ -233,14 +260,23 @@
#define MBEDTLS_DEPRECATED
#endif
/**
- * \brief Output = SHA-512( input buffer )
+ * \brief This function calculates the SHA-512 or SHA-384
+ * checksum of a buffer.
+ *
+ * The function allocates the context, performs the
+ * calculation, and frees the context.
+ *
+ * The SHA-512 result is calculated as
+ * output = SHA-512(input buffer).
*
* \deprecated Superseded by mbedtls_sha512_ret() in 2.7.0
*
- * \param input buffer holding the data
- * \param ilen length of the input data
- * \param output SHA-384/512 checksum result
- * \param is384 0 = use SHA512, 1 = use SHA384
+ * \param input The buffer holding the data.
+ * \param ilen The length of the input data.
+ * \param output The SHA-384 or SHA-512 checksum result.
+ * \param is384 Determines which function to use.
+ * <ul><li>0: Use SHA-512.</li>
+ * <li>1: Use SHA-384.</li></ul>
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha512(
const unsigned char *input,
@@ -253,11 +289,10 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
-
-/**
- * \brief Checkup routine
+ /**
+ * \brief The SHA-384 or SHA-512 checkup routine.
*
- * \return 0 if successful, or 1 if the test failed
+ * \return \c 0 on success, or \c 1 on failure.
*/
int mbedtls_sha512_self_test( int verbose );
diff --git a/library/error.c b/library/error.c
index 42bcde6..0292480 100644
--- a/library/error.c
+++ b/library/error.c
@@ -210,7 +210,7 @@
if( use_ret == -(MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE) )
mbedtls_snprintf( buf, buflen, "CIPHER - The selected feature is not available" );
if( use_ret == -(MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA) )
- mbedtls_snprintf( buf, buflen, "CIPHER - Bad input parameters to function" );
+ mbedtls_snprintf( buf, buflen, "CIPHER - Bad input parameters" );
if( use_ret == -(MBEDTLS_ERR_CIPHER_ALLOC_FAILED) )
mbedtls_snprintf( buf, buflen, "CIPHER - Failed to allocate memory" );
if( use_ret == -(MBEDTLS_ERR_CIPHER_INVALID_PADDING) )
@@ -220,14 +220,14 @@
if( use_ret == -(MBEDTLS_ERR_CIPHER_AUTH_FAILED) )
mbedtls_snprintf( buf, buflen, "CIPHER - Authentication failed (for AEAD modes)" );
if( use_ret == -(MBEDTLS_ERR_CIPHER_INVALID_CONTEXT) )
- mbedtls_snprintf( buf, buflen, "CIPHER - The context is invalid, eg because it was free()ed" );
+ mbedtls_snprintf( buf, buflen, "CIPHER - The context is invalid. For example, because it was freed" );
if( use_ret == -(MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED) )
mbedtls_snprintf( buf, buflen, "CIPHER - Cipher hardware accelerator failed" );
#endif /* MBEDTLS_CIPHER_C */
#if defined(MBEDTLS_DHM_C)
if( use_ret == -(MBEDTLS_ERR_DHM_BAD_INPUT_DATA) )
- mbedtls_snprintf( buf, buflen, "DHM - Bad input parameters to function" );
+ mbedtls_snprintf( buf, buflen, "DHM - Bad input parameters" );
if( use_ret == -(MBEDTLS_ERR_DHM_READ_PARAMS_FAILED) )
mbedtls_snprintf( buf, buflen, "DHM - Reading of the DHM parameters failed" );
if( use_ret == -(MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED) )
@@ -243,7 +243,7 @@
if( use_ret == -(MBEDTLS_ERR_DHM_ALLOC_FAILED) )
mbedtls_snprintf( buf, buflen, "DHM - Allocation of memory failed" );
if( use_ret == -(MBEDTLS_ERR_DHM_FILE_IO_ERROR) )
- mbedtls_snprintf( buf, buflen, "DHM - Read/write of file failed" );
+ mbedtls_snprintf( buf, buflen, "DHM - Read or write of file failed" );
if( use_ret == -(MBEDTLS_ERR_DHM_HW_ACCEL_FAILED) )
mbedtls_snprintf( buf, buflen, "DHM - DHM hardware accelerator failed" );
if( use_ret == -(MBEDTLS_ERR_DHM_SET_GROUP_FAILED) )
@@ -368,7 +368,7 @@
if( use_ret == -(MBEDTLS_ERR_RSA_KEY_GEN_FAILED) )
mbedtls_snprintf( buf, buflen, "RSA - Something failed during generation of a key" );
if( use_ret == -(MBEDTLS_ERR_RSA_KEY_CHECK_FAILED) )
- mbedtls_snprintf( buf, buflen, "RSA - Key failed to pass the library's validity check" );
+ mbedtls_snprintf( buf, buflen, "RSA - Key failed to pass the validity check of the library" );
if( use_ret == -(MBEDTLS_ERR_RSA_PUBLIC_FAILED) )
mbedtls_snprintf( buf, buflen, "RSA - The public key operation failed" );
if( use_ret == -(MBEDTLS_ERR_RSA_PRIVATE_FAILED) )
@@ -380,7 +380,7 @@
if( use_ret == -(MBEDTLS_ERR_RSA_RNG_FAILED) )
mbedtls_snprintf( buf, buflen, "RSA - The random generator failed to generate non-zeros" );
if( use_ret == -(MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION) )
- mbedtls_snprintf( buf, buflen, "RSA - The implementation doesn't offer the requested operation, e.g. because of security violations or lack of functionality" );
+ mbedtls_snprintf( buf, buflen, "RSA - The implementation does not offer the requested operation, for example, because of security violations or lack of functionality" );
if( use_ret == -(MBEDTLS_ERR_RSA_HW_ACCEL_FAILED) )
mbedtls_snprintf( buf, buflen, "RSA - RSA hardware accelerator failed" );
#endif /* MBEDTLS_RSA_C */
@@ -571,7 +571,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 */
@@ -644,7 +644,7 @@
#if defined(MBEDTLS_CCM_C)
if( use_ret == -(MBEDTLS_ERR_CCM_BAD_INPUT) )
- mbedtls_snprintf( buf, buflen, "CCM - Bad input parameters to function" );
+ mbedtls_snprintf( buf, buflen, "CCM - Bad input parameters to the function" );
if( use_ret == -(MBEDTLS_ERR_CCM_AUTH_FAILED) )
mbedtls_snprintf( buf, buflen, "CCM - Authenticated decryption failed" );
if( use_ret == -(MBEDTLS_ERR_CCM_HW_ACCEL_FAILED) )
@@ -660,11 +660,11 @@
if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED) )
mbedtls_snprintf( buf, buflen, "CTR_DRBG - The entropy source failed" );
if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG) )
- mbedtls_snprintf( buf, buflen, "CTR_DRBG - Too many random requested in single call" );
+ mbedtls_snprintf( buf, buflen, "CTR_DRBG - The requested random buffer length is too big" );
if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG) )
- mbedtls_snprintf( buf, buflen, "CTR_DRBG - Input too large (Entropy + additional)" );
+ mbedtls_snprintf( buf, buflen, "CTR_DRBG - The input (entropy + additional data) is too large" );
if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR) )
- mbedtls_snprintf( buf, buflen, "CTR_DRBG - Read/write error in file" );
+ mbedtls_snprintf( buf, buflen, "CTR_DRBG - Read or write error in file" );
#endif /* MBEDTLS_CTR_DRBG_C */
#if defined(MBEDTLS_DES_C)
