Merge branch 'development' into iotssl-1260-non-blocking-ecc-restricted
Summary of merge conflicts:
include/mbedtls/ecdh.h -> documentation style
include/mbedtls/ecdsa.h -> documentation style
include/mbedtls/ecp.h -> alt style, new error codes, documentation style
include/mbedtls/error.h -> new error codes
library/error.c -> new error codes (generated anyway)
library/ecp.c:
- code of an extracted function was changed
library/ssl_cli.c:
- code addition on one side near code change on the other side
(ciphersuite validation)
library/x509_crt.c -> various things
- top fo file: helper structure added near old zeroize removed
- documentation of find_parent_in()'s signature: improved on one side,
added arguments on the other side
- documentation of find_parent()'s signature: same as above
- verify_chain(): variables initialised later to give compiler an
opportunity to warn us if not initialised on a code path
- find_parent(): funcion structure completely changed, for some reason git
tried to insert a paragraph of the old structure...
- merge_flags_with_cb(): data structure changed, one line was fixed with a
cast to keep MSVC happy, this cast is already in the new version
- in verify_restratable(): adjacent independent changes (function
signature on one line, variable type on the next)
programs/ssl/ssl_client2.c:
- testing for IN_PROGRESS return code near idle() (event-driven):
don't wait for data in the the socket if ECP_IN_PROGRESS
tests/data_files/Makefile: adjacent independent additions
tests/suites/test_suite_ecdsa.data: adjacent independent additions
tests/suites/test_suite_x509parse.data: adjacent independent additions
* development: (1059 commits)
Change symlink to hardlink to avoid permission issues
Fix out-of-tree testing symlinks on Windows
Updated version number to 2.10.0 for release
Add a disabled CMAC define in the no-entropy configuration
Adapt the ARIA test cases for new ECB function
Fix file permissions for ssl.h
Add ChangeLog entry for PR#1651
Fix MicroBlaze register typo.
Fix typo in doc and copy missing warning
Fix edit mistake in cipher_wrap.c
Update CTR doc for the 64-bit block cipher
Update CTR doc for other 128-bit block ciphers
Slightly tune ARIA CTR documentation
Remove double declaration of mbedtls_ssl_list_ciphersuites
Update CTR documentation
Use zeroize function from new platform_util
Move to new header style for ALT implementations
Add ifdef for selftest in header file
Fix typo in comments
Use more appropriate type for local variable
...
diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h
index 3440a84..710fdb9 100644
--- a/include/mbedtls/ecdsa.h
+++ b/include/mbedtls/ecdsa.h
@@ -1,9 +1,17 @@
/**
* \file ecdsa.h
*
- * \brief Elliptic curve DSA
+ * \brief This file contains ECDSA definitions and functions.
*
- * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * The Elliptic Curve Digital Signature Algorithm (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 +26,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 +36,7 @@
#include "md.h"
/*
- * RFC 4492 page 20:
+ * RFC-4492 page 20:
*
* Ecdsa-Sig-Value ::= SEQUENCE {
* r INTEGER,
@@ -43,7 +52,7 @@
#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 ) )
#ifdef __cplusplus
@@ -51,7 +60,7 @@
#endif
/**
- * \brief ECDSA context structure
+ * \brief The ECDSA context structure.
*
* \warning Performing multiple operations concurrently on the same
* ECDSA context is not supported; objects of this type
@@ -105,25 +114,31 @@
#endif /* MBEDTLS_ECP_RESTARTABLE */
/**
- * \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.
- *
- * \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
+ * \note The deterministic version is usually preferred.
*
* \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
+ * \see ecp.h
+ *
+ * \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 context.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX
+ * or \c MBEDTLS_MPI_XXX error code on failure.
*/
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,
@@ -131,23 +146,32 @@
#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.
*
- * \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
+ * For more information, see <em>RFC-6979: Deterministic
+ * Usage of the Digital Signature Algorithm (DSA) and Elliptic
+ * Curve Digital Signature Algorithm (ECDSA)</em>.
*
* \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
+ * \see ecp.h
+ *
+ * \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.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
+ * error code on failure.
*/
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,
@@ -155,55 +179,74 @@
#endif /* MBEDTLS_ECDSA_DETERMINISTIC */
/**
- * \brief Verify 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
+ * \brief This function verifies the ECDSA signature of a
+ * previously-hashed 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.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_VERIFY_FAILED if signature is invalid
- * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \see ecp.h
+ *
+ * \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.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature
+ * is invalid.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
+ * error code on failure for any other reason.
*/
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.
+ * \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
+ * \see ecp.h
+ *
+ * \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 context.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
+ * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
*/
int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hlen,
@@ -212,24 +255,29 @@
void *p_rng );
/**
- * \brief Restartable version of \c mbedtls_ecdsa_write_signature()
+ * \brief This function computes the ECDSA signature and writes it
+ * to a buffer, in a restartable way.
*
- * \note Performs the same job as \c mbedtls_ecdsa_write_signature()
- * but can return early and restart according to the limit
+ * \see \c mbedtls_ecdsa_write_signature()
+ *
+ * \note This function is like \c mbedtls_ecdsa_write_signature()
+ * but it can return early and restart according to the limit
* set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
*
- * \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
- * \param rs_ctx Restart context
+ * \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 context.
+ * \param rs_ctx The restart context.
*
- * \return See \c mbedtls_ecdsa_write_signature(), or
- * MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
+ * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
+ * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
* operations was reached: see \c mbedtls_ecp_set_max_ops().
*/
int mbedtls_ecdsa_write_signature_restartable( mbedtls_ecdsa_context *ctx,
@@ -248,31 +296,44 @@
#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>.
*
- * \deprecated Superseded by mbedtls_ecdsa_write_signature() in 2.0.0
+ * 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>.
*
- * \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
+ * \warning It is not thread-safe to use the same context in
+ * multiple threads.
*
- * \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
+ * \see ecp.h
+ *
+ * \deprecated Superseded by mbedtls_ecdsa_write_signature() in
+ * Mbed TLS version 2.0 and later.
+ *
+ * \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.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
+ * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
*/
int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
const unsigned char *hash, size_t hlen,
@@ -283,44 +344,57 @@
#endif /* MBEDTLS_ECDSA_DETERMINISTIC */
/**
- * \brief Read and verify 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
+ * \brief This function reads and verifies an ECDSA 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,
- * 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
+ * \see ecp.h
+ *
+ * \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.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
+ * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid
+ * signature in \p sig, but its length is less than \p siglen.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
+ * error code on failure for any other reason.
*/
int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
const unsigned char *hash, size_t hlen,
const unsigned char *sig, size_t slen );
/**
- * \brief Restartable version of \c mbedtls_ecdsa_read_signature()
+ * \brief This function reads and verifies an ECDSA signature,
+ * in a restartable way.
*
- * \note Performs the same job as \c mbedtls_ecdsa_read_signature()
- * but can return early and restart according to the limit
+ * \see \c mbedtls_ecdsa_read_signature()
+ *
+ * \note This function is like \c mbedtls_ecdsa_read_signature()
+ * but it can return early and restart according to the limit
* set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
*
- * \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 rs_ctx Restart context
+ * \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.
+ * \param rs_ctx The restart context
*
- * \return See \c mbedtls_ecdsa_read_signature(), or
- * MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
+ * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid
+ * signature in \p sig, but its length is less than \p siglen.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
+ * error code on failure for any other reason.
+ * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
* operations was reached: see \c mbedtls_ecp_set_max_ops().
*/
int mbedtls_ecdsa_read_signature_restartable( mbedtls_ecdsa_context *ctx,
@@ -329,40 +403,46 @@
mbedtls_ecdsa_restart_ctx *rs_ctx );
/**
- * \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
+ * \see ecp.h
*
- * \return 0 on success, or a MBEDTLS_ERR_ECP_XXX code.
+ * \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 context.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX code on failure.
*/
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
+ * \see ecp.h
*
- * \return 0 on success, or a MBEDTLS_ERR_ECP_XXX code.
+ * \param ctx The ECDSA context to set.
+ * \param key The EC key to use.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX code on failure.
*/
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 );