yuzu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2025-03-24 12:55:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update ecp.h

Browse source 
Changes based on review comments. 
2 comments still open pending decisions
This commit is contained in:
Rose Zadik 2018-04-20 10:13:48 +01:00 committed by GitHub
parent f56cb34d60
commit b2e111a288
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 49 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

95
include/mbedtls/ecp.h
View file

@ -1,11 +1,11 @@
/** /**
* \file ecp.h * \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 * The use of ECP in cryptography and TLS is defined in
* TLS is defined in <em>Standards for Efficient Cryptography Group * <em>Standards for Efficient Cryptography Group (SECG): SEC1
* (SECG): SEC1 Elliptic Curve Cryptography</em> and * Elliptic Curve Cryptography</em> and
* <em>RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites * <em>RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites
* for Transport Layer Security (TLS)</em>. * 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_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_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_VERIFY_FAILED -0x4E00 /**< The signature is not valid. */
#define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80 /**< Memory allocation failed. */ #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. */
@ -65,7 +65,7 @@ extern "C" {
#endif #endif
/** /**
* Definition of domain parameter identifiers: curve, subgroup and generator. * Domain parameters: curve, subgroup, and generator.
* *
* \note Only curves over prime fields are supported. * \note Only curves over prime fields are supported.
* *
@ -76,16 +76,16 @@ extern "C" {
typedef enum typedef enum
{ {
MBEDTLS_ECP_DP_NONE = 0, /*!< Curve not defined. */ MBEDTLS_ECP_DP_NONE = 0, /*!< Curve not defined. */
MBEDTLS_ECP_DP_SECP192R1, /*!< Domain parameters for 192-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 224-bit NIST curve. */ 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 256-bit NIST curve. */ 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 384-bit NIST curve. */ 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 521-bit NIST curve. */ 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_BP256R1, /*!< Domain parameters for 256-bit Brainpool curve. */
MBEDTLS_ECP_DP_BP384R1, /*!< Domain parameters for 384-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_BP512R1, /*!< Domain parameters for 512-bit Brainpool curve. */
MBEDTLS_ECP_DP_CURVE25519, /*!< Domain parameters for a Curve25519 curve. */ MBEDTLS_ECP_DP_CURVE25519, /*!< Domain parameters for Curve25519. */
MBEDTLS_ECP_DP_CURVE448, /*!< Domain parameters for a Curve448 curve. */ MBEDTLS_ECP_DP_CURVE448, /*!< Domain parameters for Curve448. */
MBEDTLS_ECP_DP_SECP192K1, /*!< Domain parameters for 192-bit "Koblitz" curve. */ 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_SECP224K1, /*!< Domain parameters for 224-bit "Koblitz" curve. */
MBEDTLS_ECP_DP_SECP256K1, /*!< Domain parameters for 256-bit "Koblitz" curve. */ MBEDTLS_ECP_DP_SECP256K1, /*!< Domain parameters for 256-bit "Koblitz" curve. */
@ -105,7 +105,7 @@ typedef struct
{ {
mbedtls_ecp_group_id grp_id; /*!< An internal identifier. */ mbedtls_ecp_group_id grp_id; /*!< An internal identifier. */
uint16_t tls_id; /*!< The TLS NamedCurve 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. */ const char *name; /*!< A human-friendly name. */
} mbedtls_ecp_curve_info; } mbedtls_ecp_curve_info;
@ -132,15 +132,16 @@ mbedtls_ecp_point;
* \brief The ECP group structure. * \brief The ECP group structure.
* *
* We consider two types of curve equations: * 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> * (SEC1 + RFC-4492)</li>
* <li>Montgomery: <code>y^2 = x^3 + A x^2 + x mod P</code> (Curve25519, * <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. * 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 * 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 * 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>, * 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 * which is the quantity used in the formulas. Additionally, \p nbits is
@ -160,15 +161,15 @@ typedef struct
{ {
mbedtls_ecp_group_id id; /*!< An internal group identifier. */ mbedtls_ecp_group_id id; /*!< An internal group identifier. */
mbedtls_mpi P; /*!< The prime modulus of the base field. */ mbedtls_mpi P; /*!< The prime modulus of the base field. */
mbedtls_mpi A; /*!< For (1) \p A in the equation or for mbedtls_mpi A; /*!< For Short Weierstrass: \p A in the equation. For
(2) <code>(A + 2) / 4</code>. */ Montgomery curves: <code>(A + 2) / 4</code>. */
mbedtls_mpi B; /*!< For (1) \p B in the equation or mbedtls_mpi B; /*!< For Short Weierstrass: \p B in the equation.
for (2) Unused. */ For Montgomery curves: unused. */
mbedtls_ecp_point G; /*!< The generator of the subgroup used. */ mbedtls_ecp_point G; /*!< The generator of the subgroup used. */
mbedtls_mpi N; /*!< The order of \p G. */ mbedtls_mpi N; /*!< The order of \p G. */
size_t pbits; /*!< The number of bits in \p P.*/ size_t pbits; /*!< The number of bits in \p P.*/
size_t nbits; /*!< For (1) The number of bits in \p P, or size_t nbits; /*!< For Short Weierstrass: The number of bits in \p P.
for (2) the private keys. */ For Montgomery curves: the private keys. */
unsigned int h; /*!< \internal 1 if the constants are static. */ unsigned int h; /*!< \internal 1 if the constants are static. */
int (*modp)(mbedtls_mpi *); /*!< The function for fast pseudo-reduction int (*modp)(mbedtls_mpi *); /*!< The function for fast pseudo-reduction
mod \p P (see above).*/ mod \p P (see above).*/
@ -176,7 +177,7 @@ typedef struct
int (*t_post)(mbedtls_ecp_point *, void *); /*!< Unused. */ int (*t_post)(mbedtls_ecp_point *, void *); /*!< Unused. */
void *t_data; /*!< Unused. */ void *t_data; /*!< Unused. */
mbedtls_ecp_point *T; /*!< Pre-computed points for ecp_mul_comb(). */ 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; mbedtls_ecp_group;
@ -498,7 +499,7 @@ int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point
* \brief This function exports a point as a TLS ECPoint record. * \brief This function exports a point as a TLS ECPoint record.
* *
* \param grp The ECP group used. * \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 format The export format.
* \param olen The length of the data written. * \param olen The length of the data written.
* \param buf The buffer to write to. * \param buf The buffer to write to.
@ -631,9 +632,9 @@ int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
* the NIST groups which all have a cofactor of 1. * the NIST groups which all have a cofactor of 1.
* *
* \note This function uses bare components rather than an * \note This function uses bare components rather than an
* mbedtls_ecp_keypair() structure, to ease use with other * ::mbedtls_ecp_keypair structure, to ease use with other
* structures. For example, mbedtls_ecdh_context() or * structures, such as ::mbedtls_ecdh_context or
* mbedtls_ecdsa_context(). * ::mbedtls_ecdsa_context.
* *
* \param grp The curve the point should lie on. * \param grp The curve the point should lie on.
* \param pt The point to check. * \param pt The point to check.
@ -648,9 +649,9 @@ int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_po
* key for this curve. * key for this curve.
* *
* \note This function uses bare components rather than an * \note This function uses bare components rather than an
* mbedtls_ecp_keypair() structure to ease use with other * ::mbedtls_ecp_keypair structure to ease use with other
* structures such as mbedtls_ecdh_context() or * structures, such as ::mbedtls_ecdh_context() or
* mbedtls_ecdsa_context(). * ::mbedtls_ecdsa_context.
* *
* \param grp The group used. * \param grp The group used.
* \param d The integer to check. * \param d The integer to check.
@ -665,10 +666,10 @@ int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *
* point. * point.
* *
* \note This function uses bare components rather than an * \note This function uses bare components rather than an
* mbedtls_ecp_keypair() structure to ease use with other * ::mbedtls_ecp_keypair structure to ease use with other
* structures such as mbedtls_ecdh_context() or * structures, such as ::mbedtls_ecdh_context or
* mbedtls_ecdsa_context(). * ::mbedtls_ecdsa_context.
* *
* \param grp The ECP group. * \param grp The ECP group.
* \param G The chosen base point. * \param G The chosen base point.
* \param d The destination MPI (secret part). * \param d The destination MPI (secret part).
@ -690,9 +691,9 @@ int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp,
* \brief This function generates an ECP keypair. * \brief This function generates an ECP keypair.
* *
* \note This function uses bare components rather than an * \note This function uses bare components rather than an
* mbedtls_ecp_keypair() structure to ease use with other * ::mbedtls_ecp_keypair structure to ease use with other
* structures such as mbedtls_ecdh_context() or * structures, such as ::mbedtls_ecdh_context or
* mbedtls_ecdsa_context(). * ::mbedtls_ecdsa_context.
* *
* \param grp The ECP group. * \param grp The ECP group.
* \param d The destination MPI (secret part). * \param d The destination MPI (secret part).
@ -724,17 +725,19 @@ 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 ); 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 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, 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 \c 0 on success - the keys are valid and match. * \return An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA, or an \c * error code on calculation failure.
* MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX
* error code on failure.
*/ */
int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv ); int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv );