Update ecp.h
Changes based on review comments.
2 comments still open pending decisions
diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h
index c58a4b6..050283c 100644
--- a/include/mbedtls/ecp.h
+++ b/include/mbedtls/ecp.h
@@ -1,11 +1,11 @@
/**
* \file ecp.h
*
- * \brief This file contains ECP definitions and functions.
+ * \brief This file provides an API for Elliptic Curves over GF(P) (ECP).
*
- * The use of Elliptic Curves over GF(P) (ECP) in cryptography and
- * TLS is defined in <em>Standards for Efficient Cryptography Group
- * (SECG): SEC1 Elliptic Curve Cryptography</em> and
+ * 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>.
*
@@ -43,7 +43,7 @@
*/
#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 /**< The requested curve not available. */
+#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< The requested curve is not available. */
#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. */
@@ -65,7 +65,7 @@
#endif
/**
- * Definition of domain parameter identifiers: curve, subgroup and generator.
+ * Domain parameters: curve, subgroup, and generator.
*
* \note Only curves over prime fields are supported.
*
@@ -76,16 +76,16 @@
typedef enum
{
MBEDTLS_ECP_DP_NONE = 0, /*!< Curve not defined. */
- MBEDTLS_ECP_DP_SECP192R1, /*!< Domain parameters for 192-bit NIST curve. */
- MBEDTLS_ECP_DP_SECP224R1, /*!< Domain parameters for 224-bit NIST curve. */
- MBEDTLS_ECP_DP_SECP256R1, /*!< Domain parameters for 256-bit NIST curve. */
- MBEDTLS_ECP_DP_SECP384R1, /*!< Domain parameters for 384-bit NIST curve. */
- MBEDTLS_ECP_DP_SECP521R1, /*!< Domain parameters for 521-bit NIST curve. */
+ 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 a Curve25519 curve. */
- MBEDTLS_ECP_DP_CURVE448, /*!< Domain parameters for a Curve448 curve. */
+ MBEDTLS_ECP_DP_CURVE25519, /*!< Domain parameters for Curve25519. */
+ MBEDTLS_ECP_DP_CURVE448, /*!< Domain parameters for Curve448. */
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. */
@@ -105,7 +105,7 @@
{
mbedtls_ecp_group_id grp_id; /*!< An internal identifier. */
uint16_t tls_id; /*!< The TLS NamedCurve identifier. */
- uint16_t bit_size; /*!< The size of the curve in bits. */
+ uint16_t bit_size; /*!< The curve size in bits. */
const char *name; /*!< A human-friendly name. */
} mbedtls_ecp_curve_info;
@@ -132,15 +132,16 @@
* \brief The ECP group structure.
*
* We consider two types of curve equations:
- * <ol><li>Short Weierstrass: <code>y^2 = x^3 + A x + B mod P</code>
+ * <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></ol>
+ * Curve448)</li></ul>
* In both cases, the generator (\p G) for a prime-order subgroup is fixed.
*
* 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.
+ * 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
@@ -160,15 +161,15 @@
{
mbedtls_ecp_group_id id; /*!< An internal group identifier. */
mbedtls_mpi P; /*!< The prime modulus of the base field. */
- mbedtls_mpi A; /*!< For (1) \p A in the equation or for
- (2) <code>(A + 2) / 4</code>. */
- mbedtls_mpi B; /*!< For (1) \p B in the equation or
- for (2) Unused. */
+ 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 (1) The number of bits in \p P, or
- for (2) the private keys. */
+ size_t nbits; /*!< For Short Weierstrass: The number of bits in \p P.
+ For Montgomery curves: 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).*/
@@ -176,7 +177,7 @@
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 for pre-computed points. */
+ size_t T_size; /*!< The number of pre-computed points. */
}
mbedtls_ecp_group;
@@ -498,7 +499,7 @@
* \brief This function exports a point as a TLS ECPoint record.
*
* \param grp The ECP group used.
- * \param pt The point to export.
+ * \param pt he point format to export to 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.
@@ -631,9 +632,9 @@
* 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. For example, mbedtls_ecdh_context() or
- * mbedtls_ecdsa_context().
+ * ::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.
@@ -648,9 +649,9 @@
* key for this curve.
*
* \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().
+ * ::mbedtls_ecp_keypair structure to ease use with other
+ * structures, such as ::mbedtls_ecdh_context() or
+ * ::mbedtls_ecdsa_context.
*
* \param grp The group used.
* \param d The integer to check.
@@ -665,10 +666,10 @@
* point.
*
* \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().
-*
+ * ::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).
@@ -690,9 +691,9 @@
* \brief This function generates an ECP keypair.
*
* \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().
+ * ::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 d The destination MPI (secret part).
@@ -724,17 +725,19 @@
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
/**
- * \brief This function checks 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 The keypair structure holding the public key.
- * \param prv The keypair structure holding the private key.
+ * If it contains a private key, that part is ignored.
+ * \param prv The keypair structure holding the full keypair.
*
- * \note The both are keypairs, and may optionally hold the corresponding other key, but the public key passed in thee pub is checked against the private key passed in prv.
- *
- * \return \c 0 on success - the keys are valid and match.
- * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA, or an \c
- * MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX
- * error code on failure.
+ * \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 );