Merge branch 'mbedtls_ssl_get_key_exchange_md_ssl_tls-return_hashlen' into tls_async_server-2.9
Conflict resolution:
* ChangeLog: put the new entry from my branch in the proper place.
* include/mbedtls/error.h: counted high-level module error codes again.
* include/mbedtls/ssl.h: picked different numeric codes for the
concurrently added errors; made the new error a full sentence per
current standards.
* library/error.c: ran scripts/generate_errors.pl.
* library/ssl_srv.c:
* ssl_prepare_server_key_exchange "DHE key exchanges": the conflict
was due to style corrections in development
(4cb1f4d49cff999d0c853bc696ad7eea68888c35) which I merged with
my refactoring.
* ssl_prepare_server_key_exchange "For key exchanges involving the
server signing", first case, variable declarations: merged line
by line:
* dig_signed_len: added in async
* signature_len: removed in async
* hashlen: type changed to size_t in development
* hash: size changed to MBEDTLS_MD_MAX_SIZE in async
* ret: added in async
* ssl_prepare_server_key_exchange "For key exchanges involving the
server signing", first cae comment: the conflict was due to style
corrections in development (4cb1f4d49cff999d0c853bc696ad7eea68888c35)
which I merged with my comment changes made as part of refactoring
the function.
* ssl_prepare_server_key_exchange "Compute the hash to be signed" if
`md_alg != MBEDTLS_MD_NONE`: conflict between
ebd652fe2dfc2c82d774bfd334398279d9027492
"ssl_write_server_key_exchange: calculate hashlen explicitly" and
46f5a3e9b4d5db3cacfe2ba33480a27317c62d46 "Check return codes from
MD in ssl code". I took the code from commit
ca1d74290439ec9e2723a911657fd96aa320e219 made on top of development
which makes mbedtls_ssl_get_key_exchange_md_ssl_tls return the
hash length.
* programs/ssl/ssl_server2.c: multiple conflicts between the introduction
of MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS and new auxiliary functions and
definitions for async support, and the introduction of idle().
* definitions before main: concurrent additions, kept both.
* main, just after `handshake:`: in the loop around
mbedtls_ssl_handshake(), merge the addition of support for
MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS and SSL_ASYNC_INJECT_ERROR_CANCEL
with the addition of the idle() call.
* main, if `opt.transport == MBEDTLS_SSL_TRANSPORT_STREAM`: take the
code from development and add a check for
MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS.
* main, loop around mbedtls_ssl_read() in the datagram case:
take the code from development and add a check for
MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS; revert to a do...while loop.
* main, loop around mbedtls_ssl_write() in the datagram case:
take the code from development and add a check for
MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS; revert to a do...while loop.
diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h
index c8dd0f3..3c5b133 100644
--- a/include/mbedtls/aes.h
+++ b/include/mbedtls/aes.h
@@ -1,9 +1,21 @@
/**
* \file aes.h
*
- * \brief AES block cipher
+ * \brief This file contains AES definitions and functions.
*
- * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * The Advanced Encryption Standard (AES) specifies a FIPS-approved
+ * cryptographic algorithm that can be used to protect electronic
+ * data.
+ *
+ * The AES algorithm is a symmetric block cipher that can
+ * encrypt and decrypt information. For more information, see
+ * <em>FIPS Publication 197: Advanced Encryption Standard</em> and
+ * <em>ISO/IEC 18033-2:2006: Information technology -- Security
+ * techniques -- Encryption algorithms -- Part 2: Asymmetric
+ * ciphers</em>.
+ */
+
+/* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -18,8 +30,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
@@ -33,15 +46,16 @@
#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-0x0023 */
-#define MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE -0x0023 /**< Feature not available, e.g. unsupported AES key size. */
+/* Error codes in range 0x0023-0x0025 */
+#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) ) && \
!defined(inline) && !defined(__cplusplus)
@@ -57,68 +71,91 @@
#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.
+ * \return #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.
+ * \return #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,
@@ -127,26 +164,41 @@
#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.
+ * \return #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
+ * on failure.
*/
int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx,
int mode,
@@ -158,29 +210,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,
@@ -191,28 +252,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,
@@ -224,26 +293,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,
@@ -255,30 +330,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],
@@ -294,11 +369,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],
@@ -308,11 +383,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],
@@ -334,9 +409,10 @@
#endif
/**
- * \brief Checkup routine
+ * \brief Checkup routine.
*
- * \return 0 if successful, or 1 if the test failed
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_aes_self_test( int verbose );
diff --git a/include/mbedtls/aesni.h b/include/mbedtls/aesni.h
index b1b7f1c..746baa0 100644
--- a/include/mbedtls/aesni.h
+++ b/include/mbedtls/aesni.h
@@ -2,7 +2,8 @@
* \file aesni.h
*
* \brief AES-NI for hardware AES acceleration on some Intel processors
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/arc4.h b/include/mbedtls/arc4.h
index 5fc5395..f9d93f8 100644
--- a/include/mbedtls/arc4.h
+++ b/include/mbedtls/arc4.h
@@ -3,6 +3,10 @@
*
* \brief The ARCFOUR stream cipher
*
+ * \warning ARC4 is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers instead.
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -19,6 +23,7 @@
* limitations under the License.
*
* This file is part of mbed TLS (https://tls.mbed.org)
+ *
*/
#ifndef MBEDTLS_ARC4_H
#define MBEDTLS_ARC4_H
@@ -31,6 +36,8 @@
#include <stddef.h>
+#define MBEDTLS_ERR_ARC4_HW_ACCEL_FAILED -0x0019 /**< ARC4 hardware accelerator failed. */
+
#if !defined(MBEDTLS_ARC4_ALT)
// Regular implementation
//
@@ -40,7 +47,11 @@
#endif
/**
- * \brief ARC4 context structure
+ * \brief ARC4 context structure
+ *
+ * \warning ARC4 is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers instead.
+ *
*/
typedef struct
{
@@ -54,6 +65,11 @@
* \brief Initialize ARC4 context
*
* \param ctx ARC4 context to be initialized
+ *
+ * \warning ARC4 is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
+ *
*/
void mbedtls_arc4_init( mbedtls_arc4_context *ctx );
@@ -61,6 +77,11 @@
* \brief Clear ARC4 context
*
* \param ctx ARC4 context to be cleared
+ *
+ * \warning ARC4 is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
+ *
*/
void mbedtls_arc4_free( mbedtls_arc4_context *ctx );
@@ -70,6 +91,11 @@
* \param ctx ARC4 context to be setup
* \param key the secret key
* \param keylen length of the key, in bytes
+ *
+ * \warning ARC4 is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
+ *
*/
void mbedtls_arc4_setup( mbedtls_arc4_context *ctx, const unsigned char *key,
unsigned int keylen );
@@ -83,6 +109,11 @@
* \param output buffer for the output data
*
* \return 0 if successful
+ *
+ * \warning ARC4 is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
+ *
*/
int mbedtls_arc4_crypt( mbedtls_arc4_context *ctx, size_t length, const unsigned char *input,
unsigned char *output );
@@ -103,6 +134,11 @@
* \brief Checkup routine
*
* \return 0 if successful, or 1 if the test failed
+ *
+ * \warning ARC4 is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
+ *
*/
int mbedtls_arc4_self_test( int verbose );
diff --git a/include/mbedtls/asn1.h b/include/mbedtls/asn1.h
index e159e57..96c1c9a 100644
--- a/include/mbedtls/asn1.h
+++ b/include/mbedtls/asn1.h
@@ -2,7 +2,8 @@
* \file asn1.h
*
* \brief Generic ASN.1 parsing
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -87,6 +88,21 @@
#define MBEDTLS_ASN1_PRIMITIVE 0x00
#define MBEDTLS_ASN1_CONSTRUCTED 0x20
#define MBEDTLS_ASN1_CONTEXT_SPECIFIC 0x80
+
+/*
+ * Bit masks for each of the components of an ASN.1 tag as specified in
+ * ITU X.690 (08/2015), section 8.1 "General rules for encoding",
+ * paragraph 8.1.2.2:
+ *
+ * Bit 8 7 6 5 1
+ * +-------+-----+------------+
+ * | Class | P/C | Tag number |
+ * +-------+-----+------------+
+ */
+#define MBEDTLS_ASN1_TAG_CLASS_MASK 0xC0
+#define MBEDTLS_ASN1_TAG_PC_MASK 0x20
+#define MBEDTLS_ASN1_TAG_VALUE_MASK 0x1F
+
/* \} name */
/* \} addtogroup asn1_module */
diff --git a/include/mbedtls/asn1write.h b/include/mbedtls/asn1write.h
index 73ff32b..f76fc80 100644
--- a/include/mbedtls/asn1write.h
+++ b/include/mbedtls/asn1write.h
@@ -2,7 +2,8 @@
* \file asn1write.h
*
* \brief ASN.1 buffer writing functionality
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/base64.h b/include/mbedtls/base64.h
index 352c652..7a64f52 100644
--- a/include/mbedtls/base64.h
+++ b/include/mbedtls/base64.h
@@ -2,7 +2,8 @@
* \file base64.h
*
* \brief RFC 1521 base64 encoding/decoding
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h
index 456a804..31383b1 100644
--- a/include/mbedtls/bignum.h
+++ b/include/mbedtls/bignum.h
@@ -1,8 +1,9 @@
/**
* \file bignum.h
*
- * \brief Multi-precision integer library
- *
+ * \brief Multi-precision integer library
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -70,7 +71,7 @@
* Maximum size of MPIs allowed in bits and bytes for user-MPIs.
* ( Default: 512 bytes => 4096 bits, Maximum tested: 2048 bytes => 16384 bits )
*
- * Note: Calculations can results temporarily in larger MPIs. So the number
+ * Note: Calculations can temporarily result in larger MPIs. So the number
* of limbs required (MBEDTLS_MPI_MAX_LIMBS) is higher.
*/
#define MBEDTLS_MPI_MAX_SIZE 1024 /**< Maximum number of bytes for usable MPIs. */
@@ -203,6 +204,8 @@
/**
* \brief Enlarge to the specified number of limbs
*
+ * This function does nothing if the MPI is already large enough.
+ *
* \param X MPI to grow
* \param nblimbs The target number of limbs
*
@@ -214,19 +217,23 @@
/**
* \brief Resize down, keeping at least the specified number of limbs
*
+ * If \c X is smaller than \c nblimbs, it is resized up
+ * instead.
+ *
* \param X MPI to shrink
* \param nblimbs The minimum number of limbs to keep
*
* \return 0 if successful,
* MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * (this can only happen when resizing up).
*/
int mbedtls_mpi_shrink( mbedtls_mpi *X, size_t nblimbs );
/**
* \brief Copy the contents of Y into X
*
- * \param X Destination MPI
- * \param Y Source MPI
+ * \param X Destination MPI. It is enlarged if necessary.
+ * \param Y Source MPI.
*
* \return 0 if successful,
* MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
@@ -683,6 +690,10 @@
*
* \return 0 if successful,
* MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ *
+ * \note The bytes obtained from the PRNG are interpreted
+ * as a big-endian representation of an MPI; this can
+ * be relevant in applications like deterministic ECDSA.
*/
int mbedtls_mpi_fill_random( mbedtls_mpi *X, size_t size,
int (*f_rng)(void *, unsigned char *, size_t),
diff --git a/include/mbedtls/blowfish.h b/include/mbedtls/blowfish.h
index 34626ee..c0ef5a0 100644
--- a/include/mbedtls/blowfish.h
+++ b/include/mbedtls/blowfish.h
@@ -2,7 +2,8 @@
* \file blowfish.h
*
* \brief Blowfish block cipher
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -40,6 +41,7 @@
#define MBEDTLS_BLOWFISH_BLOCKSIZE 8 /* Blowfish uses 64 bit blocks */
#define MBEDTLS_ERR_BLOWFISH_INVALID_KEY_LENGTH -0x0016 /**< Invalid key length. */
+#define MBEDTLS_ERR_BLOWFISH_HW_ACCEL_FAILED -0x0017 /**< Blowfish hardware accelerator failed. */
#define MBEDTLS_ERR_BLOWFISH_INVALID_INPUT_LENGTH -0x0018 /**< Invalid data input length. */
#if !defined(MBEDTLS_BLOWFISH_ALT)
diff --git a/include/mbedtls/bn_mul.h b/include/mbedtls/bn_mul.h
index cac3f14..354c1cc 100644
--- a/include/mbedtls/bn_mul.h
+++ b/include/mbedtls/bn_mul.h
@@ -1,8 +1,9 @@
/**
* \file bn_mul.h
*
- * \brief Multi-precision integer library
- *
+ * \brief Multi-precision integer library
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/camellia.h b/include/mbedtls/camellia.h
index 0424d62..cf07629 100644
--- a/include/mbedtls/camellia.h
+++ b/include/mbedtls/camellia.h
@@ -2,7 +2,8 @@
* \file camellia.h
*
* \brief Camellia block cipher
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -37,6 +38,7 @@
#define MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH -0x0024 /**< Invalid key length. */
#define MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH -0x0026 /**< Invalid data input length. */
+#define MBEDTLS_ERR_CAMELLIA_HW_ACCEL_FAILED -0x0027 /**< Camellia hardware accelerator failed. */
#if !defined(MBEDTLS_CAMELLIA_ALT)
// Regular implementation
diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h
index 579402f..630b7fd 100644
--- a/include/mbedtls/ccm.h
+++ b/include/mbedtls/ccm.h
@@ -1,9 +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.
*
- * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * 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-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
@@ -18,15 +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_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
@@ -37,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,
@@ -69,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, 12, 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,
@@ -107,21 +122,25 @@
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.
+ * 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 in Bytes.
+ * 4, 6, 8, 10, 12, 14 or 16.
*
- * \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,
@@ -133,9 +152,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" {
@@ -143,9 +162,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/certs.h b/include/mbedtls/certs.h
index ca49086..8dab7b5 100644
--- a/include/mbedtls/certs.h
+++ b/include/mbedtls/certs.h
@@ -2,7 +2,8 @@
* \file certs.h
*
* \brief Sample certificates and DHM parameters for testing
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/check_config.h b/include/mbedtls/check_config.h
index fa72454..be80332 100644
--- a/include/mbedtls/check_config.h
+++ b/include/mbedtls/check_config.h
@@ -2,7 +2,8 @@
* \file check_config.h
*
* \brief Consistency checks for configuration options
- *
+ */
+/*
* Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -77,6 +78,10 @@
#error "MBEDTLS_DHM_C defined, but not all prerequisites"
#endif
+#if defined(MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT) && !defined(MBEDTLS_SSL_TRUNCATED_HMAC)
+#error "MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT defined, but not all prerequisites"
+#endif
+
#if defined(MBEDTLS_CMAC_C) && \
!defined(MBEDTLS_AES_C) && !defined(MBEDTLS_DES_C)
#error "MBEDTLS_CMAC_C defined, but not all prerequisites"
diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h
index b12e388..d1f4efe 100644
--- a/include/mbedtls/cipher.h
+++ b/include/mbedtls/cipher.h
@@ -1,11 +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
@@ -20,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
@@ -51,21 +52,29 @@
#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_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
+/**
+ * \brief An enumeration of supported ciphers.
+ *
+ * \warning ARC4 and DES are considered weak ciphers and their use
+ * constitutes a security risk. We recommend considering stronger
+ * ciphers instead.
+ */
typedef enum {
MBEDTLS_CIPHER_ID_NONE = 0,
MBEDTLS_CIPHER_ID_NULL,
@@ -77,6 +86,13 @@
MBEDTLS_CIPHER_ID_ARC4,
} mbedtls_cipher_id_t;
+/**
+ * \brief An enumeration of supported (cipher, mode) pairs.
+ *
+ * \warning ARC4 and DES are considered weak ciphers and their use
+ * constitutes a security risk. We recommend considering stronger
+ * ciphers instead.
+ */
typedef enum {
MBEDTLS_CIPHER_NONE = 0,
MBEDTLS_CIPHER_NULL,
@@ -129,6 +145,7 @@
MBEDTLS_CIPHER_CAMELLIA_256_CCM,
} mbedtls_cipher_type_t;
+/** Supported cipher modes. */
typedef enum {
MBEDTLS_MODE_NONE = 0,
MBEDTLS_MODE_ECB,
@@ -141,14 +158,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,
@@ -156,19 +175,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
/**
@@ -182,33 +201,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;
@@ -217,125 +243,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 )
{
@@ -346,13 +380,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 )
{
@@ -363,13 +397,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 )
{
@@ -383,12 +418,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 )
{
@@ -399,11 +434,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 )
{
@@ -414,13 +451,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 )
{
@@ -431,13 +468,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 )
{
@@ -448,18 +485,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,
@@ -467,170 +504,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,
@@ -639,26 +682,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,
@@ -668,31 +711,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/cipher_internal.h b/include/mbedtls/cipher_internal.h
index 6c58bcc..969ff9c 100644
--- a/include/mbedtls/cipher_internal.h
+++ b/include/mbedtls/cipher_internal.h
@@ -4,7 +4,8 @@
* \brief Cipher wrappers.
*
* \author Adriaan de Jong <dejong@fox-it.com>
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/cmac.h b/include/mbedtls/cmac.h
index 4d3f2d2..0ada742 100644
--- a/include/mbedtls/cmac.h
+++ b/include/mbedtls/cmac.h
@@ -1,10 +1,13 @@
/**
* \file cmac.h
*
- * \brief Cipher-based Message Authentication Code (CMAC) Mode for
- * Authentication
+ * \brief This file contains CMAC definitions and functions.
*
- * Copyright (C) 2015-2016, ARM Limited, All Rights Reserved
+ * The Cipher-based Message Authentication Code (CMAC) Mode for
+ * Authentication is defined in <em>RFC-4493: The AES-CMAC Algorithm</em>.
+ */
+/*
+ * 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
@@ -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_CMAC_H
#define MBEDTLS_CMAC_H
@@ -30,108 +34,128 @@
extern "C" {
#endif
+#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: MBEDTLS_CIPHER_AES_128_ECB,
+ * MBEDTLS_CIPHER_AES_192_ECB, MBEDTLS_CIPHER_AES_256_ECB,
+ * or MBEDTLS_CIPHER_DES_EDE3_ECB.
+ * \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.
+ * \return A cipher-specific error code on failure.
*/
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.
+ *
+ * \return \c 0 on success.
+ * \return #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.
+ *
+ * \return \c 0 on success.
+ * \return #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.
+ *
+ * \return \c 0 on success.
+ * \return #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.
+ *
+ * \return \c 0 on success.
+ * \return #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,
@@ -140,16 +164,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,
@@ -170,9 +199,10 @@
#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.
+ * \return \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/compat-1.3.h b/include/mbedtls/compat-1.3.h
index bba1d2c..600a0f1 100644
--- a/include/mbedtls/compat-1.3.h
+++ b/include/mbedtls/compat-1.3.h
@@ -5,7 +5,8 @@
* for the PolarSSL naming conventions.
*
* \deprecated Use the new names directly instead
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 6b7ecf2..4aec9ac 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -6,7 +6,8 @@
* This set of compile-time options may be used to enable
* or disable features selectively, and reduce the global
* memory footprint.
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -261,6 +262,12 @@
*
* Uncomment a macro to enable alternate implementation of the corresponding
* module.
+ *
+ * \warning MD2, MD4, MD5, ARC4, DES and SHA-1 are considered weak and their
+ * use constitutes a security risk. If possible, we recommend
+ * avoiding dependencies on them, and considering stronger message
+ * digests and ciphers instead.
+ *
*/
//#define MBEDTLS_AES_ALT
//#define MBEDTLS_ARC4_ALT
@@ -269,15 +276,18 @@
//#define MBEDTLS_CCM_ALT
//#define MBEDTLS_CMAC_ALT
//#define MBEDTLS_DES_ALT
+//#define MBEDTLS_DHM_ALT
+//#define MBEDTLS_ECJPAKE_ALT
//#define MBEDTLS_GCM_ALT
-//#define MBEDTLS_XTEA_ALT
//#define MBEDTLS_MD2_ALT
//#define MBEDTLS_MD4_ALT
//#define MBEDTLS_MD5_ALT
//#define MBEDTLS_RIPEMD160_ALT
+//#define MBEDTLS_RSA_ALT
//#define MBEDTLS_SHA1_ALT
//#define MBEDTLS_SHA256_ALT
//#define MBEDTLS_SHA512_ALT
+//#define MBEDTLS_XTEA_ALT
/*
* When replacing the elliptic curve module, pleace consider, that it is
* implemented with two .c files:
@@ -317,6 +327,12 @@
*
* Uncomment a macro to enable alternate implementation of the corresponding
* function.
+ *
+ * \warning MD2, MD4, MD5, DES and SHA-1 are considered weak and their use
+ * constitutes a security risk. If possible, we recommend avoiding
+ * dependencies on them, and considering stronger message digests
+ * and ciphers instead.
+ *
*/
//#define MBEDTLS_MD2_PROCESS_ALT
//#define MBEDTLS_MD4_PROCESS_ALT
@@ -332,6 +348,11 @@
//#define MBEDTLS_AES_SETKEY_DEC_ALT
//#define MBEDTLS_AES_ENCRYPT_ALT
//#define MBEDTLS_AES_DECRYPT_ALT
+//#define MBEDTLS_ECDH_GEN_PUBLIC_ALT
+//#define MBEDTLS_ECDH_COMPUTE_SHARED_ALT
+//#define MBEDTLS_ECDSA_VERIFY_ALT
+//#define MBEDTLS_ECDSA_SIGN_ALT
+//#define MBEDTLS_ECDSA_GENKEY_ALT
/**
* \def MBEDTLS_ECP_INTERNAL_ALT
@@ -419,13 +440,46 @@
/**
* \def MBEDTLS_AES_ROM_TABLES
*
- * Store the AES tables in ROM.
+ * Use precomputed AES tables stored in ROM.
*
- * Uncomment this macro to store the AES tables in ROM.
+ * Uncomment this macro to use precomputed AES tables stored in ROM.
+ * Comment this macro to generate AES tables in RAM at runtime.
+ *
+ * Tradeoff: Using precomputed ROM tables reduces RAM usage by ~8kb
+ * (or ~2kb if \c MBEDTLS_AES_FEWER_TABLES is used) and reduces the
+ * initialization time before the first AES operation can be performed.
+ * It comes at the cost of additional ~8kb ROM use (resp. ~2kb if \c
+ * MBEDTLS_AES_FEWER_TABLES below is used), and potentially degraded
+ * performance if ROM access is slower than RAM access.
+ *
+ * This option is independent of \c MBEDTLS_AES_FEWER_TABLES.
+ *
*/
//#define MBEDTLS_AES_ROM_TABLES
/**
+ * \def MBEDTLS_AES_FEWER_TABLES
+ *
+ * Use less ROM/RAM for AES tables.
+ *
+ * Uncommenting this macro omits 75% of the AES tables from
+ * ROM / RAM (depending on the value of \c MBEDTLS_AES_ROM_TABLES)
+ * by computing their values on the fly during operations
+ * (the tables are entry-wise rotations of one another).
+ *
+ * Tradeoff: Uncommenting this reduces the RAM / ROM footprint
+ * by ~6kb but at the cost of more arithmetic operations during
+ * runtime. Specifically, one has to compare 4 accesses within
+ * different tables to 4 accesses with additional arithmetic
+ * operations within the same table. The performance gain/loss
+ * depends on the system and memory details.
+ *
+ * This option is independent of \c MBEDTLS_AES_ROM_TABLES.
+ *
+ */
+//#define MBEDTLS_AES_FEWER_TABLES
+
+/**
* \def MBEDTLS_CAMELLIA_SMALL_MEMORY
*
* Use less ROM for the Camellia implementation (saves about 768 bytes).
@@ -516,6 +570,9 @@
* MBEDTLS_TLS_DHE_RSA_WITH_DES_CBC_SHA
*
* Uncomment this macro to enable weak ciphersuites
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers instead.
*/
//#define MBEDTLS_ENABLE_WEAK_CIPHERSUITES
@@ -552,6 +609,7 @@
#define MBEDTLS_ECP_DP_BP384R1_ENABLED
#define MBEDTLS_ECP_DP_BP512R1_ENABLED
#define MBEDTLS_ECP_DP_CURVE25519_ENABLED
+#define MBEDTLS_ECP_DP_CURVE448_ENABLED
/**
* \def MBEDTLS_ECP_NIST_OPTIM
@@ -621,6 +679,13 @@
* MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256
* MBEDTLS_TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA
* MBEDTLS_TLS_DHE_PSK_WITH_RC4_128_SHA
+ *
+ * \warning Using DHE constitutes a security risk as it
+ * is not possible to validate custom DH parameters.
+ * If possible, it is recommended users should consider
+ * preferring other methods of key exchange.
+ * See dhm.h for more details.
+ *
*/
#define MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED
@@ -720,6 +785,13 @@
* MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256
* MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA
* MBEDTLS_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
+ *
+ * \warning Using DHE constitutes a security risk as it
+ * is not possible to validate custom DH parameters.
+ * If possible, it is recommended users should consider
+ * preferring other methods of key exchange.
+ * See dhm.h for more details.
+ *
*/
#define MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED
@@ -1011,7 +1083,8 @@
/**
* \def MBEDTLS_RSA_NO_CRT
*
- * Do not use the Chinese Remainder Theorem for the RSA private operation.
+ * Do not use the Chinese Remainder Theorem
+ * for the RSA private operation.
*
* Uncomment this macro to disable the use of CRT in RSA.
*
@@ -1374,6 +1447,30 @@
#define MBEDTLS_SSL_TRUNCATED_HMAC
/**
+ * \def MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT
+ *
+ * Fallback to old (pre-2.7), non-conforming implementation of the truncated
+ * HMAC extension which also truncates the HMAC key. Note that this option is
+ * only meant for a transitory upgrade period and is likely to be removed in
+ * a future version of the library.
+ *
+ * \warning The old implementation is non-compliant and has a security weakness
+ * (2^80 brute force attack on the HMAC key used for a single,
+ * uninterrupted connection). This should only be enabled temporarily
+ * when (1) the use of truncated HMAC is essential in order to save
+ * bandwidth, and (2) the peer is an Mbed TLS stack that doesn't use
+ * the fixed implementation yet (pre-2.7).
+ *
+ * \deprecated This option is deprecated and will likely be removed in a
+ * future version of Mbed TLS.
+ *
+ * Uncomment to fallback to old, non-compliant truncated HMAC implementation.
+ *
+ * Requires: MBEDTLS_SSL_TRUNCATED_HMAC
+ */
+//#define MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT
+
+/**
* \def MBEDTLS_THREADING_ALT
*
* Provide your own alternate threading implementation.
@@ -1479,6 +1576,9 @@
*
* \note Currently compression can't be used with DTLS.
*
+ * \deprecated This feature is deprecated and will be removed
+ * in the next major revision of the library.
+ *
* Used in: library/ssl_tls.c
* library/ssl_cli.c
* library/ssl_srv.c
@@ -1606,6 +1706,11 @@
* MBEDTLS_TLS_RSA_WITH_RC4_128_MD5
* MBEDTLS_TLS_RSA_PSK_WITH_RC4_128_SHA
* MBEDTLS_TLS_PSK_WITH_RC4_128_SHA
+ *
+ * \warning ARC4 is considered a weak cipher and its use constitutes a
+ * security risk. If possible, we recommend avoidng dependencies on
+ * it, and considering stronger ciphers instead.
+ *
*/
#define MBEDTLS_ARC4_C
@@ -1659,6 +1764,7 @@
* library/ecp.c
* library/ecdsa.c
* library/rsa.c
+ * library/rsa_internal.c
* library/ssl_tls.c
*
* This module is required for RSA, DHM and ECC (ECDH, ECDSA) support.
@@ -1831,6 +1937,9 @@
* MBEDTLS_TLS_PSK_WITH_3DES_EDE_CBC_SHA
*
* PEM_PARSE uses DES/3DES for decrypting encrypted keys.
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers instead.
*/
#define MBEDTLS_DES_C
@@ -1845,6 +1954,13 @@
*
* This module is used by the following key exchanges:
* DHE-RSA, DHE-PSK
+ *
+ * \warning Using DHE constitutes a security risk as it
+ * is not possible to validate custom DH parameters.
+ * If possible, it is recommended users should consider
+ * preferring other methods of key exchange.
+ * See dhm.h for more details.
+ *
*/
#define MBEDTLS_DHM_C
@@ -2010,6 +2126,11 @@
* Caller:
*
* Uncomment to enable support for (rare) MD2-signed X.509 certs.
+ *
+ * \warning MD2 is considered a weak message digest and its use constitutes a
+ * security risk. If possible, we recommend avoiding dependencies on
+ * it, and considering stronger message digests instead.
+ *
*/
//#define MBEDTLS_MD2_C
@@ -2022,6 +2143,11 @@
* Caller:
*
* Uncomment to enable support for (rare) MD4-signed X.509 certs.
+ *
+ * \warning MD4 is considered a weak message digest and its use constitutes a
+ * security risk. If possible, we recommend avoiding dependencies on
+ * it, and considering stronger message digests instead.
+ *
*/
//#define MBEDTLS_MD4_C
@@ -2035,8 +2161,15 @@
* library/pem.c
* library/ssl_tls.c
*
- * This module is required for SSL/TLS and X.509.
- * PEM_PARSE uses MD5 for decrypting encrypted keys.
+ * This module is required for SSL/TLS up to version 1.1, and for TLS 1.2
+ * depending on the handshake parameters. Further, it is used for checking
+ * MD5-signed certificates, and for PBKDF1 when decrypting PEM-encoded
+ * encrypted keys.
+ *
+ * \warning MD5 is considered a weak message digest and its use constitutes a
+ * security risk. If possible, we recommend avoiding dependencies on
+ * it, and considering stronger message digests instead.
+ *
*/
#define MBEDTLS_MD5_C
@@ -2272,6 +2405,7 @@
* Enable the RSA public-key cryptosystem.
*
* Module: library/rsa.c
+ * library/rsa_internal.c
* Caller: library/ssl_cli.c
* library/ssl_srv.c
* library/ssl_tls.c
@@ -2298,6 +2432,11 @@
*
* This module is required for SSL/TLS up to version 1.1, for TLS 1.2
* depending on the handshake parameters, and for SHA1-signed certificates.
+ *
+ * \warning SHA-1 is considered a weak message digest and its use constitutes
+ * a security risk. If possible, we recommend avoiding dependencies
+ * on it, and considering stronger message digests instead.
+ *
*/
#define MBEDTLS_SHA1_C
@@ -2697,8 +2836,13 @@
* Allow SHA-1 in the default TLS configuration for certificate signing.
* Without this build-time option, SHA-1 support must be activated explicitly
* through mbedtls_ssl_conf_cert_profile. Turning on this option is not
- * recommended because of it is possible to generte SHA-1 collisions, however
+ * recommended because of it is possible to generate SHA-1 collisions, however
* this may be safe for legacy infrastructure where additional controls apply.
+ *
+ * \warning SHA-1 is considered a weak message digest and its use constitutes
+ * a security risk. If possible, we recommend avoiding dependencies
+ * on it, and considering stronger message digests instead.
+ *
*/
// #define MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES
@@ -2709,7 +2853,13 @@
* The use of SHA-1 in TLS <= 1.1 and in HMAC-SHA-1 is always allowed by
* default. At the time of writing, there is no practical attack on the use
* of SHA-1 in handshake signatures, hence this option is turned on by default
- * for compatibility with existing peers.
+ * to preserve compatibility with existing peers, but the general
+ * warning applies nonetheless:
+ *
+ * \warning SHA-1 is considered a weak message digest and its use constitutes
+ * a security risk. If possible, we recommend avoiding dependencies
+ * on it, and considering stronger message digests instead.
+ *
*/
#define MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE
diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h
index 059d3c5..dcbc047 100644
--- a/include/mbedtls/ctr_drbg.h
+++ b/include/mbedtls/ctr_drbg.h
@@ -1,9 +1,18 @@
/**
* \file ctr_drbg.h
*
- * \brief CTR_DRBG based on AES-256 (NIST SP 800-90)
+ * \brief This file contains CTR_DRBG definitions and functions.
*
- * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * CTR_DRBG is a standardized way of building a PRNG from a block-cipher
+ * in counter mode operation, as defined in <em>NIST SP 800-90A:
+ * Recommendation for Random Number Generation Using Deterministic Random
+ * Bit Generators</em>.
+ *
+ * The Mbed TLS implementation of CTR_DRBG uses AES-256 as the underlying
+ * block cipher.
+ */
+/*
+ * 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
@@ -18,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_CTR_DRBG_H
#define MBEDTLS_CTR_DRBG_H
@@ -30,78 +40,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;
@@ -110,31 +137,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.
+ * \return #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),
@@ -143,138 +171,150 @@
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.
+ * \return #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
+ * \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.
*
- * \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.
+ * \param ctx The CTR_DRBG context.
+ * \param additional The data to update the state with.
+ * \param add_len Length of \p additional data.
+ *
*/
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.
+ * \return #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.
+ * \return #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.
+ * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
+ * \return #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.
+ * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
+ * \return #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.
+ * \return \c 1 on failure.
*/
int mbedtls_ctr_drbg_self_test( int verbose );
diff --git a/include/mbedtls/debug.h b/include/mbedtls/debug.h
index 2957996..ef8db67 100644
--- a/include/mbedtls/debug.h
+++ b/include/mbedtls/debug.h
@@ -2,7 +2,8 @@
* \file debug.h
*
* \brief Functions for controlling and providing debug output from the library.
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/des.h b/include/mbedtls/des.h
index 5ca2ecf..5a1a636 100644
--- a/include/mbedtls/des.h
+++ b/include/mbedtls/des.h
@@ -3,6 +3,11 @@
*
* \brief DES block cipher
*
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -19,6 +24,7 @@
* limitations under the License.
*
* This file is part of mbed TLS (https://tls.mbed.org)
+ *
*/
#ifndef MBEDTLS_DES_H
#define MBEDTLS_DES_H
@@ -36,6 +42,7 @@
#define MBEDTLS_DES_DECRYPT 0
#define MBEDTLS_ERR_DES_INVALID_INPUT_LENGTH -0x0032 /**< The data input has an invalid length. */
+#define MBEDTLS_ERR_DES_HW_ACCEL_FAILED -0x0033 /**< DES hardware accelerator failed. */
#define MBEDTLS_DES_KEY_SIZE 8
@@ -49,6 +56,10 @@
/**
* \brief DES context structure
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
typedef struct
{
@@ -69,6 +80,10 @@
* \brief Initialize DES context
*
* \param ctx DES context to be initialized
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
void mbedtls_des_init( mbedtls_des_context *ctx );
@@ -76,6 +91,10 @@
* \brief Clear DES context
*
* \param ctx DES context to be cleared
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
void mbedtls_des_free( mbedtls_des_context *ctx );
@@ -100,6 +119,10 @@
* a parity bit to allow verification.
*
* \param key 8-byte secret key
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
void mbedtls_des_key_set_parity( unsigned char key[MBEDTLS_DES_KEY_SIZE] );
@@ -112,6 +135,10 @@
* \param key 8-byte secret key
*
* \return 0 is parity was ok, 1 if parity was not correct.
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
int mbedtls_des_key_check_key_parity( const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
@@ -121,6 +148,10 @@
* \param key 8-byte secret key
*
* \return 0 if no weak key was found, 1 if a weak key was identified.
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
int mbedtls_des_key_check_weak( const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
@@ -131,6 +162,10 @@
* \param key 8-byte secret key
*
* \return 0
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
int mbedtls_des_setkey_enc( mbedtls_des_context *ctx, const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
@@ -141,6 +176,10 @@
* \param key 8-byte secret key
*
* \return 0
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
int mbedtls_des_setkey_dec( mbedtls_des_context *ctx, const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
@@ -196,6 +235,10 @@
* \param output 64-bit output block
*
* \return 0 if successful
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
int mbedtls_des_crypt_ecb( mbedtls_des_context *ctx,
const unsigned char input[8],
@@ -219,6 +262,10 @@
* \param iv initialization vector (updated after use)
* \param input buffer holding the input data
* \param output buffer holding the output data
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
int mbedtls_des_crypt_cbc( mbedtls_des_context *ctx,
int mode,
@@ -277,6 +324,10 @@
*
* \param SK Round keys
* \param key Base key
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
void mbedtls_des_setkey( uint32_t SK[32],
const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
diff --git a/include/mbedtls/dhm.h b/include/mbedtls/dhm.h
index d7ab152..00fafd8 100644
--- a/include/mbedtls/dhm.h
+++ b/include/mbedtls/dhm.h
@@ -1,9 +1,44 @@
/**
* \file dhm.h
*
- * \brief Diffie-Hellman-Merkle key exchange
+ * \brief Diffie-Hellman-Merkle key exchange.
*
- * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * <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
+ * of non-safe primes both decreases the difficulty of the underlying
+ * discrete logarithm problem and can lead to small subgroup attacks
+ * leaking private exponent bits when invalid public keys are used
+ * and not detected. This is especially relevant if the same DHM
+ * parameters are reused for multiple key exchanges as in static DHM,
+ * while the criticality of small-subgroup attacks is lower for
+ * ephemeral DHM.
+ *
+ * \warning For performance reasons, the code does neither perform primality
+ * nor safe primality tests, nor the expensive checks for invalid
+ * subgroups. Moreover, even if these were performed, non-standardized
+ * primes cannot be trusted because of the possibility of backdoors
+ * that can't be effectively checked for.
+ *
+ * \warning Diffie-Hellman-Merkle is therefore a security risk when not using
+ * standardized primes generated using a trustworthy ("nothing up
+ * my sleeve") method, such as the RFC 3526 / 7919 primes. In the TLS
+ * protocol, DH parameters need to be negotiated, so using the default
+ * primes systematically is not always an option. If possible, use
+ * Elliptic Curve Diffie-Hellman (ECDH), which has better performance,
+ * and for which the TLS protocol mandates the use of standard
+ * parameters.
+ *
+ */
+/*
+ * 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
@@ -18,17 +53,24 @@
* 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
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
#include "bignum.h"
+#if !defined(MBEDTLS_DHM_ALT)
/*
* 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. */
@@ -36,167 +78,85 @@
#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. */
-
-/**
- * RFC 3526 defines a number of standardized Diffie-Hellman groups
- * for IKE.
- * RFC 5114 defines a number of standardized Diffie-Hellman groups
- * that can be used.
- *
- * Some are included here for convenience.
- *
- * Included are:
- * RFC 3526 3. 2048-bit MODP Group
- * RFC 3526 4. 3072-bit MODP Group
- * RFC 3526 5. 4096-bit MODP Group
- * RFC 5114 2.2. 2048-bit MODP Group with 224-bit Prime Order Subgroup
- */
-#define MBEDTLS_DHM_RFC3526_MODP_2048_P \
- "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
- "29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
- "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
- "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
- "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
- "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
- "83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
- "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
- "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
- "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
- "15728E5A8AACAA68FFFFFFFFFFFFFFFF"
-
-#define MBEDTLS_DHM_RFC3526_MODP_2048_G "02"
-
-#define MBEDTLS_DHM_RFC3526_MODP_3072_P \
- "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
- "29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
- "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
- "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
- "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
- "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
- "83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
- "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
- "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
- "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
- "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64" \
- "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7" \
- "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B" \
- "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C" \
- "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \
- "43DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF"
-
-#define MBEDTLS_DHM_RFC3526_MODP_3072_G "02"
-
-#define MBEDTLS_DHM_RFC3526_MODP_4096_P \
- "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
- "29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
- "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
- "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
- "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
- "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
- "83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
- "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
- "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
- "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
- "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64" \
- "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7" \
- "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B" \
- "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C" \
- "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \
- "43DB5BFCE0FD108E4B82D120A92108011A723C12A787E6D7" \
- "88719A10BDBA5B2699C327186AF4E23C1A946834B6150BDA" \
- "2583E9CA2AD44CE8DBBBC2DB04DE8EF92E8EFC141FBECAA6" \
- "287C59474E6BC05D99B2964FA090C3A2233BA186515BE7ED" \
- "1F612970CEE2D7AFB81BDD762170481CD0069127D5B05AA9" \
- "93B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934063199" \
- "FFFFFFFFFFFFFFFF"
-
-#define MBEDTLS_DHM_RFC3526_MODP_4096_G "02"
-
-#define MBEDTLS_DHM_RFC5114_MODP_2048_P \
- "AD107E1E9123A9D0D660FAA79559C51FA20D64E5683B9FD1" \
- "B54B1597B61D0A75E6FA141DF95A56DBAF9A3C407BA1DF15" \
- "EB3D688A309C180E1DE6B85A1274A0A66D3F8152AD6AC212" \
- "9037C9EDEFDA4DF8D91E8FEF55B7394B7AD5B7D0B6C12207" \
- "C9F98D11ED34DBF6C6BA0B2C8BBC27BE6A00E0A0B9C49708" \
- "B3BF8A317091883681286130BC8985DB1602E714415D9330" \
- "278273C7DE31EFDC7310F7121FD5A07415987D9ADC0A486D" \
- "CDF93ACC44328387315D75E198C641A480CD86A1B9E587E8" \
- "BE60E69CC928B2B9C52172E413042E9B23F10B0E16E79763" \
- "C9B53DCF4BA80A29E3FB73C16B8E75B97EF363E2FFA31F71" \
- "CF9DE5384E71B81C0AC4DFFE0C10E64F"
-
-#define MBEDTLS_DHM_RFC5114_MODP_2048_G \
- "AC4032EF4F2D9AE39DF30B5C8FFDAC506CDEBE7B89998CAF"\
- "74866A08CFE4FFE3A6824A4E10B9A6F0DD921F01A70C4AFA"\
- "AB739D7700C29F52C57DB17C620A8652BE5E9001A8D66AD7"\
- "C17669101999024AF4D027275AC1348BB8A762D0521BC98A"\
- "E247150422EA1ED409939D54DA7460CDB5F6C6B250717CBE"\
- "F180EB34118E98D119529A45D6F834566E3025E316A330EF"\
- "BB77A86F0C1AB15B051AE3D428C8F8ACB70A8137150B8EEB"\
- "10E183EDD19963DDD9E263E4770589EF6AA21E7F5F2FF381"\
- "B539CCE3409D13CD566AFBB48D6C019181E1BCFE94B30269"\
- "EDFE72FE9B6AA4BD7B5A0F1C71CFFF4C19C418E1F6EC0179"\
- "81BC087F2A7065B384B890D3191F2BFA"
+#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. */
#ifdef __cplusplus
extern "C" {
#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 p &(start of input buffer)
- * \param end end of buffer
+ * \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
+ * past the end of the ServerKeyExchange parameters.
+ * On error, this is the point at which an error has been
+ * detected, which is usually not useful except to debug
+ * failures.
+ * \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 This function assumes that ctx->P and ctx->G
- * have already been properly set (for example
- * using mbedtls_mpi_read_string or mbedtls_mpi_read_binary).
+ * \note The destination buffer must be large enough to hold
+ * the reduced binary presentation of the modulus, the generator
+ * and the public key, each wrapped with a 2-byte length field.
+ * It is the responsibility of the caller to ensure that enough
+ * space is available. Refer to \c mbedtls_mpi_size to computing
+ * the byte-size of an MPI.
*
- * \return 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
+ * \note This function assumes that \c ctx->P and \c ctx->G
+ * have already been properly set. For that, use
+ * mbedtls_dhm_set_group() below in conjunction with
+ * mbedtls_mpi_read_binary() and mbedtls_mpi_read_string().
+ *
+ * \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,
@@ -204,28 +164,54 @@
void *p_rng );
/**
- * \brief Import the peer's public value G^Y
+ * \brief Set prime modulus and generator
*
- * \param ctx DHM context
- * \param input input buffer
- * \param ilen size of buffer
+ * \param ctx The DHM context.
+ * \param P The MPI holding DHM prime modulus.
+ * \param G The MPI holding DHM generator.
*
- * \return 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
+ * \note This function can be used to set P, G
+ * in preparation for \c mbedtls_dhm_make_params.
+ *
+ * \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 This function imports the public value G^Y of the peer.
+ *
+ * \param ctx The DHM context.
+ * \param input The input buffer.
+ * \param ilen The size of the input buffer.
+ *
+ * \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 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.
*
- * \return 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
+ * \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 \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,
@@ -233,22 +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
- * \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,
@@ -256,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 );
@@ -280,21 +270,34 @@
#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 */
#endif /* MBEDTLS_ASN1_PARSE_C */
+#ifdef __cplusplus
+}
+#endif
+
+#else /* MBEDTLS_DHM_ALT */
+#include "dhm_alt.h"
+#endif /* MBEDTLS_DHM_ALT */
+
+#ifdef __cplusplus
+extern "C" {
+#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 );
@@ -302,4 +305,757 @@
}
#endif
+/**
+ * RFC 3526, RFC 5114 and RFC 7919 standardize a number of
+ * Diffie-Hellman groups, some of which are included here
+ * for use within the SSL/TLS module and the user's convenience
+ * when configuring the Diffie-Hellman parameters by hand
+ * through \c mbedtls_ssl_conf_dh_param.
+ *
+ * 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
+ * of the associated prime field.
+ *
+ * The constants further suffixed with "_bin" are provided in binary format,
+ * while all other constants represent null-terminated strings holding the
+ * hexadecimal presentation of the respective numbers.
+ *
+ * The primes from RFC 3526 and RFC 7919 have been generating by the following
+ * trust-worthy procedure:
+ * - Fix N in { 2048, 3072, 4096, 6144, 8192 } and consider the N-bit number
+ * the first and last 64 bits are all 1, and the remaining N - 128 bits of
+ * which are 0x7ff...ff.
+ * - Add the smallest multiple of the first N - 129 bits of the binary expansion
+ * of pi (for RFC 5236) or e (for RFC 7919) to this intermediate bit-string
+ * such that the resulting integer is a safe-prime.
+ * - The result is the respective RFC 3526 / 7919 prime, and the corresponding
+ * generator is always chosen to be 2 (which is a square for these prime,
+ * hence the corresponding subgroup has order (p-1)/2 and avoids leaking a
+ * bit in the private exponent).
+ *
+ */
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t;
+#define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL ) \
+ ( (mbedtls_deprecated_constant_t) ( VAL ) )
+#else
+#define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL ) VAL
+#endif /* ! MBEDTLS_DEPRECATED_WARNING */
+
+/**
+ * \warning The origin of the primes in RFC 5114 is not documented and
+ * their use therefore constitutes a security risk!
+ *
+ * \deprecated The hex-encoded primes from RFC 5114 are deprecated and are
+ * likely to be removed in a future version of the library without
+ * 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_2048_P \
+ MBEDTLS_DEPRECATED_STRING_CONSTANT( \
+ "AD107E1E9123A9D0D660FAA79559C51FA20D64E5683B9FD1" \
+ "B54B1597B61D0A75E6FA141DF95A56DBAF9A3C407BA1DF15" \
+ "EB3D688A309C180E1DE6B85A1274A0A66D3F8152AD6AC212" \
+ "9037C9EDEFDA4DF8D91E8FEF55B7394B7AD5B7D0B6C12207" \
+ "C9F98D11ED34DBF6C6BA0B2C8BBC27BE6A00E0A0B9C49708" \
+ "B3BF8A317091883681286130BC8985DB1602E714415D9330" \
+ "278273C7DE31EFDC7310F7121FD5A07415987D9ADC0A486D" \
+ "CDF93ACC44328387315D75E198C641A480CD86A1B9E587E8" \
+ "BE60E69CC928B2B9C52172E413042E9B23F10B0E16E79763" \
+ "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" \
+ "74866A08CFE4FFE3A6824A4E10B9A6F0DD921F01A70C4AFA" \
+ "AB739D7700C29F52C57DB17C620A8652BE5E9001A8D66AD7" \
+ "C17669101999024AF4D027275AC1348BB8A762D0521BC98A" \
+ "E247150422EA1ED409939D54DA7460CDB5F6C6B250717CBE" \
+ "F180EB34118E98D119529A45D6F834566E3025E316A330EF" \
+ "BB77A86F0C1AB15B051AE3D428C8F8ACB70A8137150B8EEB" \
+ "10E183EDD19963DDD9E263E4770589EF6AA21E7F5F2FF381" \
+ "B539CCE3409D13CD566AFBB48D6C019181E1BCFE94B30269" \
+ "EDFE72FE9B6AA4BD7B5A0F1C71CFFF4C19C418E1F6EC0179" \
+ "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" \
+ "29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
+ "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
+ "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
+ "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
+ "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
+ "83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
+ "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
+ "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
+ "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" \
+ "29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
+ "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
+ "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
+ "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
+ "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
+ "83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
+ "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
+ "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
+ "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
+ "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64" \
+ "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7" \
+ "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B" \
+ "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C" \
+ "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" \
+ "29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
+ "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
+ "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
+ "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
+ "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
+ "83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
+ "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
+ "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
+ "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
+ "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64" \
+ "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7" \
+ "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B" \
+ "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C" \
+ "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \
+ "43DB5BFCE0FD108E4B82D120A92108011A723C12A787E6D7" \
+ "88719A10BDBA5B2699C327186AF4E23C1A946834B6150BDA" \
+ "2583E9CA2AD44CE8DBBBC2DB04DE8EF92E8EFC141FBECAA6" \
+ "287C59474E6BC05D99B2964FA090C3A2233BA186515BE7ED" \
+ "1F612970CEE2D7AFB81BDD762170481CD0069127D5B05AA9" \
+ "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" )
+
+#endif /* MBEDTLS_DEPRECATED_REMOVED */
+
+/*
+ * Trustworthy DHM parameters in binary form
+ */
+
+#define MBEDTLS_DHM_RFC3526_MODP_2048_P_BIN { \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, \
+ 0xC9, 0x0F, 0xDA, 0xA2, 0x21, 0x68, 0xC2, 0x34, \
+ 0xC4, 0xC6, 0x62, 0x8B, 0x80, 0xDC, 0x1C, 0xD1, \
+ 0x29, 0x02, 0x4E, 0x08, 0x8A, 0x67, 0xCC, 0x74, \
+ 0x02, 0x0B, 0xBE, 0xA6, 0x3B, 0x13, 0x9B, 0x22, \
+ 0x51, 0x4A, 0x08, 0x79, 0x8E, 0x34, 0x04, 0xDD, \
+ 0xEF, 0x95, 0x19, 0xB3, 0xCD, 0x3A, 0x43, 0x1B, \
+ 0x30, 0x2B, 0x0A, 0x6D, 0xF2, 0x5F, 0x14, 0x37, \
+ 0x4F, 0xE1, 0x35, 0x6D, 0x6D, 0x51, 0xC2, 0x45, \
+ 0xE4, 0x85, 0xB5, 0x76, 0x62, 0x5E, 0x7E, 0xC6, \
+ 0xF4, 0x4C, 0x42, 0xE9, 0xA6, 0x37, 0xED, 0x6B, \
+ 0x0B, 0xFF, 0x5C, 0xB6, 0xF4, 0x06, 0xB7, 0xED, \
+ 0xEE, 0x38, 0x6B, 0xFB, 0x5A, 0x89, 0x9F, 0xA5, \
+ 0xAE, 0x9F, 0x24, 0x11, 0x7C, 0x4B, 0x1F, 0xE6, \
+ 0x49, 0x28, 0x66, 0x51, 0xEC, 0xE4, 0x5B, 0x3D, \
+ 0xC2, 0x00, 0x7C, 0xB8, 0xA1, 0x63, 0xBF, 0x05, \
+ 0x98, 0xDA, 0x48, 0x36, 0x1C, 0x55, 0xD3, 0x9A, \
+ 0x69, 0x16, 0x3F, 0xA8, 0xFD, 0x24, 0xCF, 0x5F, \
+ 0x83, 0x65, 0x5D, 0x23, 0xDC, 0xA3, 0xAD, 0x96, \
+ 0x1C, 0x62, 0xF3, 0x56, 0x20, 0x85, 0x52, 0xBB, \
+ 0x9E, 0xD5, 0x29, 0x07, 0x70, 0x96, 0x96, 0x6D, \
+ 0x67, 0x0C, 0x35, 0x4E, 0x4A, 0xBC, 0x98, 0x04, \
+ 0xF1, 0x74, 0x6C, 0x08, 0xCA, 0x18, 0x21, 0x7C, \
+ 0x32, 0x90, 0x5E, 0x46, 0x2E, 0x36, 0xCE, 0x3B, \
+ 0xE3, 0x9E, 0x77, 0x2C, 0x18, 0x0E, 0x86, 0x03, \
+ 0x9B, 0x27, 0x83, 0xA2, 0xEC, 0x07, 0xA2, 0x8F, \
+ 0xB5, 0xC5, 0x5D, 0xF0, 0x6F, 0x4C, 0x52, 0xC9, \
+ 0xDE, 0x2B, 0xCB, 0xF6, 0x95, 0x58, 0x17, 0x18, \
+ 0x39, 0x95, 0x49, 0x7C, 0xEA, 0x95, 0x6A, 0xE5, \
+ 0x15, 0xD2, 0x26, 0x18, 0x98, 0xFA, 0x05, 0x10, \
+ 0x15, 0x72, 0x8E, 0x5A, 0x8A, 0xAC, 0xAA, 0x68, \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }
+
+#define MBEDTLS_DHM_RFC3526_MODP_2048_G_BIN { 0x02 }
+
+#define MBEDTLS_DHM_RFC3526_MODP_3072_P_BIN { \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, \
+ 0xC9, 0x0F, 0xDA, 0xA2, 0x21, 0x68, 0xC2, 0x34, \
+ 0xC4, 0xC6, 0x62, 0x8B, 0x80, 0xDC, 0x1C, 0xD1, \
+ 0x29, 0x02, 0x4E, 0x08, 0x8A, 0x67, 0xCC, 0x74, \
+ 0x02, 0x0B, 0xBE, 0xA6, 0x3B, 0x13, 0x9B, 0x22, \
+ 0x51, 0x4A, 0x08, 0x79, 0x8E, 0x34, 0x04, 0xDD, \
+ 0xEF, 0x95, 0x19, 0xB3, 0xCD, 0x3A, 0x43, 0x1B, \
+ 0x30, 0x2B, 0x0A, 0x6D, 0xF2, 0x5F, 0x14, 0x37, \
+ 0x4F, 0xE1, 0x35, 0x6D, 0x6D, 0x51, 0xC2, 0x45, \
+ 0xE4, 0x85, 0xB5, 0x76, 0x62, 0x5E, 0x7E, 0xC6, \
+ 0xF4, 0x4C, 0x42, 0xE9, 0xA6, 0x37, 0xED, 0x6B, \
+ 0x0B, 0xFF, 0x5C, 0xB6, 0xF4, 0x06, 0xB7, 0xED, \
+ 0xEE, 0x38, 0x6B, 0xFB, 0x5A, 0x89, 0x9F, 0xA5, \
+ 0xAE, 0x9F, 0x24, 0x11, 0x7C, 0x4B, 0x1F, 0xE6, \
+ 0x49, 0x28, 0x66, 0x51, 0xEC, 0xE4, 0x5B, 0x3D, \
+ 0xC2, 0x00, 0x7C, 0xB8, 0xA1, 0x63, 0xBF, 0x05, \
+ 0x98, 0xDA, 0x48, 0x36, 0x1C, 0x55, 0xD3, 0x9A, \
+ 0x69, 0x16, 0x3F, 0xA8, 0xFD, 0x24, 0xCF, 0x5F, \
+ 0x83, 0x65, 0x5D, 0x23, 0xDC, 0xA3, 0xAD, 0x96, \
+ 0x1C, 0x62, 0xF3, 0x56, 0x20, 0x85, 0x52, 0xBB, \
+ 0x9E, 0xD5, 0x29, 0x07, 0x70, 0x96, 0x96, 0x6D, \
+ 0x67, 0x0C, 0x35, 0x4E, 0x4A, 0xBC, 0x98, 0x04, \
+ 0xF1, 0x74, 0x6C, 0x08, 0xCA, 0x18, 0x21, 0x7C, \
+ 0x32, 0x90, 0x5E, 0x46, 0x2E, 0x36, 0xCE, 0x3B, \
+ 0xE3, 0x9E, 0x77, 0x2C, 0x18, 0x0E, 0x86, 0x03, \
+ 0x9B, 0x27, 0x83, 0xA2, 0xEC, 0x07, 0xA2, 0x8F, \
+ 0xB5, 0xC5, 0x5D, 0xF0, 0x6F, 0x4C, 0x52, 0xC9, \
+ 0xDE, 0x2B, 0xCB, 0xF6, 0x95, 0x58, 0x17, 0x18, \
+ 0x39, 0x95, 0x49, 0x7C, 0xEA, 0x95, 0x6A, 0xE5, \
+ 0x15, 0xD2, 0x26, 0x18, 0x98, 0xFA, 0x05, 0x10, \
+ 0x15, 0x72, 0x8E, 0x5A, 0x8A, 0xAA, 0xC4, 0x2D, \
+ 0xAD, 0x33, 0x17, 0x0D, 0x04, 0x50, 0x7A, 0x33, \
+ 0xA8, 0x55, 0x21, 0xAB, 0xDF, 0x1C, 0xBA, 0x64, \
+ 0xEC, 0xFB, 0x85, 0x04, 0x58, 0xDB, 0xEF, 0x0A, \
+ 0x8A, 0xEA, 0x71, 0x57, 0x5D, 0x06, 0x0C, 0x7D, \
+ 0xB3, 0x97, 0x0F, 0x85, 0xA6, 0xE1, 0xE4, 0xC7, \
+ 0xAB, 0xF5, 0xAE, 0x8C, 0xDB, 0x09, 0x33, 0xD7, \
+ 0x1E, 0x8C, 0x94, 0xE0, 0x4A, 0x25, 0x61, 0x9D, \
+ 0xCE, 0xE3, 0xD2, 0x26, 0x1A, 0xD2, 0xEE, 0x6B, \
+ 0xF1, 0x2F, 0xFA, 0x06, 0xD9, 0x8A, 0x08, 0x64, \
+ 0xD8, 0x76, 0x02, 0x73, 0x3E, 0xC8, 0x6A, 0x64, \
+ 0x52, 0x1F, 0x2B, 0x18, 0x17, 0x7B, 0x20, 0x0C, \
+ 0xBB, 0xE1, 0x17, 0x57, 0x7A, 0x61, 0x5D, 0x6C, \
+ 0x77, 0x09, 0x88, 0xC0, 0xBA, 0xD9, 0x46, 0xE2, \
+ 0x08, 0xE2, 0x4F, 0xA0, 0x74, 0xE5, 0xAB, 0x31, \
+ 0x43, 0xDB, 0x5B, 0xFC, 0xE0, 0xFD, 0x10, 0x8E, \
+ 0x4B, 0x82, 0xD1, 0x20, 0xA9, 0x3A, 0xD2, 0xCA, \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }
+
+#define MBEDTLS_DHM_RFC3526_MODP_3072_G_BIN { 0x02 }
+
+#define MBEDTLS_DHM_RFC3526_MODP_4096_P_BIN { \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, \
+ 0xC9, 0x0F, 0xDA, 0xA2, 0x21, 0x68, 0xC2, 0x34, \
+ 0xC4, 0xC6, 0x62, 0x8B, 0x80, 0xDC, 0x1C, 0xD1, \
+ 0x29, 0x02, 0x4E, 0x08, 0x8A, 0x67, 0xCC, 0x74, \
+ 0x02, 0x0B, 0xBE, 0xA6, 0x3B, 0x13, 0x9B, 0x22, \
+ 0x51, 0x4A, 0x08, 0x79, 0x8E, 0x34, 0x04, 0xDD, \
+ 0xEF, 0x95, 0x19, 0xB3, 0xCD, 0x3A, 0x43, 0x1B, \
+ 0x30, 0x2B, 0x0A, 0x6D, 0xF2, 0x5F, 0x14, 0x37, \
+ 0x4F, 0xE1, 0x35, 0x6D, 0x6D, 0x51, 0xC2, 0x45, \
+ 0xE4, 0x85, 0xB5, 0x76, 0x62, 0x5E, 0x7E, 0xC6, \
+ 0xF4, 0x4C, 0x42, 0xE9, 0xA6, 0x37, 0xED, 0x6B, \
+ 0x0B, 0xFF, 0x5C, 0xB6, 0xF4, 0x06, 0xB7, 0xED, \
+ 0xEE, 0x38, 0x6B, 0xFB, 0x5A, 0x89, 0x9F, 0xA5, \
+ 0xAE, 0x9F, 0x24, 0x11, 0x7C, 0x4B, 0x1F, 0xE6, \
+ 0x49, 0x28, 0x66, 0x51, 0xEC, 0xE4, 0x5B, 0x3D, \
+ 0xC2, 0x00, 0x7C, 0xB8, 0xA1, 0x63, 0xBF, 0x05, \
+ 0x98, 0xDA, 0x48, 0x36, 0x1C, 0x55, 0xD3, 0x9A, \
+ 0x69, 0x16, 0x3F, 0xA8, 0xFD, 0x24, 0xCF, 0x5F, \
+ 0x83, 0x65, 0x5D, 0x23, 0xDC, 0xA3, 0xAD, 0x96, \
+ 0x1C, 0x62, 0xF3, 0x56, 0x20, 0x85, 0x52, 0xBB, \
+ 0x9E, 0xD5, 0x29, 0x07, 0x70, 0x96, 0x96, 0x6D, \
+ 0x67, 0x0C, 0x35, 0x4E, 0x4A, 0xBC, 0x98, 0x04, \
+ 0xF1, 0x74, 0x6C, 0x08, 0xCA, 0x18, 0x21, 0x7C, \
+ 0x32, 0x90, 0x5E, 0x46, 0x2E, 0x36, 0xCE, 0x3B, \
+ 0xE3, 0x9E, 0x77, 0x2C, 0x18, 0x0E, 0x86, 0x03, \
+ 0x9B, 0x27, 0x83, 0xA2, 0xEC, 0x07, 0xA2, 0x8F, \
+ 0xB5, 0xC5, 0x5D, 0xF0, 0x6F, 0x4C, 0x52, 0xC9, \
+ 0xDE, 0x2B, 0xCB, 0xF6, 0x95, 0x58, 0x17, 0x18, \
+ 0x39, 0x95, 0x49, 0x7C, 0xEA, 0x95, 0x6A, 0xE5, \
+ 0x15, 0xD2, 0x26, 0x18, 0x98, 0xFA, 0x05, 0x10, \
+ 0x15, 0x72, 0x8E, 0x5A, 0x8A, 0xAA, 0xC4, 0x2D, \
+ 0xAD, 0x33, 0x17, 0x0D, 0x04, 0x50, 0x7A, 0x33, \
+ 0xA8, 0x55, 0x21, 0xAB, 0xDF, 0x1C, 0xBA, 0x64, \
+ 0xEC, 0xFB, 0x85, 0x04, 0x58, 0xDB, 0xEF, 0x0A, \
+ 0x8A, 0xEA, 0x71, 0x57, 0x5D, 0x06, 0x0C, 0x7D, \
+ 0xB3, 0x97, 0x0F, 0x85, 0xA6, 0xE1, 0xE4, 0xC7, \
+ 0xAB, 0xF5, 0xAE, 0x8C, 0xDB, 0x09, 0x33, 0xD7, \
+ 0x1E, 0x8C, 0x94, 0xE0, 0x4A, 0x25, 0x61, 0x9D, \
+ 0xCE, 0xE3, 0xD2, 0x26, 0x1A, 0xD2, 0xEE, 0x6B, \
+ 0xF1, 0x2F, 0xFA, 0x06, 0xD9, 0x8A, 0x08, 0x64, \
+ 0xD8, 0x76, 0x02, 0x73, 0x3E, 0xC8, 0x6A, 0x64, \
+ 0x52, 0x1F, 0x2B, 0x18, 0x17, 0x7B, 0x20, 0x0C, \
+ 0xBB, 0xE1, 0x17, 0x57, 0x7A, 0x61, 0x5D, 0x6C, \
+ 0x77, 0x09, 0x88, 0xC0, 0xBA, 0xD9, 0x46, 0xE2, \
+ 0x08, 0xE2, 0x4F, 0xA0, 0x74, 0xE5, 0xAB, 0x31, \
+ 0x43, 0xDB, 0x5B, 0xFC, 0xE0, 0xFD, 0x10, 0x8E, \
+ 0x4B, 0x82, 0xD1, 0x20, 0xA9, 0x21, 0x08, 0x01, \
+ 0x1A, 0x72, 0x3C, 0x12, 0xA7, 0x87, 0xE6, 0xD7, \
+ 0x88, 0x71, 0x9A, 0x10, 0xBD, 0xBA, 0x5B, 0x26, \
+ 0x99, 0xC3, 0x27, 0x18, 0x6A, 0xF4, 0xE2, 0x3C, \
+ 0x1A, 0x94, 0x68, 0x34, 0xB6, 0x15, 0x0B, 0xDA, \
+ 0x25, 0x83, 0xE9, 0xCA, 0x2A, 0xD4, 0x4C, 0xE8, \
+ 0xDB, 0xBB, 0xC2, 0xDB, 0x04, 0xDE, 0x8E, 0xF9, \
+ 0x2E, 0x8E, 0xFC, 0x14, 0x1F, 0xBE, 0xCA, 0xA6, \
+ 0x28, 0x7C, 0x59, 0x47, 0x4E, 0x6B, 0xC0, 0x5D, \
+ 0x99, 0xB2, 0x96, 0x4F, 0xA0, 0x90, 0xC3, 0xA2, \
+ 0x23, 0x3B, 0xA1, 0x86, 0x51, 0x5B, 0xE7, 0xED, \
+ 0x1F, 0x61, 0x29, 0x70, 0xCE, 0xE2, 0xD7, 0xAF, \
+ 0xB8, 0x1B, 0xDD, 0x76, 0x21, 0x70, 0x48, 0x1C, \
+ 0xD0, 0x06, 0x91, 0x27, 0xD5, 0xB0, 0x5A, 0xA9, \
+ 0x93, 0xB4, 0xEA, 0x98, 0x8D, 0x8F, 0xDD, 0xC1, \
+ 0x86, 0xFF, 0xB7, 0xDC, 0x90, 0xA6, 0xC0, 0x8F, \
+ 0x4D, 0xF4, 0x35, 0xC9, 0x34, 0x06, 0x31, 0x99, \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }
+
+#define MBEDTLS_DHM_RFC3526_MODP_4096_G_BIN { 0x02 }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE2048_P_BIN { \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, \
+ 0xAD, 0xF8, 0x54, 0x58, 0xA2, 0xBB, 0x4A, 0x9A, \
+ 0xAF, 0xDC, 0x56, 0x20, 0x27, 0x3D, 0x3C, 0xF1, \
+ 0xD8, 0xB9, 0xC5, 0x83, 0xCE, 0x2D, 0x36, 0x95, \
+ 0xA9, 0xE1, 0x36, 0x41, 0x14, 0x64, 0x33, 0xFB, \
+ 0xCC, 0x93, 0x9D, 0xCE, 0x24, 0x9B, 0x3E, 0xF9, \
+ 0x7D, 0x2F, 0xE3, 0x63, 0x63, 0x0C, 0x75, 0xD8, \
+ 0xF6, 0x81, 0xB2, 0x02, 0xAE, 0xC4, 0x61, 0x7A, \
+ 0xD3, 0xDF, 0x1E, 0xD5, 0xD5, 0xFD, 0x65, 0x61, \
+ 0x24, 0x33, 0xF5, 0x1F, 0x5F, 0x06, 0x6E, 0xD0, \
+ 0x85, 0x63, 0x65, 0x55, 0x3D, 0xED, 0x1A, 0xF3, \
+ 0xB5, 0x57, 0x13, 0x5E, 0x7F, 0x57, 0xC9, 0x35, \
+ 0x98, 0x4F, 0x0C, 0x70, 0xE0, 0xE6, 0x8B, 0x77, \
+ 0xE2, 0xA6, 0x89, 0xDA, 0xF3, 0xEF, 0xE8, 0x72, \
+ 0x1D, 0xF1, 0x58, 0xA1, 0x36, 0xAD, 0xE7, 0x35, \
+ 0x30, 0xAC, 0xCA, 0x4F, 0x48, 0x3A, 0x79, 0x7A, \
+ 0xBC, 0x0A, 0xB1, 0x82, 0xB3, 0x24, 0xFB, 0x61, \
+ 0xD1, 0x08, 0xA9, 0x4B, 0xB2, 0xC8, 0xE3, 0xFB, \
+ 0xB9, 0x6A, 0xDA, 0xB7, 0x60, 0xD7, 0xF4, 0x68, \
+ 0x1D, 0x4F, 0x42, 0xA3, 0xDE, 0x39, 0x4D, 0xF4, \
+ 0xAE, 0x56, 0xED, 0xE7, 0x63, 0x72, 0xBB, 0x19, \
+ 0x0B, 0x07, 0xA7, 0xC8, 0xEE, 0x0A, 0x6D, 0x70, \
+ 0x9E, 0x02, 0xFC, 0xE1, 0xCD, 0xF7, 0xE2, 0xEC, \
+ 0xC0, 0x34, 0x04, 0xCD, 0x28, 0x34, 0x2F, 0x61, \
+ 0x91, 0x72, 0xFE, 0x9C, 0xE9, 0x85, 0x83, 0xFF, \
+ 0x8E, 0x4F, 0x12, 0x32, 0xEE, 0xF2, 0x81, 0x83, \
+ 0xC3, 0xFE, 0x3B, 0x1B, 0x4C, 0x6F, 0xAD, 0x73, \
+ 0x3B, 0xB5, 0xFC, 0xBC, 0x2E, 0xC2, 0x20, 0x05, \
+ 0xC5, 0x8E, 0xF1, 0x83, 0x7D, 0x16, 0x83, 0xB2, \
+ 0xC6, 0xF3, 0x4A, 0x26, 0xC1, 0xB2, 0xEF, 0xFA, \
+ 0x88, 0x6B, 0x42, 0x38, 0x61, 0x28, 0x5C, 0x97, \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE2048_G_BIN { 0x02 }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE3072_P_BIN { \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, \
+ 0xAD, 0xF8, 0x54, 0x58, 0xA2, 0xBB, 0x4A, 0x9A, \
+ 0xAF, 0xDC, 0x56, 0x20, 0x27, 0x3D, 0x3C, 0xF1, \
+ 0xD8, 0xB9, 0xC5, 0x83, 0xCE, 0x2D, 0x36, 0x95, \
+ 0xA9, 0xE1, 0x36, 0x41, 0x14, 0x64, 0x33, 0xFB, \
+ 0xCC, 0x93, 0x9D, 0xCE, 0x24, 0x9B, 0x3E, 0xF9, \
+ 0x7D, 0x2F, 0xE3, 0x63, 0x63, 0x0C, 0x75, 0xD8, \
+ 0xF6, 0x81, 0xB2, 0x02, 0xAE, 0xC4, 0x61, 0x7A, \
+ 0xD3, 0xDF, 0x1E, 0xD5, 0xD5, 0xFD, 0x65, 0x61, \
+ 0x24, 0x33, 0xF5, 0x1F, 0x5F, 0x06, 0x6E, 0xD0, \
+ 0x85, 0x63, 0x65, 0x55, 0x3D, 0xED, 0x1A, 0xF3, \
+ 0xB5, 0x57, 0x13, 0x5E, 0x7F, 0x57, 0xC9, 0x35, \
+ 0x98, 0x4F, 0x0C, 0x70, 0xE0, 0xE6, 0x8B, 0x77, \
+ 0xE2, 0xA6, 0x89, 0xDA, 0xF3, 0xEF, 0xE8, 0x72, \
+ 0x1D, 0xF1, 0x58, 0xA1, 0x36, 0xAD, 0xE7, 0x35, \
+ 0x30, 0xAC, 0xCA, 0x4F, 0x48, 0x3A, 0x79, 0x7A, \
+ 0xBC, 0x0A, 0xB1, 0x82, 0xB3, 0x24, 0xFB, 0x61, \
+ 0xD1, 0x08, 0xA9, 0x4B, 0xB2, 0xC8, 0xE3, 0xFB, \
+ 0xB9, 0x6A, 0xDA, 0xB7, 0x60, 0xD7, 0xF4, 0x68, \
+ 0x1D, 0x4F, 0x42, 0xA3, 0xDE, 0x39, 0x4D, 0xF4, \
+ 0xAE, 0x56, 0xED, 0xE7, 0x63, 0x72, 0xBB, 0x19, \
+ 0x0B, 0x07, 0xA7, 0xC8, 0xEE, 0x0A, 0x6D, 0x70, \
+ 0x9E, 0x02, 0xFC, 0xE1, 0xCD, 0xF7, 0xE2, 0xEC, \
+ 0xC0, 0x34, 0x04, 0xCD, 0x28, 0x34, 0x2F, 0x61, \
+ 0x91, 0x72, 0xFE, 0x9C, 0xE9, 0x85, 0x83, 0xFF, \
+ 0x8E, 0x4F, 0x12, 0x32, 0xEE, 0xF2, 0x81, 0x83, \
+ 0xC3, 0xFE, 0x3B, 0x1B, 0x4C, 0x6F, 0xAD, 0x73, \
+ 0x3B, 0xB5, 0xFC, 0xBC, 0x2E, 0xC2, 0x20, 0x05, \
+ 0xC5, 0x8E, 0xF1, 0x83, 0x7D, 0x16, 0x83, 0xB2, \
+ 0xC6, 0xF3, 0x4A, 0x26, 0xC1, 0xB2, 0xEF, 0xFA, \
+ 0x88, 0x6B, 0x42, 0x38, 0x61, 0x1F, 0xCF, 0xDC, \
+ 0xDE, 0x35, 0x5B, 0x3B, 0x65, 0x19, 0x03, 0x5B, \
+ 0xBC, 0x34, 0xF4, 0xDE, 0xF9, 0x9C, 0x02, 0x38, \
+ 0x61, 0xB4, 0x6F, 0xC9, 0xD6, 0xE6, 0xC9, 0x07, \
+ 0x7A, 0xD9, 0x1D, 0x26, 0x91, 0xF7, 0xF7, 0xEE, \
+ 0x59, 0x8C, 0xB0, 0xFA, 0xC1, 0x86, 0xD9, 0x1C, \
+ 0xAE, 0xFE, 0x13, 0x09, 0x85, 0x13, 0x92, 0x70, \
+ 0xB4, 0x13, 0x0C, 0x93, 0xBC, 0x43, 0x79, 0x44, \
+ 0xF4, 0xFD, 0x44, 0x52, 0xE2, 0xD7, 0x4D, 0xD3, \
+ 0x64, 0xF2, 0xE2, 0x1E, 0x71, 0xF5, 0x4B, 0xFF, \
+ 0x5C, 0xAE, 0x82, 0xAB, 0x9C, 0x9D, 0xF6, 0x9E, \
+ 0xE8, 0x6D, 0x2B, 0xC5, 0x22, 0x36, 0x3A, 0x0D, \
+ 0xAB, 0xC5, 0x21, 0x97, 0x9B, 0x0D, 0xEA, 0xDA, \
+ 0x1D, 0xBF, 0x9A, 0x42, 0xD5, 0xC4, 0x48, 0x4E, \
+ 0x0A, 0xBC, 0xD0, 0x6B, 0xFA, 0x53, 0xDD, 0xEF, \
+ 0x3C, 0x1B, 0x20, 0xEE, 0x3F, 0xD5, 0x9D, 0x7C, \
+ 0x25, 0xE4, 0x1D, 0x2B, 0x66, 0xC6, 0x2E, 0x37, \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE3072_G_BIN { 0x02 }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE4096_P_BIN { \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, \
+ 0xAD, 0xF8, 0x54, 0x58, 0xA2, 0xBB, 0x4A, 0x9A, \
+ 0xAF, 0xDC, 0x56, 0x20, 0x27, 0x3D, 0x3C, 0xF1, \
+ 0xD8, 0xB9, 0xC5, 0x83, 0xCE, 0x2D, 0x36, 0x95, \
+ 0xA9, 0xE1, 0x36, 0x41, 0x14, 0x64, 0x33, 0xFB, \
+ 0xCC, 0x93, 0x9D, 0xCE, 0x24, 0x9B, 0x3E, 0xF9, \
+ 0x7D, 0x2F, 0xE3, 0x63, 0x63, 0x0C, 0x75, 0xD8, \
+ 0xF6, 0x81, 0xB2, 0x02, 0xAE, 0xC4, 0x61, 0x7A, \
+ 0xD3, 0xDF, 0x1E, 0xD5, 0xD5, 0xFD, 0x65, 0x61, \
+ 0x24, 0x33, 0xF5, 0x1F, 0x5F, 0x06, 0x6E, 0xD0, \
+ 0x85, 0x63, 0x65, 0x55, 0x3D, 0xED, 0x1A, 0xF3, \
+ 0xB5, 0x57, 0x13, 0x5E, 0x7F, 0x57, 0xC9, 0x35, \
+ 0x98, 0x4F, 0x0C, 0x70, 0xE0, 0xE6, 0x8B, 0x77, \
+ 0xE2, 0xA6, 0x89, 0xDA, 0xF3, 0xEF, 0xE8, 0x72, \
+ 0x1D, 0xF1, 0x58, 0xA1, 0x36, 0xAD, 0xE7, 0x35, \
+ 0x30, 0xAC, 0xCA, 0x4F, 0x48, 0x3A, 0x79, 0x7A, \
+ 0xBC, 0x0A, 0xB1, 0x82, 0xB3, 0x24, 0xFB, 0x61, \
+ 0xD1, 0x08, 0xA9, 0x4B, 0xB2, 0xC8, 0xE3, 0xFB, \
+ 0xB9, 0x6A, 0xDA, 0xB7, 0x60, 0xD7, 0xF4, 0x68, \
+ 0x1D, 0x4F, 0x42, 0xA3, 0xDE, 0x39, 0x4D, 0xF4, \
+ 0xAE, 0x56, 0xED, 0xE7, 0x63, 0x72, 0xBB, 0x19, \
+ 0x0B, 0x07, 0xA7, 0xC8, 0xEE, 0x0A, 0x6D, 0x70, \
+ 0x9E, 0x02, 0xFC, 0xE1, 0xCD, 0xF7, 0xE2, 0xEC, \
+ 0xC0, 0x34, 0x04, 0xCD, 0x28, 0x34, 0x2F, 0x61, \
+ 0x91, 0x72, 0xFE, 0x9C, 0xE9, 0x85, 0x83, 0xFF, \
+ 0x8E, 0x4F, 0x12, 0x32, 0xEE, 0xF2, 0x81, 0x83, \
+ 0xC3, 0xFE, 0x3B, 0x1B, 0x4C, 0x6F, 0xAD, 0x73, \
+ 0x3B, 0xB5, 0xFC, 0xBC, 0x2E, 0xC2, 0x20, 0x05, \
+ 0xC5, 0x8E, 0xF1, 0x83, 0x7D, 0x16, 0x83, 0xB2, \
+ 0xC6, 0xF3, 0x4A, 0x26, 0xC1, 0xB2, 0xEF, 0xFA, \
+ 0x88, 0x6B, 0x42, 0x38, 0x61, 0x1F, 0xCF, 0xDC, \
+ 0xDE, 0x35, 0x5B, 0x3B, 0x65, 0x19, 0x03, 0x5B, \
+ 0xBC, 0x34, 0xF4, 0xDE, 0xF9, 0x9C, 0x02, 0x38, \
+ 0x61, 0xB4, 0x6F, 0xC9, 0xD6, 0xE6, 0xC9, 0x07, \
+ 0x7A, 0xD9, 0x1D, 0x26, 0x91, 0xF7, 0xF7, 0xEE, \
+ 0x59, 0x8C, 0xB0, 0xFA, 0xC1, 0x86, 0xD9, 0x1C, \
+ 0xAE, 0xFE, 0x13, 0x09, 0x85, 0x13, 0x92, 0x70, \
+ 0xB4, 0x13, 0x0C, 0x93, 0xBC, 0x43, 0x79, 0x44, \
+ 0xF4, 0xFD, 0x44, 0x52, 0xE2, 0xD7, 0x4D, 0xD3, \
+ 0x64, 0xF2, 0xE2, 0x1E, 0x71, 0xF5, 0x4B, 0xFF, \
+ 0x5C, 0xAE, 0x82, 0xAB, 0x9C, 0x9D, 0xF6, 0x9E, \
+ 0xE8, 0x6D, 0x2B, 0xC5, 0x22, 0x36, 0x3A, 0x0D, \
+ 0xAB, 0xC5, 0x21, 0x97, 0x9B, 0x0D, 0xEA, 0xDA, \
+ 0x1D, 0xBF, 0x9A, 0x42, 0xD5, 0xC4, 0x48, 0x4E, \
+ 0x0A, 0xBC, 0xD0, 0x6B, 0xFA, 0x53, 0xDD, 0xEF, \
+ 0x3C, 0x1B, 0x20, 0xEE, 0x3F, 0xD5, 0x9D, 0x7C, \
+ 0x25, 0xE4, 0x1D, 0x2B, 0x66, 0x9E, 0x1E, 0xF1, \
+ 0x6E, 0x6F, 0x52, 0xC3, 0x16, 0x4D, 0xF4, 0xFB, \
+ 0x79, 0x30, 0xE9, 0xE4, 0xE5, 0x88, 0x57, 0xB6, \
+ 0xAC, 0x7D, 0x5F, 0x42, 0xD6, 0x9F, 0x6D, 0x18, \
+ 0x77, 0x63, 0xCF, 0x1D, 0x55, 0x03, 0x40, 0x04, \
+ 0x87, 0xF5, 0x5B, 0xA5, 0x7E, 0x31, 0xCC, 0x7A, \
+ 0x71, 0x35, 0xC8, 0x86, 0xEF, 0xB4, 0x31, 0x8A, \
+ 0xED, 0x6A, 0x1E, 0x01, 0x2D, 0x9E, 0x68, 0x32, \
+ 0xA9, 0x07, 0x60, 0x0A, 0x91, 0x81, 0x30, 0xC4, \
+ 0x6D, 0xC7, 0x78, 0xF9, 0x71, 0xAD, 0x00, 0x38, \
+ 0x09, 0x29, 0x99, 0xA3, 0x33, 0xCB, 0x8B, 0x7A, \
+ 0x1A, 0x1D, 0xB9, 0x3D, 0x71, 0x40, 0x00, 0x3C, \
+ 0x2A, 0x4E, 0xCE, 0xA9, 0xF9, 0x8D, 0x0A, 0xCC, \
+ 0x0A, 0x82, 0x91, 0xCD, 0xCE, 0xC9, 0x7D, 0xCF, \
+ 0x8E, 0xC9, 0xB5, 0x5A, 0x7F, 0x88, 0xA4, 0x6B, \
+ 0x4D, 0xB5, 0xA8, 0x51, 0xF4, 0x41, 0x82, 0xE1, \
+ 0xC6, 0x8A, 0x00, 0x7E, 0x5E, 0x65, 0x5F, 0x6A, \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE4096_G_BIN { 0x02 }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE6144_P_BIN { \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, \
+ 0xAD, 0xF8, 0x54, 0x58, 0xA2, 0xBB, 0x4A, 0x9A, \
+ 0xAF, 0xDC, 0x56, 0x20, 0x27, 0x3D, 0x3C, 0xF1, \
+ 0xD8, 0xB9, 0xC5, 0x83, 0xCE, 0x2D, 0x36, 0x95, \
+ 0xA9, 0xE1, 0x36, 0x41, 0x14, 0x64, 0x33, 0xFB, \
+ 0xCC, 0x93, 0x9D, 0xCE, 0x24, 0x9B, 0x3E, 0xF9, \
+ 0x7D, 0x2F, 0xE3, 0x63, 0x63, 0x0C, 0x75, 0xD8, \
+ 0xF6, 0x81, 0xB2, 0x02, 0xAE, 0xC4, 0x61, 0x7A, \
+ 0xD3, 0xDF, 0x1E, 0xD5, 0xD5, 0xFD, 0x65, 0x61, \
+ 0x24, 0x33, 0xF5, 0x1F, 0x5F, 0x06, 0x6E, 0xD0, \
+ 0x85, 0x63, 0x65, 0x55, 0x3D, 0xED, 0x1A, 0xF3, \
+ 0xB5, 0x57, 0x13, 0x5E, 0x7F, 0x57, 0xC9, 0x35, \
+ 0x98, 0x4F, 0x0C, 0x70, 0xE0, 0xE6, 0x8B, 0x77, \
+ 0xE2, 0xA6, 0x89, 0xDA, 0xF3, 0xEF, 0xE8, 0x72, \
+ 0x1D, 0xF1, 0x58, 0xA1, 0x36, 0xAD, 0xE7, 0x35, \
+ 0x30, 0xAC, 0xCA, 0x4F, 0x48, 0x3A, 0x79, 0x7A, \
+ 0xBC, 0x0A, 0xB1, 0x82, 0xB3, 0x24, 0xFB, 0x61, \
+ 0xD1, 0x08, 0xA9, 0x4B, 0xB2, 0xC8, 0xE3, 0xFB, \
+ 0xB9, 0x6A, 0xDA, 0xB7, 0x60, 0xD7, 0xF4, 0x68, \
+ 0x1D, 0x4F, 0x42, 0xA3, 0xDE, 0x39, 0x4D, 0xF4, \
+ 0xAE, 0x56, 0xED, 0xE7, 0x63, 0x72, 0xBB, 0x19, \
+ 0x0B, 0x07, 0xA7, 0xC8, 0xEE, 0x0A, 0x6D, 0x70, \
+ 0x9E, 0x02, 0xFC, 0xE1, 0xCD, 0xF7, 0xE2, 0xEC, \
+ 0xC0, 0x34, 0x04, 0xCD, 0x28, 0x34, 0x2F, 0x61, \
+ 0x91, 0x72, 0xFE, 0x9C, 0xE9, 0x85, 0x83, 0xFF, \
+ 0x8E, 0x4F, 0x12, 0x32, 0xEE, 0xF2, 0x81, 0x83, \
+ 0xC3, 0xFE, 0x3B, 0x1B, 0x4C, 0x6F, 0xAD, 0x73, \
+ 0x3B, 0xB5, 0xFC, 0xBC, 0x2E, 0xC2, 0x20, 0x05, \
+ 0xC5, 0x8E, 0xF1, 0x83, 0x7D, 0x16, 0x83, 0xB2, \
+ 0xC6, 0xF3, 0x4A, 0x26, 0xC1, 0xB2, 0xEF, 0xFA, \
+ 0x88, 0x6B, 0x42, 0x38, 0x61, 0x1F, 0xCF, 0xDC, \
+ 0xDE, 0x35, 0x5B, 0x3B, 0x65, 0x19, 0x03, 0x5B, \
+ 0xBC, 0x34, 0xF4, 0xDE, 0xF9, 0x9C, 0x02, 0x38, \
+ 0x61, 0xB4, 0x6F, 0xC9, 0xD6, 0xE6, 0xC9, 0x07, \
+ 0x7A, 0xD9, 0x1D, 0x26, 0x91, 0xF7, 0xF7, 0xEE, \
+ 0x59, 0x8C, 0xB0, 0xFA, 0xC1, 0x86, 0xD9, 0x1C, \
+ 0xAE, 0xFE, 0x13, 0x09, 0x85, 0x13, 0x92, 0x70, \
+ 0xB4, 0x13, 0x0C, 0x93, 0xBC, 0x43, 0x79, 0x44, \
+ 0xF4, 0xFD, 0x44, 0x52, 0xE2, 0xD7, 0x4D, 0xD3, \
+ 0x64, 0xF2, 0xE2, 0x1E, 0x71, 0xF5, 0x4B, 0xFF, \
+ 0x5C, 0xAE, 0x82, 0xAB, 0x9C, 0x9D, 0xF6, 0x9E, \
+ 0xE8, 0x6D, 0x2B, 0xC5, 0x22, 0x36, 0x3A, 0x0D, \
+ 0xAB, 0xC5, 0x21, 0x97, 0x9B, 0x0D, 0xEA, 0xDA, \
+ 0x1D, 0xBF, 0x9A, 0x42, 0xD5, 0xC4, 0x48, 0x4E, \
+ 0x0A, 0xBC, 0xD0, 0x6B, 0xFA, 0x53, 0xDD, 0xEF, \
+ 0x3C, 0x1B, 0x20, 0xEE, 0x3F, 0xD5, 0x9D, 0x7C, \
+ 0x25, 0xE4, 0x1D, 0x2B, 0x66, 0x9E, 0x1E, 0xF1, \
+ 0x6E, 0x6F, 0x52, 0xC3, 0x16, 0x4D, 0xF4, 0xFB, \
+ 0x79, 0x30, 0xE9, 0xE4, 0xE5, 0x88, 0x57, 0xB6, \
+ 0xAC, 0x7D, 0x5F, 0x42, 0xD6, 0x9F, 0x6D, 0x18, \
+ 0x77, 0x63, 0xCF, 0x1D, 0x55, 0x03, 0x40, 0x04, \
+ 0x87, 0xF5, 0x5B, 0xA5, 0x7E, 0x31, 0xCC, 0x7A, \
+ 0x71, 0x35, 0xC8, 0x86, 0xEF, 0xB4, 0x31, 0x8A, \
+ 0xED, 0x6A, 0x1E, 0x01, 0x2D, 0x9E, 0x68, 0x32, \
+ 0xA9, 0x07, 0x60, 0x0A, 0x91, 0x81, 0x30, 0xC4, \
+ 0x6D, 0xC7, 0x78, 0xF9, 0x71, 0xAD, 0x00, 0x38, \
+ 0x09, 0x29, 0x99, 0xA3, 0x33, 0xCB, 0x8B, 0x7A, \
+ 0x1A, 0x1D, 0xB9, 0x3D, 0x71, 0x40, 0x00, 0x3C, \
+ 0x2A, 0x4E, 0xCE, 0xA9, 0xF9, 0x8D, 0x0A, 0xCC, \
+ 0x0A, 0x82, 0x91, 0xCD, 0xCE, 0xC9, 0x7D, 0xCF, \
+ 0x8E, 0xC9, 0xB5, 0x5A, 0x7F, 0x88, 0xA4, 0x6B, \
+ 0x4D, 0xB5, 0xA8, 0x51, 0xF4, 0x41, 0x82, 0xE1, \
+ 0xC6, 0x8A, 0x00, 0x7E, 0x5E, 0x0D, 0xD9, 0x02, \
+ 0x0B, 0xFD, 0x64, 0xB6, 0x45, 0x03, 0x6C, 0x7A, \
+ 0x4E, 0x67, 0x7D, 0x2C, 0x38, 0x53, 0x2A, 0x3A, \
+ 0x23, 0xBA, 0x44, 0x42, 0xCA, 0xF5, 0x3E, 0xA6, \
+ 0x3B, 0xB4, 0x54, 0x32, 0x9B, 0x76, 0x24, 0xC8, \
+ 0x91, 0x7B, 0xDD, 0x64, 0xB1, 0xC0, 0xFD, 0x4C, \
+ 0xB3, 0x8E, 0x8C, 0x33, 0x4C, 0x70, 0x1C, 0x3A, \
+ 0xCD, 0xAD, 0x06, 0x57, 0xFC, 0xCF, 0xEC, 0x71, \
+ 0x9B, 0x1F, 0x5C, 0x3E, 0x4E, 0x46, 0x04, 0x1F, \
+ 0x38, 0x81, 0x47, 0xFB, 0x4C, 0xFD, 0xB4, 0x77, \
+ 0xA5, 0x24, 0x71, 0xF7, 0xA9, 0xA9, 0x69, 0x10, \
+ 0xB8, 0x55, 0x32, 0x2E, 0xDB, 0x63, 0x40, 0xD8, \
+ 0xA0, 0x0E, 0xF0, 0x92, 0x35, 0x05, 0x11, 0xE3, \
+ 0x0A, 0xBE, 0xC1, 0xFF, 0xF9, 0xE3, 0xA2, 0x6E, \
+ 0x7F, 0xB2, 0x9F, 0x8C, 0x18, 0x30, 0x23, 0xC3, \
+ 0x58, 0x7E, 0x38, 0xDA, 0x00, 0x77, 0xD9, 0xB4, \
+ 0x76, 0x3E, 0x4E, 0x4B, 0x94, 0xB2, 0xBB, 0xC1, \
+ 0x94, 0xC6, 0x65, 0x1E, 0x77, 0xCA, 0xF9, 0x92, \
+ 0xEE, 0xAA, 0xC0, 0x23, 0x2A, 0x28, 0x1B, 0xF6, \
+ 0xB3, 0xA7, 0x39, 0xC1, 0x22, 0x61, 0x16, 0x82, \
+ 0x0A, 0xE8, 0xDB, 0x58, 0x47, 0xA6, 0x7C, 0xBE, \
+ 0xF9, 0xC9, 0x09, 0x1B, 0x46, 0x2D, 0x53, 0x8C, \
+ 0xD7, 0x2B, 0x03, 0x74, 0x6A, 0xE7, 0x7F, 0x5E, \
+ 0x62, 0x29, 0x2C, 0x31, 0x15, 0x62, 0xA8, 0x46, \
+ 0x50, 0x5D, 0xC8, 0x2D, 0xB8, 0x54, 0x33, 0x8A, \
+ 0xE4, 0x9F, 0x52, 0x35, 0xC9, 0x5B, 0x91, 0x17, \
+ 0x8C, 0xCF, 0x2D, 0xD5, 0xCA, 0xCE, 0xF4, 0x03, \
+ 0xEC, 0x9D, 0x18, 0x10, 0xC6, 0x27, 0x2B, 0x04, \
+ 0x5B, 0x3B, 0x71, 0xF9, 0xDC, 0x6B, 0x80, 0xD6, \
+ 0x3F, 0xDD, 0x4A, 0x8E, 0x9A, 0xDB, 0x1E, 0x69, \
+ 0x62, 0xA6, 0x95, 0x26, 0xD4, 0x31, 0x61, 0xC1, \
+ 0xA4, 0x1D, 0x57, 0x0D, 0x79, 0x38, 0xDA, 0xD4, \
+ 0xA4, 0x0E, 0x32, 0x9C, 0xD0, 0xE4, 0x0E, 0x65, \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE6144_G_BIN { 0x02 }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE8192_P_BIN { \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, \
+ 0xAD, 0xF8, 0x54, 0x58, 0xA2, 0xBB, 0x4A, 0x9A, \
+ 0xAF, 0xDC, 0x56, 0x20, 0x27, 0x3D, 0x3C, 0xF1, \
+ 0xD8, 0xB9, 0xC5, 0x83, 0xCE, 0x2D, 0x36, 0x95, \
+ 0xA9, 0xE1, 0x36, 0x41, 0x14, 0x64, 0x33, 0xFB, \
+ 0xCC, 0x93, 0x9D, 0xCE, 0x24, 0x9B, 0x3E, 0xF9, \
+ 0x7D, 0x2F, 0xE3, 0x63, 0x63, 0x0C, 0x75, 0xD8, \
+ 0xF6, 0x81, 0xB2, 0x02, 0xAE, 0xC4, 0x61, 0x7A, \
+ 0xD3, 0xDF, 0x1E, 0xD5, 0xD5, 0xFD, 0x65, 0x61, \
+ 0x24, 0x33, 0xF5, 0x1F, 0x5F, 0x06, 0x6E, 0xD0, \
+ 0x85, 0x63, 0x65, 0x55, 0x3D, 0xED, 0x1A, 0xF3, \
+ 0xB5, 0x57, 0x13, 0x5E, 0x7F, 0x57, 0xC9, 0x35, \
+ 0x98, 0x4F, 0x0C, 0x70, 0xE0, 0xE6, 0x8B, 0x77, \
+ 0xE2, 0xA6, 0x89, 0xDA, 0xF3, 0xEF, 0xE8, 0x72, \
+ 0x1D, 0xF1, 0x58, 0xA1, 0x36, 0xAD, 0xE7, 0x35, \
+ 0x30, 0xAC, 0xCA, 0x4F, 0x48, 0x3A, 0x79, 0x7A, \
+ 0xBC, 0x0A, 0xB1, 0x82, 0xB3, 0x24, 0xFB, 0x61, \
+ 0xD1, 0x08, 0xA9, 0x4B, 0xB2, 0xC8, 0xE3, 0xFB, \
+ 0xB9, 0x6A, 0xDA, 0xB7, 0x60, 0xD7, 0xF4, 0x68, \
+ 0x1D, 0x4F, 0x42, 0xA3, 0xDE, 0x39, 0x4D, 0xF4, \
+ 0xAE, 0x56, 0xED, 0xE7, 0x63, 0x72, 0xBB, 0x19, \
+ 0x0B, 0x07, 0xA7, 0xC8, 0xEE, 0x0A, 0x6D, 0x70, \
+ 0x9E, 0x02, 0xFC, 0xE1, 0xCD, 0xF7, 0xE2, 0xEC, \
+ 0xC0, 0x34, 0x04, 0xCD, 0x28, 0x34, 0x2F, 0x61, \
+ 0x91, 0x72, 0xFE, 0x9C, 0xE9, 0x85, 0x83, 0xFF, \
+ 0x8E, 0x4F, 0x12, 0x32, 0xEE, 0xF2, 0x81, 0x83, \
+ 0xC3, 0xFE, 0x3B, 0x1B, 0x4C, 0x6F, 0xAD, 0x73, \
+ 0x3B, 0xB5, 0xFC, 0xBC, 0x2E, 0xC2, 0x20, 0x05, \
+ 0xC5, 0x8E, 0xF1, 0x83, 0x7D, 0x16, 0x83, 0xB2, \
+ 0xC6, 0xF3, 0x4A, 0x26, 0xC1, 0xB2, 0xEF, 0xFA, \
+ 0x88, 0x6B, 0x42, 0x38, 0x61, 0x1F, 0xCF, 0xDC, \
+ 0xDE, 0x35, 0x5B, 0x3B, 0x65, 0x19, 0x03, 0x5B, \
+ 0xBC, 0x34, 0xF4, 0xDE, 0xF9, 0x9C, 0x02, 0x38, \
+ 0x61, 0xB4, 0x6F, 0xC9, 0xD6, 0xE6, 0xC9, 0x07, \
+ 0x7A, 0xD9, 0x1D, 0x26, 0x91, 0xF7, 0xF7, 0xEE, \
+ 0x59, 0x8C, 0xB0, 0xFA, 0xC1, 0x86, 0xD9, 0x1C, \
+ 0xAE, 0xFE, 0x13, 0x09, 0x85, 0x13, 0x92, 0x70, \
+ 0xB4, 0x13, 0x0C, 0x93, 0xBC, 0x43, 0x79, 0x44, \
+ 0xF4, 0xFD, 0x44, 0x52, 0xE2, 0xD7, 0x4D, 0xD3, \
+ 0x64, 0xF2, 0xE2, 0x1E, 0x71, 0xF5, 0x4B, 0xFF, \
+ 0x5C, 0xAE, 0x82, 0xAB, 0x9C, 0x9D, 0xF6, 0x9E, \
+ 0xE8, 0x6D, 0x2B, 0xC5, 0x22, 0x36, 0x3A, 0x0D, \
+ 0xAB, 0xC5, 0x21, 0x97, 0x9B, 0x0D, 0xEA, 0xDA, \
+ 0x1D, 0xBF, 0x9A, 0x42, 0xD5, 0xC4, 0x48, 0x4E, \
+ 0x0A, 0xBC, 0xD0, 0x6B, 0xFA, 0x53, 0xDD, 0xEF, \
+ 0x3C, 0x1B, 0x20, 0xEE, 0x3F, 0xD5, 0x9D, 0x7C, \
+ 0x25, 0xE4, 0x1D, 0x2B, 0x66, 0x9E, 0x1E, 0xF1, \
+ 0x6E, 0x6F, 0x52, 0xC3, 0x16, 0x4D, 0xF4, 0xFB, \
+ 0x79, 0x30, 0xE9, 0xE4, 0xE5, 0x88, 0x57, 0xB6, \
+ 0xAC, 0x7D, 0x5F, 0x42, 0xD6, 0x9F, 0x6D, 0x18, \
+ 0x77, 0x63, 0xCF, 0x1D, 0x55, 0x03, 0x40, 0x04, \
+ 0x87, 0xF5, 0x5B, 0xA5, 0x7E, 0x31, 0xCC, 0x7A, \
+ 0x71, 0x35, 0xC8, 0x86, 0xEF, 0xB4, 0x31, 0x8A, \
+ 0xED, 0x6A, 0x1E, 0x01, 0x2D, 0x9E, 0x68, 0x32, \
+ 0xA9, 0x07, 0x60, 0x0A, 0x91, 0x81, 0x30, 0xC4, \
+ 0x6D, 0xC7, 0x78, 0xF9, 0x71, 0xAD, 0x00, 0x38, \
+ 0x09, 0x29, 0x99, 0xA3, 0x33, 0xCB, 0x8B, 0x7A, \
+ 0x1A, 0x1D, 0xB9, 0x3D, 0x71, 0x40, 0x00, 0x3C, \
+ 0x2A, 0x4E, 0xCE, 0xA9, 0xF9, 0x8D, 0x0A, 0xCC, \
+ 0x0A, 0x82, 0x91, 0xCD, 0xCE, 0xC9, 0x7D, 0xCF, \
+ 0x8E, 0xC9, 0xB5, 0x5A, 0x7F, 0x88, 0xA4, 0x6B, \
+ 0x4D, 0xB5, 0xA8, 0x51, 0xF4, 0x41, 0x82, 0xE1, \
+ 0xC6, 0x8A, 0x00, 0x7E, 0x5E, 0x0D, 0xD9, 0x02, \
+ 0x0B, 0xFD, 0x64, 0xB6, 0x45, 0x03, 0x6C, 0x7A, \
+ 0x4E, 0x67, 0x7D, 0x2C, 0x38, 0x53, 0x2A, 0x3A, \
+ 0x23, 0xBA, 0x44, 0x42, 0xCA, 0xF5, 0x3E, 0xA6, \
+ 0x3B, 0xB4, 0x54, 0x32, 0x9B, 0x76, 0x24, 0xC8, \
+ 0x91, 0x7B, 0xDD, 0x64, 0xB1, 0xC0, 0xFD, 0x4C, \
+ 0xB3, 0x8E, 0x8C, 0x33, 0x4C, 0x70, 0x1C, 0x3A, \
+ 0xCD, 0xAD, 0x06, 0x57, 0xFC, 0xCF, 0xEC, 0x71, \
+ 0x9B, 0x1F, 0x5C, 0x3E, 0x4E, 0x46, 0x04, 0x1F, \
+ 0x38, 0x81, 0x47, 0xFB, 0x4C, 0xFD, 0xB4, 0x77, \
+ 0xA5, 0x24, 0x71, 0xF7, 0xA9, 0xA9, 0x69, 0x10, \
+ 0xB8, 0x55, 0x32, 0x2E, 0xDB, 0x63, 0x40, 0xD8, \
+ 0xA0, 0x0E, 0xF0, 0x92, 0x35, 0x05, 0x11, 0xE3, \
+ 0x0A, 0xBE, 0xC1, 0xFF, 0xF9, 0xE3, 0xA2, 0x6E, \
+ 0x7F, 0xB2, 0x9F, 0x8C, 0x18, 0x30, 0x23, 0xC3, \
+ 0x58, 0x7E, 0x38, 0xDA, 0x00, 0x77, 0xD9, 0xB4, \
+ 0x76, 0x3E, 0x4E, 0x4B, 0x94, 0xB2, 0xBB, 0xC1, \
+ 0x94, 0xC6, 0x65, 0x1E, 0x77, 0xCA, 0xF9, 0x92, \
+ 0xEE, 0xAA, 0xC0, 0x23, 0x2A, 0x28, 0x1B, 0xF6, \
+ 0xB3, 0xA7, 0x39, 0xC1, 0x22, 0x61, 0x16, 0x82, \
+ 0x0A, 0xE8, 0xDB, 0x58, 0x47, 0xA6, 0x7C, 0xBE, \
+ 0xF9, 0xC9, 0x09, 0x1B, 0x46, 0x2D, 0x53, 0x8C, \
+ 0xD7, 0x2B, 0x03, 0x74, 0x6A, 0xE7, 0x7F, 0x5E, \
+ 0x62, 0x29, 0x2C, 0x31, 0x15, 0x62, 0xA8, 0x46, \
+ 0x50, 0x5D, 0xC8, 0x2D, 0xB8, 0x54, 0x33, 0x8A, \
+ 0xE4, 0x9F, 0x52, 0x35, 0xC9, 0x5B, 0x91, 0x17, \
+ 0x8C, 0xCF, 0x2D, 0xD5, 0xCA, 0xCE, 0xF4, 0x03, \
+ 0xEC, 0x9D, 0x18, 0x10, 0xC6, 0x27, 0x2B, 0x04, \
+ 0x5B, 0x3B, 0x71, 0xF9, 0xDC, 0x6B, 0x80, 0xD6, \
+ 0x3F, 0xDD, 0x4A, 0x8E, 0x9A, 0xDB, 0x1E, 0x69, \
+ 0x62, 0xA6, 0x95, 0x26, 0xD4, 0x31, 0x61, 0xC1, \
+ 0xA4, 0x1D, 0x57, 0x0D, 0x79, 0x38, 0xDA, 0xD4, \
+ 0xA4, 0x0E, 0x32, 0x9C, 0xCF, 0xF4, 0x6A, 0xAA, \
+ 0x36, 0xAD, 0x00, 0x4C, 0xF6, 0x00, 0xC8, 0x38, \
+ 0x1E, 0x42, 0x5A, 0x31, 0xD9, 0x51, 0xAE, 0x64, \
+ 0xFD, 0xB2, 0x3F, 0xCE, 0xC9, 0x50, 0x9D, 0x43, \
+ 0x68, 0x7F, 0xEB, 0x69, 0xED, 0xD1, 0xCC, 0x5E, \
+ 0x0B, 0x8C, 0xC3, 0xBD, 0xF6, 0x4B, 0x10, 0xEF, \
+ 0x86, 0xB6, 0x31, 0x42, 0xA3, 0xAB, 0x88, 0x29, \
+ 0x55, 0x5B, 0x2F, 0x74, 0x7C, 0x93, 0x26, 0x65, \
+ 0xCB, 0x2C, 0x0F, 0x1C, 0xC0, 0x1B, 0xD7, 0x02, \
+ 0x29, 0x38, 0x88, 0x39, 0xD2, 0xAF, 0x05, 0xE4, \
+ 0x54, 0x50, 0x4A, 0xC7, 0x8B, 0x75, 0x82, 0x82, \
+ 0x28, 0x46, 0xC0, 0xBA, 0x35, 0xC3, 0x5F, 0x5C, \
+ 0x59, 0x16, 0x0C, 0xC0, 0x46, 0xFD, 0x82, 0x51, \
+ 0x54, 0x1F, 0xC6, 0x8C, 0x9C, 0x86, 0xB0, 0x22, \
+ 0xBB, 0x70, 0x99, 0x87, 0x6A, 0x46, 0x0E, 0x74, \
+ 0x51, 0xA8, 0xA9, 0x31, 0x09, 0x70, 0x3F, 0xEE, \
+ 0x1C, 0x21, 0x7E, 0x6C, 0x38, 0x26, 0xE5, 0x2C, \
+ 0x51, 0xAA, 0x69, 0x1E, 0x0E, 0x42, 0x3C, 0xFC, \
+ 0x99, 0xE9, 0xE3, 0x16, 0x50, 0xC1, 0x21, 0x7B, \
+ 0x62, 0x48, 0x16, 0xCD, 0xAD, 0x9A, 0x95, 0xF9, \
+ 0xD5, 0xB8, 0x01, 0x94, 0x88, 0xD9, 0xC0, 0xA0, \
+ 0xA1, 0xFE, 0x30, 0x75, 0xA5, 0x77, 0xE2, 0x31, \
+ 0x83, 0xF8, 0x1D, 0x4A, 0x3F, 0x2F, 0xA4, 0x57, \
+ 0x1E, 0xFC, 0x8C, 0xE0, 0xBA, 0x8A, 0x4F, 0xE8, \
+ 0xB6, 0x85, 0x5D, 0xFE, 0x72, 0xB0, 0xA6, 0x6E, \
+ 0xDE, 0xD2, 0xFB, 0xAB, 0xFB, 0xE5, 0x8A, 0x30, \
+ 0xFA, 0xFA, 0xBE, 0x1C, 0x5D, 0x71, 0xA8, 0x7E, \
+ 0x2F, 0x74, 0x1E, 0xF8, 0xC1, 0xFE, 0x86, 0xFE, \
+ 0xA6, 0xBB, 0xFD, 0xE5, 0x30, 0x67, 0x7F, 0x0D, \
+ 0x97, 0xD1, 0x1D, 0x49, 0xF7, 0xA8, 0x44, 0x3D, \
+ 0x08, 0x22, 0xE5, 0x06, 0xA9, 0xF4, 0x61, 0x4E, \
+ 0x01, 0x1E, 0x2A, 0x94, 0x83, 0x8F, 0xF8, 0x8C, \
+ 0xD6, 0x8C, 0x8B, 0xB7, 0xC5, 0xC6, 0x42, 0x4C, \
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE8192_G_BIN { 0x02 }
+
#endif /* dhm.h */
diff --git a/include/mbedtls/ecdh.h b/include/mbedtls/ecdh.h
index 625a281..922f029 100644
--- a/include/mbedtls/ecdh.h
+++ b/include/mbedtls/ecdh.h
@@ -1,9 +1,19 @@
/**
* \file ecdh.h
*
- * \brief Elliptic curve Diffie-Hellman
+ * \brief This file contains ECDH definitions and functions.
+ *
+ * The Elliptic Curve Diffie-Hellman (ECDH) protocol 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.
*
- * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * 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-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
@@ -18,8 +28,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
@@ -30,65 +41,79 @@
#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.
*/
typedef enum
{
- MBEDTLS_ECDH_OURS,
- MBEDTLS_ECDH_THEIRS,
+ MBEDTLS_ECDH_OURS, /**< Our key. */
+ MBEDTLS_ECDH_THEIRS, /**< The key of the peer. */
} 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
+ * \see ecp.h
+ *
+ * \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 context.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or
+ * \c MBEDTLS_MPI_XXX error code on failure.
+ *
*/
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
+ * \see ecp.h
*
- * \note If f_rng is not NULL, it is used to implement
- * countermeasures against potential elaborate timing
- * attacks, see \c mbedtls_ecp_mul() for details.
+ * \note If \p f_rng is not NULL, it is used to implement
+ * countermeasures against side-channel attacks.
+ * For more information, see mbedtls_ecp_mul().
+ *
+ * \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 context.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or
+ * \c MBEDTLS_MPI_XXX error code on failure.
*/
int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
@@ -96,34 +121,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).
+ * \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 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
+ * \see ecp.h
+ *
+ * \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 context.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
*/
int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
unsigned char *buf, size_t blen,
@@ -131,45 +163,64 @@
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
+ * \see ecp.h
+ *
+ * \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.
+ * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
+ *
*/
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
+ * \see ecp.h
+ *
+ * \param ctx The ECDH context to set up.
+ * \param key The EC key to use.
+ * \param side Defines the source of the key: 1: Our key, or
+ * 0: The key of the peer.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
+ *
*/
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
+ * \see ecp.h
+ *
+ * \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 context.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
*/
int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
unsigned char *buf, size_t blen,
@@ -177,30 +228,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
+ * \see ecp.h
+ *
+ * \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.
+ * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
*/
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
+ * \note If \p f_rng is not NULL, it is used to implement
+ * countermeasures against side-channel attacks.
+ * For more information, see mbedtls_ecp_mul().
+ *
+ * \see ecp.h
+ *
+ * \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 context.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
*/
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 a277715..ff6efbc 100644
--- a/include/mbedtls/ecdsa.h
+++ b/include/mbedtls/ecdsa.h
@@ -1,9 +1,16 @@
/**
* \file ecdsa.h
*
- * \brief Elliptic curve DSA
+ * \brief The Elliptic Curve Digital Signature Algorithm (ECDSA).
*
- * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * 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-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
@@ -18,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
@@ -27,7 +35,7 @@
#include "md.h"
/*
- * RFC 4492 page 20:
+ * RFC-4492 page 20:
*
* Ecdsa-Sig-Value ::= SEQUENCE {
* r INTEGER,
@@ -43,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;
@@ -56,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,
@@ -82,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,
@@ -106,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,
@@ -170,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,
@@ -205,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 there is a valid
+ * signature in sig but its 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/ecjpake.h b/include/mbedtls/ecjpake.h
index 161a5b2..d86e820 100644
--- a/include/mbedtls/ecjpake.h
+++ b/include/mbedtls/ecjpake.h
@@ -2,7 +2,8 @@
* \file ecjpake.h
*
* \brief Elliptic curve J-PAKE
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -43,6 +44,8 @@
#include "ecp.h"
#include "md.h"
+#if !defined(MBEDTLS_ECJPAKE_ALT)
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -222,17 +225,31 @@
*/
void mbedtls_ecjpake_free( mbedtls_ecjpake_context *ctx );
+#ifdef __cplusplus
+}
+#endif
+
+#else /* MBEDTLS_ECJPAKE_ALT */
+#include "ecjpake_alt.h"
+#endif /* MBEDTLS_ECJPAKE_ALT */
+
#if defined(MBEDTLS_SELF_TEST)
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
/**
* \brief Checkup routine
*
* \return 0 if successful, or 1 if a test failed
*/
int mbedtls_ecjpake_self_test( int verbose );
-#endif
#ifdef __cplusplus
}
#endif
+#endif /* MBEDTLS_SELF_TEST */
+
#endif /* ecjpake.h */
diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h
index dad9aef..e024da8 100644
--- a/include/mbedtls/ecp.h
+++ b/include/mbedtls/ecp.h
@@ -2,7 +2,8 @@
* \file ecp.h
*
* \brief Elliptic curves over GF(p)
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -35,7 +36,8 @@
#define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80 /**< Memory allocation failed. */
#define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00 /**< Generation of random value, such as (ephemeral) key, failed. */
#define MBEDTLS_ERR_ECP_INVALID_KEY -0x4C80 /**< Invalid private or public key. */
-#define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH -0x4C00 /**< Signature is valid but shorter than the user-supplied length. */
+#define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH -0x4C00 /**< The buffer contains a valid signature followed by more data. */
+#define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED -0x4B80 /**< ECP hardware accelerator failed. */
#if !defined(MBEDTLS_ECP_ALT)
/*
@@ -70,7 +72,8 @@
MBEDTLS_ECP_DP_BP256R1, /*!< 256-bits Brainpool curve */
MBEDTLS_ECP_DP_BP384R1, /*!< 384-bits Brainpool curve */
MBEDTLS_ECP_DP_BP512R1, /*!< 512-bits Brainpool curve */
- MBEDTLS_ECP_DP_CURVE25519, /*!< Curve25519 */
+ MBEDTLS_ECP_DP_CURVE25519, /*!< Curve25519 */
+ MBEDTLS_ECP_DP_CURVE448, /*!< Curve448 */
MBEDTLS_ECP_DP_SECP192K1, /*!< 192-bits "Koblitz" curve */
MBEDTLS_ECP_DP_SECP224K1, /*!< 224-bits "Koblitz" curve */
MBEDTLS_ECP_DP_SECP256K1, /*!< 256-bits "Koblitz" curve */
@@ -142,7 +145,7 @@
mbedtls_mpi A; /*!< 1. A in the equation, or 2. (A + 2) / 4 */
mbedtls_mpi B; /*!< 1. B in the equation, or 2. unused */
mbedtls_ecp_point G; /*!< generator of the (sub)group used */
- mbedtls_mpi N; /*!< 1. the order of G, or 2. unused */
+ mbedtls_mpi N; /*!< the order of G */
size_t pbits; /*!< number of bits in P */
size_t nbits; /*!< number of bits in 1. P, or 2. private keys */
unsigned int h; /*!< internal: 1 if the constants are static */
diff --git a/include/mbedtls/ecp_internal.h b/include/mbedtls/ecp_internal.h
index 2991e26..8a6d517 100644
--- a/include/mbedtls/ecp_internal.h
+++ b/include/mbedtls/ecp_internal.h
@@ -3,7 +3,8 @@
*
* \brief Function declarations for alternative implementation of elliptic curve
* point arithmetic.
- *
+ */
+/*
* Copyright (C) 2016, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/entropy.h b/include/mbedtls/entropy.h
index 747aca4..fcb4d02 100644
--- a/include/mbedtls/entropy.h
+++ b/include/mbedtls/entropy.h
@@ -2,7 +2,8 @@
* \file entropy.h
*
* \brief Entropy accumulator implementation
- *
+ */
+/*
* Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -121,6 +122,7 @@
*/
typedef struct
{
+ int accumulator_started;
#if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
mbedtls_sha512_context accumulator;
#else
diff --git a/include/mbedtls/entropy_poll.h b/include/mbedtls/entropy_poll.h
index 81258d5..94dd657 100644
--- a/include/mbedtls/entropy_poll.h
+++ b/include/mbedtls/entropy_poll.h
@@ -2,7 +2,8 @@
* \file entropy_poll.h
*
* \brief Platform-specific and custom entropy polling functions
- *
+ */
+/*
* Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/error.h b/include/mbedtls/error.h
index 2fc9e46..698a5b6 100644
--- a/include/mbedtls/error.h
+++ b/include/mbedtls/error.h
@@ -2,7 +2,8 @@
* \file error.h
*
* \brief Error to string translation
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -49,23 +50,32 @@
*
* Module Nr Codes assigned
* MPI 7 0x0002-0x0010
- * GCM 2 0x0012-0x0014
- * BLOWFISH 2 0x0016-0x0018
+ * GCM 3 0x0012-0x0014 0x0013-0x0013
+ * BLOWFISH 3 0x0016-0x0018 0x0017-0x0017
* THREADING 3 0x001A-0x001E
- * AES 2 0x0020-0x0022 0x0023-0x0023
- * CAMELLIA 2 0x0024-0x0026
- * XTEA 1 0x0028-0x0028
+ * AES 4 0x0020-0x0022 0x0023-0x0025
+ * CAMELLIA 3 0x0024-0x0026 0x0027-0x0027
+ * XTEA 2 0x0028-0x0028 0x0029-0x0029
* BASE64 2 0x002A-0x002C
* OID 1 0x002E-0x002E 0x000B-0x000B
* PADLOCK 1 0x0030-0x0030
- * DES 1 0x0032-0x0032
+ * DES 2 0x0032-0x0032 0x0033-0x0033
* CTR_DBRG 4 0x0034-0x003A
* ENTROPY 3 0x003C-0x0040 0x003D-0x003F
* NET 11 0x0042-0x0052 0x0043-0x0045
* ASN1 7 0x0060-0x006C
+ * CMAC 1 0x007A-0x007A
* PBKDF2 1 0x007C-0x007C
- * HMAC_DRBG 4 0x0003-0x0009
- * CCM 2 0x000D-0x000F
+ * HMAC_DRBG 4 0x0003-0x0009
+ * CCM 3 0x000D-0x0011
+ * ARC4 1 0x0019-0x0019
+ * MD2 1 0x002B-0x002B
+ * MD4 1 0x002D-0x002D
+ * MD5 1 0x002F-0x002F
+ * RIPEMD160 1 0x0031-0x0031
+ * SHA1 1 0x0035-0x0035
+ * SHA256 1 0x0037-0x0037
+ * SHA512 1 0x0039-0x0039
*
* High-level module nr (3 bits - 0x0...-0x7...)
* Name ID Nr of Errors
@@ -73,13 +83,13 @@
* PKCS#12 1 4 (Started from top)
* X509 2 20
* PKCS5 2 4 (Started from top)
- * DHM 3 9
- * PK 3 14 (Started from top)
- * RSA 4 10
- * ECP 4 8 (Started from top)
- * MD 5 4
- * CIPHER 6 6
- * SSL 6 21 (Started from top)
+ * DHM 3 11
+ * PK 3 15 (Started from top)
+ * RSA 4 11
+ * ECP 4 9 (Started from top)
+ * MD 5 5
+ * CIPHER 6 8
+ * SSL 6 22 (Started from top)
* SSL 7 31
*
* Module dependent error code (5 bits 0x.00.-0x.F8.)
diff --git a/include/mbedtls/gcm.h b/include/mbedtls/gcm.h
index 8f3b565..1e5a507 100644
--- a/include/mbedtls/gcm.h
+++ b/include/mbedtls/gcm.h
@@ -1,9 +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>
*
- * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * 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-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
@@ -18,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
@@ -31,6 +39,7 @@
#define MBEDTLS_GCM_DECRYPT 0
#define MBEDTLS_ERR_GCM_AUTH_FAILED -0x0012 /**< Authenticated decryption failed. */
+#define MBEDTLS_ERR_GCM_HW_ACCEL_FAILED -0x0013 /**< GCM hardware accelerator failed. */
#define MBEDTLS_ERR_GCM_BAD_INPUT -0x0014 /**< Bad input parameters to function. */
#if !defined(MBEDTLS_GCM_ALT)
@@ -40,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,
@@ -80,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,
@@ -114,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,
@@ -146,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,
@@ -165,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,
@@ -187,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 );
@@ -221,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/havege.h b/include/mbedtls/havege.h
index dac5d31..d4cb3ed 100644
--- a/include/mbedtls/havege.h
+++ b/include/mbedtls/havege.h
@@ -2,7 +2,8 @@
* \file havege.h
*
* \brief HAVEGE: HArdware Volatile Entropy Gathering and Expansion
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/hmac_drbg.h b/include/mbedtls/hmac_drbg.h
index e010558..e0821cf 100644
--- a/include/mbedtls/hmac_drbg.h
+++ b/include/mbedtls/hmac_drbg.h
@@ -2,7 +2,8 @@
* \file hmac_drbg.h
*
* \brief HMAC_DRBG (NIST SP 800-90A)
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/md.h b/include/mbedtls/md.h
index 89be847..6b6f5c5 100644
--- a/include/mbedtls/md.h
+++ b/include/mbedtls/md.h
@@ -1,11 +1,12 @@
-/**
+ /**
* \file md.h
*
- * \brief Generic message digest wrapper
+ * \brief This file contains 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
@@ -20,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
@@ -37,22 +39,31 @@
#define MBEDTLS_ERR_MD_BAD_INPUT_DATA -0x5100 /**< Bad input parameters to function. */
#define MBEDTLS_ERR_MD_ALLOC_FAILED -0x5180 /**< Failed to allocate memory. */
#define MBEDTLS_ERR_MD_FILE_IO_ERROR -0x5200 /**< Opening or reading of file failed. */
+#define MBEDTLS_ERR_MD_HW_ACCEL_FAILED -0x5280 /**< MD hardware accelerator failed. */
#ifdef __cplusplus
extern "C" {
#endif
+/**
+ * \brief Supported message digests.
+ *
+ * \warning MD2, MD4, MD5 and SHA-1 are considered weak message digests and
+ * their use constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
typedef enum {
- MBEDTLS_MD_NONE=0,
- MBEDTLS_MD_MD2,
- MBEDTLS_MD_MD4,
- MBEDTLS_MD_MD5,
- MBEDTLS_MD_SHA1,
- MBEDTLS_MD_SHA224,
- MBEDTLS_MD_SHA256,
- MBEDTLS_MD_SHA384,
- MBEDTLS_MD_SHA512,
- MBEDTLS_MD_RIPEMD160,
+ MBEDTLS_MD_NONE=0, /**< None. */
+ MBEDTLS_MD_MD2, /**< The MD2 message digest. */
+ MBEDTLS_MD_MD4, /**< The MD4 message digest. */
+ MBEDTLS_MD_MD5, /**< The MD5 message digest. */
+ MBEDTLS_MD_SHA1, /**< The SHA-1 message digest. */
+ MBEDTLS_MD_SHA224, /**< The SHA-224 message digest. */
+ MBEDTLS_MD_SHA256, /**< The SHA-256 message digest. */
+ MBEDTLS_MD_SHA384, /**< The SHA-384 message digest. */
+ MBEDTLS_MD_SHA512, /**< The SHA-512 message digest. */
+ MBEDTLS_MD_RIPEMD160, /**< The RIPEMD-160 message digest. */
} mbedtls_md_type_t;
#if defined(MBEDTLS_SHA512_C)
@@ -62,65 +73,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.
+ * \return NULL if the associated message-digest information is 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.
+ * \return NULL if the associated message-digest information is 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 );
@@ -131,220 +156,300 @@
#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.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
+ * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on 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.
*
- * \returns \c 0 on success,
- * \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure,
- * \c MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure.
+ * \param ctx The context to set up.
+ * \param md_info The information structure of the message-digest algorithm
+ * to use.
+ * \param hmac Defines if HMAC is used. 0: HMAC is not used (saves some memory),
+ * or non-zero: HMAC is used with this context.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
+ * \return #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.
*
- * \return \c 0 on success,
- * \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure.
+ * \param dst The destination context.
+ * \param src The context to be cloned.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 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.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
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.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
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.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
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.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
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.
+ * \return #MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing
+ * the file pointed by \p path.
+ * \return #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.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
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.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
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.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
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.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
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.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ * failure.
*/
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/md2.h b/include/mbedtls/md2.h
index 0f93fbf..0fd8b5a 100644
--- a/include/mbedtls/md2.h
+++ b/include/mbedtls/md2.h
@@ -3,6 +3,11 @@
*
* \brief MD2 message digest algorithm (hash function)
*
+ * \warning MD2 is considered a weak message digest and its use constitutes a
+ * security risk. We recommend considering stronger message digests
+ * instead.
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -19,6 +24,7 @@
* limitations under the License.
*
* This file is part of mbed TLS (https://tls.mbed.org)
+ *
*/
#ifndef MBEDTLS_MD2_H
#define MBEDTLS_MD2_H
@@ -31,6 +37,8 @@
#include <stddef.h>
+#define MBEDTLS_ERR_MD2_HW_ACCEL_FAILED -0x002B /**< MD2 hardware accelerator failed */
+
#if !defined(MBEDTLS_MD2_ALT)
// Regular implementation
//
@@ -41,6 +49,11 @@
/**
* \brief MD2 context structure
+ *
+ * \warning MD2 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
typedef struct
{
@@ -55,6 +68,11 @@
* \brief Initialize MD2 context
*
* \param ctx MD2 context to be initialized
+ *
+ * \warning MD2 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
void mbedtls_md2_init( mbedtls_md2_context *ctx );
@@ -62,6 +80,11 @@
* \brief Clear MD2 context
*
* \param ctx MD2 context to be cleared
+ *
+ * \warning MD2 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
void mbedtls_md2_free( mbedtls_md2_context *ctx );
@@ -70,6 +93,11 @@
*
* \param dst The destination context
* \param src The context to be cloned
+ *
+ * \warning MD2 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
void mbedtls_md2_clone( mbedtls_md2_context *dst,
const mbedtls_md2_context *src );
@@ -78,25 +106,134 @@
* \brief MD2 context setup
*
* \param ctx context to be initialized
+ *
+ * \return 0 if successful
+ *
+ * \warning MD2 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
-void mbedtls_md2_starts( mbedtls_md2_context *ctx );
+int mbedtls_md2_starts_ret( mbedtls_md2_context *ctx );
/**
* \brief MD2 process buffer
*
* \param ctx MD2 context
- * \param input buffer holding the data
+ * \param input buffer holding the data
* \param ilen length of the input data
+ *
+ * \return 0 if successful
+ *
+ * \warning MD2 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
-void mbedtls_md2_update( mbedtls_md2_context *ctx, const unsigned char *input, size_t ilen );
+int mbedtls_md2_update_ret( mbedtls_md2_context *ctx,
+ const unsigned char *input,
+ size_t ilen );
/**
* \brief MD2 final digest
*
* \param ctx MD2 context
* \param output MD2 checksum result
+ *
+ * \return 0 if successful
+ *
+ * \warning MD2 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
-void mbedtls_md2_finish( mbedtls_md2_context *ctx, unsigned char output[16] );
+int mbedtls_md2_finish_ret( mbedtls_md2_context *ctx,
+ unsigned char output[16] );
+
+/**
+ * \brief MD2 process data block (internal use only)
+ *
+ * \param ctx MD2 context
+ *
+ * \return 0 if successful
+ *
+ * \warning MD2 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+int mbedtls_internal_md2_process( mbedtls_md2_context *ctx );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief MD2 context setup
+ *
+ * \deprecated Superseded by mbedtls_md2_starts_ret() in 2.7.0
+ *
+ * \param ctx context to be initialized
+ *
+ * \warning MD2 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_md2_starts( mbedtls_md2_context *ctx );
+
+/**
+ * \brief MD2 process buffer
+ *
+ * \deprecated Superseded by mbedtls_md2_update_ret() in 2.7.0
+ *
+ * \param ctx MD2 context
+ * \param input buffer holding the data
+ * \param ilen length of the input data
+ *
+ * \warning MD2 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_md2_update( mbedtls_md2_context *ctx,
+ const unsigned char *input,
+ size_t ilen );
+
+/**
+ * \brief MD2 final digest
+ *
+ * \deprecated Superseded by mbedtls_md2_finish_ret() in 2.7.0
+ *
+ * \param ctx MD2 context
+ * \param output MD2 checksum result
+ *
+ * \warning MD2 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_md2_finish( mbedtls_md2_context *ctx,
+ unsigned char output[16] );
+
+/**
+ * \brief MD2 process data block (internal use only)
+ *
+ * \deprecated Superseded by mbedtls_internal_md2_process() in 2.7.0
+ *
+ * \param ctx MD2 context
+ *
+ * \warning MD2 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_md2_process( mbedtls_md2_context *ctx );
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
#ifdef __cplusplus
}
@@ -113,22 +250,58 @@
/**
* \brief Output = MD2( input buffer )
*
- * \param input buffer holding the data
+ * \param input buffer holding the data
* \param ilen length of the input data
* \param output MD2 checksum result
+ *
+ * \warning MD2 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
-void mbedtls_md2( const unsigned char *input, size_t ilen, unsigned char output[16] );
+int mbedtls_md2_ret( const unsigned char *input,
+ size_t ilen,
+ unsigned char output[16] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief Output = MD2( input buffer )
+ *
+ * \deprecated Superseded by mbedtls_md2_ret() in 2.7.0
+ *
+ * \param input buffer holding the data
+ * \param ilen length of the input data
+ * \param output MD2 checksum result
+ *
+ * \warning MD2 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_md2( const unsigned char *input,
+ size_t ilen,
+ unsigned char output[16] );
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
/**
* \brief Checkup routine
*
* \return 0 if successful, or 1 if the test failed
+ *
+ * \warning MD2 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
int mbedtls_md2_self_test( int verbose );
-/* Internal use */
-void mbedtls_md2_process( mbedtls_md2_context *ctx );
-
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/md4.h b/include/mbedtls/md4.h
index 45214d4..23fa95e 100644
--- a/include/mbedtls/md4.h
+++ b/include/mbedtls/md4.h
@@ -3,6 +3,11 @@
*
* \brief MD4 message digest algorithm (hash function)
*
+ * \warning MD4 is considered a weak message digest and its use constitutes a
+ * security risk. We recommend considering stronger message digests
+ * instead.
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -19,6 +24,7 @@
* limitations under the License.
*
* This file is part of mbed TLS (https://tls.mbed.org)
+ *
*/
#ifndef MBEDTLS_MD4_H
#define MBEDTLS_MD4_H
@@ -32,6 +38,8 @@
#include <stddef.h>
#include <stdint.h>
+#define MBEDTLS_ERR_MD4_HW_ACCEL_FAILED -0x002D /**< MD4 hardware accelerator failed */
+
#if !defined(MBEDTLS_MD4_ALT)
// Regular implementation
//
@@ -42,6 +50,11 @@
/**
* \brief MD4 context structure
+ *
+ * \warning MD4 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
typedef struct
{
@@ -55,6 +68,11 @@
* \brief Initialize MD4 context
*
* \param ctx MD4 context to be initialized
+ *
+ * \warning MD4 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
void mbedtls_md4_init( mbedtls_md4_context *ctx );
@@ -62,6 +80,11 @@
* \brief Clear MD4 context
*
* \param ctx MD4 context to be cleared
+ *
+ * \warning MD4 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
void mbedtls_md4_free( mbedtls_md4_context *ctx );
@@ -70,6 +93,11 @@
*
* \param dst The destination context
* \param src The context to be cloned
+ *
+ * \warning MD4 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
void mbedtls_md4_clone( mbedtls_md4_context *dst,
const mbedtls_md4_context *src );
@@ -78,25 +106,137 @@
* \brief MD4 context setup
*
* \param ctx context to be initialized
+ *
+ * \return 0 if successful
+ *
+ * \warning MD4 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
*/
-void mbedtls_md4_starts( mbedtls_md4_context *ctx );
+int mbedtls_md4_starts_ret( mbedtls_md4_context *ctx );
/**
* \brief MD4 process buffer
*
* \param ctx MD4 context
- * \param input buffer holding the data
+ * \param input buffer holding the data
* \param ilen length of the input data
+ *
+ * \return 0 if successful
+ *
+ * \warning MD4 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
-void mbedtls_md4_update( mbedtls_md4_context *ctx, const unsigned char *input, size_t ilen );
+int mbedtls_md4_update_ret( mbedtls_md4_context *ctx,
+ const unsigned char *input,
+ size_t ilen );
/**
* \brief MD4 final digest
*
* \param ctx MD4 context
* \param output MD4 checksum result
+ *
+ * \return 0 if successful
+ *
+ * \warning MD4 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
-void mbedtls_md4_finish( mbedtls_md4_context *ctx, unsigned char output[16] );
+int mbedtls_md4_finish_ret( mbedtls_md4_context *ctx,
+ unsigned char output[16] );
+
+/**
+ * \brief MD4 process data block (internal use only)
+ *
+ * \param ctx MD4 context
+ * \param data buffer holding one block of data
+ *
+ * \return 0 if successful
+ *
+ * \warning MD4 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+int mbedtls_internal_md4_process( mbedtls_md4_context *ctx,
+ const unsigned char data[64] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief MD4 context setup
+ *
+ * \deprecated Superseded by mbedtls_md4_starts_ret() in 2.7.0
+ *
+ * \param ctx context to be initialized
+ *
+ * \warning MD4 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_md4_starts( mbedtls_md4_context *ctx );
+
+/**
+ * \brief MD4 process buffer
+ *
+ * \deprecated Superseded by mbedtls_md4_update_ret() in 2.7.0
+ *
+ * \param ctx MD4 context
+ * \param input buffer holding the data
+ * \param ilen length of the input data
+ *
+ * \warning MD4 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_md4_update( mbedtls_md4_context *ctx,
+ const unsigned char *input,
+ size_t ilen );
+
+/**
+ * \brief MD4 final digest
+ *
+ * \deprecated Superseded by mbedtls_md4_finish_ret() in 2.7.0
+ *
+ * \param ctx MD4 context
+ * \param output MD4 checksum result
+ *
+ * \warning MD4 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_md4_finish( mbedtls_md4_context *ctx,
+ unsigned char output[16] );
+
+/**
+ * \brief MD4 process data block (internal use only)
+ *
+ * \deprecated Superseded by mbedtls_internal_md4_process() in 2.7.0
+ *
+ * \param ctx MD4 context
+ * \param data buffer holding one block of data
+ *
+ * \warning MD4 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_md4_process( mbedtls_md4_context *ctx,
+ const unsigned char data[64] );
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
#ifdef __cplusplus
}
@@ -113,22 +253,60 @@
/**
* \brief Output = MD4( input buffer )
*
- * \param input buffer holding the data
+ * \param input buffer holding the data
* \param ilen length of the input data
* \param output MD4 checksum result
+ *
+ * \return 0 if successful
+ *
+ * \warning MD4 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
-void mbedtls_md4( const unsigned char *input, size_t ilen, unsigned char output[16] );
+int mbedtls_md4_ret( const unsigned char *input,
+ size_t ilen,
+ unsigned char output[16] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief Output = MD4( input buffer )
+ *
+ * \deprecated Superseded by mbedtls_md4_ret() in 2.7.0
+ *
+ * \param input buffer holding the data
+ * \param ilen length of the input data
+ * \param output MD4 checksum result
+ *
+ * \warning MD4 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_md4( const unsigned char *input,
+ size_t ilen,
+ unsigned char output[16] );
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
/**
* \brief Checkup routine
*
* \return 0 if successful, or 1 if the test failed
+ *
+ * \warning MD4 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
int mbedtls_md4_self_test( int verbose );
-/* Internal use */
-void mbedtls_md4_process( mbedtls_md4_context *ctx, const unsigned char data[64] );
-
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/md5.h b/include/mbedtls/md5.h
index 5a64061..06ea4c5 100644
--- a/include/mbedtls/md5.h
+++ b/include/mbedtls/md5.h
@@ -3,6 +3,11 @@
*
* \brief MD5 message digest algorithm (hash function)
*
+ * \warning MD5 is considered a weak message digest and its use constitutes a
+ * security risk. We recommend considering stronger message
+ * digests instead.
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -32,6 +37,8 @@
#include <stddef.h>
#include <stdint.h>
+#define MBEDTLS_ERR_MD5_HW_ACCEL_FAILED -0x002F /**< MD5 hardware accelerator failed */
+
#if !defined(MBEDTLS_MD5_ALT)
// Regular implementation
//
@@ -42,6 +49,11 @@
/**
* \brief MD5 context structure
+ *
+ * \warning MD5 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
typedef struct
{
@@ -55,6 +67,11 @@
* \brief Initialize MD5 context
*
* \param ctx MD5 context to be initialized
+ *
+ * \warning MD5 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
void mbedtls_md5_init( mbedtls_md5_context *ctx );
@@ -62,6 +79,11 @@
* \brief Clear MD5 context
*
* \param ctx MD5 context to be cleared
+ *
+ * \warning MD5 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
void mbedtls_md5_free( mbedtls_md5_context *ctx );
@@ -70,6 +92,11 @@
*
* \param dst The destination context
* \param src The context to be cloned
+ *
+ * \warning MD5 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
void mbedtls_md5_clone( mbedtls_md5_context *dst,
const mbedtls_md5_context *src );
@@ -78,28 +105,138 @@
* \brief MD5 context setup
*
* \param ctx context to be initialized
+ *
+ * \return 0 if successful
+ *
+ * \warning MD5 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
-void mbedtls_md5_starts( mbedtls_md5_context *ctx );
+int mbedtls_md5_starts_ret( mbedtls_md5_context *ctx );
/**
* \brief MD5 process buffer
*
* \param ctx MD5 context
- * \param input buffer holding the data
+ * \param input buffer holding the data
* \param ilen length of the input data
+ *
+ * \return 0 if successful
+ *
+ * \warning MD5 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
-void mbedtls_md5_update( mbedtls_md5_context *ctx, const unsigned char *input, size_t ilen );
+int mbedtls_md5_update_ret( mbedtls_md5_context *ctx,
+ const unsigned char *input,
+ size_t ilen );
/**
* \brief MD5 final digest
*
* \param ctx MD5 context
* \param output MD5 checksum result
+ *
+ * \return 0 if successful
+ *
+ * \warning MD5 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
-void mbedtls_md5_finish( mbedtls_md5_context *ctx, unsigned char output[16] );
+int mbedtls_md5_finish_ret( mbedtls_md5_context *ctx,
+ unsigned char output[16] );
-/* Internal use */
-void mbedtls_md5_process( mbedtls_md5_context *ctx, const unsigned char data[64] );
+/**
+ * \brief MD5 process data block (internal use only)
+ *
+ * \param ctx MD5 context
+ * \param data buffer holding one block of data
+ *
+ * \return 0 if successful
+ *
+ * \warning MD5 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+int mbedtls_internal_md5_process( mbedtls_md5_context *ctx,
+ const unsigned char data[64] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief MD5 context setup
+ *
+ * \deprecated Superseded by mbedtls_md5_starts_ret() in 2.7.0
+ *
+ * \param ctx context to be initialized
+ *
+ * \warning MD5 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_md5_starts( mbedtls_md5_context *ctx );
+
+/**
+ * \brief MD5 process buffer
+ *
+ * \deprecated Superseded by mbedtls_md5_update_ret() in 2.7.0
+ *
+ * \param ctx MD5 context
+ * \param input buffer holding the data
+ * \param ilen length of the input data
+ *
+ * \warning MD5 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_md5_update( mbedtls_md5_context *ctx,
+ const unsigned char *input,
+ size_t ilen );
+
+/**
+ * \brief MD5 final digest
+ *
+ * \deprecated Superseded by mbedtls_md5_finish_ret() in 2.7.0
+ *
+ * \param ctx MD5 context
+ * \param output MD5 checksum result
+ *
+ * \warning MD5 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_md5_finish( mbedtls_md5_context *ctx,
+ unsigned char output[16] );
+
+/**
+ * \brief MD5 process data block (internal use only)
+ *
+ * \deprecated Superseded by mbedtls_internal_md5_process() in 2.7.0
+ *
+ * \param ctx MD5 context
+ * \param data buffer holding one block of data
+ *
+ * \warning MD5 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_md5_process( mbedtls_md5_context *ctx,
+ const unsigned char data[64] );
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
#ifdef __cplusplus
}
@@ -116,16 +253,57 @@
/**
* \brief Output = MD5( input buffer )
*
- * \param input buffer holding the data
+ * \param input buffer holding the data
* \param ilen length of the input data
* \param output MD5 checksum result
+ *
+ * \return 0 if successful
+ *
+ * \warning MD5 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
-void mbedtls_md5( const unsigned char *input, size_t ilen, unsigned char output[16] );
+int mbedtls_md5_ret( const unsigned char *input,
+ size_t ilen,
+ unsigned char output[16] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief Output = MD5( input buffer )
+ *
+ * \deprecated Superseded by mbedtls_md5_ret() in 2.7.0
+ *
+ * \param input buffer holding the data
+ * \param ilen length of the input data
+ * \param output MD5 checksum result
+ *
+ * \warning MD5 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_md5( const unsigned char *input,
+ size_t ilen,
+ unsigned char output[16] );
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
/**
* \brief Checkup routine
*
* \return 0 if successful, or 1 if the test failed
+ *
+ * \warning MD5 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
int mbedtls_md5_self_test( int verbose );
diff --git a/include/mbedtls/md_internal.h b/include/mbedtls/md_internal.h
index e2441bb..04de482 100644
--- a/include/mbedtls/md_internal.h
+++ b/include/mbedtls/md_internal.h
@@ -6,7 +6,8 @@
* \warning This in an internal header. Do not include directly.
*
* \author Adriaan de Jong <dejong@fox-it.com>
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -58,17 +59,17 @@
int block_size;
/** Digest initialisation function */
- void (*starts_func)( void *ctx );
+ int (*starts_func)( void *ctx );
/** Digest update function */
- void (*update_func)( void *ctx, const unsigned char *input, size_t ilen );
+ int (*update_func)( void *ctx, const unsigned char *input, size_t ilen );
/** Digest finalisation function */
- void (*finish_func)( void *ctx, unsigned char *output );
+ int (*finish_func)( void *ctx, unsigned char *output );
/** Generic digest function */
- void (*digest_func)( const unsigned char *input, size_t ilen,
- unsigned char *output );
+ int (*digest_func)( const unsigned char *input, size_t ilen,
+ unsigned char *output );
/** Allocate a new context */
void * (*ctx_alloc_func)( void );
@@ -80,7 +81,7 @@
void (*clone_func)( void *dst, const void *src );
/** Internal use only */
- void (*process_func)( void *ctx, const unsigned char *input );
+ int (*process_func)( void *ctx, const unsigned char *input );
};
#if defined(MBEDTLS_MD2_C)
diff --git a/include/mbedtls/memory_buffer_alloc.h b/include/mbedtls/memory_buffer_alloc.h
index d5df316..705f9a6 100644
--- a/include/mbedtls/memory_buffer_alloc.h
+++ b/include/mbedtls/memory_buffer_alloc.h
@@ -2,7 +2,8 @@
* \file memory_buffer_alloc.h
*
* \brief Buffer-based memory allocator
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/net.h b/include/mbedtls/net.h
index 774559b..28ae821 100644
--- a/include/mbedtls/net.h
+++ b/include/mbedtls/net.h
@@ -3,6 +3,9 @@
*
* \brief Deprecated header file that includes mbedtls/net_sockets.h
*
+ * \deprecated Superseded by mbedtls/net_sockets.h
+ */
+/*
* Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -19,8 +22,6 @@
* limitations under the License.
*
* This file is part of mbed TLS (https://tls.mbed.org)
- *
- * \deprecated Superseded by mbedtls/net_sockets.h
*/
#if !defined(MBEDTLS_DEPRECATED_REMOVED)
diff --git a/include/mbedtls/net_sockets.h b/include/mbedtls/net_sockets.h
index de33552..0f9b31e 100644
--- a/include/mbedtls/net_sockets.h
+++ b/include/mbedtls/net_sockets.h
@@ -2,7 +2,8 @@
* \file net_sockets.h
*
* \brief Network communication functions
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -45,12 +46,17 @@
#define MBEDTLS_ERR_NET_UNKNOWN_HOST -0x0052 /**< Failed to get an IP address for the given hostname. */
#define MBEDTLS_ERR_NET_BUFFER_TOO_SMALL -0x0043 /**< Buffer is too small to hold the data. */
#define MBEDTLS_ERR_NET_INVALID_CONTEXT -0x0045 /**< The context is invalid, eg because it was free()ed. */
+#define MBEDTLS_ERR_NET_POLL_FAILED -0x0047 /**< Polling the net context failed. */
+#define MBEDTLS_ERR_NET_BAD_INPUT_DATA -0x0049 /**< Input invalid. */
#define MBEDTLS_NET_LISTEN_BACKLOG 10 /**< The backlog that listen() should use. */
#define MBEDTLS_NET_PROTO_TCP 0 /**< The TCP transport protocol */
#define MBEDTLS_NET_PROTO_UDP 1 /**< The UDP transport protocol */
+#define MBEDTLS_NET_POLL_READ 1 /**< Used in \c mbedtls_net_poll to check for pending data */
+#define MBEDTLS_NET_POLL_WRITE 2 /**< Used in \c mbedtls_net_poll to check if write possible */
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -117,9 +123,10 @@
*
* \param bind_ctx Relevant socket
* \param client_ctx Will contain the connected client socket
- * \param client_ip Will contain the client IP address
+ * \param client_ip Will contain the client IP address, can be NULL
* \param buf_size Size of the client_ip buffer
- * \param ip_len Will receive the size of the client IP written
+ * \param ip_len Will receive the size of the client IP written,
+ * can be NULL if client_ip is null
*
* \return 0 if successful, or
* MBEDTLS_ERR_NET_ACCEPT_FAILED, or
@@ -132,6 +139,29 @@
void *client_ip, size_t buf_size, size_t *ip_len );
/**
+ * \brief Check and wait for the context to be ready for read/write
+ *
+ * \param ctx Socket to check
+ * \param rw Bitflag composed of MBEDTLS_NET_POLL_READ and
+ * MBEDTLS_NET_POLL_WRITE specifying the events
+ * to wait for:
+ * - If MBEDTLS_NET_POLL_READ is set, the function
+ * will return as soon as the net context is available
+ * for reading.
+ * - If MBEDTLS_NET_POLL_WRITE is set, the function
+ * will return as soon as the net context is available
+ * for writing.
+ * \param timeout Maximal amount of time to wait before returning,
+ * in milliseconds. If \c timeout is zero, the
+ * function returns immediately. If \c timeout is
+ * -1u, the function blocks potentially indefinitely.
+ *
+ * \return Bitmask composed of MBEDTLS_NET_POLL_READ/WRITE
+ * on success or timeout, or a negative return code otherwise.
+ */
+int mbedtls_net_poll( mbedtls_net_context *ctx, uint32_t rw, uint32_t timeout );
+
+/**
* \brief Set the socket blocking
*
* \param ctx Socket to set
diff --git a/include/mbedtls/oid.h b/include/mbedtls/oid.h
index fcecdaf..408645e 100644
--- a/include/mbedtls/oid.h
+++ b/include/mbedtls/oid.h
@@ -2,7 +2,8 @@
* \file oid.h
*
* \brief Object Identifier (OID) database
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -227,6 +228,14 @@
#define MBEDTLS_OID_HMAC_SHA1 MBEDTLS_OID_RSA_COMPANY "\x02\x07" /**< id-hmacWithSHA1 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 7 } */
+#define MBEDTLS_OID_HMAC_SHA224 MBEDTLS_OID_RSA_COMPANY "\x02\x08" /**< id-hmacWithSHA224 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 8 } */
+
+#define MBEDTLS_OID_HMAC_SHA256 MBEDTLS_OID_RSA_COMPANY "\x02\x09" /**< id-hmacWithSHA256 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 9 } */
+
+#define MBEDTLS_OID_HMAC_SHA384 MBEDTLS_OID_RSA_COMPANY "\x02\x0A" /**< id-hmacWithSHA384 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 10 } */
+
+#define MBEDTLS_OID_HMAC_SHA512 MBEDTLS_OID_RSA_COMPANY "\x02\x0B" /**< id-hmacWithSHA512 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) rsadsi(113549) digestAlgorithm(2) 11 } */
+
/*
* Encryption algorithms
*/
@@ -513,6 +522,16 @@
* \return 0 if successful, or MBEDTLS_ERR_OID_NOT_FOUND
*/
int mbedtls_oid_get_md_alg( const mbedtls_asn1_buf *oid, mbedtls_md_type_t *md_alg );
+
+/**
+ * \brief Translate hmac algorithm OID into md_type
+ *
+ * \param oid OID to use
+ * \param md_hmac place to store message hmac algorithm
+ *
+ * \return 0 if successful, or MBEDTLS_ERR_OID_NOT_FOUND
+ */
+int mbedtls_oid_get_md_hmac( const mbedtls_asn1_buf *oid, mbedtls_md_type_t *md_hmac );
#endif /* MBEDTLS_MD_C */
/**
diff --git a/include/mbedtls/padlock.h b/include/mbedtls/padlock.h
index 2045a5a..677936e 100644
--- a/include/mbedtls/padlock.h
+++ b/include/mbedtls/padlock.h
@@ -3,7 +3,8 @@
*
* \brief VIA PadLock ACE for HW encryption/decryption supported by some
* processors
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/pem.h b/include/mbedtls/pem.h
index 54dc02d..2cf4c0a 100644
--- a/include/mbedtls/pem.h
+++ b/include/mbedtls/pem.h
@@ -2,7 +2,8 @@
* \file pem.h
*
* \brief Privacy Enhanced Mail (PEM) decoding
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index f9f9b9b..ee06b2f 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -2,7 +2,8 @@
* \file pk.h
*
* \brief Public Key abstraction layer
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -62,7 +63,8 @@
#define MBEDTLS_ERR_PK_INVALID_ALG -0x3A80 /**< The algorithm tag or value is invalid. */
#define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00 /**< Elliptic curve is unsupported (only NIST curves are supported). */
#define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980 /**< Unavailable feature, e.g. RSA disabled for RSA key. */
-#define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH -0x3900 /**< The signature is valid but its length is less than expected. */
+#define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH -0x3900 /**< The buffer contains a valid signature followed by more data. */
+#define MBEDTLS_ERR_PK_HW_ACCEL_FAILED -0x3880 /**< PK hardware accelerator failed. */
#ifdef __cplusplus
extern "C" {
@@ -267,8 +269,8 @@
* \param sig_len Signature length
*
* \return 0 on success (signature is valid),
- * MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if the signature is
- * valid but its actual length is less than sig_len,
+ * #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
+ * signature in sig but its length is less than \p siglen,
* or a specific error code.
*
* \note For RSA keys, the default padding type is PKCS#1 v1.5.
@@ -298,10 +300,10 @@
* \param sig_len Signature length
*
* \return 0 on success (signature is valid),
- * MBEDTLS_ERR_PK_TYPE_MISMATCH if the PK context can't be
+ * #MBEDTLS_ERR_PK_TYPE_MISMATCH if the PK context can't be
* used for this type of signatures,
- * MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if the signature is
- * valid but its actual length is less than sig_len,
+ * #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
+ * signature in sig but its length is less than \p siglen,
* or a specific error code.
*
* \note If hash_len is 0, then the length associated with md_alg
diff --git a/include/mbedtls/pk_internal.h b/include/mbedtls/pk_internal.h
index 01d0f21..3dae0fc 100644
--- a/include/mbedtls/pk_internal.h
+++ b/include/mbedtls/pk_internal.h
@@ -1,8 +1,9 @@
/**
- * \file pk.h
+ * \file pk_internal.h
*
* \brief Public Key abstraction layer: wrapper functions
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/pkcs11.h b/include/mbedtls/pkcs11.h
index 2e88928..bf65c55 100644
--- a/include/mbedtls/pkcs11.h
+++ b/include/mbedtls/pkcs11.h
@@ -4,7 +4,8 @@
* \brief Wrapper for PKCS#11 library libpkcs11-helper
*
* \author Adriaan de Jong <dejong@fox-it.com>
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/pkcs12.h b/include/mbedtls/pkcs12.h
index 9b2d904..a621ef5 100644
--- a/include/mbedtls/pkcs12.h
+++ b/include/mbedtls/pkcs12.h
@@ -2,7 +2,8 @@
* \file pkcs12.h
*
* \brief PKCS#12 Personal Information Exchange Syntax
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/pkcs5.h b/include/mbedtls/pkcs5.h
index ec5cb9e..9a3c9fd 100644
--- a/include/mbedtls/pkcs5.h
+++ b/include/mbedtls/pkcs5.h
@@ -4,7 +4,8 @@
* \brief PKCS#5 functions
*
* \author Mathias Olsson <mathias@kompetensum.com>
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h
index 35010f8..d50b266 100644
--- a/include/mbedtls/platform.h
+++ b/include/mbedtls/platform.h
@@ -1,9 +1,19 @@
/**
* \file platform.h
*
- * \brief mbed TLS Platform abstraction layer
+ * \brief This file contains the definitions and functions of the
+ * Mbed TLS platform abstraction layer.
*
- * Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
+ * The platform abstraction layer removes the need for the library
+ * to directly link to standard C library functions or operating
+ * system services, making the library easier to port and embed.
+ * Application developers and users of the library can provide their own
+ * implementations of these functions, or implementations specific to
+ * their platform, which can be statically linked to the library or
+ * dynamically configured at runtime.
+ */
+/*
+ * 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
@@ -18,7 +28,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
@@ -51,34 +61,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)
@@ -101,7 +111,7 @@
/* \} name SECTION: Module settings */
/*
- * The function pointers for calloc and free
+ * The function pointers for calloc and free.
*/
#if defined(MBEDTLS_PLATFORM_MEMORY)
#if defined(MBEDTLS_PLATFORM_FREE_MACRO) && \
@@ -115,12 +125,13 @@
extern void (*mbedtls_free)( void *ptr );
/**
- * \brief Set your own memory implementation function pointers
+ * \brief This function dynamically sets the memory-management
+ * functions used by the library, during runtime.
*
- * \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 * ) );
@@ -139,11 +150,13 @@
extern int (*mbedtls_fprintf)( FILE *stream, const char *format, ... );
/**
- * \brief Set your own fprintf function pointer
+ * \brief This function dynamically configures the fprintf
+ * function that is called when the
+ * mbedtls_fprintf() function is invoked by the library.
*
- * \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 *,
... ) );
@@ -162,11 +175,13 @@
extern int (*mbedtls_printf)( const char *format, ... );
/**
- * \brief Set your own printf function pointer
+ * \brief This function dynamically configures the snprintf
+ * function that is called when the mbedtls_snprintf()
+ * function is invoked by the library.
*
- * \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 */
@@ -195,11 +210,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, ... ) );
@@ -218,11 +234,13 @@
extern void (*mbedtls_exit)( int status );
/**
- * \brief Set your own exit function pointer
+ * \brief This function dynamically configures the exit
+ * function that is called when the mbedtls_exit()
+ * function is invoked by the library.
*
- * \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
@@ -265,12 +283,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 ),
@@ -291,13 +310,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; /**< A placeholder member, as empty structs are not portable. */
}
mbedtls_platform_context;
@@ -306,33 +325,34 @@
#endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */
/**
- * \brief Perform any platform initialisation operations
+ * \brief This function performs any platform-specific initialization
+ * operations.
*
- * \param ctx mbed TLS context
+ * \note This function should be called before any other library functions.
*
- * \return 0 if successful
+ * Its implementation is platform-specific, and unless
+ * platform-specific code is provided, it does nothing.
*
- * \note This function is intended to allow platform specific initialisation,
- * 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.
+ * \note The usage and necessity of this function is dependent on the platform.
*
- * Its use and whether its necessary to be called is dependent on the
- * platform.
+ * \param ctx The platform context.
+ *
+ * \return \c 0 on success.
*/
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
+ * \note This function should be called after every other Mbed TLS module
+ * has been correctly freed using the appropriate free function.
*
- * \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.
+ * 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
- * platform.
+ * \note The usage and necessity of this function is dependent on the platform.
+ *
+ * \param ctx The platform context.
+ *
*/
void mbedtls_platform_teardown( mbedtls_platform_context *ctx );
diff --git a/include/mbedtls/platform_time.h b/include/mbedtls/platform_time.h
index abb3431..2ed36f5 100644
--- a/include/mbedtls/platform_time.h
+++ b/include/mbedtls/platform_time.h
@@ -2,7 +2,8 @@
* \file platform_time.h
*
* \brief mbed TLS Platform time abstraction
- *
+ */
+/*
* Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/ripemd160.h b/include/mbedtls/ripemd160.h
index 7083fc8..3a8b50a 100644
--- a/include/mbedtls/ripemd160.h
+++ b/include/mbedtls/ripemd160.h
@@ -2,7 +2,8 @@
* \file ripemd160.h
*
* \brief RIPE MD-160 message digest
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -32,6 +33,8 @@
#include <stddef.h>
#include <stdint.h>
+#define MBEDTLS_ERR_RIPEMD160_HW_ACCEL_FAILED -0x0031 /**< RIPEMD160 hardware accelerator failed */
+
#if !defined(MBEDTLS_RIPEMD160_ALT)
// Regular implementation
//
@@ -78,36 +81,109 @@
* \brief RIPEMD-160 context setup
*
* \param ctx context to be initialized
+ *
+ * \return 0 if successful
*/
-void mbedtls_ripemd160_starts( mbedtls_ripemd160_context *ctx );
+int mbedtls_ripemd160_starts_ret( mbedtls_ripemd160_context *ctx );
/**
* \brief RIPEMD-160 process buffer
*
* \param ctx RIPEMD-160 context
- * \param input buffer holding the data
+ * \param input buffer holding the data
* \param ilen length of the input data
+ *
+ * \return 0 if successful
*/
-void mbedtls_ripemd160_update( mbedtls_ripemd160_context *ctx,
- const unsigned char *input, size_t ilen );
+int mbedtls_ripemd160_update_ret( mbedtls_ripemd160_context *ctx,
+ const unsigned char *input,
+ size_t ilen );
/**
* \brief RIPEMD-160 final digest
*
* \param ctx RIPEMD-160 context
* \param output RIPEMD-160 checksum result
+ *
+ * \return 0 if successful
*/
-void mbedtls_ripemd160_finish( mbedtls_ripemd160_context *ctx, unsigned char output[20] );
+int mbedtls_ripemd160_finish_ret( mbedtls_ripemd160_context *ctx,
+ unsigned char output[20] );
-/* Internal use */
-void mbedtls_ripemd160_process( mbedtls_ripemd160_context *ctx, const unsigned char data[64] );
+/**
+ * \brief RIPEMD-160 process data block (internal use only)
+ *
+ * \param ctx RIPEMD-160 context
+ * \param data buffer holding one block of data
+ *
+ * \return 0 if successful
+ */
+int mbedtls_internal_ripemd160_process( mbedtls_ripemd160_context *ctx,
+ const unsigned char data[64] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief RIPEMD-160 context setup
+ *
+ * \deprecated Superseded by mbedtls_ripemd160_starts_ret() in 2.7.0
+ *
+ * \param ctx context to be initialized
+ */
+MBEDTLS_DEPRECATED void mbedtls_ripemd160_starts(
+ mbedtls_ripemd160_context *ctx );
+
+/**
+ * \brief RIPEMD-160 process buffer
+ *
+ * \deprecated Superseded by mbedtls_ripemd160_update_ret() in 2.7.0
+ *
+ * \param ctx RIPEMD-160 context
+ * \param input buffer holding the data
+ * \param ilen length of the input data
+ */
+MBEDTLS_DEPRECATED void mbedtls_ripemd160_update(
+ mbedtls_ripemd160_context *ctx,
+ const unsigned char *input,
+ size_t ilen );
+
+/**
+ * \brief RIPEMD-160 final digest
+ *
+ * \deprecated Superseded by mbedtls_ripemd160_finish_ret() in 2.7.0
+ *
+ * \param ctx RIPEMD-160 context
+ * \param output RIPEMD-160 checksum result
+ */
+MBEDTLS_DEPRECATED void mbedtls_ripemd160_finish(
+ mbedtls_ripemd160_context *ctx,
+ unsigned char output[20] );
+
+/**
+ * \brief RIPEMD-160 process data block (internal use only)
+ *
+ * \deprecated Superseded by mbedtls_internal_ripemd160_process() in 2.7.0
+ *
+ * \param ctx RIPEMD-160 context
+ * \param data buffer holding one block of data
+ */
+MBEDTLS_DEPRECATED void mbedtls_ripemd160_process(
+ mbedtls_ripemd160_context *ctx,
+ const unsigned char data[64] );
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
#ifdef __cplusplus
}
#endif
#else /* MBEDTLS_RIPEMD160_ALT */
-#include "ripemd160.h"
+#include "ripemd160_alt.h"
#endif /* MBEDTLS_RIPEMD160_ALT */
#ifdef __cplusplus
@@ -117,12 +193,37 @@
/**
* \brief Output = RIPEMD-160( input buffer )
*
- * \param input buffer holding the data
+ * \param input buffer holding the data
+ * \param ilen length of the input data
+ * \param output RIPEMD-160 checksum result
+ *
+ * \return 0 if successful
+ */
+int mbedtls_ripemd160_ret( const unsigned char *input,
+ size_t ilen,
+ unsigned char output[20] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief Output = RIPEMD-160( input buffer )
+ *
+ * \deprecated Superseded by mbedtls_ripemd160_ret() in 2.7.0
+ *
+ * \param input buffer holding the data
* \param ilen length of the input data
* \param output RIPEMD-160 checksum result
*/
-void mbedtls_ripemd160( const unsigned char *input, size_t ilen,
- unsigned char output[20] );
+MBEDTLS_DEPRECATED void mbedtls_ripemd160( const unsigned char *input,
+ size_t ilen,
+ unsigned char output[20] );
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
/**
* \brief Checkup routine
diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h
index d04e71d..f8b8965 100644
--- a/include/mbedtls/rsa.h
+++ b/include/mbedtls/rsa.h
@@ -1,9 +1,16 @@
/**
* \file rsa.h
*
- * \brief The RSA public-key cryptosystem
+ * \brief This file provides an API for the RSA public-key cryptosystem.
*
- * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * The RSA public-key cryptosystem is defined in <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-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
@@ -18,7 +25,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
@@ -42,25 +49,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
@@ -68,168 +76,465 @@
* The above constants may be used even if the RSA module is compile out,
* eg for alternative (PKCS#11) RSA implemenations in the PK layers.
*/
-#if defined(MBEDTLS_RSA_C)
+
+#if !defined(MBEDTLS_RSA_ALT)
+// Regular implementation
+//
#ifdef __cplusplus
extern "C" {
#endif
/**
- * \brief RSA context structure
+ * \brief The RSA context structure.
+ *
+ * \note Direct manipulation of the members of this structure
+ * 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 DP; /*!< D % (P - 1) */
- mbedtls_mpi DQ; /*!< D % (Q - 1) */
- mbedtls_mpi QP; /*!< 1 / (Q % P) */
+ mbedtls_mpi D; /*!< The private exponent. */
+ mbedtls_mpi P; /*!< The first prime factor. */
+ mbedtls_mpi Q; /*!< The second prime factor. */
- mbedtls_mpi RN; /*!< cached R^2 mod N */
- mbedtls_mpi RP; /*!< cached R^2 mod P */
- mbedtls_mpi RQ; /*!< cached R^2 mod Q */
+ mbedtls_mpi DP; /*!< <code>D % (P - 1)</code>. */
+ mbedtls_mpi DQ; /*!< <code>D % (Q - 1)</code>. */
+ mbedtls_mpi QP; /*!< <code>1 / (Q % P)</code>. */
- mbedtls_mpi Vi; /*!< cached blinding value */
- mbedtls_mpi Vf; /*!< cached un-blinding value */
+ mbedtls_mpi RN; /*!< cached <code>R^2 mod N</code>. */
- int padding; /*!< MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
- 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 */
+ mbedtls_mpi RP; /*!< cached <code>R^2 mod P</code>. */
+ mbedtls_mpi RQ; /*!< cached <code>R^2 mod Q</code>. */
+
+ mbedtls_mpi Vi; /*!< The cached blinding value. */
+ mbedtls_mpi Vf; /*!< The cached un-blinding value. */
+
+ 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 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 MBEDTLS_RSA_PKCS_V15 or MBEDTLS_RSA_PKCS_V21
- * \param hash_id MBEDTLS_RSA_PKCS_V21 hash identifier
+ * \note The \p hash_id parameter is ignored when using
+ * #MBEDTLS_RSA_PKCS_V15 padding.
*
- * \note The hash_id parameter is actually 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
- * 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.
+ *
+ * \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.
*/
void mbedtls_rsa_init( mbedtls_rsa_context *ctx,
- int padding,
- int hash_id);
+ int padding,
+ int hash_id);
/**
- * \brief Set padding for an already initialized RSA context
- * See \c mbedtls_rsa_init() for details.
+ * \brief This function imports a set of core parameters into an
+ * RSA context.
*
- * \param ctx RSA context to be set
- * \param padding MBEDTLS_RSA_PKCS_V15 or MBEDTLS_RSA_PKCS_V21
- * \param hash_id MBEDTLS_RSA_PKCS_V21 hash identifier
+ * \note This function can be called multiple times for successive
+ * imports, if the parameters are not simultaneously present.
+ *
+ * Any sequence of calls to this function should be followed
+ * 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 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.
+ *
+ * \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.
+ *
+ * \return \c 0 on success.
+ * \return A non-zero error code on failure.
*/
-void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding, int hash_id);
+int mbedtls_rsa_import( mbedtls_rsa_context *ctx,
+ const mbedtls_mpi *N,
+ const mbedtls_mpi *P, const mbedtls_mpi *Q,
+ const mbedtls_mpi *D, const mbedtls_mpi *E );
/**
- * \brief Generate an RSA keypair
+ * \brief This function imports core RSA parameters, in raw big-endian
+ * binary format, into an RSA context.
*
- * \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)
+ * \note This function can be called multiple times for successive
+ * imports, if the parameters are not simultaneously present.
*
- * \note mbedtls_rsa_init() must be called beforehand to setup
- * the RSA context.
+ * Any sequence of calls to this function should be followed
+ * by a call to mbedtls_rsa_complete(), which checks and
+ * completes the provided information to a ready-for-use
+ * public or private RSA key.
*
- * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code
+ * \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.
+ *
+ * \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.
+ *
+ * \return \c 0 on success.
+ * \return A non-zero error code on failure.
+ */
+int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx,
+ unsigned char const *N, size_t N_len,
+ unsigned char const *P, size_t P_len,
+ unsigned char const *Q, size_t Q_len,
+ unsigned char const *D, size_t D_len,
+ unsigned char const *E, size_t E_len );
+
+/**
+ * \brief This function completes an RSA context from
+ * a set of imported core parameters.
+ *
+ * To setup an RSA public key, precisely \p N and \p E
+ * must have been imported.
+ *
+ * To setup an RSA private key, sufficient 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.
+ *
+ * If this function runs successfully, it guarantees that
+ * the RSA context can be used for RSA operations without
+ * the risk of failure or crash.
+ *
+ * \warning This function need not perform consistency checks
+ * 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().
+ *
+ * \param ctx The initialized RSA context holding imported parameters.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted derivations
+ * failed.
+ *
+ */
+int mbedtls_rsa_complete( mbedtls_rsa_context *ctx );
+
+/**
+ * \brief This function exports the core parameters of an RSA key.
+ *
+ * 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 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.
+ * \return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
+ * requested parameters cannot be done due to missing
+ * functionality or because of security policies.
+ * \return A non-zero return code on any other failure.
+ *
+ */
+int mbedtls_rsa_export( const mbedtls_rsa_context *ctx,
+ mbedtls_mpi *N, mbedtls_mpi *P, mbedtls_mpi *Q,
+ mbedtls_mpi *D, mbedtls_mpi *E );
+
+/**
+ * \brief This function exports core parameters of an RSA key
+ * in raw big-endian binary format.
+ *
+ * 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.
+ *
+ * \note The length parameters are ignored if the corresponding
+ * buffer pointers are NULL.
+ *
+ * \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.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
+ * requested parameters cannot be done due to missing
+ * functionality or because of security policies.
+ * \return 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,
+ unsigned char *P, size_t P_len,
+ unsigned char *Q, size_t Q_len,
+ unsigned char *D, size_t D_len,
+ unsigned char *E, size_t E_len );
+
+/**
+ * \brief This function exports CRT parameters of a private RSA key.
+ *
+ * \note Alternative RSA implementations not using CRT-parameters
+ * internally can implement this function based on
+ * mbedtls_rsa_deduce_opt().
+ *
+ * \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 \c 0 on success.
+ * \return A non-zero error code on failure.
+ *
+ */
+int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx,
+ mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP );
+
+/**
+ * \brief This function sets padding for an already initialized RSA
+ * context. See mbedtls_rsa_init() for details.
+ *
+ * \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 This function retrieves the length of RSA modulus in Bytes.
+ *
+ * \param ctx The initialized RSA context.
+ *
+ * \return The length of the RSA modulus in Bytes.
+ *
+ */
+size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx );
+
+/**
+ * \brief This function generates an RSA keypair.
+ *
+ * \note mbedtls_rsa_init() must be called before this function,
+ * to set up the RSA context.
+ *
+ * \param ctx The RSA context used to hold the key.
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG context.
+ * \param nbits The size of the public key in bits.
+ * \param exponent The public exponent. For example, 65537.
+ *
+ * \return \c 0 on success.
+ * \return 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),
- void *p_rng,
- unsigned int nbits, int exponent );
+ int (*f_rng)(void *, unsigned char *, size_t),
+ void *p_rng,
+ unsigned int nbits, int exponent );
/**
- * \brief Check a public RSA 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 MBEDTLS_ERR_RSA_XXX error code
+ * \param ctx The RSA context to check.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
+ *
*/
int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
/**
- * \brief Check a private RSA 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
+ * \note The consistency checks performed by this function not only
+ * 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
+ * mbedtls_rsa_public() and mbedtls_rsa_private() are inverses.
*
- * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code
+ * \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:
+ * <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>
+ *
+ * \param ctx The RSA context to check.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
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 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.
+ * \return 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 );
+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
+ * \note This function does not handle message padding.
*
- * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code
- *
- * \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 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.
+ *
+ * \param ctx The RSA context.
+ * \param input The input buffer.
+ * \param output The output buffer.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_public( mbedtls_rsa_context *ctx,
const unsigned char *input,
unsigned char *output );
/**
- * \brief Do 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
- *
- * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code
+ * \brief This function performs an RSA private key operation.
*
* \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.
+ *
+ * \note Blinding is used if and only if a PRNG is provided.
+ *
+ * \note If blinding is used, both the base of exponentation
+ * and the exponent are blinded, providing protection
+ * against some side-channel attacks.
+ *
+ * \warning It is deprecated and a security risk to not provide
+ * a PRNG here and thereby prevent the use of blinding.
+ * Future versions of the library may enforce the presence
+ * of a PRNG.
+ *
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Needed for blinding.
+ * \param p_rng The RNG context.
+ * \param input The input buffer.
+ * \param output The output buffer.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
+ *
*/
int mbedtls_rsa_private( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -238,32 +543,35 @@
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 MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode MBEDTLS_RSA_PUBLIC or 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.
+ *
+ * \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.
*
* \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 MBEDTLS_ERR_RSA_XXX error code
+ * \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 context.
+ * \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.
*
- * \note The output buffer must be as large as the size
- * of ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -273,29 +581,32 @@
unsigned char *output );
/**
- * \brief Perform a PKCS#1 v1.5 encryption (RSAES-PKCS1-v1_5-ENCRYPT)
- *
- * \param ctx RSA context
- * \param f_rng RNG function (Needed for padding and MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode MBEDTLS_RSA_PUBLIC or 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
- *
- * \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.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PRIVATE and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
- * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code
+ * \brief This function performs a PKCS#1 v1.5 encryption operation
+ * (RSAES-PKCS1-v1_5-ENCRYPT).
*
* \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.
+ *
+ * \deprecated It is deprecated and discouraged to call this function
+ * 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 might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Needed for padding and
+ * #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG context.
+ * \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.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -305,32 +616,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 MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode MBEDTLS_RSA_PUBLIC or 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
+ * \note The output buffer must be as large as the size
+ * of ctx->N. For example, 128 Bytes if RSA-1024 is used.
*
- * \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.
+ * \deprecated It is deprecated and discouraged to call this function
+ * 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.
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code
+ * \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 context.
+ * \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.
*
- * \note The output buffer must be as large as the size
- * of ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -342,39 +655,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 MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode MBEDTLS_RSA_PUBLIC or 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
- *
- * \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.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PUBLIC and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
- * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code
+ * It is the generic wrapper for performing a PKCS#1 decryption
+ * operation using the \p mode from the context.
*
* \note The output buffer length \c output_max_len should be
- * as large as the size ctx->len of 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 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 ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
+ *
+ * \deprecated It is deprecated and discouraged to call this function
+ * 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 might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG context.
+ * \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.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -385,37 +701,40 @@
size_t output_max_len );
/**
- * \brief Perform a PKCS#1 v1.5 decryption (RSAES-PKCS1-v1_5-DECRYPT)
- *
- * \param ctx RSA context
- * \param f_rng RNG function (Only needed for MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode MBEDTLS_RSA_PUBLIC or 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
- *
- * \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.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PUBLIC and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
- * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code
+ * \brief This function performs a PKCS#1 v1.5 decryption
+ * operation (RSAES-PKCS1-v1_5-DECRYPT).
*
* \note The output buffer length \c output_max_len should be
- * as large as the size ctx->len of 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 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 ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
+ *
+ * \deprecated It is deprecated and discouraged to call this function
+ * 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 might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG context.
+ * \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.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
+ *
*/
int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -426,39 +745,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 MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode MBEDTLS_RSA_PUBLIC or 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
+ * \note The output buffer length \c output_max_len should be
+ * 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.
*
- * \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.
+ * \note The input buffer must be as large as the size
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*
- * \note Alternative implementations of RSA need not support
- * mode being set to MBEDTLS_RSA_PUBLIC and may instead
- * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ * \deprecated It is deprecated and discouraged to call this function
+ * 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.
*
- * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
*
- * \note The output buffer length \c output_max_len should be
- * as large as the size ctx->len of 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 MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG context.
+ * \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.
*
- * \note The input buffer must be as large as the size
- * of ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -471,37 +793,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
- * MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode MBEDTLS_RSA_PUBLIC or MBEDTLS_RSA_PRIVATE
- * \param md_alg a MBEDTLS_MD_XXX (use MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen message digest length (for 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.
+ *
+ * \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 For PKCS#1 v2.1 encoding, see comments on
+ * mbedtls_rsa_rsassa_pss_sign() for details on
+ * \p md_alg and \p hash_id.
*
* \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 MBEDTLS_ERR_RSA_XXX error code
+ * \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 context.
+ * \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.
*
- * \note The "sig" buffer must be as large as the size
- * of ctx->N (eg. 128 bytes if RSA-1024 is used).
- *
- * \note In case of PKCS#1 v2.1 encoding, see comments on
- * \note \c mbedtls_rsa_rsassa_pss_sign() for details on md_alg and hash_id.
+ * \return \c 0 if the signing operation was successful.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -513,31 +839,33 @@
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 MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode MBEDTLS_RSA_PUBLIC or MBEDTLS_RSA_PRIVATE
- * \param md_alg a MBEDTLS_MD_XXX (use MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen message digest length (for MBEDTLS_MD_NONE only)
- * \param hash buffer holding the message digest
- * \param sig buffer that will hold the ciphertext
+ * \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.
*
* \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 MBEDTLS_ERR_RSA_XXX error code
+ * \param ctx The RSA context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG context.
+ * \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.
*
- * \note The "sig" buffer must be as large as the size
- * of ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \return \c 0 if the signing operation was successful.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -549,37 +877,41 @@
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
- * MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode MBEDTLS_RSA_PUBLIC or MBEDTLS_RSA_PRIVATE
- * \param md_alg a MBEDTLS_MD_XXX (use MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen message digest length (for MBEDTLS_MD_NONE only)
- * \param hash buffer holding the message digest
- * \param sig buffer that will hold the ciphertext
+ * \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 \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.
*
* \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 MBEDTLS_ERR_RSA_XXX error code
+ * \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 context.
+ * \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.
*
- * \note The "sig" buffer must be as large as the size
- * of ctx->N (eg. 128 bytes if RSA-1024 is used).
- *
- * \note The hash_id in the RSA context is the one used for the
- * encoding. 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.
+ * \return \c 0 if the signing operation was successful.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -591,36 +923,40 @@
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 MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode MBEDTLS_RSA_PUBLIC or MBEDTLS_RSA_PRIVATE
- * \param md_alg a MBEDTLS_MD_XXX (use MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen message digest length (for 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.
+ *
+ * \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 For PKCS#1 v2.1 encoding, see comments on
+ * mbedtls_rsa_rsassa_pss_verify() about \p md_alg and
+ * \p hash_id.
*
* \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,
- * or an MBEDTLS_ERR_RSA_XXX error code
+ * \param ctx The RSA public key context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG context.
+ * \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.
*
- * \note The "sig" buffer must be as large as the size
- * of ctx->N (eg. 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.
+ * \return \c 0 if the verify operation was successful.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -632,31 +968,33 @@
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 MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode MBEDTLS_RSA_PUBLIC or MBEDTLS_RSA_PRIVATE
- * \param md_alg a MBEDTLS_MD_XXX (use MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen message digest length (for MBEDTLS_MD_NONE only)
- * \param hash buffer holding the message digest
- * \param sig buffer holding the ciphertext
+ * \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.
*
* \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,
- * or an MBEDTLS_ERR_RSA_XXX error code
+ * \param ctx The RSA public key context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG context.
+ * \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.
*
- * \note The "sig" buffer must be as large as the size
- * of ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \return \c 0 if the verify operation was successful.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -668,38 +1006,44 @@
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 MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode MBEDTLS_RSA_PUBLIC or MBEDTLS_RSA_PRIVATE
- * \param md_alg a MBEDTLS_MD_XXX (use MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen message digest length (for 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.
+ *
+ * \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 \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.
*
* \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,
- * or an MBEDTLS_ERR_RSA_XXX error code
+ * \param ctx The RSA public key context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG context.
+ * \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.
*
- * \note The "sig" buffer must be as large as the size
- * of ctx->N (eg. 128 bytes if RSA-1024 is used).
- *
- * \note The hash_id in the RSA context is the one used for the
- * verification. 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 hash_id in the RSA context is
- * unset, the md_alg from the function call is used.
+ * \return \c 0 if the verify operation was successful.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -711,28 +1055,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 MBEDTLS_RSA_PRIVATE)
- * \param p_rng RNG parameter
- * \param mode MBEDTLS_RSA_PUBLIC or MBEDTLS_RSA_PRIVATE
- * \param md_alg a MBEDTLS_MD_XXX (use MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen message digest length (for 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
- * 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,
- * or an MBEDTLS_ERR_RSA_XXX error code
+ * \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 "sig" buffer must be as large as the size
- * of ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note The \p hash_id in the RSA context is ignored.
*
- * \note The hash_id in the RSA context is ignored.
+ * \param ctx The RSA public key context.
+ * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng The RNG context.
+ * \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.
+ * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
*/
int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -746,27 +1095,40 @@
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,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure
+ * \return \c 0 on success.
+ * \return #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 );
+#ifdef __cplusplus
+}
+#endif
+
+#else /* MBEDTLS_RSA_ALT */
+#include "rsa_alt.h"
+#endif /* MBEDTLS_RSA_ALT */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
/**
- * \brief Checkup routine
+ * \brief The RSA checkup routine.
*
- * \return 0 if successful, or 1 if the test failed
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_rsa_self_test( int verbose );
@@ -774,6 +1136,4 @@
}
#endif
-#endif /* MBEDTLS_RSA_C */
-
#endif /* rsa.h */
diff --git a/include/mbedtls/rsa_internal.h b/include/mbedtls/rsa_internal.h
new file mode 100644
index 0000000..53abd3c
--- /dev/null
+++ b/include/mbedtls/rsa_internal.h
@@ -0,0 +1,226 @@
+/**
+ * \file rsa_internal.h
+ *
+ * \brief Context-independent RSA helper functions
+ *
+ * This module declares some RSA-related helper functions useful when
+ * implementing the RSA interface. These functions are provided in a separate
+ * compilation unit in order to make it easy for designers of alternative RSA
+ * implementations to use them in their own code, as it is conceived that the
+ * functionality they provide will be necessary for most complete
+ * implementations.
+ *
+ * End-users of Mbed TLS who are not providing their own alternative RSA
+ * implementations should not use these functions directly, and should instead
+ * use only the functions declared in rsa.h.
+ *
+ * The interface provided by this module will be maintained through LTS (Long
+ * Term Support) branches of Mbed TLS, but may otherwise be subject to change,
+ * and must be considered an internal interface of the library.
+ *
+ * There are two classes of helper functions:
+ *
+ * (1) Parameter-generating helpers. These are:
+ * - mbedtls_rsa_deduce_primes
+ * - mbedtls_rsa_deduce_private_exponent
+ * - mbedtls_rsa_deduce_crt
+ * Each of these functions takes a set of core RSA parameters and
+ * generates some other, or CRT related parameters.
+ *
+ * (2) Parameter-checking helpers. These are:
+ * - mbedtls_rsa_validate_params
+ * - mbedtls_rsa_validate_crt
+ * They take a set of core or CRT related RSA parameters and check their
+ * validity.
+ *
+ */
+/*
+ * Copyright (C) 2006-2017, ARM Limited, All Rights Reserved
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * 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)
+ *
+ */
+
+#ifndef MBEDTLS_RSA_INTERNAL_H
+#define MBEDTLS_RSA_INTERNAL_H
+
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
+#include "bignum.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+/**
+ * \brief Compute RSA prime moduli P, Q from public modulus N=PQ
+ * and a pair of private and public key.
+ *
+ * \note This is a 'static' helper function not operating on
+ * an RSA context. Alternative implementations need not
+ * overwrite it.
+ *
+ * \param N RSA modulus N = PQ, with P, Q to be found
+ * \param E RSA public exponent
+ * \param D RSA private exponent
+ * \param P Pointer to MPI holding first prime factor of N on success
+ * \param Q Pointer to MPI holding second prime factor of N on success
+ *
+ * \return
+ * - 0 if successful. In this case, P and Q constitute a
+ * factorization of N.
+ * - A non-zero error code otherwise.
+ *
+ * \note It is neither checked that P, Q are prime nor that
+ * D, E are modular inverses wrt. P-1 and Q-1. For that,
+ * use the helper function \c mbedtls_rsa_validate_params.
+ *
+ */
+int mbedtls_rsa_deduce_primes( mbedtls_mpi const *N, mbedtls_mpi const *E,
+ mbedtls_mpi const *D,
+ mbedtls_mpi *P, mbedtls_mpi *Q );
+
+/**
+ * \brief Compute RSA private exponent from
+ * prime moduli and public key.
+ *
+ * \note This is a 'static' helper function not operating on
+ * an RSA context. Alternative implementations need not
+ * overwrite it.
+ *
+ * \param P First prime factor of RSA modulus
+ * \param Q Second prime factor of RSA modulus
+ * \param E RSA public exponent
+ * \param D Pointer to MPI holding the private exponent on success.
+ *
+ * \return
+ * - 0 if successful. In this case, D is set to a simultaneous
+ * modular inverse of E modulo both P-1 and Q-1.
+ * - A non-zero error code otherwise.
+ *
+ * \note This function does not check whether P and Q are primes.
+ *
+ */
+int mbedtls_rsa_deduce_private_exponent( mbedtls_mpi const *P,
+ mbedtls_mpi const *Q,
+ mbedtls_mpi const *E,
+ mbedtls_mpi *D );
+
+
+/**
+ * \brief Generate RSA-CRT parameters
+ *
+ * \note This is a 'static' helper function not operating on
+ * an RSA context. Alternative implementations need not
+ * overwrite it.
+ *
+ * \param P First prime factor of N
+ * \param Q Second prime factor of N
+ * \param D RSA private exponent
+ * \param DP Output variable for D modulo P-1
+ * \param DQ Output variable for D modulo Q-1
+ * \param QP Output variable for the modular inverse of Q modulo P.
+ *
+ * \return 0 on success, non-zero error code otherwise.
+ *
+ * \note This function does not check whether P, Q are
+ * prime and whether D is a valid private exponent.
+ *
+ */
+int mbedtls_rsa_deduce_crt( const mbedtls_mpi *P, const mbedtls_mpi *Q,
+ const mbedtls_mpi *D, mbedtls_mpi *DP,
+ mbedtls_mpi *DQ, mbedtls_mpi *QP );
+
+
+/**
+ * \brief Check validity of core RSA parameters
+ *
+ * \note This is a 'static' helper function not operating on
+ * an RSA context. Alternative implementations need not
+ * overwrite it.
+ *
+ * \param N RSA modulus N = PQ
+ * \param P First prime factor of N
+ * \param Q Second prime factor of N
+ * \param D RSA private exponent
+ * \param E RSA public exponent
+ * \param f_rng PRNG to be used for primality check, or NULL
+ * \param p_rng PRNG context for f_rng, or NULL
+ *
+ * \return
+ * - 0 if the following conditions are satisfied
+ * if all relevant parameters are provided:
+ * - P prime if f_rng != NULL (%)
+ * - Q prime if f_rng != NULL (%)
+ * - 1 < N = P * Q
+ * - 1 < D, E < N
+ * - D and E are modular inverses modulo P-1 and Q-1
+ * (%) This is only done if MBEDTLS_GENPRIME is defined.
+ * - A non-zero error code otherwise.
+ *
+ * \note The function can be used with a restricted set of arguments
+ * to perform specific checks only. E.g., calling it with
+ * (-,P,-,-,-) and a PRNG amounts to a primality check for P.
+ */
+int mbedtls_rsa_validate_params( const mbedtls_mpi *N, const mbedtls_mpi *P,
+ const mbedtls_mpi *Q, const mbedtls_mpi *D,
+ const mbedtls_mpi *E,
+ int (*f_rng)(void *, unsigned char *, size_t),
+ void *p_rng );
+
+/**
+ * \brief Check validity of RSA CRT parameters
+ *
+ * \note This is a 'static' helper function not operating on
+ * an RSA context. Alternative implementations need not
+ * overwrite it.
+ *
+ * \param P First prime factor of RSA modulus
+ * \param Q Second prime factor of RSA modulus
+ * \param D RSA private exponent
+ * \param DP MPI to check for D modulo P-1
+ * \param DQ MPI to check for D modulo P-1
+ * \param QP MPI to check for the modular inverse of Q modulo P.
+ *
+ * \return
+ * - 0 if the following conditions are satisfied:
+ * - D = DP mod P-1 if P, D, DP != NULL
+ * - Q = DQ mod P-1 if P, D, DQ != NULL
+ * - QP = Q^-1 mod P if P, Q, QP != NULL
+ * - \c MBEDTLS_ERR_RSA_KEY_CHECK_FAILED if check failed,
+ * potentially including \c MBEDTLS_ERR_MPI_XXX if some
+ * MPI calculations failed.
+ * - \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA if insufficient
+ * data was provided to check DP, DQ or QP.
+ *
+ * \note The function can be used with a restricted set of arguments
+ * to perform specific checks only. E.g., calling it with the
+ * parameters (P, -, D, DP, -, -) will check DP = D mod P-1.
+ */
+int mbedtls_rsa_validate_crt( const mbedtls_mpi *P, const mbedtls_mpi *Q,
+ const mbedtls_mpi *D, const mbedtls_mpi *DP,
+ const mbedtls_mpi *DQ, const mbedtls_mpi *QP );
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* rsa_internal.h */
diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h
index 7a67c6c..eec3f95 100644
--- a/include/mbedtls/sha1.h
+++ b/include/mbedtls/sha1.h
@@ -1,9 +1,17 @@
/**
* \file sha1.h
*
- * \brief SHA-1 cryptographic hash function
+ * \brief This file contains SHA-1 definitions and functions.
*
- * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * The Secure Hash Algorithm 1 (SHA-1) cryptographic hash function is defined in
+ * <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
+ *
+ * \warning SHA-1 is considered a weak message digest and its use constitutes
+ * a security risk. We recommend considering stronger message
+ * digests instead.
+ */
+/*
+ * 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
@@ -18,7 +26,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
@@ -32,6 +40,8 @@
#include <stddef.h>
#include <stdint.h>
+#define MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED -0x0035 /**< SHA-1 hardware accelerator failed */
+
#if !defined(MBEDTLS_SHA1_ALT)
// Regular implementation
//
@@ -41,65 +51,197 @@
#endif
/**
- * \brief SHA-1 context structure
+ * \brief The SHA-1 context structure.
+ *
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
*/
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
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ * \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
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ * \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
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ * \param dst The SHA-1 context to clone to.
+ * \param src The SHA-1 context to clone from.
+ *
*/
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
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ * \param ctx The SHA-1 context to initialize.
+ *
+ * \return \c 0 on success.
+ *
*/
-void mbedtls_sha1_starts( mbedtls_sha1_context *ctx );
+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
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ * \param ctx The SHA-1 context.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ *
+ * \return \c 0 on success.
*/
-void mbedtls_sha1_update( mbedtls_sha1_context *ctx, const unsigned char *input, size_t ilen );
+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
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ * \param ctx The SHA-1 context.
+ * \param output The SHA-1 checksum result.
+ *
+ * \return \c 0 on success.
*/
-void mbedtls_sha1_finish( mbedtls_sha1_context *ctx, unsigned char output[20] );
+int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx,
+ unsigned char output[20] );
-/* Internal use */
-void mbedtls_sha1_process( mbedtls_sha1_context *ctx, const unsigned char data[64] );
+/**
+ * \brief SHA-1 process data block (internal use only).
+ *
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ * \param ctx The SHA-1 context.
+ * \param data The data block being processed.
+ *
+ * \return \c 0 on success.
+ *
+ */
+int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
+ const unsigned char data[64] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief This function starts a SHA-1 checksum calculation.
+ *
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ * \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0.
+ *
+ * \param ctx The SHA-1 context to initialize.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_sha1_starts( mbedtls_sha1_context *ctx );
+
+/**
+ * \brief This function feeds an input buffer into an ongoing SHA-1
+ * checksum calculation.
+ *
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ * \deprecated Superseded by mbedtls_sha1_update_ret() in 2.7.0.
+ *
+ * \param ctx The SHA-1 context.
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_sha1_update( mbedtls_sha1_context *ctx,
+ const unsigned char *input,
+ size_t ilen );
+
+/**
+ * \brief This function finishes the SHA-1 operation, and writes
+ * the result to the output buffer.
+ *
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ * \deprecated Superseded by mbedtls_sha1_finish_ret() in 2.7.0.
+ *
+ * \param ctx The SHA-1 context.
+ * \param output The SHA-1 checksum result.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_sha1_finish( mbedtls_sha1_context *ctx,
+ unsigned char output[20] );
+
+/**
+ * \brief SHA-1 process data block (internal use only).
+ *
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ * \deprecated Superseded by mbedtls_internal_sha1_process() in 2.7.0.
+ *
+ * \param ctx The SHA-1 context.
+ * \param data The data block being processed.
+ *
+ */
+MBEDTLS_DEPRECATED void mbedtls_sha1_process( mbedtls_sha1_context *ctx,
+ const unsigned char data[64] );
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
#ifdef __cplusplus
}
@@ -114,18 +256,72 @@
#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.
+ *
+ * The SHA-1 result is calculated as
+ * output = SHA-1(input buffer).
+ *
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ * \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 on success.
+ *
*/
-void mbedtls_sha1( const unsigned char *input, size_t ilen, unsigned char output[20] );
+int mbedtls_sha1_ret( const unsigned char *input,
+ size_t ilen,
+ unsigned char output[20] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief This function calculates the SHA-1 checksum of a buffer.
+ *
+ * The function allocates the context, performs the
+ * calculation, and frees the context.
+ *
+ * The SHA-1 result is calculated as
+ * output = SHA-1(input buffer).
+ *
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ * \deprecated Superseded by mbedtls_sha1_ret() in 2.7.0
+ *
+ * \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 void mbedtls_sha1( const unsigned char *input,
+ size_t ilen,
+ unsigned char output[20] );
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
/**
- * \brief Checkup routine
+ * \brief The SHA-1 checkup routine.
*
- * \return 0 if successful, or 1 if the test failed
+ * \warning SHA-1 is considered a weak message digest and its use
+ * constitutes a security risk. We recommend considering
+ * stronger message digests instead.
+ *
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
+ *
*/
int mbedtls_sha1_self_test( int verbose );
diff --git a/include/mbedtls/sha256.h b/include/mbedtls/sha256.h
index f8041ad..c4465e5 100644
--- a/include/mbedtls/sha256.h
+++ b/include/mbedtls/sha256.h
@@ -1,9 +1,13 @@
/**
* \file sha256.h
*
- * \brief SHA-224 and SHA-256 cryptographic hash function
+ * \brief This file contains SHA-224 and SHA-256 definitions and functions.
*
- * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * The Secure Hash Algorithms 224 and 256 (SHA-224 and SHA-256) cryptographic
+ * hash functions are defined in <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
+ */
+/*
+ * 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
@@ -18,7 +22,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
@@ -32,6 +36,8 @@
#include <stddef.h>
#include <stdint.h>
+#define MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED -0x0037 /**< SHA-256 hardware accelerator failed */
+
#if !defined(MBEDTLS_SHA256_ALT)
// Regular implementation
//
@@ -41,69 +47,157 @@
#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:
+ 0: Use SHA-256, or 1: Use SHA-224. */
}
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:
+ * 0: Use SHA-256, or 1: Use SHA-224.
+ *
+ * \return \c 0 on success.
*/
-void mbedtls_sha256_starts( mbedtls_sha256_context *ctx, int is224 );
+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
+ * \param ctx The SHA-256 context.
+ * \param input The buffer holding the data.
+ * \param ilen The length of the input data.
+ *
+ * \return \c 0 on success.
*/
-void mbedtls_sha256_update( mbedtls_sha256_context *ctx, const unsigned char *input,
- size_t ilen );
+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 \c 0 on success.
*/
-void mbedtls_sha256_finish( mbedtls_sha256_context *ctx, unsigned char output[32] );
+int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx,
+ unsigned char output[32] );
-/* Internal use */
-void mbedtls_sha256_process( mbedtls_sha256_context *ctx, const unsigned char data[64] );
+/**
+ * \brief This function processes a single data block within
+ * the ongoing SHA-256 computation. This function is for
+ * internal use only.
+ *
+ * \param ctx The SHA-256 context.
+ * \param data The buffer holding one block of data.
+ *
+ * \return \c 0 on success.
+ */
+int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx,
+ const unsigned char data[64] );
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief This function starts a SHA-224 or SHA-256 checksum
+ * calculation.
+ *
+ *
+ * \deprecated Superseded by mbedtls_sha256_starts_ret() in 2.7.0.
+ *
+ * \param ctx The context to initialize.
+ * \param is224 Determines which function to use:
+ * 0: Use SHA-256, or 1: Use SHA-224.
+ */
+MBEDTLS_DEPRECATED void mbedtls_sha256_starts( mbedtls_sha256_context *ctx,
+ int is224 );
+
+/**
+ * \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.
+ *
+ * \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 void mbedtls_sha256_update( mbedtls_sha256_context *ctx,
+ const unsigned char *input,
+ size_t ilen );
+
+/**
+ * \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.
+ *
+ * \param ctx The SHA-256 context.
+ * \param output The SHA-224 or SHA-256 checksum result.
+ */
+MBEDTLS_DEPRECATED void mbedtls_sha256_finish( mbedtls_sha256_context *ctx,
+ unsigned char output[32] );
+
+/**
+ * \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.
+ *
+ * \param ctx The SHA-256 context.
+ * \param data The buffer holding one block of data.
+ */
+MBEDTLS_DEPRECATED void mbedtls_sha256_process( mbedtls_sha256_context *ctx,
+ const unsigned char data[64] );
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
#ifdef __cplusplus
}
#endif
@@ -117,20 +211,64 @@
#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.
+ *
+ * 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:
+ * 0: Use SHA-256, or 1: Use SHA-224.
*/
-void mbedtls_sha256( const unsigned char *input, size_t ilen,
- unsigned char output[32], int is224 );
+int mbedtls_sha256_ret( const unsigned char *input,
+ size_t ilen,
+ unsigned char output[32],
+ int is224 );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
/**
- * \brief Checkup routine
+ * \brief This function calculates the SHA-224 or SHA-256 checksum
+ * of a buffer.
*
- * \return 0 if successful, or 1 if the test failed
+ * The function allocates the context, performs the
+ * calculation, and frees the context.
+ *
+ * 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:
+ * 0: Use SHA-256, or 1: Use SHA-224.
+ */
+MBEDTLS_DEPRECATED void mbedtls_sha256( const unsigned char *input,
+ size_t ilen,
+ unsigned char output[32],
+ int is224 );
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+
+/**
+ * \brief The SHA-224 and SHA-256 checkup routine.
+ *
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_sha256_self_test( int verbose );
diff --git a/include/mbedtls/sha512.h b/include/mbedtls/sha512.h
index 627694f..ee88fcf 100644
--- a/include/mbedtls/sha512.h
+++ b/include/mbedtls/sha512.h
@@ -1,9 +1,12 @@
/**
* \file sha512.h
+ * \brief This file contains SHA-384 and SHA-512 definitions and functions.
*
- * \brief SHA-384 and SHA-512 cryptographic hash function
- *
- * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * The Secure Hash Algorithms 384 and 512 (SHA-384 and SHA-512) cryptographic
+ * hash functions are defined in <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
+ */
+/*
+ * 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
@@ -18,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_SHA512_H
#define MBEDTLS_SHA512_H
@@ -32,6 +35,8 @@
#include <stddef.h>
#include <stdint.h>
+#define MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED -0x0039 /**< SHA-512 hardware accelerator failed */
+
#if !defined(MBEDTLS_SHA512_ALT)
// Regular implementation
//
@@ -41,65 +46,156 @@
#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:
+ 0: Use SHA-512, or 1: Use SHA-384. */
}
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:
+ * 0: Use SHA-512, or 1: Use SHA-384.
+ *
+ * \return \c 0 on success.
*/
-void mbedtls_sha512_starts( mbedtls_sha512_context *ctx, int is384 );
+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 \c 0 on success.
*/
-void mbedtls_sha512_update( mbedtls_sha512_context *ctx, const unsigned char *input,
+int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,
+ 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 \c 0 on success.
*/
-void mbedtls_sha512_finish( mbedtls_sha512_context *ctx, unsigned char output[64] );
+int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
+ unsigned char output[64] );
+
+/**
+ * \brief This function processes a single data block within
+ * the ongoing SHA-512 computation.
+ *
+ * \param ctx The SHA-512 context.
+ * \param data The buffer holding one block of data.
+ *
+ * \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))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \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 The SHA-512 context to initialize.
+ * \param is384 Determines which function to use:
+ * 0: Use SHA-512, or 1: Use SHA-384.
+ */
+MBEDTLS_DEPRECATED void mbedtls_sha512_starts( mbedtls_sha512_context *ctx,
+ int is384 );
+
+/**
+ * \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 The SHA-512 context.
+ * \param input The buffer holding the data.
+ * \param ilen The length of the input data.
+ */
+MBEDTLS_DEPRECATED void mbedtls_sha512_update( mbedtls_sha512_context *ctx,
+ const unsigned char *input,
+ size_t ilen );
+
+/**
+ * \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 The SHA-512 context.
+ * \param output The SHA-384 or SHA-512 checksum result.
+ */
+MBEDTLS_DEPRECATED void mbedtls_sha512_finish( mbedtls_sha512_context *ctx,
+ unsigned char output[64] );
+
+/**
+ * \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 The SHA-512 context.
+ * \param data The buffer holding one block of data.
+ */
+MBEDTLS_DEPRECATED void mbedtls_sha512_process(
+ mbedtls_sha512_context *ctx,
+ const unsigned char data[128] );
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
#ifdef __cplusplus
}
@@ -114,26 +210,67 @@
#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.
+ *
+ * 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:
+ * 0: Use SHA-512, or 1: Use SHA-384.
+ *
+ * \return \c 0 on success.
*/
-void mbedtls_sha512( const unsigned char *input, size_t ilen,
- unsigned char output[64], int is384 );
+int mbedtls_sha512_ret( const unsigned char *input,
+ size_t ilen,
+ unsigned char output[64],
+ int is384 );
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
/**
- * \brief Checkup routine
+ * \brief This function calculates the SHA-512 or SHA-384
+ * checksum of a buffer.
*
- * \return 0 if successful, or 1 if the test failed
+ * 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 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:
+ * 0: Use SHA-512, or 1: Use SHA-384.
+ */
+MBEDTLS_DEPRECATED void mbedtls_sha512( const unsigned char *input,
+ size_t ilen,
+ unsigned char output[64],
+ int is384 );
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+ /**
+ * \brief The SHA-384 or SHA-512 checkup routine.
+ *
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_sha512_self_test( int verbose );
-/* Internal use */
-void mbedtls_sha512_process( mbedtls_sha512_context *ctx, const unsigned char data[128] );
-
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index d895f3a..720c338 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -2,7 +2,8 @@
* \file ssl.h
*
* \brief SSL/TLS functions.
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -48,6 +49,15 @@
#endif
#if defined(MBEDTLS_ZLIB_SUPPORT)
+
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#warning "Record compression support via MBEDTLS_ZLIB_SUPPORT is deprecated and will be removed in the next major revision of the library"
+#endif
+
+#if defined(MBEDTLS_DEPRECATED_REMOVED)
+#error "Record compression support via MBEDTLS_ZLIB_SUPPORT is deprecated and cannot be used if MBEDTLS_DEPRECATED_REMOVED is set"
+#endif
+
#include "zlib.h"
#endif
@@ -102,14 +112,15 @@
#define MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED -0x6A80 /**< DTLS client must retry for hello verification */
#define MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL -0x6A00 /**< A buffer is too small to receive or write a message */
#define MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE -0x6980 /**< None of the common ciphersuites is usable (eg, no suitable certificate, see debug messages). */
-#define MBEDTLS_ERR_SSL_WANT_READ -0x6900 /**< Connection requires a read call. */
+#define MBEDTLS_ERR_SSL_WANT_READ -0x6900 /**< No data of requested type currently available on underlying transport. */
#define MBEDTLS_ERR_SSL_WANT_WRITE -0x6880 /**< Connection requires a write call. */
#define MBEDTLS_ERR_SSL_TIMEOUT -0x6800 /**< The operation timed out. */
#define MBEDTLS_ERR_SSL_CLIENT_RECONNECT -0x6780 /**< The client initiated a reconnect from the same port. */
#define MBEDTLS_ERR_SSL_UNEXPECTED_RECORD -0x6700 /**< Record header looks valid but is not expected. */
#define MBEDTLS_ERR_SSL_NON_FATAL -0x6680 /**< The alert message received indicates a non-fatal error. */
#define MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH -0x6600 /**< Couldn't set the hash for verifying CertificateVerify */
-#define MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS -0x6580 /**< Asynchronous operation is not completed yet */
+#define MBEDTLS_ERR_SSL_CONTINUE_PROCESSING -0x6580 /**< Internal-only message signaling that further message-processing should be done */
+#define MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS -0x6500 /**< The asynchronous operation is not completed yet. */
/*
* Various constants
@@ -839,10 +850,18 @@
#endif
#if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
- unsigned char *psk; /*!< pre-shared key */
- size_t psk_len; /*!< length of the pre-shared key */
- unsigned char *psk_identity; /*!< identity for PSK negotiation */
- size_t psk_identity_len;/*!< length of identity */
+ unsigned char *psk; /*!< pre-shared key. This field should
+ only be set via
+ mbedtls_ssl_conf_psk() */
+ size_t psk_len; /*!< length of the pre-shared key. This
+ field should only be set via
+ mbedtls_ssl_conf_psk() */
+ unsigned char *psk_identity; /*!< identity for PSK negotiation. This
+ field should only be set via
+ mbedtls_ssl_conf_psk() */
+ size_t psk_identity_len;/*!< length of identity. This field should
+ only be set via
+ mbedtls_ssl_conf_psk() */
#endif
#if defined(MBEDTLS_SSL_ALPN)
@@ -1137,8 +1156,13 @@
* \note No copy of the configuration context is made, it can be
* shared by many mbedtls_ssl_context structures.
*
- * \warning Modifying the conf structure after it has been used in this
- * function is unsupported!
+ * \warning The conf structure will be accessed during the session.
+ * It must not be modified or freed as long as the session
+ * is active.
+ *
+ * \warning This function must be called exactly once per context.
+ * Calling mbedtls_ssl_setup again is not supported, even
+ * if no session is active.
*
* \param ssl SSL context
* \param conf SSL configuration to use
@@ -1787,6 +1811,10 @@
/**
* \brief Set the data required to verify peer certificate
*
+ * \note See \c mbedtls_x509_crt_verify() for notes regarding the
+ * parameters ca_chain (maps to trust_ca for that function)
+ * and ca_crl.
+ *
* \param conf SSL configuration
* \param ca_chain trusted CA chain (meaning all fully trusted top-level CAs)
* \param ca_crl trusted CA CRLs
@@ -1900,18 +1928,50 @@
#endif /* MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED */
#if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_SRV_C)
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+
/**
* \brief Set the Diffie-Hellman public P and G values,
* read as hexadecimal strings (server-side only)
- * (Default: MBEDTLS_DHM_RFC5114_MODP_2048_[PG])
+ * (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG])
*
* \param conf SSL configuration
* \param dhm_P Diffie-Hellman-Merkle modulus
* \param dhm_G Diffie-Hellman-Merkle generator
*
+ * \deprecated Superseded by \c mbedtls_ssl_conf_dh_param_bin.
+ *
* \return 0 if successful
*/
-int mbedtls_ssl_conf_dh_param( mbedtls_ssl_config *conf, const char *dhm_P, const char *dhm_G );
+MBEDTLS_DEPRECATED int mbedtls_ssl_conf_dh_param( mbedtls_ssl_config *conf,
+ const char *dhm_P,
+ const char *dhm_G );
+
+#endif /* MBEDTLS_DEPRECATED_REMOVED */
+
+/**
+ * \brief Set the Diffie-Hellman public P and G values
+ * from big-endian binary presentations.
+ * (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG]_BIN)
+ *
+ * \param conf SSL configuration
+ * \param dhm_P Diffie-Hellman-Merkle modulus in big-endian binary form
+ * \param P_len Length of DHM modulus
+ * \param dhm_G Diffie-Hellman-Merkle generator in big-endian binary form
+ * \param G_len Length of DHM generator
+ *
+ * \return 0 if successful
+ */
+int mbedtls_ssl_conf_dh_param_bin( mbedtls_ssl_config *conf,
+ const unsigned char *dhm_P, size_t P_len,
+ const unsigned char *dhm_G, size_t G_len );
/**
* \brief Set the Diffie-Hellman public P and G values,
@@ -2443,11 +2503,59 @@
#endif /* MBEDTLS_SSL_RENEGOTIATION */
/**
- * \brief Return the number of data bytes available to read
+ * \brief Check if there is data already read from the
+ * underlying transport but not yet processed.
*
* \param ssl SSL context
*
- * \return how many bytes are available in the read buffer
+ * \return 0 if nothing's pending, 1 otherwise.
+ *
+ * \note This is different in purpose and behaviour from
+ * \c mbedtls_ssl_get_bytes_avail in that it considers
+ * any kind of unprocessed data, not only unread
+ * application data. If \c mbedtls_ssl_get_bytes
+ * returns a non-zero value, this function will
+ * also signal pending data, but the converse does
+ * not hold. For example, in DTLS there might be
+ * further records waiting to be processed from
+ * the current underlying transport's datagram.
+ *
+ * \note If this function returns 1 (data pending), this
+ * does not imply that a subsequent call to
+ * \c mbedtls_ssl_read will provide any data;
+ * e.g., the unprocessed data might turn out
+ * to be an alert or a handshake message.
+ *
+ * \note This function is useful in the following situation:
+ * If the SSL/TLS module successfully returns from an
+ * operation - e.g. a handshake or an application record
+ * read - and you're awaiting incoming data next, you
+ * must not immediately idle on the underlying transport
+ * to have data ready, but you need to check the value
+ * of this function first. The reason is that the desired
+ * data might already be read but not yet processed.
+ * If, in contrast, a previous call to the SSL/TLS module
+ * returned MBEDTLS_ERR_SSL_WANT_READ, it is not necessary
+ * to call this function, as the latter error code entails
+ * that all internal data has been processed.
+ *
+ */
+int mbedtls_ssl_check_pending( const mbedtls_ssl_context *ssl );
+
+/**
+ * \brief Return the number of application data bytes
+ * remaining to be read from the current record.
+ *
+ * \param ssl SSL context
+ *
+ * \return How many bytes are available in the application
+ * data record read buffer.
+ *
+ * \note When working over a datagram transport, this is
+ * useful to detect the current datagram's boundary
+ * in case \c mbedtls_ssl_read has written the maximal
+ * amount of data fitting into the input buffer.
+ *
*/
size_t mbedtls_ssl_get_bytes_avail( const mbedtls_ssl_context *ssl );
@@ -2562,11 +2670,25 @@
* MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED (see below), or
* a specific SSL error code.
*
+ * If this function returns MBEDTLS_ERR_SSL_WANT_READ, the
+ * handshake is unfinished and no further data is available
+ * from the underlying transport. In this case, you must call
+ * the function again at some later stage.
+ *
+ * \note Remarks regarding event-driven DTLS:
+ * If the function returns MBEDTLS_ERR_SSL_WANT_READ, no datagram
+ * from the underlying transport layer is currently being processed,
+ * and it is safe to idle until the timer or the underlying transport
+ * signal a new event. This is not true for a successful handshake,
+ * in which case the datagram of the underlying transport that is
+ * currently being processed might or might not contain further
+ * DTLS records.
+ *
* \note If this function returns something other than 0 or
- * MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
- * becomes unusable, and you should either free it or call
- * \c mbedtls_ssl_session_reset() on it before re-using it for
- * a new connection; the current connection must be closed.
+ * MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
+ * the SSL context for reading or writing, and either free it or
+ * call \c mbedtls_ssl_session_reset() on it before re-using it
+ * for a new connection; the current connection must be closed.
*
* \note If DTLS is in use, then you may choose to handle
* MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging
@@ -2583,10 +2705,10 @@
* call this function if state is MBEDTLS_SSL_HANDSHAKE_OVER.
*
* \note If this function returns something other than 0 or
- * MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
- * becomes unusable, and you should either free it or call
- * \c mbedtls_ssl_session_reset() on it before re-using it for
- * a new connection; the current connection must be closed.
+ * MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
+ * the SSL context for reading or writing, and either free it or
+ * call \c mbedtls_ssl_session_reset() on it before re-using it
+ * for a new connection; the current connection must be closed.
*
* \param ssl SSL context
*
@@ -2610,10 +2732,10 @@
* value.
*
* \note If this function returns something other than 0 or
- * MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
- * becomes unusable, and you should either free it or call
- * \c mbedtls_ssl_session_reset() on it before re-using it for
- * a new connection; the current connection must be closed.
+ * MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
+ * the SSL context for reading or writing, and either free it or
+ * call \c mbedtls_ssl_session_reset() on it before re-using it
+ * for a new connection; the current connection must be closed.
*/
int mbedtls_ssl_renegotiate( mbedtls_ssl_context *ssl );
#endif /* MBEDTLS_SSL_RENEGOTIATION */
@@ -2625,20 +2747,20 @@
* \param buf buffer that will hold the data
* \param len maximum number of bytes to read
*
- * \return the number of bytes read, or
- * 0 for EOF, or
- * MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or
- * MBEDTLS_ERR_SSL_CLIENT_RECONNECT (see below), or
- * another negative error code.
+ * \return One of the following:
+ * - 0 if the read end of the underlying transport was closed,
+ * - the (positive) number of bytes read, or
+ * - a negative error code on failure.
*
- * \note If this function returns something other than a positive
- * value or MBEDTLS_ERR_SSL_WANT_READ/WRITE or
- * MBEDTLS_ERR_SSL_CLIENT_RECONNECT, then the ssl context
- * becomes unusable, and you should either free it or call
- * \c mbedtls_ssl_session_reset() on it before re-using it for
- * a new connection; the current connection must be closed.
+ * If MBEDTLS_ERR_SSL_WANT_READ is returned, no application data
+ * is available from the underlying transport. In this case,
+ * the function needs to be called again at some later stage.
*
- * \note When this function return MBEDTLS_ERR_SSL_CLIENT_RECONNECT
+ * If MBEDTLS_ERR_SSL_WANT_WRITE is returned, a write is pending
+ * but the underlying transport isn't available for writing. In this
+ * case, the function needs to be called again at some later stage.
+ *
+ * When this function return MBEDTLS_ERR_SSL_CLIENT_RECONNECT
* (which can only happen server-side), it means that a client
* is initiating a new connection using the same source port.
* You can either treat that as a connection close and wait
@@ -2651,6 +2773,28 @@
* again. WARNING: not validating the identity of the client
* again, or not transmitting the new identity to the
* application layer, would allow authentication bypass!
+ *
+ * \note If this function returns something other than a positive value
+ * or MBEDTLS_ERR_SSL_WANT_READ/WRITE or MBEDTLS_ERR_SSL_CLIENT_RECONNECT,
+ * you must stop using the SSL context for reading or writing,
+ * and either free it or call \c mbedtls_ssl_session_reset() on it
+ * before re-using it for a new connection; the current connection
+ * must be closed.
+ *
+ * \note Remarks regarding event-driven DTLS:
+ * - If the function returns MBEDTLS_ERR_SSL_WANT_READ, no datagram
+ * from the underlying transport layer is currently being processed,
+ * and it is safe to idle until the timer or the underlying transport
+ * signal a new event.
+ * - This function may return MBEDTLS_ERR_SSL_WANT_READ even if data was
+ * initially available on the underlying transport, as this data may have
+ * been only e.g. duplicated messages or a renegotiation request.
+ * Therefore, you must be prepared to receive MBEDTLS_ERR_SSL_WANT_READ even
+ * when reacting to an incoming-data event from the underlying transport.
+ * - On success, the datagram of the underlying transport that is currently
+ * being processed may contain further DTLS records. You should call
+ * \c mbedtls_ssl_check_pending to check for remaining records.
+ *
*/
int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len );
@@ -2671,15 +2815,17 @@
* or MBEDTLS_ERR_SSL_WANT_WRITE or MBEDTLS_ERR_SSL_WANT_READ,
* or another negative error code.
*
- * \note If this function returns something other than a positive
- * value or MBEDTLS_ERR_SSL_WANT_READ/WRITE, the ssl context
- * becomes unusable, and you should either free it or call
- * \c mbedtls_ssl_session_reset() on it before re-using it for
- * a new connection; the current connection must be closed.
+ * \note If this function returns something other than a positive value
+ * or MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
+ * the SSL context for reading or writing, and either free it or
+ * call \c mbedtls_ssl_session_reset() on it before re-using it
+ * for a new connection; the current connection must be closed.
*
* \note When this function returns MBEDTLS_ERR_SSL_WANT_WRITE/READ,
* it must be called later with the *same* arguments,
- * until it returns a positive value.
+ * until it returns a positive value. When the function returns
+ * MBEDTLS_ERR_SSL_WANT_WRITE there may be some partial
+ * data in the output buffer, however this is not yet sent.
*
* \note If the requested length is greater than the maximum
* fragment length (either the built-in limit or the one set
@@ -2702,10 +2848,10 @@
* \return 0 if successful, or a specific SSL error code.
*
* \note If this function returns something other than 0 or
- * MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
- * becomes unusable, and you should either free it or call
- * \c mbedtls_ssl_session_reset() on it before re-using it for
- * a new connection; the current connection must be closed.
+ * MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
+ * the SSL context for reading or writing, and either free it or
+ * call \c mbedtls_ssl_session_reset() on it before re-using it
+ * for a new connection; the current connection must be closed.
*/
int mbedtls_ssl_send_alert_message( mbedtls_ssl_context *ssl,
unsigned char level,
@@ -2718,10 +2864,10 @@
* \return 0 if successful, or a specific SSL error code.
*
* \note If this function returns something other than 0 or
- * MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
- * becomes unusable, and you should either free it or call
- * \c mbedtls_ssl_session_reset() on it before re-using it for
- * a new connection; the current connection must be closed.
+ * MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
+ * the SSL context for reading or writing, and either free it or
+ * call \c mbedtls_ssl_session_reset() on it before re-using it
+ * for a new connection; the current connection must be closed.
*/
int mbedtls_ssl_close_notify( mbedtls_ssl_context *ssl );
diff --git a/include/mbedtls/ssl_cache.h b/include/mbedtls/ssl_cache.h
index 3734bb7..ec081e6 100644
--- a/include/mbedtls/ssl_cache.h
+++ b/include/mbedtls/ssl_cache.h
@@ -2,7 +2,8 @@
* \file ssl_cache.h
*
* \brief SSL session cache implementation
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/ssl_ciphersuites.h b/include/mbedtls/ssl_ciphersuites.h
index 9101d9c..545468a 100644
--- a/include/mbedtls/ssl_ciphersuites.h
+++ b/include/mbedtls/ssl_ciphersuites.h
@@ -2,7 +2,8 @@
* \file ssl_ciphersuites.h
*
* \brief SSL Ciphersuites for mbed TLS
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/ssl_cookie.h b/include/mbedtls/ssl_cookie.h
index 037e1c3..80b65bb 100644
--- a/include/mbedtls/ssl_cookie.h
+++ b/include/mbedtls/ssl_cookie.h
@@ -2,7 +2,8 @@
* \file ssl_cookie.h
*
* \brief DTLS cookie callbacks implementation
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/ssl_internal.h b/include/mbedtls/ssl_internal.h
index c141e8a..6f36711 100644
--- a/include/mbedtls/ssl_internal.h
+++ b/include/mbedtls/ssl_internal.h
@@ -1,8 +1,9 @@
/**
- * \file ssl_ticket.h
+ * \file ssl_internal.h
*
* \brief Internal functions shared by the SSL modules
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -24,6 +25,7 @@
#define MBEDTLS_SSL_INTERNAL_H
#include "ssl.h"
+#include "cipher.h"
#if defined(MBEDTLS_MD5_C)
#include "md5.h"
@@ -69,6 +71,9 @@
#endif /* MBEDTLS_SSL_PROTO_TLS1 */
#endif /* MBEDTLS_SSL_PROTO_SSL3 */
+#define MBEDTLS_SSL_MIN_VALID_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_1
+#define MBEDTLS_SSL_MIN_VALID_MAJOR_VERSION MBEDTLS_SSL_MAJOR_VERSION_3
+
/* Determine maximum supported version */
#define MBEDTLS_SSL_MAX_MAJOR_VERSION MBEDTLS_SSL_MAJOR_VERSION_3
@@ -138,14 +143,34 @@
#define MBEDTLS_SSL_PADDING_ADD 0
#endif
-#define MBEDTLS_SSL_BUFFER_LEN ( MBEDTLS_SSL_MAX_CONTENT_LEN \
- + MBEDTLS_SSL_COMPRESSION_ADD \
- + 29 /* counter + header + IV */ \
- + MBEDTLS_SSL_MAC_ADD \
- + MBEDTLS_SSL_PADDING_ADD \
+#define MBEDTLS_SSL_PAYLOAD_LEN ( MBEDTLS_SSL_MAX_CONTENT_LEN \
+ + MBEDTLS_SSL_COMPRESSION_ADD \
+ + MBEDTLS_MAX_IV_LENGTH \
+ + MBEDTLS_SSL_MAC_ADD \
+ + MBEDTLS_SSL_PADDING_ADD \
)
/*
+ * Check that we obey the standard's message size bounds
+ */
+
+#if MBEDTLS_SSL_MAX_CONTENT_LEN > 16384
+#error Bad configuration - record content too large.
+#endif
+
+#if MBEDTLS_SSL_PAYLOAD_LEN > 16384 + 2048
+#error Bad configuration - protected record payload too large.
+#endif
+
+/* Note: Even though the TLS record header is only 5 bytes
+ long, we're internally using 8 bytes to store the
+ implicit sequence number. */
+#define MBEDTLS_SSL_HEADER_LEN 13
+
+#define MBEDTLS_SSL_BUFFER_LEN \
+ ( ( MBEDTLS_SSL_HEADER_LEN ) + ( MBEDTLS_SSL_PAYLOAD_LEN ) )
+
+/*
* TLS extension flags (for extensions with outgoing ServerHello content
* that need it (e.g. for RENEGOTIATION_INFO the server already knows because
* of state of the renegotiation flag, so no indicator is required)
@@ -606,9 +631,9 @@
static inline int mbedtls_ssl_safer_memcmp( const void *a, const void *b, size_t n )
{
size_t i;
- const unsigned char *A = (const unsigned char *) a;
- const unsigned char *B = (const unsigned char *) b;
- unsigned char diff = 0;
+ volatile const unsigned char *A = (volatile const unsigned char *) a;
+ volatile const unsigned char *B = (volatile const unsigned char *) b;
+ volatile unsigned char diff = 0;
for( i = 0; i < n; i++ )
diff |= A[i] ^ B[i];
@@ -616,6 +641,23 @@
return( diff );
}
+#if defined(MBEDTLS_SSL_PROTO_SSL3) || defined(MBEDTLS_SSL_PROTO_TLS1) || \
+ defined(MBEDTLS_SSL_PROTO_TLS1_1)
+int mbedtls_ssl_get_key_exchange_md_ssl_tls( mbedtls_ssl_context *ssl,
+ unsigned char *output,
+ unsigned char *data, size_t data_len );
+#endif /* MBEDTLS_SSL_PROTO_SSL3 || MBEDTLS_SSL_PROTO_TLS1 || \
+ MBEDTLS_SSL_PROTO_TLS1_1 */
+
+#if defined(MBEDTLS_SSL_PROTO_TLS1) || defined(MBEDTLS_SSL_PROTO_TLS1_1) || \
+ defined(MBEDTLS_SSL_PROTO_TLS1_2)
+int mbedtls_ssl_get_key_exchange_md_tls1_2( mbedtls_ssl_context *ssl,
+ unsigned char *hash, size_t *hashlen,
+ unsigned char *data, size_t data_len,
+ mbedtls_md_type_t md_alg );
+#endif /* MBEDTLS_SSL_PROTO_TLS1 || MBEDTLS_SSL_PROTO_TLS1_1 || \
+ MBEDTLS_SSL_PROTO_TLS1_2 */
+
#ifdef __cplusplus
}
#endif
diff --git a/include/mbedtls/ssl_ticket.h b/include/mbedtls/ssl_ticket.h
index 7c6bc61..93ad46a 100644
--- a/include/mbedtls/ssl_ticket.h
+++ b/include/mbedtls/ssl_ticket.h
@@ -2,7 +2,8 @@
* \file ssl_ticket.h
*
* \brief TLS server ticket callbacks implementation
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/threading.h b/include/mbedtls/threading.h
index b0c34ec..aeea5d0 100644
--- a/include/mbedtls/threading.h
+++ b/include/mbedtls/threading.h
@@ -2,7 +2,8 @@
* \file threading.h
*
* \brief Threading abstraction layer
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -95,8 +96,12 @@
/*
* Global mutexes
*/
+#if defined(MBEDTLS_FS_IO)
extern mbedtls_threading_mutex_t mbedtls_threading_readdir_mutex;
+#endif
+#if defined(MBEDTLS_HAVE_TIME_DATE)
extern mbedtls_threading_mutex_t mbedtls_threading_gmtime_mutex;
+#endif
#endif /* MBEDTLS_THREADING_C */
#ifdef __cplusplus
diff --git a/include/mbedtls/timing.h b/include/mbedtls/timing.h
index bfb8579..2c497bf 100644
--- a/include/mbedtls/timing.h
+++ b/include/mbedtls/timing.h
@@ -2,7 +2,8 @@
* \file timing.h
*
* \brief Portable interface to timeouts and to the CPU cycle counter
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/version.h b/include/mbedtls/version.h
index 3b209a6..c3ee649 100644
--- a/include/mbedtls/version.h
+++ b/include/mbedtls/version.h
@@ -2,7 +2,8 @@
* \file version.h
*
* \brief Run-time version information
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -38,7 +39,7 @@
* Major, Minor, Patchlevel
*/
#define MBEDTLS_VERSION_MAJOR 2
-#define MBEDTLS_VERSION_MINOR 6
+#define MBEDTLS_VERSION_MINOR 8
#define MBEDTLS_VERSION_PATCH 0
/**
@@ -46,9 +47,9 @@
* MMNNPP00
* Major version | Minor version | Patch version
*/
-#define MBEDTLS_VERSION_NUMBER 0x02060000
-#define MBEDTLS_VERSION_STRING "2.6.0"
-#define MBEDTLS_VERSION_STRING_FULL "mbed TLS 2.6.0"
+#define MBEDTLS_VERSION_NUMBER 0x02080000
+#define MBEDTLS_VERSION_STRING "2.8.0"
+#define MBEDTLS_VERSION_STRING_FULL "mbed TLS 2.8.0"
#if defined(MBEDTLS_VERSION_C)
diff --git a/include/mbedtls/x509.h b/include/mbedtls/x509.h
index d7e318d..d6db9c6 100644
--- a/include/mbedtls/x509.h
+++ b/include/mbedtls/x509.h
@@ -2,7 +2,8 @@
* \file x509.h
*
* \brief X.509 generic defines and structures
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/x509_crl.h b/include/mbedtls/x509_crl.h
index 7988439..08a4283 100644
--- a/include/mbedtls/x509_crl.h
+++ b/include/mbedtls/x509_crl.h
@@ -2,7 +2,8 @@
* \file x509_crl.h
*
* \brief X.509 certificate revocation list parsing
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h
index 06166d8..ac23cff 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -2,7 +2,8 @@
* \file x509_crt.h
*
* \brief X.509 certificate parsing and writing
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -286,8 +287,15 @@
* used to sign the certificate, CRL verification is skipped
* silently, that is *without* setting any flag.
*
+ * \note The \c trust_ca list can contain two types of certificates:
+ * (1) those of trusted root CAs, so that certificates
+ * chaining up to those CAs will be trusted, and (2)
+ * self-signed end-entity certificates to be trusted (for
+ * specific peers you know) - in that case, the self-signed
+ * certificate doesn't need to have the CA bit set.
+ *
* \param crt a certificate (chain) to be verified
- * \param trust_ca the list of trusted CAs
+ * \param trust_ca the list of trusted CAs (see note above)
* \param ca_crl the list of CRLs for trusted CAs (see note above)
* \param cn expected Common Name (can be set to
* NULL if the CN must not be verified)
@@ -373,21 +381,22 @@
#if defined(MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE)
/**
- * \brief Check usage of certificate against extentedJeyUsage.
+ * \brief Check usage of certificate against extendedKeyUsage.
*
- * \param crt Leaf certificate used.
- * \param usage_oid Intended usage (eg MBEDTLS_OID_SERVER_AUTH or MBEDTLS_OID_CLIENT_AUTH).
+ * \param crt Leaf certificate used.
+ * \param usage_oid Intended usage (eg MBEDTLS_OID_SERVER_AUTH or
+ * MBEDTLS_OID_CLIENT_AUTH).
* \param usage_len Length of usage_oid (eg given by MBEDTLS_OID_SIZE()).
*
- * \return 0 if this use of the certificate is allowed,
- * MBEDTLS_ERR_X509_BAD_INPUT_DATA if not.
+ * \return 0 if this use of the certificate is allowed,
+ * MBEDTLS_ERR_X509_BAD_INPUT_DATA if not.
*
- * \note Usually only makes sense on leaf certificates.
+ * \note Usually only makes sense on leaf certificates.
*/
int mbedtls_x509_crt_check_extended_key_usage( const mbedtls_x509_crt *crt,
- const char *usage_oid,
- size_t usage_len );
-#endif /* MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE) */
+ const char *usage_oid,
+ size_t usage_len );
+#endif /* MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE */
#if defined(MBEDTLS_X509_CRL_PARSE_C)
/**
diff --git a/include/mbedtls/x509_csr.h b/include/mbedtls/x509_csr.h
index fe9843c..0c6ccad 100644
--- a/include/mbedtls/x509_csr.h
+++ b/include/mbedtls/x509_csr.h
@@ -2,7 +2,8 @@
* \file x509_csr.h
*
* \brief X.509 certificate signing request parsing and writing
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
diff --git a/include/mbedtls/xtea.h b/include/mbedtls/xtea.h
index b073f84..34ccee3 100644
--- a/include/mbedtls/xtea.h
+++ b/include/mbedtls/xtea.h
@@ -2,7 +2,8 @@
* \file xtea.h
*
* \brief XTEA block cipher (32-bit)
- *
+ */
+/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -36,6 +37,7 @@
#define MBEDTLS_XTEA_DECRYPT 0
#define MBEDTLS_ERR_XTEA_INVALID_INPUT_LENGTH -0x0028 /**< The data input has an invalid length. */
+#define MBEDTLS_ERR_XTEA_HW_ACCEL_FAILED -0x0029 /**< XTEA hardware accelerator failed. */
#if !defined(MBEDTLS_XTEA_ALT)
// Regular implementation