Update bundled ASN1 parser to Mbed-TLS 2.14.1
Signed-off-by: Fabio Utzig <utzig@apache.org>
diff --git a/ext/mbedtls/include/mbedtls/asn1.h b/ext/mbedtls/include/mbedtls/asn1.h
index 082832c..96c1c9a 100644
--- a/ext/mbedtls/include/mbedtls/asn1.h
+++ b/ext/mbedtls/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
*
@@ -59,7 +60,7 @@
/**
* \name DER constants
- * These constants comply with DER encoded the ANS1 type tags.
+ * These constants comply with the DER encoded ASN.1 type tags.
* DER encoding uses hexadecimal representation.
* An example DER sequence is:\n
* - 0x02 -- tag indicating INTEGER
@@ -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/ext/mbedtls/include/mbedtls/bignum.h b/ext/mbedtls/include/mbedtls/bignum.h
index 456a804..40cfab4 100644
--- a/ext/mbedtls/include/mbedtls/bignum.h
+++ b/ext/mbedtls/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. */
@@ -176,7 +177,7 @@
/**
* \brief MPI structure
*/
-typedef struct
+typedef struct mbedtls_mpi
{
int s; /*!< integer sign */
size_t n; /*!< total # of limbs */
@@ -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),
@@ -714,8 +725,18 @@
*/
int mbedtls_mpi_inv_mod( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *N );
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
/**
- * \brief Miller-Rabin primality test
+ * \brief Miller-Rabin primality test with error probability of
+ * 2<sup>-80</sup>
+ *
+ * \deprecated Superseded by mbedtls_mpi_is_prime_ext() which allows
+ * specifying the number of Miller-Rabin rounds.
*
* \param X MPI to check
* \param f_rng RNG function
@@ -725,9 +746,48 @@
* MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
* MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if X is not prime
*/
-int mbedtls_mpi_is_prime( const mbedtls_mpi *X,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng );
+MBEDTLS_DEPRECATED int mbedtls_mpi_is_prime( const mbedtls_mpi *X,
+ int (*f_rng)(void *, unsigned char *, size_t),
+ void *p_rng );
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+
+/**
+ * \brief Miller-Rabin primality test.
+ *
+ * \warning If \p X is potentially generated by an adversary, for example
+ * when validating cryptographic parameters that you didn't
+ * generate yourself and that are supposed to be prime, then
+ * \p rounds should be at least the half of the security
+ * strength of the cryptographic algorithm. On the other hand,
+ * if \p X is chosen uniformly or non-adversially (as is the
+ * case when mbedtls_mpi_gen_prime calls this function), then
+ * \p rounds can be much lower.
+ *
+ * \param X MPI to check
+ * \param rounds Number of bases to perform Miller-Rabin primality test for.
+ * The probability of returning 0 on a composite is at most
+ * 2<sup>-2*\p rounds</sup>.
+ * \param f_rng RNG function
+ * \param p_rng RNG parameter
+ *
+ * \return 0 if successful (probably prime),
+ * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
+ * MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if X is not prime
+ */
+int mbedtls_mpi_is_prime_ext( const mbedtls_mpi *X, int rounds,
+ int (*f_rng)(void *, unsigned char *, size_t),
+ void *p_rng );
+/**
+ * \brief Flags for mbedtls_mpi_gen_prime()
+ *
+ * Each of these flags is a constraint on the result X returned by
+ * mbedtls_mpi_gen_prime().
+ */
+typedef enum {
+ MBEDTLS_MPI_GEN_PRIME_FLAG_DH = 0x0001, /**< (X-1)/2 is prime too */
+ MBEDTLS_MPI_GEN_PRIME_FLAG_LOW_ERR = 0x0002, /**< lower error rate from 2<sup>-80</sup> to 2<sup>-128</sup> */
+} mbedtls_mpi_gen_prime_flag_t;
/**
* \brief Prime number generation
@@ -735,7 +795,7 @@
* \param X Destination MPI
* \param nbits Required size of X in bits
* ( 3 <= nbits <= MBEDTLS_MPI_MAX_BITS )
- * \param dh_flag If 1, then (X-1)/2 will be prime too
+ * \param flags Mask of flags of type #mbedtls_mpi_gen_prime_flag_t
* \param f_rng RNG function
* \param p_rng RNG parameter
*
@@ -743,7 +803,7 @@
* MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
* MBEDTLS_ERR_MPI_BAD_INPUT_DATA if nbits is < 3
*/
-int mbedtls_mpi_gen_prime( mbedtls_mpi *X, size_t nbits, int dh_flag,
+int mbedtls_mpi_gen_prime( mbedtls_mpi *X, size_t nbits, int flags,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng );
diff --git a/ext/mbedtls/include/mbedtls/check_config.h b/ext/mbedtls/include/mbedtls/check_config.h
index fa72454..425e3ea 100644
--- a/ext/mbedtls/include/mbedtls/check_config.h
+++ b/ext/mbedtls/include/mbedtls/check_config.h
@@ -2,8 +2,9 @@
* \file check_config.h
*
* \brief Consistency checks for configuration options
- *
- * Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
+ */
+/*
+ * Copyright (C) 2006-2018, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -77,11 +78,20 @@
#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"
#endif
+#if defined(MBEDTLS_NIST_KW_C) && \
+ ( !defined(MBEDTLS_AES_C) || !defined(MBEDTLS_CIPHER_C) )
+#error "MBEDTLS_NIST_KW_C defined, but not all prerequisites"
+#endif
+
#if defined(MBEDTLS_ECDH_C) && !defined(MBEDTLS_ECP_C)
#error "MBEDTLS_ECDH_C defined, but not all prerequisites"
#endif
@@ -98,6 +108,16 @@
#error "MBEDTLS_ECJPAKE_C defined, but not all prerequisites"
#endif
+#if defined(MBEDTLS_ECP_RESTARTABLE) && \
+ ( defined(MBEDTLS_ECDH_COMPUTE_SHARED_ALT) || \
+ defined(MBEDTLS_ECDH_GEN_PUBLIC_ALT) || \
+ defined(MBEDTLS_ECDSA_SIGN_ALT) || \
+ defined(MBEDTLS_ECDSA_VERIFY_ALT) || \
+ defined(MBEDTLS_ECDSA_GENKEY_ALT) || \
+ defined(MBEDTLS_ECP_ALT) )
+#error "MBEDTLS_ECP_RESTARTABLE defined, but it cannot coexist with an alternative ECP implementation"
+#endif
+
#if defined(MBEDTLS_ECDSA_DETERMINISTIC) && !defined(MBEDTLS_HMAC_DRBG_C)
#error "MBEDTLS_ECDSA_DETERMINISTIC defined, but not all prerequisites"
#endif
@@ -186,6 +206,10 @@
#error "MBEDTLS_HAVEGE_C defined, but not all prerequisites"
#endif
+#if defined(MBEDTLS_HKDF_C) && !defined(MBEDTLS_MD_C)
+#error "MBEDTLS_HKDF_C defined, but not all prerequisites"
+#endif
+
#if defined(MBEDTLS_HMAC_DRBG_C) && !defined(MBEDTLS_MD_C)
#error "MBEDTLS_HMAC_DRBG_C defined, but not all prerequisites"
#endif
diff --git a/ext/mbedtls/include/mbedtls/ecdsa.h b/ext/mbedtls/include/mbedtls/ecdsa.h
index a277715..4057828 100644
--- a/ext/mbedtls/include/mbedtls/ecdsa.h
+++ b/ext/mbedtls/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,38 +52,94 @@
#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
- */
-typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
-
#ifdef __cplusplus
extern "C" {
#endif
/**
- * \brief Compute ECDSA signature of a previously hashed message
+ * \brief The ECDSA context structure.
*
- * \note The deterministic version is usually prefered.
+ * \warning Performing multiple operations concurrently on the same
+ * ECDSA context is not supported; objects of this type
+ * should not be shared between multiple threads.
+ */
+typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
+
+#if defined(MBEDTLS_ECP_RESTARTABLE)
+
+/**
+ * \brief Internal restart context for ecdsa_verify()
*
- * \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 Opaque struct, defined in ecdsa.c
+ */
+typedef struct mbedtls_ecdsa_restart_ver mbedtls_ecdsa_restart_ver_ctx;
+
+/**
+ * \brief Internal restart context for ecdsa_sign()
+ *
+ * \note Opaque struct, defined in ecdsa.c
+ */
+typedef struct mbedtls_ecdsa_restart_sig mbedtls_ecdsa_restart_sig_ctx;
+
+#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
+/**
+ * \brief Internal restart context for ecdsa_sign_det()
+ *
+ * \note Opaque struct, defined in ecdsa.c
+ */
+typedef struct mbedtls_ecdsa_restart_det mbedtls_ecdsa_restart_det_ctx;
+#endif
+
+/**
+ * \brief General context for resuming ECDSA operations
+ */
+typedef struct
+{
+ mbedtls_ecp_restart_ctx ecp; /*!< base context for ECP restart and
+ shared administrative info */
+ mbedtls_ecdsa_restart_ver_ctx *ver; /*!< ecdsa_verify() sub-context */
+ mbedtls_ecdsa_restart_sig_ctx *sig; /*!< ecdsa_sign() sub-context */
+#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
+ mbedtls_ecdsa_restart_det_ctx *det; /*!< ecdsa_sign_det() sub-context */
+#endif
+} mbedtls_ecdsa_restart_ctx;
+
+#else /* MBEDTLS_ECP_RESTARTABLE */
+
+/* Now we can declare functions that take a pointer to that */
+typedef void mbedtls_ecdsa_restart_ctx;
+
+#endif /* MBEDTLS_ECP_RESTARTABLE */
+
+/**
+ * \brief This function computes the ECDSA signature of a
+ * previously-hashed message.
+ *
+ * \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,
@@ -82,23 +147,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,
@@ -106,55 +180,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_BAD_INPUT_DATA 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,
@@ -162,6 +255,40 @@
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng );
+/**
+ * \brief This function computes the ECDSA signature and writes it
+ * to a buffer, in a restartable way.
+ *
+ * \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 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 (NULL disables restart).
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
+ * operations was reached: see \c mbedtls_ecp_set_max_ops().
+ * \return Another \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_restartable( mbedtls_ecdsa_context *ctx,
+ mbedtls_md_type_t md_alg,
+ const unsigned char *hash, size_t hlen,
+ unsigned char *sig, size_t *slen,
+ int (*f_rng)(void *, unsigned char *, size_t),
+ void *p_rng,
+ mbedtls_ecdsa_restart_ctx *rs_ctx );
+
#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
#if defined(MBEDTLS_DEPRECATED_WARNING)
@@ -170,31 +297,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,
@@ -205,66 +345,120 @@
#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 Generate an ECDSA keypair on the given curve
+ * \brief This function reads and verifies an ECDSA signature,
+ * in a restartable way.
*
- * \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 \c mbedtls_ecdsa_read_signature()
*
- * \return 0 on success, or a MBEDTLS_ERR_ECP_XXX code.
+ * \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 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 (NULL disables restart).
+ *
+ * \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 #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
+ * operations was reached: see \c mbedtls_ecp_set_max_ops().
+ * \return Another \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
+ * error code on failure for any other reason.
+ */
+int mbedtls_ecdsa_read_signature_restartable( mbedtls_ecdsa_context *ctx,
+ const unsigned char *hash, size_t hlen,
+ const unsigned char *sig, size_t slen,
+ mbedtls_ecdsa_restart_ctx *rs_ctx );
+
+/**
+ * \brief This function generates an ECDSA keypair on the given curve.
+ *
+ * \see ecp.h
+ *
+ * \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 );
+#if defined(MBEDTLS_ECP_RESTARTABLE)
+/**
+ * \brief Initialize a restart context
+ */
+void mbedtls_ecdsa_restart_init( mbedtls_ecdsa_restart_ctx *ctx );
+
+/**
+ * \brief Free the components of a restart context
+ */
+void mbedtls_ecdsa_restart_free( mbedtls_ecdsa_restart_ctx *ctx );
+#endif /* MBEDTLS_ECP_RESTARTABLE */
+
#ifdef __cplusplus
}
#endif
diff --git a/ext/mbedtls/include/mbedtls/ecp.h b/ext/mbedtls/include/mbedtls/ecp.h
index dad9aef..2fb1af4 100644
--- a/ext/mbedtls/include/mbedtls/ecp.h
+++ b/ext/mbedtls/include/mbedtls/ecp.h
@@ -1,9 +1,21 @@
/**
* \file ecp.h
*
- * \brief Elliptic curves over GF(p)
+ * \brief This file provides an API for Elliptic Curves over GF(P) (ECP).
*
- * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * The use of ECP in cryptography and TLS is defined in
+ * <em>Standards for Efficient Cryptography Group (SECG): SEC1
+ * Elliptic Curve Cryptography</em> and
+ * <em>RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites
+ * for Transport Layer Security (TLS)</em>.
+ *
+ * <em>RFC-2409: The Internet Key Exchange (IKE)</em> defines ECP
+ * group types.
+ *
+ */
+
+/*
+ * 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_ECP_H
#define MBEDTLS_ECP_H
@@ -30,12 +43,85 @@
*/
#define MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80 /**< Bad input parameters to function. */
#define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL -0x4F00 /**< The buffer is too small to write to. */
-#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< Requested curve not available. */
+#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< The requested feature is not available, for example, the requested curve is not supported. */
#define MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00 /**< The signature is not valid. */
#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_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. */
+
+/* MBEDTLS_ERR_ECP_HW_ACCEL_FAILED is deprecated and should not be used. */
+#define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED -0x4B80 /**< The ECP hardware accelerator failed. */
+
+#define MBEDTLS_ERR_ECP_IN_PROGRESS -0x4B00 /**< Operation in progress, call again with the same parameters to continue. */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Domain-parameter identifiers: curve, subgroup, and generator.
+ *
+ * \note Only curves over prime fields are supported.
+ *
+ * \warning This library does not support validation of arbitrary domain
+ * parameters. Therefore, only standardized domain parameters from trusted
+ * sources should be used. See mbedtls_ecp_group_load().
+ */
+typedef enum
+{
+ MBEDTLS_ECP_DP_NONE = 0, /*!< Curve not defined. */
+ MBEDTLS_ECP_DP_SECP192R1, /*!< Domain parameters for the 192-bit curve defined by FIPS 186-4 and SEC1. */
+ MBEDTLS_ECP_DP_SECP224R1, /*!< Domain parameters for the 224-bit curve defined by FIPS 186-4 and SEC1. */
+ MBEDTLS_ECP_DP_SECP256R1, /*!< Domain parameters for the 256-bit curve defined by FIPS 186-4 and SEC1. */
+ MBEDTLS_ECP_DP_SECP384R1, /*!< Domain parameters for the 384-bit curve defined by FIPS 186-4 and SEC1. */
+ MBEDTLS_ECP_DP_SECP521R1, /*!< Domain parameters for the 521-bit curve defined by FIPS 186-4 and SEC1. */
+ MBEDTLS_ECP_DP_BP256R1, /*!< Domain parameters for 256-bit Brainpool curve. */
+ MBEDTLS_ECP_DP_BP384R1, /*!< Domain parameters for 384-bit Brainpool curve. */
+ MBEDTLS_ECP_DP_BP512R1, /*!< Domain parameters for 512-bit Brainpool curve. */
+ MBEDTLS_ECP_DP_CURVE25519, /*!< Domain parameters for Curve25519. */
+ MBEDTLS_ECP_DP_SECP192K1, /*!< Domain parameters for 192-bit "Koblitz" curve. */
+ MBEDTLS_ECP_DP_SECP224K1, /*!< Domain parameters for 224-bit "Koblitz" curve. */
+ MBEDTLS_ECP_DP_SECP256K1, /*!< Domain parameters for 256-bit "Koblitz" curve. */
+ MBEDTLS_ECP_DP_CURVE448, /*!< Domain parameters for Curve448. */
+} mbedtls_ecp_group_id;
+
+/**
+ * The number of supported curves, plus one for #MBEDTLS_ECP_DP_NONE.
+ *
+ * \note Montgomery curves are currently excluded.
+ */
+#define MBEDTLS_ECP_DP_MAX 12
+
+/**
+ * Curve information, for use by other modules.
+ */
+typedef struct mbedtls_ecp_curve_info
+{
+ mbedtls_ecp_group_id grp_id; /*!< An internal identifier. */
+ uint16_t tls_id; /*!< The TLS NamedCurve identifier. */
+ uint16_t bit_size; /*!< The curve size in bits. */
+ const char *name; /*!< A human-friendly name. */
+} mbedtls_ecp_curve_info;
+
+/**
+ * \brief The ECP point structure, in Jacobian coordinates.
+ *
+ * \note All functions expect and return points satisfying
+ * the following condition: <code>Z == 0</code> or
+ * <code>Z == 1</code>. Other values of \p Z are
+ * used only by internal functions.
+ * The point is zero, or "at infinity", if <code>Z == 0</code>.
+ * Otherwise, \p X and \p Y are its standard (affine)
+ * coordinates.
+ */
+typedef struct mbedtls_ecp_point
+{
+ mbedtls_mpi X; /*!< The X coordinate of the ECP point. */
+ mbedtls_mpi Y; /*!< The Y coordinate of the ECP point. */
+ mbedtls_mpi Z; /*!< The Z coordinate of the ECP point. */
+}
+mbedtls_ecp_point;
#if !defined(MBEDTLS_ECP_ALT)
/*
@@ -46,143 +132,136 @@
* one.)
*/
-#ifdef __cplusplus
-extern "C" {
-#endif
-
/**
- * Domain parameters (curve, subgroup and generator) identifiers.
+ * \brief The ECP group structure.
*
- * Only curves over prime fields are supported.
+ * We consider two types of curve equations:
+ * <ul><li>Short Weierstrass: <code>y^2 = x^3 + A x + B mod P</code>
+ * (SEC1 + RFC-4492)</li>
+ * <li>Montgomery: <code>y^2 = x^3 + A x^2 + x mod P</code> (Curve25519,
+ * Curve448)</li></ul>
+ * In both cases, the generator (\p G) for a prime-order subgroup is fixed.
*
- * \warning This library does not support validation of arbitrary domain
- * parameters. Therefore, only well-known domain parameters from trusted
- * sources should be used. See mbedtls_ecp_group_load().
+ * For Short Weierstrass, this subgroup is the whole curve, and its
+ * cardinality is denoted by \p N. Our code requires that \p N is an
+ * odd prime as mbedtls_ecp_mul() requires an odd number, and
+ * mbedtls_ecdsa_sign() requires that it is prime for blinding purposes.
+ *
+ * For Montgomery curves, we do not store \p A, but <code>(A + 2) / 4</code>,
+ * which is the quantity used in the formulas. Additionally, \p nbits is
+ * not the size of \p N but the required size for private keys.
+ *
+ * If \p modp is NULL, reduction modulo \p P is done using a generic algorithm.
+ * Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the
+ * range of <code>0..2^(2*pbits)-1</code>, and transforms it in-place to an integer
+ * which is congruent mod \p P to the given MPI, and is close enough to \p pbits
+ * in size, so that it may be efficiently brought in the 0..P-1 range by a few
+ * additions or subtractions. Therefore, it is only an approximative modular
+ * reduction. It must return 0 on success and non-zero on failure.
+ *
*/
-typedef enum
+typedef struct mbedtls_ecp_group
{
- MBEDTLS_ECP_DP_NONE = 0,
- MBEDTLS_ECP_DP_SECP192R1, /*!< 192-bits NIST curve */
- MBEDTLS_ECP_DP_SECP224R1, /*!< 224-bits NIST curve */
- MBEDTLS_ECP_DP_SECP256R1, /*!< 256-bits NIST curve */
- MBEDTLS_ECP_DP_SECP384R1, /*!< 384-bits NIST curve */
- MBEDTLS_ECP_DP_SECP521R1, /*!< 521-bits NIST curve */
- 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_SECP192K1, /*!< 192-bits "Koblitz" curve */
- MBEDTLS_ECP_DP_SECP224K1, /*!< 224-bits "Koblitz" curve */
- MBEDTLS_ECP_DP_SECP256K1, /*!< 256-bits "Koblitz" curve */
-} mbedtls_ecp_group_id;
-
-/**
- * Number of supported curves (plus one for NONE).
- *
- * (Montgomery curves excluded for now.)
- */
-#define MBEDTLS_ECP_DP_MAX 12
-
-/**
- * Curve information for use by other modules
- */
-typedef struct
-{
- mbedtls_ecp_group_id grp_id; /*!< Internal identifier */
- uint16_t tls_id; /*!< TLS NamedCurve identifier */
- uint16_t bit_size; /*!< Curve size in bits */
- const char *name; /*!< Human-friendly name */
-} mbedtls_ecp_curve_info;
-
-/**
- * \brief ECP point structure (jacobian coordinates)
- *
- * \note All functions expect and return points satisfying
- * the following condition: Z == 0 or Z == 1. (Other
- * values of Z are used by internal functions only.)
- * The point is zero, or "at infinity", if Z == 0.
- * Otherwise, X and Y are its standard (affine) coordinates.
- */
-typedef struct
-{
- mbedtls_mpi X; /*!< the point's X coordinate */
- mbedtls_mpi Y; /*!< the point's Y coordinate */
- mbedtls_mpi Z; /*!< the point's Z coordinate */
-}
-mbedtls_ecp_point;
-
-/**
- * \brief ECP group structure
- *
- * We consider two types of curves equations:
- * 1. Short Weierstrass y^2 = x^3 + A x + B mod P (SEC1 + RFC 4492)
- * 2. Montgomery, y^2 = x^3 + A x^2 + x mod P (Curve25519 + draft)
- * In both cases, a generator G for a prime-order subgroup is fixed. In the
- * short weierstrass, this subgroup is actually the whole curve, and its
- * cardinal is denoted by N.
- *
- * In the case of Short Weierstrass curves, our code requires that N is an odd
- * prime. (Use odd in mbedtls_ecp_mul() and prime in mbedtls_ecdsa_sign() for blinding.)
- *
- * In the case of Montgomery curves, we don't store A but (A + 2) / 4 which is
- * the quantity actually used in the formulas. Also, nbits is not the size of N
- * but the required size for private keys.
- *
- * If modp is NULL, reduction modulo P is done using a generic algorithm.
- * Otherwise, it must point to a function that takes an mbedtls_mpi in the range
- * 0..2^(2*pbits)-1 and transforms it in-place in an integer of little more
- * than pbits, so that the integer may be efficiently brought in the 0..P-1
- * range by a few additions or substractions. It must return 0 on success and
- * non-zero on failure.
- */
-typedef struct
-{
- mbedtls_ecp_group_id id; /*!< internal group identifier */
- mbedtls_mpi P; /*!< prime modulus of the base field */
- 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 */
- 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 */
- int (*modp)(mbedtls_mpi *); /*!< function for fast reduction mod P */
- int (*t_pre)(mbedtls_ecp_point *, void *); /*!< unused */
- int (*t_post)(mbedtls_ecp_point *, void *); /*!< unused */
- void *t_data; /*!< unused */
- mbedtls_ecp_point *T; /*!< pre-computed points for ecp_mul_comb() */
- size_t T_size; /*!< number for pre-computed points */
+ mbedtls_ecp_group_id id; /*!< An internal group identifier. */
+ mbedtls_mpi P; /*!< The prime modulus of the base field. */
+ mbedtls_mpi A; /*!< For Short Weierstrass: \p A in the equation. For
+ Montgomery curves: <code>(A + 2) / 4</code>. */
+ mbedtls_mpi B; /*!< For Short Weierstrass: \p B in the equation.
+ For Montgomery curves: unused. */
+ mbedtls_ecp_point G; /*!< The generator of the subgroup used. */
+ mbedtls_mpi N; /*!< The order of \p G. */
+ size_t pbits; /*!< The number of bits in \p P.*/
+ size_t nbits; /*!< For Short Weierstrass: The number of bits in \p P.
+ For Montgomery curves: the number of bits in the
+ private keys. */
+ unsigned int h; /*!< \internal 1 if the constants are static. */
+ int (*modp)(mbedtls_mpi *); /*!< The function for fast pseudo-reduction
+ mod \p P (see above).*/
+ int (*t_pre)(mbedtls_ecp_point *, void *); /*!< Unused. */
+ int (*t_post)(mbedtls_ecp_point *, void *); /*!< Unused. */
+ void *t_data; /*!< Unused. */
+ mbedtls_ecp_point *T; /*!< Pre-computed points for ecp_mul_comb(). */
+ size_t T_size; /*!< The number of pre-computed points. */
}
mbedtls_ecp_group;
+#if defined(MBEDTLS_ECP_RESTARTABLE)
+
/**
- * \brief ECP key pair structure
+ * \brief Internal restart context for multiplication
*
- * A generic key pair that could be used for ECDSA, fixed ECDH, etc.
+ * \note Opaque struct
+ */
+typedef struct mbedtls_ecp_restart_mul mbedtls_ecp_restart_mul_ctx;
+
+/**
+ * \brief Internal restart context for ecp_muladd()
*
- * \note Members purposefully in the same order as struc mbedtls_ecdsa_context.
+ * \note Opaque struct
+ */
+typedef struct mbedtls_ecp_restart_muladd mbedtls_ecp_restart_muladd_ctx;
+
+/**
+ * \brief General context for resuming ECC operations
*/
typedef struct
{
- mbedtls_ecp_group grp; /*!< Elliptic curve and base point */
- mbedtls_mpi d; /*!< our secret value */
- mbedtls_ecp_point Q; /*!< our public value */
-}
-mbedtls_ecp_keypair;
+ unsigned ops_done; /*!< current ops count */
+ unsigned depth; /*!< call depth (0 = top-level) */
+ mbedtls_ecp_restart_mul_ctx *rsm; /*!< ecp_mul_comb() sub-context */
+ mbedtls_ecp_restart_muladd_ctx *ma; /*!< ecp_muladd() sub-context */
+} mbedtls_ecp_restart_ctx;
+
+/*
+ * Operation counts for restartable functions
+ */
+#define MBEDTLS_ECP_OPS_CHK 3 /*!< basic ops count for ecp_check_pubkey() */
+#define MBEDTLS_ECP_OPS_DBL 8 /*!< basic ops count for ecp_double_jac() */
+#define MBEDTLS_ECP_OPS_ADD 11 /*!< basic ops count for see ecp_add_mixed() */
+#define MBEDTLS_ECP_OPS_INV 120 /*!< empirical equivalent for mpi_mod_inv() */
+
+/**
+ * \brief Internal; for restartable functions in other modules.
+ * Check and update basic ops budget.
+ *
+ * \param grp Group structure
+ * \param rs_ctx Restart context
+ * \param ops Number of basic ops to do
+ *
+ * \return \c 0 if doing \p ops basic ops is still allowed,
+ * \return #MBEDTLS_ERR_ECP_IN_PROGRESS otherwise.
+ */
+int mbedtls_ecp_check_budget( const mbedtls_ecp_group *grp,
+ mbedtls_ecp_restart_ctx *rs_ctx,
+ unsigned ops );
+
+/* Utility macro for checking and updating ops budget */
+#define MBEDTLS_ECP_BUDGET( ops ) \
+ MBEDTLS_MPI_CHK( mbedtls_ecp_check_budget( grp, rs_ctx, \
+ (unsigned) (ops) ) );
+
+#else /* MBEDTLS_ECP_RESTARTABLE */
+
+#define MBEDTLS_ECP_BUDGET( ops ) /* no-op; for compatibility */
+
+/* We want to declare restartable versions of existing functions anyway */
+typedef void mbedtls_ecp_restart_ctx;
+
+#endif /* MBEDTLS_ECP_RESTARTABLE */
/**
* \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_ECP_MAX_BITS)
/**
- * Maximum size of the groups (that is, of N and P)
+ * The maximum size of the groups, that is, of \c N and \c P.
*/
-#define MBEDTLS_ECP_MAX_BITS 521 /**< Maximum bit size of groups */
+#define MBEDTLS_ECP_MAX_BITS 521 /**< The maximum size of groups, in bits. */
#endif
#define MBEDTLS_ECP_MAX_BYTES ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 )
@@ -205,11 +284,10 @@
* 521 145 141 135 120 97
* 384 214 209 198 177 146
* 256 320 320 303 262 226
-
* 224 475 475 453 398 342
* 192 640 640 633 587 476
*/
-#define MBEDTLS_ECP_WINDOW_SIZE 6 /**< Maximum window size used */
+#define MBEDTLS_ECP_WINDOW_SIZE 6 /**< The maximum window size used. */
#endif /* MBEDTLS_ECP_WINDOW_SIZE */
#if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM)
@@ -224,33 +302,124 @@
*
* Change this value to 0 to reduce peak memory usage.
*/
-#define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up */
+#define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up. */
#endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */
/* \} name SECTION: Module settings */
+#else /* MBEDTLS_ECP_ALT */
+#include "ecp_alt.h"
+#endif /* MBEDTLS_ECP_ALT */
+
+/**
+ * \brief The ECP key-pair structure.
+ *
+ * A generic key-pair that may be used for ECDSA and fixed ECDH, for example.
+ *
+ * \note Members are deliberately in the same order as in the
+ * ::mbedtls_ecdsa_context structure.
+ */
+typedef struct mbedtls_ecp_keypair
+{
+ mbedtls_ecp_group grp; /*!< Elliptic curve and base point */
+ mbedtls_mpi d; /*!< our secret value */
+ mbedtls_ecp_point Q; /*!< our public value */
+}
+mbedtls_ecp_keypair;
+
/*
* Point formats, from RFC 4492's enum ECPointFormat
*/
-#define MBEDTLS_ECP_PF_UNCOMPRESSED 0 /**< Uncompressed point format */
-#define MBEDTLS_ECP_PF_COMPRESSED 1 /**< Compressed point format */
+#define MBEDTLS_ECP_PF_UNCOMPRESSED 0 /**< Uncompressed point format. */
+#define MBEDTLS_ECP_PF_COMPRESSED 1 /**< Compressed point format. */
/*
* Some other constants from RFC 4492
*/
-#define MBEDTLS_ECP_TLS_NAMED_CURVE 3 /**< ECCurveType's named_curve */
+#define MBEDTLS_ECP_TLS_NAMED_CURVE 3 /**< The named_curve of ECCurveType. */
+
+#if defined(MBEDTLS_ECP_RESTARTABLE)
+/**
+ * \brief Set the maximum number of basic operations done in a row.
+ *
+ * If more operations are needed to complete a computation,
+ * #MBEDTLS_ERR_ECP_IN_PROGRESS will be returned by the
+ * function performing the computation. It is then the
+ * caller's responsibility to either call again with the same
+ * parameters until it returns 0 or an error code; or to free
+ * the restart context if the operation is to be aborted.
+ *
+ * It is strictly required that all input parameters and the
+ * restart context be the same on successive calls for the
+ * same operation, but output parameters need not be the
+ * same; they must not be used until the function finally
+ * returns 0.
+ *
+ * This only applies to functions whose documentation
+ * mentions they may return #MBEDTLS_ERR_ECP_IN_PROGRESS (or
+ * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS for functions in the
+ * SSL module). For functions that accept a "restart context"
+ * argument, passing NULL disables restart and makes the
+ * function equivalent to the function with the same name
+ * with \c _restartable removed. For functions in the ECDH
+ * module, restart is disabled unless the function accepts
+ * an "ECDH context" argument and
+ * mbedtls_ecdh_enable_restart() was previously called on
+ * that context. For function in the SSL module, restart is
+ * only enabled for specific sides and key exchanges
+ * (currently only for clients and ECDHE-ECDSA).
+ *
+ * \param max_ops Maximum number of basic operations done in a row.
+ * Default: 0 (unlimited).
+ * Lower (non-zero) values mean ECC functions will block for
+ * a lesser maximum amount of time.
+ *
+ * \note A "basic operation" is defined as a rough equivalent of a
+ * multiplication in GF(p) for the NIST P-256 curve.
+ * As an indication, with default settings, a scalar
+ * multiplication (full run of \c mbedtls_ecp_mul()) is:
+ * - about 3300 basic operations for P-256
+ * - about 9400 basic operations for P-384
+ *
+ * \note Very low values are not always respected: sometimes
+ * functions need to block for a minimum number of
+ * operations, and will do so even if max_ops is set to a
+ * lower value. That minimum depends on the curve size, and
+ * can be made lower by decreasing the value of
+ * \c MBEDTLS_ECP_WINDOW_SIZE. As an indication, here is the
+ * lowest effective value for various curves and values of
+ * that parameter (w for short):
+ * w=6 w=5 w=4 w=3 w=2
+ * P-256 208 208 160 136 124
+ * P-384 682 416 320 272 248
+ * P-521 1364 832 640 544 496
+ *
+ * \note This setting is currently ignored by Curve25519.
+ */
+void mbedtls_ecp_set_max_ops( unsigned max_ops );
/**
- * \brief Get the list of supported curves in order of preferrence
- * (full information)
+ * \brief Check if restart is enabled (max_ops != 0)
*
- * \return A statically allocated array, the last entry is 0.
+ * \return \c 0 if \c max_ops == 0 (restart disabled)
+ * \return \c 1 otherwise (restart enabled)
+ */
+int mbedtls_ecp_restart_is_enabled( void );
+#endif /* MBEDTLS_ECP_RESTARTABLE */
+
+/**
+ * \brief This function retrieves the information defined in
+ * mbedtls_ecp_curve_info() for all supported curves in order
+ * of preference.
+ *
+ * \return A statically allocated array. The last entry is 0.
*/
const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void );
/**
- * \brief Get the list of supported curves in order of preferrence
- * (grp_id only)
+ * \brief This function retrieves the list of internal group
+ * identifiers of all supported curves in the order of
+ * preference.
*
* \return A statically allocated array,
* terminated with MBEDTLS_ECP_DP_NONE.
@@ -258,357 +427,492 @@
const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void );
/**
- * \brief Get curve information from an internal group identifier
+ * \brief This function retrieves curve information from an internal
+ * group identifier.
*
- * \param grp_id A MBEDTLS_ECP_DP_XXX value
+ * \param grp_id An \c MBEDTLS_ECP_DP_XXX value.
*
- * \return The associated curve information or NULL
+ * \return The associated curve information on success.
+ * \return NULL on failure.
*/
const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_group_id grp_id );
/**
- * \brief Get curve information from a TLS NamedCurve value
+ * \brief This function retrieves curve information from a TLS
+ * NamedCurve value.
*
- * \param tls_id A MBEDTLS_ECP_DP_XXX value
+ * \param tls_id An \c MBEDTLS_ECP_DP_XXX value.
*
- * \return The associated curve information or NULL
+ * \return The associated curve information on success.
+ * \return NULL on failure.
*/
const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_id );
/**
- * \brief Get curve information from a human-readable name
+ * \brief This function retrieves curve information from a
+ * human-readable name.
*
- * \param name The name
+ * \param name The human-readable name.
*
- * \return The associated curve information or NULL
+ * \return The associated curve information on success.
+ * \return NULL on failure.
*/
const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name( const char *name );
/**
- * \brief Initialize a point (as zero)
+ * \brief This function initializes a point as zero.
+ *
+ * \param pt The point to initialize.
*/
void mbedtls_ecp_point_init( mbedtls_ecp_point *pt );
/**
- * \brief Initialize a group (to something meaningless)
+ * \brief This function initializes an ECP group context
+ * without loading any domain parameters.
+ *
+ * \note After this function is called, domain parameters
+ * for various ECP groups can be loaded through the
+ * mbedtls_ecp_load() or mbedtls_ecp_tls_read_group()
+ * functions.
*/
void mbedtls_ecp_group_init( mbedtls_ecp_group *grp );
/**
- * \brief Initialize a key pair (as an invalid one)
+ * \brief This function initializes a key pair as an invalid one.
+ *
+ * \param key The key pair to initialize.
*/
void mbedtls_ecp_keypair_init( mbedtls_ecp_keypair *key );
/**
- * \brief Free the components of a point
+ * \brief This function frees the components of a point.
+ *
+ * \param pt The point to free.
*/
void mbedtls_ecp_point_free( mbedtls_ecp_point *pt );
/**
- * \brief Free the components of an ECP group
+ * \brief This function frees the components of an ECP group.
+ * \param grp The group to free.
*/
void mbedtls_ecp_group_free( mbedtls_ecp_group *grp );
/**
- * \brief Free the components of a key pair
+ * \brief This function frees the components of a key pair.
+ * \param key The key pair to free.
*/
void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key );
+#if defined(MBEDTLS_ECP_RESTARTABLE)
/**
- * \brief Copy the contents of point Q into P
+ * \brief Initialize a restart context
+ */
+void mbedtls_ecp_restart_init( mbedtls_ecp_restart_ctx *ctx );
+
+/**
+ * \brief Free the components of a restart context
+ */
+void mbedtls_ecp_restart_free( mbedtls_ecp_restart_ctx *ctx );
+#endif /* MBEDTLS_ECP_RESTARTABLE */
+
+/**
+ * \brief This function copies the contents of point \p Q into
+ * point \p P.
*
- * \param P Destination point
- * \param Q Source point
+ * \param P The destination point.
+ * \param Q The source point.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
*/
int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q );
/**
- * \brief Copy the contents of a group object
+ * \brief This function copies the contents of group \p src into
+ * group \p dst.
*
- * \param dst Destination group
- * \param src Source group
+ * \param dst The destination group.
+ * \param src The source group.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
*/
int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src );
/**
- * \brief Set a point to zero
+ * \brief This function sets a point to zero.
*
- * \param pt Destination point
+ * \param pt The point to set.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
*/
int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt );
/**
- * \brief Tell if a point is zero
+ * \brief This function checks if a point is zero.
*
- * \param pt Point to test
+ * \param pt The point to test.
*
- * \return 1 if point is zero, 0 otherwise
+ * \return \c 1 if the point is zero.
+ * \return \c 0 if the point is non-zero.
*/
int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt );
/**
- * \brief Compare two points
+ * \brief This function compares two points.
*
- * \note This assumes the points are normalized. Otherwise,
+ * \note This assumes that the points are normalized. Otherwise,
* they may compare as "not equal" even if they are.
*
- * \param P First point to compare
- * \param Q Second point to compare
+ * \param P The first point to compare.
+ * \param Q The second point to compare.
*
- * \return 0 if the points are equal,
- * MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise
+ * \return \c 0 if the points are equal.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal.
*/
int mbedtls_ecp_point_cmp( const mbedtls_ecp_point *P,
const mbedtls_ecp_point *Q );
/**
- * \brief Import a non-zero point from two ASCII strings
+ * \brief This function imports a non-zero point from two ASCII
+ * strings.
*
- * \param P Destination point
- * \param radix Input numeric base
- * \param x First affine coordinate as a null-terminated string
- * \param y Second affine coordinate as a null-terminated string
+ * \param P The destination point.
+ * \param radix The numeric base of the input.
+ * \param x The first affine coordinate, as a null-terminated string.
+ * \param y The second affine coordinate, as a null-terminated string.
*
- * \return 0 if successful, or a MBEDTLS_ERR_MPI_XXX error code
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_MPI_XXX error code on failure.
*/
int mbedtls_ecp_point_read_string( mbedtls_ecp_point *P, int radix,
const char *x, const char *y );
/**
- * \brief Export a point into unsigned binary data
+ * \brief This function exports a point into unsigned binary data.
*
- * \param grp Group to which the point should belong
- * \param P Point to export
- * \param format Point format, should be a MBEDTLS_ECP_PF_XXX macro
- * \param olen Length of the actual output
- * \param buf Output buffer
- * \param buflen Length of the output buffer
+ * \param grp The group to which the point should belong.
+ * \param P The point to export.
+ * \param format The point format. Should be an \c MBEDTLS_ECP_PF_XXX macro.
+ * \param olen The length of the output.
+ * \param buf The output buffer.
+ * \param buflen The length of the output buffer.
*
- * \return 0 if successful,
- * or MBEDTLS_ERR_ECP_BAD_INPUT_DATA
- * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA
+ * or #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
*/
int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *P,
int format, size_t *olen,
unsigned char *buf, size_t buflen );
/**
- * \brief Import a point from unsigned binary data
+ * \brief This function imports a point from unsigned binary data.
*
- * \param grp Group to which the point should belong
- * \param P Point to import
- * \param buf Input buffer
- * \param ilen Actual length of input
+ * \note This function does not check that the point actually
+ * belongs to the given group, see mbedtls_ecp_check_pubkey()
+ * for that.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- * MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
+ * \param grp The group to which the point should belong.
+ * \param P The point to import.
+ * \param buf The input buffer.
+ * \param ilen The length of the input.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
+ * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
* is not implemented.
*
- * \note This function does NOT check that the point actually
- * belongs to the given group, see mbedtls_ecp_check_pubkey() for
- * that.
*/
int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_point *P,
const unsigned char *buf, size_t ilen );
/**
- * \brief Import a point from a TLS ECPoint record
+ * \brief This function imports a point from a TLS ECPoint record.
*
- * \param grp ECP group used
- * \param pt Destination point
- * \param buf $(Start of input buffer)
- * \param len Buffer length
+ * \note On function return, \p buf is updated to point to immediately
+ * after the ECPoint record.
*
- * \note buf is updated to point right after the ECPoint on exit
+ * \param grp The ECP group used.
+ * \param pt The destination point.
+ * \param buf The address of the pointer to the start of the input buffer.
+ * \param len The length of the buffer.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_XXX if initialization failed
- * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
*/
int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point *pt,
const unsigned char **buf, size_t len );
/**
- * \brief Export a point as a TLS ECPoint record
+ * \brief This function exports a point as a TLS ECPoint record.
*
- * \param grp ECP group used
- * \param pt Point to export
- * \param format Export format
- * \param olen length of data written
- * \param buf Buffer to write to
- * \param blen Buffer length
+ * \param grp The ECP group used.
+ * \param pt The point format to export to. The point format is an
+ * \c MBEDTLS_ECP_PF_XXX constant.
+ * \param format The export format.
+ * \param olen The length of the data written.
+ * \param buf The buffer to write to.
+ * \param blen The length of the buffer.
*
- * \return 0 if successful,
- * or MBEDTLS_ERR_ECP_BAD_INPUT_DATA
- * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA or
+ * #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
*/
int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt,
int format, size_t *olen,
unsigned char *buf, size_t blen );
/**
- * \brief Set a group using well-known domain parameters
+ * \brief This function sets a group using standardized domain parameters.
*
- * \param grp Destination group
- * \param id Index in the list of well-known domain parameters
+ * \note The index should be a value of the NamedCurve enum,
+ * as defined in <em>RFC-4492: Elliptic Curve Cryptography
+ * (ECC) Cipher Suites for Transport Layer Security (TLS)</em>,
+ * usually in the form of an \c MBEDTLS_ECP_DP_XXX macro.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_XXX if initialization failed
- * MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups
+ * \param grp The destination group.
+ * \param id The identifier of the domain parameter set to load.
*
- * \note Index should be a value of RFC 4492's enum NamedCurve,
- * usually in the form of a MBEDTLS_ECP_DP_XXX macro.
+ * \return \c 0 on success,
+ * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure.
+ * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups.
+
*/
int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id );
/**
- * \brief Set a group from a TLS ECParameters record
+ * \brief This function sets a group from a TLS ECParameters record.
*
- * \param grp Destination group
- * \param buf &(Start of input buffer)
- * \param len Buffer length
+ * \note \p buf is updated to point right after the ECParameters record
+ * on exit.
*
- * \note buf is updated to point right after ECParameters on exit
+ * \param grp The destination group.
+ * \param buf The address of the pointer to the start of the input buffer.
+ * \param len The length of the buffer.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_MPI_XXX if initialization failed
- * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
*/
int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp, const unsigned char **buf, size_t len );
/**
- * \brief Write the TLS ECParameters record for a group
+ * \brief This function writes the TLS ECParameters record for a group.
*
- * \param grp ECP group used
- * \param olen Number of bytes actually written
- * \param buf Buffer to write to
- * \param blen Buffer length
+ * \param grp The ECP group used.
+ * \param olen The number of Bytes written.
+ * \param buf The buffer to write to.
+ * \param blen The length of the buffer.
*
- * \return 0 if successful,
- * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
*/
int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen,
unsigned char *buf, size_t blen );
/**
- * \brief Multiplication by an integer: R = m * P
- * (Not thread-safe to use same group in multiple threads)
+ * \brief This function performs multiplication of a point by
+ * an integer: \p R = \p m * \p P.
*
- * \note In order to prevent timing attacks, this function
- * executes the exact same sequence of (base field)
- * operations for any valid m. It avoids any if-branch or
- * array index depending on the value of m.
+ * It is not thread-safe to use same group in multiple threads.
*
- * \note If f_rng is not NULL, it is used to randomize intermediate
- * results in order to prevent potential timing attacks
- * targeting these results. It is recommended to always
- * provide a non-NULL f_rng (the overhead is negligible).
+ * \note To prevent timing attacks, this function
+ * executes the exact same sequence of base-field
+ * operations for any valid \p m. It avoids any if-branch or
+ * array index depending on the value of \p m.
*
- * \param grp ECP group
- * \param R Destination point
- * \param m Integer by which to multiply
- * \param P Point to multiply
- * \param f_rng RNG function (see notes)
- * \param p_rng RNG parameter
+ * \note If \p f_rng is not NULL, it is used to randomize
+ * intermediate results to prevent potential timing attacks
+ * targeting these results. We recommend always providing
+ * a non-NULL \p f_rng. The overhead is negligible.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_ECP_INVALID_KEY if m is not a valid privkey
- * or P is not a valid pubkey,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \param grp The ECP group.
+ * \param R The destination point.
+ * \param m The integer by which to multiply.
+ * \param P The point to multiply.
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG context.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
+ * key, or \p P is not a valid public key.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
*/
int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
const mbedtls_mpi *m, const mbedtls_ecp_point *P,
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
/**
- * \brief Multiplication and addition of two points by integers:
- * R = m * P + n * Q
- * (Not thread-safe to use same group in multiple threads)
+ * \brief This function performs multiplication of a point by
+ * an integer: \p R = \p m * \p P in a restartable way.
*
- * \note In contrast to mbedtls_ecp_mul(), this function does not guarantee
- * a constant execution flow and timing.
+ * \see mbedtls_ecp_mul()
*
- * \param grp ECP group
- * \param R Destination point
- * \param m Integer by which to multiply P
- * \param P Point to multiply by m
- * \param n Integer by which to multiply Q
- * \param Q Point to be multiplied by n
+ * \note This function does the same as \c mbedtls_ecp_mul(), but
+ * it can return early and restart according to the limit set
+ * with \c mbedtls_ecp_set_max_ops() to reduce blocking.
*
- * \return 0 if successful,
- * MBEDTLS_ERR_ECP_INVALID_KEY if m or n is not a valid privkey
- * or P or Q is not a valid pubkey,
- * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \param grp The ECP group.
+ * \param R The destination point.
+ * \param m The integer by which to multiply.
+ * \param P The point to multiply.
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG context.
+ * \param rs_ctx The restart context (NULL disables restart).
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
+ * key, or \p P is not a valid public key.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
+ * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
+ * operations was reached: see \c mbedtls_ecp_set_max_ops().
+ */
+int mbedtls_ecp_mul_restartable( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
+ const mbedtls_mpi *m, const mbedtls_ecp_point *P,
+ int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
+ mbedtls_ecp_restart_ctx *rs_ctx );
+
+/**
+ * \brief This function performs multiplication and addition of two
+ * points by integers: \p R = \p m * \p P + \p n * \p Q
+ *
+ * It is not thread-safe to use same group in multiple threads.
+ *
+ * \note In contrast to mbedtls_ecp_mul(), this function does not
+ * guarantee a constant execution flow and timing.
+ *
+ * \param grp The ECP group.
+ * \param R The destination point.
+ * \param m The integer by which to multiply \p P.
+ * \param P The point to multiply by \p m.
+ * \param n The integer by which to multiply \p Q.
+ * \param Q The point to be multiplied by \p n.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
+ * valid private keys, or \p P or \p Q are not valid public
+ * keys.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
*/
int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
const mbedtls_mpi *m, const mbedtls_ecp_point *P,
const mbedtls_mpi *n, const mbedtls_ecp_point *Q );
/**
- * \brief Check that a point is a valid public key on this curve
+ * \brief This function performs multiplication and addition of two
+ * points by integers: \p R = \p m * \p P + \p n * \p Q in a
+ * restartable way.
*
- * \param grp Curve/group the point should belong to
- * \param pt Point to check
+ * \see \c mbedtls_ecp_muladd()
*
- * \return 0 if point is a valid public key,
- * MBEDTLS_ERR_ECP_INVALID_KEY otherwise.
+ * \note This function works the same as \c mbedtls_ecp_muladd(),
+ * but it can return early and restart according to the limit
+ * set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
*
- * \note This function only checks the point is non-zero, has valid
- * coordinates and lies on the curve, but not that it is
- * indeed a multiple of G. This is additional check is more
- * expensive, isn't required by standards, and shouldn't be
- * necessary if the group used has a small cofactor. In
- * particular, it is useless for the NIST groups which all
- * have a cofactor of 1.
+ * \param grp The ECP group.
+ * \param R The destination point.
+ * \param m The integer by which to multiply \p P.
+ * \param P The point to multiply by \p m.
+ * \param n The integer by which to multiply \p Q.
+ * \param Q The point to be multiplied by \p n.
+ * \param rs_ctx The restart context (NULL disables restart).
*
- * \note Uses bare components rather than an mbedtls_ecp_keypair structure
- * in order to ease use with other structures such as
- * mbedtls_ecdh_context of mbedtls_ecdsa_context.
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
+ * valid private keys, or \p P or \p Q are not valid public
+ * keys.
+ * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
+ * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
+ * operations was reached: see \c mbedtls_ecp_set_max_ops().
+ */
+int mbedtls_ecp_muladd_restartable(
+ mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
+ const mbedtls_mpi *m, const mbedtls_ecp_point *P,
+ const mbedtls_mpi *n, const mbedtls_ecp_point *Q,
+ mbedtls_ecp_restart_ctx *rs_ctx );
+
+/**
+ * \brief This function checks that a point is a valid public key
+ * on this curve.
+ *
+ * It only checks that the point is non-zero, has
+ * valid coordinates and lies on the curve. It does not verify
+ * that it is indeed a multiple of \p G. This additional
+ * check is computationally more expensive, is not required
+ * by standards, and should not be necessary if the group
+ * used has a small cofactor. In particular, it is useless for
+ * the NIST groups which all have a cofactor of 1.
+ *
+ * \note This function uses bare components rather than an
+ * ::mbedtls_ecp_keypair structure, to ease use with other
+ * structures, such as ::mbedtls_ecdh_context or
+ * ::mbedtls_ecdsa_context.
+ *
+ * \param grp The curve the point should lie on.
+ * \param pt The point to check.
+ *
+ * \return \c 0 if the point is a valid public key.
+ * \return #MBEDTLS_ERR_ECP_INVALID_KEY on failure.
*/
int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt );
/**
- * \brief Check that an mbedtls_mpi is a valid private key for this curve
+ * \brief This function checks that an \p mbedtls_mpi is a valid private
+ * key for this curve.
*
- * \param grp Group used
- * \param d Integer to check
+ * \note This function uses bare components rather than an
+ * ::mbedtls_ecp_keypair structure to ease use with other
+ * structures, such as ::mbedtls_ecdh_context or
+ * ::mbedtls_ecdsa_context.
*
- * \return 0 if point is a valid private key,
- * MBEDTLS_ERR_ECP_INVALID_KEY otherwise.
+ * \param grp The group used.
+ * \param d The integer to check.
*
- * \note Uses bare components rather than an mbedtls_ecp_keypair structure
- * in order to ease use with other structures such as
- * mbedtls_ecdh_context of mbedtls_ecdsa_context.
+ * \return \c 0 if the point is a valid private key.
+ * \return #MBEDTLS_ERR_ECP_INVALID_KEY on failure.
*/
int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d );
/**
- * \brief Generate a keypair with configurable base point
+ * \brief This function generates a private key.
*
- * \param grp ECP group
- * \param G Chosen base point
- * \param d Destination MPI (secret part)
- * \param Q Destination point (public part)
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \param grp The ECP group.
+ * \param d The destination MPI (secret part).
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG parameter.
*
- * \return 0 if successful,
- * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
+ * on failure.
+ */
+int mbedtls_ecp_gen_privkey( const mbedtls_ecp_group *grp,
+ mbedtls_mpi *d,
+ int (*f_rng)(void *, unsigned char *, size_t),
+ void *p_rng );
+
+/**
+ * \brief This function generates a keypair with a configurable base
+ * point.
*
- * \note Uses bare components rather than an mbedtls_ecp_keypair structure
- * in order to ease use with other structures such as
- * mbedtls_ecdh_context of mbedtls_ecdsa_context.
+ * \note This function uses bare components rather than an
+ * ::mbedtls_ecp_keypair structure to ease use with other
+ * structures, such as ::mbedtls_ecdh_context or
+ * ::mbedtls_ecdsa_context.
+ *
+ * \param grp The ECP group.
+ * \param G The chosen base point.
+ * \param d The destination MPI (secret part).
+ * \param Q The destination point (public part).
+ * \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_ecp_gen_keypair_base( mbedtls_ecp_group *grp,
const mbedtls_ecp_point *G,
@@ -617,57 +921,66 @@
void *p_rng );
/**
- * \brief Generate a keypair
+ * \brief This function generates an ECP keypair.
*
- * \param grp ECP group
- * \param d Destination MPI (secret part)
- * \param Q Destination point (public part)
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \note This function uses bare components rather than an
+ * ::mbedtls_ecp_keypair structure to ease use with other
+ * structures, such as ::mbedtls_ecdh_context or
+ * ::mbedtls_ecdsa_context.
*
- * \return 0 if successful,
- * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \param grp The ECP group.
+ * \param d The destination MPI (secret part).
+ * \param Q The destination point (public part).
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG context.
*
- * \note Uses bare components rather than an mbedtls_ecp_keypair structure
- * in order to ease use with other structures such as
- * mbedtls_ecdh_context of mbedtls_ecdsa_context.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
+ * on failure.
*/
int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng );
/**
- * \brief Generate a keypair
+ * \brief This function generates an ECP key.
*
- * \param grp_id ECP group identifier
- * \param key Destination keypair
- * \param f_rng RNG function
- * \param p_rng RNG parameter
+ * \param grp_id The ECP group identifier.
+ * \param key The destination key.
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG context.
*
- * \return 0 if successful,
- * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
+ * on failure.
*/
int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
/**
- * \brief Check a public-private key pair
+ * \brief This function checks that the keypair objects
+ * \p pub and \p prv have the same group and the
+ * same public point, and that the private key in
+ * \p prv is consistent with the public key.
*
- * \param pub Keypair structure holding a public key
- * \param prv Keypair structure holding a private (plus public) key
+ * \param pub The keypair structure holding the public key.
+ * If it contains a private key, that part is ignored.
+ * \param prv The keypair structure holding the full keypair.
*
- * \return 0 if successful (keys are valid and match), or
- * MBEDTLS_ERR_ECP_BAD_INPUT_DATA, or
- * a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX code.
+ * \return \c 0 on success, meaning that the keys are valid and match.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX
+ * error code on calculation failure.
*/
int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv );
#if defined(MBEDTLS_SELF_TEST)
/**
- * \brief Checkup routine
+ * \brief The ECP checkup routine.
*
- * \return 0 if successful, or 1 if a test failed
+ * \return \c 0 on success.
+ * \return \c 1 on failure.
*/
int mbedtls_ecp_self_test( int verbose );
@@ -677,8 +990,4 @@
}
#endif
-#else /* MBEDTLS_ECP_ALT */
-#include "ecp_alt.h"
-#endif /* MBEDTLS_ECP_ALT */
-
#endif /* ecp.h */
diff --git a/ext/mbedtls/include/mbedtls/md.h b/ext/mbedtls/include/mbedtls/md.h
index 9b996a9..8bcf766 100644
--- a/ext/mbedtls/include/mbedtls/md.h
+++ b/ext/mbedtls/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,33 +21,51 @@
* 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
#include <stddef.h>
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE -0x5080 /**< The selected feature is not available. */
#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. */
+/* MBEDTLS_ERR_MD_HW_ACCEL_FAILED is deprecated and should not be used. */
+#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)
@@ -56,65 +75,80 @@
#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 */
+typedef struct mbedtls_md_context_t
+{
+ /** 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 );
@@ -125,220 +159,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/ext/mbedtls/include/mbedtls/pk.h b/ext/mbedtls/include/mbedtls/pk.h
index f9f9b9b..df3a03c 100644
--- a/ext/mbedtls/include/mbedtls/pk.h
+++ b/ext/mbedtls/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,10 @@
#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. */
+
+/* MBEDTLS_ERR_PK_HW_ACCEL_FAILED is deprecated and should not be used. */
+#define MBEDTLS_ERR_PK_HW_ACCEL_FAILED -0x3880 /**< PK hardware accelerator failed. */
#ifdef __cplusplus
extern "C" {
@@ -85,7 +89,7 @@
* \brief Options for RSASSA-PSS signature verification.
* See \c mbedtls_rsa_rsassa_pss_verify_ext()
*/
-typedef struct
+typedef struct mbedtls_pk_rsassa_pss_options
{
mbedtls_md_type_t mgf1_hash_id;
int expected_salt_len;
@@ -105,7 +109,7 @@
/**
* \brief Item to send to the debug module
*/
-typedef struct
+typedef struct mbedtls_pk_debug_item
{
mbedtls_pk_debug_type type;
const char *name;
@@ -123,12 +127,26 @@
/**
* \brief Public key container
*/
-typedef struct
+typedef struct mbedtls_pk_context
{
- const mbedtls_pk_info_t * pk_info; /**< Public key informations */
+ const mbedtls_pk_info_t * pk_info; /**< Public key information */
void * pk_ctx; /**< Underlying public key context */
} mbedtls_pk_context;
+#if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
+/**
+ * \brief Context for resuming operations
+ */
+typedef struct
+{
+ const mbedtls_pk_info_t * pk_info; /**< Public key information */
+ void * rs_ctx; /**< Underlying restart context */
+} mbedtls_pk_restart_ctx;
+#else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
+/* Now we can declare functions that take a pointer to that */
+typedef void mbedtls_pk_restart_ctx;
+#endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
+
#if defined(MBEDTLS_RSA_C)
/**
* Quick access to an RSA context inside a PK context.
@@ -188,6 +206,18 @@
*/
void mbedtls_pk_free( mbedtls_pk_context *ctx );
+#if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
+/**
+ * \brief Initialize a restart context
+ */
+void mbedtls_pk_restart_init( mbedtls_pk_restart_ctx *ctx );
+
+/**
+ * \brief Free the components of a restart context
+ */
+void mbedtls_pk_restart_free( mbedtls_pk_restart_ctx *ctx );
+#endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
+
/**
* \brief Initialize a PK context with the information given
* and allocates the type-specific PK subcontext.
@@ -267,8 +297,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.
@@ -285,6 +315,32 @@
const unsigned char *sig, size_t sig_len );
/**
+ * \brief Restartable version of \c mbedtls_pk_verify()
+ *
+ * \note Performs the same job as \c mbedtls_pk_verify(), but can
+ * return early and restart according to the limit set with
+ * \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
+ * operations. For RSA, same as \c mbedtls_pk_verify().
+ *
+ * \param ctx PK context to use
+ * \param md_alg Hash algorithm used (see notes)
+ * \param hash Hash of the message to sign
+ * \param hash_len Hash length or 0 (see notes)
+ * \param sig Signature to verify
+ * \param sig_len Signature length
+ * \param rs_ctx Restart context (NULL to disable restart)
+ *
+ * \return See \c mbedtls_pk_verify(), or
+ * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
+ * operations was reached: see \c mbedtls_ecp_set_max_ops().
+ */
+int mbedtls_pk_verify_restartable( mbedtls_pk_context *ctx,
+ mbedtls_md_type_t md_alg,
+ const unsigned char *hash, size_t hash_len,
+ const unsigned char *sig, size_t sig_len,
+ mbedtls_pk_restart_ctx *rs_ctx );
+
+/**
* \brief Verify signature, with options.
* (Includes verification of the padding depending on type.)
*
@@ -298,10 +354,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
@@ -348,6 +404,35 @@
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
/**
+ * \brief Restartable version of \c mbedtls_pk_sign()
+ *
+ * \note Performs the same job as \c mbedtls_pk_sign(), but can
+ * return early and restart according to the limit set with
+ * \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
+ * operations. For RSA, same as \c mbedtls_pk_sign().
+ *
+ * \param ctx PK context to use - must hold a private key
+ * \param md_alg Hash algorithm used (see notes)
+ * \param hash Hash of the message to sign
+ * \param hash_len Hash length or 0 (see notes)
+ * \param sig Place to write the signature
+ * \param sig_len Number of bytes written
+ * \param f_rng RNG function
+ * \param p_rng RNG parameter
+ * \param rs_ctx Restart context (NULL to disable restart)
+ *
+ * \return See \c mbedtls_pk_sign(), or
+ * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
+ * operations was reached: see \c mbedtls_ecp_set_max_ops().
+ */
+int mbedtls_pk_sign_restartable( mbedtls_pk_context *ctx,
+ mbedtls_md_type_t md_alg,
+ const unsigned char *hash, size_t hash_len,
+ unsigned char *sig, size_t *sig_len,
+ int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
+ mbedtls_pk_restart_ctx *rs_ctx );
+
+/**
* \brief Decrypt message (including padding if relevant).
*
* \param ctx PK context to use - must hold a private key
diff --git a/ext/mbedtls/include/mbedtls/platform.h b/ext/mbedtls/include/mbedtls/platform.h
index 35010f8..89fe8a7 100644
--- a/ext/mbedtls/include/mbedtls/platform.h
+++ b/ext/mbedtls/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
@@ -30,9 +40,12 @@
#endif
#if defined(MBEDTLS_HAVE_TIME)
-#include "mbedtls/platform_time.h"
+#include "platform_time.h"
#endif
+#define MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED -0x0070 /**< Hardware accelerator failed */
+#define MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED -0x0072 /**< The requested feature is not supported by the platform */
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -51,34 +64,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 +114,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) && \
@@ -111,16 +124,17 @@
#else
/* For size_t */
#include <stddef.h>
-extern void * (*mbedtls_calloc)( size_t n, size_t size );
-extern void (*mbedtls_free)( void *ptr );
+extern void *mbedtls_calloc( size_t n, size_t size );
+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 +153,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 +178,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 +213,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, ... ) );
@@ -207,7 +226,7 @@
#if defined(MBEDTLS_PLATFORM_SNPRINTF_MACRO)
#define mbedtls_snprintf MBEDTLS_PLATFORM_SNPRINTF_MACRO
#else
-#define mbedtls_snprintf snprintf
+#define mbedtls_snprintf MBEDTLS_PLATFORM_STD_SNPRINTF
#endif /* MBEDTLS_PLATFORM_SNPRINTF_MACRO */
#endif /* MBEDTLS_PLATFORM_SNPRINTF_ALT */
@@ -218,11 +237,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 +286,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 +313,14 @@
#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 */
+typedef struct mbedtls_platform_context
+{
+ char dummy; /**< A placeholder member, as empty structs are not portable. */
}
mbedtls_platform_context;
@@ -306,33 +329,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/ext/mbedtls/include/mbedtls/platform_util.h b/ext/mbedtls/include/mbedtls/platform_util.h
new file mode 100644
index 0000000..164a1a0
--- /dev/null
+++ b/ext/mbedtls/include/mbedtls/platform_util.h
@@ -0,0 +1,103 @@
+/**
+ * \file platform_util.h
+ *
+ * \brief Common and shared functions used by multiple modules in the Mbed TLS
+ * library.
+ */
+/*
+ * Copyright (C) 2018, 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_PLATFORM_UTIL_H
+#define MBEDTLS_PLATFORM_UTIL_H
+
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "mbedtls/config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
+#include <stddef.h>
+#if defined(MBEDTLS_HAVE_TIME_DATE)
+#include "mbedtls/platform_time.h"
+#include <time.h>
+#endif /* MBEDTLS_HAVE_TIME_DATE */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \brief Securely zeroize a buffer
+ *
+ * The function is meant to wipe the data contained in a buffer so
+ * that it can no longer be recovered even if the program memory
+ * is later compromised. Call this function on sensitive data
+ * stored on the stack before returning from a function, and on
+ * sensitive data stored on the heap before freeing the heap
+ * object.
+ *
+ * It is extremely difficult to guarantee that calls to
+ * mbedtls_platform_zeroize() are not removed by aggressive
+ * compiler optimizations in a portable way. For this reason, Mbed
+ * TLS provides the configuration option
+ * MBEDTLS_PLATFORM_ZEROIZE_ALT, which allows users to configure
+ * mbedtls_platform_zeroize() to use a suitable implementation for
+ * their platform and needs
+ *
+ * \param buf Buffer to be zeroized
+ * \param len Length of the buffer in bytes
+ *
+ */
+void mbedtls_platform_zeroize( void *buf, size_t len );
+
+#if defined(MBEDTLS_HAVE_TIME_DATE)
+/**
+ * \brief Platform-specific implementation of gmtime_r()
+ *
+ * The function is a thread-safe abstraction that behaves
+ * similarly to the gmtime_r() function from Unix/POSIX.
+ *
+ * Mbed TLS will try to identify the underlying platform and
+ * make use of an appropriate underlying implementation (e.g.
+ * gmtime_r() for POSIX and gmtime_s() for Windows). If this is
+ * not possible, then gmtime() will be used. In this case, calls
+ * from the library to gmtime() will be guarded by the mutex
+ * mbedtls_threading_gmtime_mutex if MBEDTLS_THREADING_C is
+ * enabled. It is recommended that calls from outside the library
+ * are also guarded by this mutex.
+ *
+ * If MBEDTLS_PLATFORM_GMTIME_R_ALT is defined, then Mbed TLS will
+ * unconditionally use the alternative implementation for
+ * mbedtls_platform_gmtime_r() supplied by the user at compile time.
+ *
+ * \param tt Pointer to an object containing time (in seconds) since the
+ * epoch to be converted
+ * \param tm_buf Pointer to an object where the results will be stored
+ *
+ * \return Pointer to an object of type struct tm on success, otherwise
+ * NULL
+ */
+struct tm *mbedtls_platform_gmtime_r( const mbedtls_time_t *tt,
+ struct tm *tm_buf );
+#endif /* MBEDTLS_HAVE_TIME_DATE */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* MBEDTLS_PLATFORM_UTIL_H */
diff --git a/ext/mbedtls/include/mbedtls/threading.h b/ext/mbedtls/include/mbedtls/threading.h
new file mode 100644
index 0000000..92e6e6b
--- /dev/null
+++ b/ext/mbedtls/include/mbedtls/threading.h
@@ -0,0 +1,122 @@
+/**
+ * \file threading.h
+ *
+ * \brief Threading abstraction layer
+ */
+/*
+ * Copyright (C) 2006-2015, 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_THREADING_H
+#define MBEDTLS_THREADING_H
+
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
+#include <stdlib.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* MBEDTLS_ERR_THREADING_FEATURE_UNAVAILABLE is deprecated and should not be
+ * used. */
+#define MBEDTLS_ERR_THREADING_FEATURE_UNAVAILABLE -0x001A /**< The selected feature is not available. */
+
+#define MBEDTLS_ERR_THREADING_BAD_INPUT_DATA -0x001C /**< Bad input parameters to function. */
+#define MBEDTLS_ERR_THREADING_MUTEX_ERROR -0x001E /**< Locking / unlocking / free failed with error code. */
+
+#if defined(MBEDTLS_THREADING_PTHREAD)
+#include <pthread.h>
+typedef struct mbedtls_threading_mutex_t
+{
+ pthread_mutex_t mutex;
+ char is_valid;
+} mbedtls_threading_mutex_t;
+#endif
+
+#if defined(MBEDTLS_THREADING_ALT)
+/* You should define the mbedtls_threading_mutex_t type in your header */
+#include "threading_alt.h"
+
+/**
+ * \brief Set your alternate threading implementation function
+ * pointers and initialize global mutexes. If used, this
+ * function must be called once in the main thread before any
+ * other mbed TLS function is called, and
+ * mbedtls_threading_free_alt() must be called once in the main
+ * thread after all other mbed TLS functions.
+ *
+ * \note mutex_init() and mutex_free() don't return a status code.
+ * If mutex_init() fails, it should leave its argument (the
+ * mutex) in a state such that mutex_lock() will fail when
+ * called with this argument.
+ *
+ * \param mutex_init the init function implementation
+ * \param mutex_free the free function implementation
+ * \param mutex_lock the lock function implementation
+ * \param mutex_unlock the unlock function implementation
+ */
+void mbedtls_threading_set_alt( void (*mutex_init)( mbedtls_threading_mutex_t * ),
+ void (*mutex_free)( mbedtls_threading_mutex_t * ),
+ int (*mutex_lock)( mbedtls_threading_mutex_t * ),
+ int (*mutex_unlock)( mbedtls_threading_mutex_t * ) );
+
+/**
+ * \brief Free global mutexes.
+ */
+void mbedtls_threading_free_alt( void );
+#endif /* MBEDTLS_THREADING_ALT */
+
+#if defined(MBEDTLS_THREADING_C)
+/*
+ * The function pointers for mutex_init, mutex_free, mutex_ and mutex_unlock
+ *
+ * All these functions are expected to work or the result will be undefined.
+ */
+extern void (*mbedtls_mutex_init)( mbedtls_threading_mutex_t *mutex );
+extern void (*mbedtls_mutex_free)( mbedtls_threading_mutex_t *mutex );
+extern int (*mbedtls_mutex_lock)( mbedtls_threading_mutex_t *mutex );
+extern int (*mbedtls_mutex_unlock)( mbedtls_threading_mutex_t *mutex );
+
+/*
+ * Global mutexes
+ */
+#if defined(MBEDTLS_FS_IO)
+extern mbedtls_threading_mutex_t mbedtls_threading_readdir_mutex;
+#endif
+
+#if defined(MBEDTLS_HAVE_TIME_DATE) && !defined(MBEDTLS_PLATFORM_GMTIME_R_ALT)
+/* This mutex may or may not be used in the default definition of
+ * mbedtls_platform_gmtime_r(), but in order to determine that,
+ * we need to check POSIX features, hence modify _POSIX_C_SOURCE.
+ * With the current approach, this declaration is orphaned, lacking
+ * an accompanying definition, in case mbedtls_platform_gmtime_r()
+ * doesn't need it, but that's not a problem. */
+extern mbedtls_threading_mutex_t mbedtls_threading_gmtime_mutex;
+#endif /* MBEDTLS_HAVE_TIME_DATE && !MBEDTLS_PLATFORM_GMTIME_R_ALT */
+
+#endif /* MBEDTLS_THREADING_C */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* threading.h */
diff --git a/ext/mbedtls/src/asn1parse.c b/ext/mbedtls/src/asn1parse.c
index 4dd65c0..171c340 100644
--- a/ext/mbedtls/src/asn1parse.c
+++ b/ext/mbedtls/src/asn1parse.c
@@ -28,6 +28,7 @@
#if defined(MBEDTLS_ASN1_PARSE_C)
#include "mbedtls/asn1.h"
+#include "mbedtls/platform_util.h"
#include <string.h>
@@ -43,11 +44,6 @@
#define mbedtls_free free
#endif
-/* Implementation that should never be optimized out by the compiler */
-static void mbedtls_zeroize( void *v, size_t n ) {
- volatile unsigned char *p = (unsigned char*)v; while( n-- ) *p++ = 0;
-}
-
/*
* ASN.1 DER decoding routines
*/
@@ -313,7 +309,7 @@
if( *p == end )
{
- mbedtls_zeroize( params, sizeof(mbedtls_asn1_buf) );
+ mbedtls_platform_zeroize( params, sizeof(mbedtls_asn1_buf) );
return( 0 );
}
@@ -358,7 +354,7 @@
mbedtls_free( cur->oid.p );
mbedtls_free( cur->val.p );
- mbedtls_zeroize( cur, sizeof( mbedtls_asn1_named_data ) );
+ mbedtls_platform_zeroize( cur, sizeof( mbedtls_asn1_named_data ) );
}
void mbedtls_asn1_free_named_data_list( mbedtls_asn1_named_data **head )
diff --git a/ext/mbedtls/src/platform_util.c b/ext/mbedtls/src/platform_util.c
new file mode 100644
index 0000000..ca5fe4f
--- /dev/null
+++ b/ext/mbedtls/src/platform_util.c
@@ -0,0 +1,135 @@
+/*
+ * Common and shared functions used by multiple modules in the Mbed TLS
+ * library.
+ *
+ * Copyright (C) 2018, 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)
+ */
+
+/*
+ * Ensure gmtime_r is available even with -std=c99; must be defined before
+ * config.h, which pulls in glibc's features.h. Harmless on other platforms.
+ */
+#if !defined(_POSIX_C_SOURCE)
+#define _POSIX_C_SOURCE 200112L
+#endif
+
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "mbedtls/config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
+#include "mbedtls/platform_util.h"
+#include "mbedtls/threading.h"
+
+#include <stddef.h>
+#include <string.h>
+
+#if !defined(MBEDTLS_PLATFORM_ZEROIZE_ALT)
+/*
+ * This implementation should never be optimized out by the compiler
+ *
+ * This implementation for mbedtls_platform_zeroize() was inspired from Colin
+ * Percival's blog article at:
+ *
+ * http://www.daemonology.net/blog/2014-09-04-how-to-zero-a-buffer.html
+ *
+ * It uses a volatile function pointer to the standard memset(). Because the
+ * pointer is volatile the compiler expects it to change at
+ * any time and will not optimize out the call that could potentially perform
+ * other operations on the input buffer instead of just setting it to 0.
+ * Nevertheless, as pointed out by davidtgoldblatt on Hacker News
+ * (refer to http://www.daemonology.net/blog/2014-09-05-erratum.html for
+ * details), optimizations of the following form are still possible:
+ *
+ * if( memset_func != memset )
+ * memset_func( buf, 0, len );
+ *
+ * Note that it is extremely difficult to guarantee that
+ * mbedtls_platform_zeroize() will not be optimized out by aggressive compilers
+ * in a portable way. For this reason, Mbed TLS also provides the configuration
+ * option MBEDTLS_PLATFORM_ZEROIZE_ALT, which allows users to configure
+ * mbedtls_platform_zeroize() to use a suitable implementation for their
+ * platform and needs.
+ */
+static void * (* const volatile memset_func)( void *, int, size_t ) = memset;
+
+void mbedtls_platform_zeroize( void *buf, size_t len )
+{
+ memset_func( buf, 0, len );
+}
+#endif /* MBEDTLS_PLATFORM_ZEROIZE_ALT */
+
+#if defined(MBEDTLS_HAVE_TIME_DATE) && !defined(MBEDTLS_PLATFORM_GMTIME_R_ALT)
+#include <time.h>
+#if !defined(_WIN32) && (defined(unix) || \
+ defined(__unix) || defined(__unix__) || (defined(__APPLE__) && \
+ defined(__MACH__)))
+#include <unistd.h>
+#endif /* !_WIN32 && (unix || __unix || __unix__ ||
+ * (__APPLE__ && __MACH__)) */
+
+#if !( ( defined(_POSIX_VERSION) && _POSIX_VERSION >= 200809L ) || \
+ ( defined(_POSIX_THREAD_SAFE_FUNCTIONS ) && \
+ _POSIX_THREAD_SAFE_FUNCTIONS >= 20112L ) )
+/*
+ * This is a convenience shorthand macro to avoid checking the long
+ * preprocessor conditions above. Ideally, we could expose this macro in
+ * platform_util.h and simply use it in platform_util.c, threading.c and
+ * threading.h. However, this macro is not part of the Mbed TLS public API, so
+ * we keep it private by only defining it in this file
+ */
+#if ! ( defined(_WIN32) && !defined(EFIX64) && !defined(EFI32) )
+#define PLATFORM_UTIL_USE_GMTIME
+#endif /* ! ( defined(_WIN32) && !defined(EFIX64) && !defined(EFI32) ) */
+
+#endif /* !( ( defined(_POSIX_VERSION) && _POSIX_VERSION >= 200809L ) || \
+ ( defined(_POSIX_THREAD_SAFE_FUNCTIONS ) && \
+ _POSIX_THREAD_SAFE_FUNCTIONS >= 20112L ) ) */
+
+struct tm *mbedtls_platform_gmtime_r( const mbedtls_time_t *tt,
+ struct tm *tm_buf )
+{
+#if defined(_WIN32) && !defined(EFIX64) && !defined(EFI32)
+ return( ( gmtime_s( tm_buf, tt ) == 0 ) ? tm_buf : NULL );
+#elif !defined(PLATFORM_UTIL_USE_GMTIME)
+ return( gmtime_r( tt, tm_buf ) );
+#else
+ struct tm *lt;
+
+#if defined(MBEDTLS_THREADING_C)
+ if( mbedtls_mutex_lock( &mbedtls_threading_gmtime_mutex ) != 0 )
+ return( NULL );
+#endif /* MBEDTLS_THREADING_C */
+
+ lt = gmtime( tt );
+
+ if( lt != NULL )
+ {
+ memcpy( tm_buf, lt, sizeof( struct tm ) );
+ }
+
+#if defined(MBEDTLS_THREADING_C)
+ if( mbedtls_mutex_unlock( &mbedtls_threading_gmtime_mutex ) != 0 )
+ return( NULL );
+#endif /* MBEDTLS_THREADING_C */
+
+ return( ( lt == NULL ) ? NULL : tm_buf );
+#endif /* _WIN32 && !EFIX64 && !EFI32 */
+}
+#endif /* MBEDTLS_HAVE_TIME_DATE && MBEDTLS_PLATFORM_GMTIME_R_ALT */