From d3c9bfcbeb02fdb89097d33326a6d1efd52c6a73 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 17 Apr 2018 10:56:55 +0100 Subject: [PATCH 1/9] Update ecp.h Reviewed and standardized --- include/mbedtls/ecp.h | 645 +++++++++++++++++++++++------------------- 1 file changed, 351 insertions(+), 294 deletions(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index e024da864..89c756b37 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -1,10 +1,20 @@ /** * \file ecp.h * - * \brief Elliptic curves over GF(p) + * \brief This file contains ECP definitions and functions. + * + * The Elliptic Curve over P (ECP) is defined in Standards for Efficient + * Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography and + * RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites + * for Transport Layer Security (TLS). + * + * RFC-2409: The Internet Key Exchange (IKE) defines ECP + * group types. + * */ -/* - * 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 @@ -19,8 +29,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 @@ -31,13 +42,13 @@ */ #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 curve 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. */ +#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 /**< The buffer contains a valid signature followed by more data. */ -#define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED -0x4B80 /**< ECP hardware accelerator failed. */ +#define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED -0x4B80 /**< The ECP hardware accelerator failed. */ #if !defined(MBEDTLS_ECP_ALT) /* @@ -53,9 +64,9 @@ extern "C" { #endif /** - * Domain parameters (curve, subgroup and generator) identifiers. + * Definition of domain parameter identifiers: curve, subgroup and generator. * - * Only curves over prime fields are supported. + * \note Only curves over prime fields are supported. * * \warning This library does not support validation of arbitrary domain * parameters. Therefore, only well-known domain parameters from trusted @@ -63,113 +74,119 @@ extern "C" { */ typedef enum { - 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_CURVE448, /*!< Curve448 */ - MBEDTLS_ECP_DP_SECP192K1, /*!< 192-bits "Koblitz" curve */ - MBEDTLS_ECP_DP_SECP224K1, /*!< 224-bits "Koblitz" curve */ - MBEDTLS_ECP_DP_SECP256K1, /*!< 256-bits "Koblitz" curve */ + 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_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_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_group_id; /** - * Number of supported curves (plus one for NONE). + * The number of supported curves, plus one for none. * - * (Montgomery curves excluded for now.) + * \note Montgomery curves are currently excluded. */ #define MBEDTLS_ECP_DP_MAX 12 /** - * Curve information for use by other modules + * 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_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. */ + const char *name; /*!< A human-friendly name. */ } mbedtls_ecp_curve_info; /** - * \brief ECP point structure (jacobian coordinates) + * \brief The ECP point structure, in 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 following condition: \p Z == 0 or \p Z == 1. Other + * values of \p Z are used only by internal functions. * 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_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; /** - * \brief ECP group structure + * \brief The 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. + * We consider two types of curve equations: + * + * In both cases, the generator (G) for a prime-order subgroup is fixed. * - * 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.) + * For Short Weierstrass, this subgroup is the whole curve, and its + * cardinal is denoted by \p N. Our code requires that \p N is an odd prime. * - * 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. + * \note For blinding, use odd in mbedtls_ecp_mul() and prime in + * mbedtls_ecdsa_sign(). * - * 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. + * For Montgomery curves, we do not store \p A, but (A + 2) / 4, 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, it must point to a function that takes an \p mbedtls_mpi in the + * range of 0..2^(2*pbits)-1, and transforms it in-place in an integer of + * little more than \p pbits, so that the integer may be efficiently brought + * in the 0..P-1 range by a few additions or substractions. + * + * \return \c 0 on success + * \return 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; /*!< the order of G */ - size_t pbits; /*!< number of bits in P */ - size_t nbits; /*!< number of bits in 1. P, or 2. private keys */ - unsigned int h; /*!< internal: 1 if the constants are static */ - 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; /*!< A prime modulus of the base field. */ + mbedtls_mpi A; /*!< \p A in the equation or (A + 2) / 4. */ + mbedtls_mpi B; /*!< \p B in the equation or unused. */ + mbedtls_ecp_point G; /*!< The generator of the (sub)group used. */ + mbedtls_mpi N; /*!< The order of \p G. */ + size_t pbits; /*!< The number of bits in \p P.*/ + size_t nbits; /*!< The number of bits in \p P, or the private + keys. */ + unsigned int h; /*!< \internal 1 if the constants are static. */ + int (*modp)(mbedtls_mpi *); /*!< The 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; /*!< The number for pre-computed points. */ } mbedtls_ecp_group; /** - * \brief ECP key pair structure + * \brief The ECP key-pair structure. * - * A generic key pair that could be used for ECDSA, fixed ECDH, etc. + * A generic key-pair that may be used for ECDSA and fixed ECDH, for example. * - * \note Members purposefully in the same order as struc mbedtls_ecdsa_context. + * \note Members are deliberately in the same order as in the + * #mbedtls_ecdsa_context structure. */ 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_group grp; /*!< The elliptic curve and base point. */ + mbedtls_mpi d; /*!< Our secret value. */ + mbedtls_ecp_point Q; /*!< Our public value. */ } mbedtls_ecp_keypair; @@ -177,15 +194,15 @@ mbedtls_ecp_keypair; * \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 N and 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 ) @@ -212,7 +229,7 @@ mbedtls_ecp_keypair; * 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) @@ -227,7 +244,7 @@ mbedtls_ecp_keypair; * * 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 */ @@ -235,25 +252,26 @@ 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. */ /** - * \brief Get the list of supported curves in order of preferrence - * (full information) + * \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. + * \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 grp_id of all supported curves + * in order of preference. * * \return A statically allocated array, * terminated with MBEDTLS_ECP_DP_NONE. @@ -261,358 +279,390 @@ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void ); 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, or NULL. */ 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, or NULL. */ 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, or NULL. */ 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 a group to something meaningless. */ 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 ); /** - * \brief Copy the contents of point Q into P + * \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 if memory allocation fails. */ 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 if memory allocation fails. */ 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 if memory allocation fails. */ 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 point is zero. + * \return \c 0 if 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 if memory allocation failed. + * \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. * - * \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 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 if initialization failed. + * \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 to export. + * \param format The export format. + * \param olen The length of 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 well-known 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 RFC-4492: Elliptic Curve Cryptography + * (ECC) Cipher Suites for Transport Layer Security (TLS), + * 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 index in the list of well-known domain parameters. * - * \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 if initialization fails. + * \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 ECParameters 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 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 if initialization fails. + * \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 privkey, + * or \p P is not a valid pubkey. + * \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 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. + * \note In contrast to mbedtls_ecp_mul(), this function does not + * guarantee a constant execution flow and timing. * - * \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 + * \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 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 + * \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 checks that a point is a valid public key + * on this curve. * - * \param grp Curve/group the point should belong to - * \param pt Point to check + * 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. * - * \return 0 if point is a valid public key, - * MBEDTLS_ERR_ECP_INVALID_KEY otherwise. + * \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(). * - * \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 curve or group the point should belong to. + * \param pt The point 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 public key. + * \return #MBEDTLS_ERR_ECP_INVALID_KEY otherwise. */ 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 otherwise. */ 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 keypair with a configurable base + * point. * - * \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 + * \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 0 if successful, - * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code - * - * \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_base( mbedtls_ecp_group *grp, const mbedtls_ecp_point *G, mbedtls_mpi *d, mbedtls_ecp_point *Q, @@ -620,57 +670,64 @@ int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp, void *p_rng ); /** - * \brief Generate a keypair + * \brief This function generates a 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 a 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 a public-private key pair. * - * \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. + * \param prv The keypair structure holding the private key. * - * \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. + * \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. */ 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 ); From f56cb34d609b9c697238c3a8f2c2096ec0b42be6 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Thu, 19 Apr 2018 12:49:10 +0100 Subject: [PATCH 2/9] Update ecp.h Updated based on review comment. One comment remains open (waiting for input) --- include/mbedtls/ecp.h | 151 +++++++++++++++++++++++------------------- 1 file changed, 84 insertions(+), 67 deletions(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index 89c756b37..c58a4b6ab 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -3,8 +3,9 @@ * * \brief This file contains ECP definitions and functions. * - * The Elliptic Curve over P (ECP) is defined in Standards for Efficient - * Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography and + * The use of Elliptic Curves over GF(P) (ECP) in cryptography and + * TLS is defined in Standards for Efficient Cryptography Group + * (SECG): SEC1 Elliptic Curve Cryptography and * RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites * for Transport Layer Security (TLS). * @@ -69,7 +70,7 @@ extern "C" { * \note Only curves over prime fields are supported. * * \warning This library does not support validation of arbitrary domain - * parameters. Therefore, only well-known domain parameters from trusted + * parameters. Therefore, only standardized domain parameters from trusted * sources should be used. See mbedtls_ecp_group_load(). */ typedef enum @@ -84,14 +85,14 @@ typedef enum 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_CURVE448, /*!< Domain parameters for a Curve448 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_SECP256K1, /*!< Domain parameters for 256-bit "Koblitz" curve. */ } mbedtls_ecp_group_id; /** - * The number of supported curves, plus one for none. + * The number of supported curves, plus one for #MBEDTLS_ECP_DP_NONE. * * \note Montgomery curves are currently excluded. */ @@ -109,13 +110,15 @@ typedef struct } mbedtls_ecp_curve_info; /** - * \brief The ECP point structure, in jacobian coordinates. + * \brief The ECP point structure, in Jacobian coordinates. * * \note All functions expect and return points satisfying - * the following condition: \p Z == 0 or \p Z == 1. Other - * values of \p Z are used only by internal functions. - * The point is zero, or "at infinity", if Z == 0. - * Otherwise, X and Y are its standard (affine) coordinates. + * the following condition: Z == 0 or + * Z == 1. Other values of \p Z are + * used only by internal functions. + * The point is zero, or "at infinity", if Z == 0. + * Otherwise, \p X and \p Y are its standard (affine) + * coordinates. */ typedef struct { @@ -129,43 +132,46 @@ mbedtls_ecp_point; * \brief The ECP group structure. * * We consider two types of curve equations: - * - * In both cases, the generator (G) for a prime-order subgroup is fixed. + *
  • Montgomery: y^2 = x^3 + A x^2 + x mod P (Curve25519, + * Curve448)
    • + * 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 - * cardinal is denoted by \p N. Our code requires that \p N is an odd prime. + * cardinality is denoted by \p N. Our code requires that \p N is an + * odd prime. * - * \note For blinding, use odd in mbedtls_ecp_mul() and prime in - * mbedtls_ecdsa_sign(). - * - * For Montgomery curves, we do not store \p A, but (A + 2) / 4, 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. + * For Montgomery curves, we do not store \p A, but (A + 2) / 4, + * 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, it must point to a function that takes an \p mbedtls_mpi in the - * range of 0..2^(2*pbits)-1, and transforms it in-place in an integer of - * little more than \p pbits, so that the integer may be efficiently brought - * in the 0..P-1 range by a few additions or substractions. + * Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the + * range of 0..2^(2*pbits)-1, 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. * * \return \c 0 on success - * \return Non-zero on failure. + * \return Non-zero error code on failure. */ typedef struct { mbedtls_ecp_group_id id; /*!< An internal group identifier. */ - mbedtls_mpi P; /*!< A prime modulus of the base field. */ - mbedtls_mpi A; /*!< \p A in the equation or (A + 2) / 4. */ - mbedtls_mpi B; /*!< \p B in the equation or unused. */ - mbedtls_ecp_point G; /*!< The generator of the (sub)group used. */ + mbedtls_mpi P; /*!< The prime modulus of the base field. */ + mbedtls_mpi A; /*!< For (1) \p A in the equation or for + (2) (A + 2) / 4. */ + mbedtls_mpi B; /*!< For (1) \p B in the equation or + for (2) 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; /*!< The number of bits in \p P, or the private - keys. */ + size_t nbits; /*!< For (1) The number of bits in \p P, or + for (2) the private keys. */ unsigned int h; /*!< \internal 1 if the constants are static. */ - int (*modp)(mbedtls_mpi *); /*!< The function for fast reduction mod P.*/ + 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. */ @@ -200,7 +206,7 @@ mbedtls_ecp_keypair; #if !defined(MBEDTLS_ECP_MAX_BITS) /** - * The 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 /**< The maximum size of groups, in bits. */ #endif @@ -262,7 +268,7 @@ mbedtls_ecp_keypair; /** * \brief This function retrieves the information defined in - * mbedtls_ecp_curve_info()for all supported curves in order + * mbedtls_ecp_curve_info() for all supported curves in order * of preference. * * \return A statically allocated array. The last entry is 0. @@ -270,8 +276,9 @@ mbedtls_ecp_keypair; const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void ); /** - * \brief This function retrieves the grp_id of all supported curves - * in order of preference. + * \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. @@ -284,7 +291,8 @@ const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void ); * * \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 ); @@ -294,7 +302,8 @@ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_gr * * \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 ); @@ -304,7 +313,8 @@ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_i * * \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 ); @@ -316,7 +326,13 @@ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name( const char *name void mbedtls_ecp_point_init( mbedtls_ecp_point *pt ); /** - * \brief This function initializes 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 ); @@ -354,7 +370,7 @@ void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key ); * \param Q The source point. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation fails. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. */ int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q ); @@ -366,7 +382,7 @@ int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q ); * \param src The source group. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation fails. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. */ int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src ); @@ -376,7 +392,7 @@ int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src * \param pt The point to set. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation fails. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. */ int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt ); @@ -385,8 +401,8 @@ int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt ); * * \param pt The point to test. * - * \return \c 1 if point is zero. - * \return \c 0 if point is non-zero. + * \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 ); @@ -452,7 +468,7 @@ int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ * * \return \c 0 on success. * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid. - * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format * is not implemented. * @@ -464,15 +480,15 @@ int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_poi * \brief This function imports a point from a TLS ECPoint record. * * \note On function return, \p buf is updated to point to immediately - * after the ECPoint. + * after the ECPoint record. * * \param grp The ECP group used. * \param pt The destination point. - * \param buf The address of the pointer to the start of input buffer. + * \param buf The address of the pointer to the start of the input buffer. * \param len The length of the buffer. * * \return \c 0 on success. - * \return An \c MBEDTLS_ERR_MPI_XXX error code if initialization failed. + * \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, @@ -484,9 +500,9 @@ int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point * \param grp The ECP group used. * \param pt The point to export. * \param format The export format. - * \param olen The length of data written. - * \param buf The Buffer to write to. - * \param blen The length of the Buffer. + * \param olen The length of the data written. + * \param buf The buffer to write to. + * \param blen The length of the buffer. * * \return \c 0 on success. * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA or @@ -497,7 +513,7 @@ int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp unsigned char *buf, size_t blen ); /** - * \brief This function sets a group using well-known domain parameters. + * \brief This function sets a group using standardized domain parameters. * * \note The index should be a value of the NamedCurve enum, * as defined in RFC-4492: Elliptic Curve Cryptography @@ -505,10 +521,10 @@ int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp * usually in the form of an \c MBEDTLS_ECP_DP_XXX macro. * * \param grp The destination group. - * \param id The index in the list of well-known domain parameters. + * \param id The identifier of the domain parameter set to load. * * \return \c 0 on success, - * \return An \c MBEDTLS_ERR_MPI_XXX error code if initialization fails. + * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure. * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups. */ @@ -517,14 +533,15 @@ int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id ); /** * \brief This function sets a group from a TLS ECParameters record. * - * \note \p buf is updated to point right after ECParameters on exit. + * \note \p buf is updated to point right after the ECParameters record + * on exit. * * \param grp The destination group. - * \param buf The address of the pointer to the start of input buffer. + * \param buf The address of the pointer to the start of the input buffer. * \param len The length of the buffer. * * \return \c 0 on success. - * \return An \c MBEDTLS_ERR_MPI_XXX error code if initialization fails. + * \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 ); @@ -567,9 +584,9 @@ int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen, * \param p_rng The RNG context. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid privkey, - * or \p P is not a valid pubkey. - * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure. + * \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, @@ -595,7 +612,7 @@ int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, * \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_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, @@ -618,11 +635,11 @@ int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, * structures. For example, mbedtls_ecdh_context() or * mbedtls_ecdsa_context(). * - * \param grp The curve or group the point should belong to. + * \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 otherwise. + * \return #MBEDTLS_ERR_ECP_INVALID_KEY on failure. */ int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt ); @@ -639,7 +656,7 @@ int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_po * \param d The integer to check. * * \return \c 0 if the point is a valid private key. - * \return #MBEDTLS_ERR_ECP_INVALID_KEY otherwise. + * \return #MBEDTLS_ERR_ECP_INVALID_KEY on failure. */ int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d ); @@ -670,7 +687,7 @@ int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp, void *p_rng ); /** - * \brief This function generates a keypair. + * \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 @@ -692,7 +709,7 @@ int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp void *p_rng ); /** - * \brief This function generates a key. + * \brief This function generates an ECP key. * * \param grp_id The ECP group identifier. * \param key The destination key. From b2e111a288811b7edd4616dda55afd680c6d4195 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Fri, 20 Apr 2018 10:13:48 +0100 Subject: [PATCH 3/9] Update ecp.h Changes based on review comments. 2 comments still open pending decisions --- include/mbedtls/ecp.h | 95 ++++++++++++++++++++++--------------------- 1 file changed, 49 insertions(+), 46 deletions(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index c58a4b6ab..050283c4a 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 Standards for Efficient Cryptography Group - * (SECG): SEC1 Elliptic Curve Cryptography and + * The use of ECP in cryptography and TLS is defined in + * Standards for Efficient Cryptography Group (SECG): SEC1 + * Elliptic Curve Cryptography and * RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites * for Transport Layer Security (TLS). * @@ -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 @@ extern "C" { #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 @@ extern "C" { 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 @@ typedef struct { 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 @@ mbedtls_ecp_point; * \brief The ECP group structure. * * We consider two types of curve equations: - *
    1. Short Weierstrass: y^2 = x^3 + A x + B mod P + *
      • Short Weierstrass: y^2 = x^3 + A x + B mod P * (SEC1 + RFC-4492)
        • *
      • Montgomery: y^2 = x^3 + A x^2 + x mod P (Curve25519, - * Curve448)
    + * Curve448) * 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 (A + 2) / 4, * 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_mpi P; /*!< The prime modulus of the base field. */ - mbedtls_mpi A; /*!< For (1) \p A in the equation or for - (2) (A + 2) / 4. */ - 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: (A + 2) / 4. */ + 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 @@ typedef struct 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 @@ 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. * * \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 @@ int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, * 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 @@ int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_po * 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 @@ int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi * * 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 @@ int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp, * \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 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 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 ); From f089fa334181d89bdd37a50b933c9568d1426e4d Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Fri, 20 Apr 2018 10:41:16 +0100 Subject: [PATCH 4/9] Update ecp.h minor spacing/comment format fixes --- include/mbedtls/ecp.h | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index 050283c4a..1a5d7d798 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -232,7 +232,6 @@ mbedtls_ecp_keypair; * 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 */ @@ -596,7 +595,7 @@ int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, /** * \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 @@ -680,7 +679,7 @@ int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi * * \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, mbedtls_mpi *d, mbedtls_ecp_point *Q, From d76ac587d3b4eb37548b032d6fd6765575ee9959 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 23 Apr 2018 06:29:34 +0100 Subject: [PATCH 5/9] Update ecp.h Changes based on review comments. Waiting for responses on 2 remaining comments --- include/mbedtls/ecp.h | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index 1a5d7d798..f7f57c073 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -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 is not available. */ +#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< The requested feature is not available, for example, . */ #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 @@ extern "C" { #endif /** - * Domain parameters: curve, subgroup, and generator. + * Domain-parameter identifiers: curve, subgroup, and generator. * * \note Only curves over prime fields are supported. * @@ -169,7 +169,8 @@ typedef struct 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 private keys. */ + 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).*/ @@ -187,7 +188,7 @@ mbedtls_ecp_group; * 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. + * ::mbedtls_ecdsa_context structure. */ typedef struct { @@ -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. * * \param grp The ECP group used. - * \param pt he point format to export to an \c MBEDTLS_ECP_PF_XXX constant. + * \param pt The 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. @@ -649,7 +650,7 @@ int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_po * * \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 + * structures, such as ::mbedtls_ecdh_context or * ::mbedtls_ecdsa_context. * * \param grp The group used. From c32efb3f641313279a5d75ff7e102ed84e32c899 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 23 Apr 2018 09:38:29 +0100 Subject: [PATCH 6/9] Update ecp.h Resolved last review comment --- include/mbedtls/ecp.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index f7f57c073..e11cdf2d8 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -499,7 +499,8 @@ 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. * * \param grp The ECP group used. - * \param pt The point format to export to an \c MBEDTLS_ECP_PF_XXX constant. + * \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. From d35340550dea413e5a7ce872561eb84c96179be3 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 23 Apr 2018 16:12:42 +0100 Subject: [PATCH 7/9] Update ecp.h fixed omittion --- include/mbedtls/ecp.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index e11cdf2d8..6924d4036 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -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 feature is not available, for example, . */ +#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. */ From a7a6155272baaae2a99a0021ac0694842eeac392 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 24 Apr 2018 13:14:01 +0100 Subject: [PATCH 8/9] Update ecp.h One fix. Removed trailing whitespaces --- include/mbedtls/ecp.h | 107 +++++++++++++++++++++--------------------- 1 file changed, 53 insertions(+), 54 deletions(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index 6924d4036..9fc650ee3 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -8,13 +8,13 @@ * Elliptic Curve Cryptography     and * RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites * for Transport Layer Security (TLS). - * + * * RFC-2409: The Internet Key Exchange (IKE) defines ECP * group types. - * + * */ -/* +/* * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved * SPDX-License-Identifier: Apache-2.0 * @@ -32,7 +32,7 @@ * * This file is part of Mbed TLS (https://tls.mbed.org) */ - + #ifndef MBEDTLS_ECP_H #define MBEDTLS_ECP_H @@ -114,10 +114,10 @@ typedef struct * * \note All functions expect and return points satisfying * the following condition: Z == 0 or - * Z == 1. Other values of \p Z are + * Z == 1. Other values of \p Z are * used only by internal functions. * The point is zero, or "at infinity", if Z == 0. - * Otherwise, \p X and \p Y are its standard (affine) + * Otherwise, \p X and \p Y are its standard (affine) * coordinates. */ typedef struct @@ -144,18 +144,17 @@ mbedtls_ecp_point; * mbedtls_ecdsa_sign() requires that it is prime for blinding purposes. * * For Montgomery curves, we do not store \p A, but (A + 2) / 4, - * which is the quantity used in the formulas. Additionally, \p nbits is + * 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 0..2^(2*pbits)-1, 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. + * 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 0..2^(2*pbits)-1, 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. * - * \return \c 0 on success - * \return Non-zero error code on failure. */ typedef struct { @@ -169,10 +168,10 @@ typedef struct 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 + 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 + 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. */ @@ -187,7 +186,7 @@ mbedtls_ecp_group; * * 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 + * \note Members are deliberately in the same order as in the * ::mbedtls_ecdsa_context structure. */ typedef struct @@ -298,7 +297,7 @@ const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void ); const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_group_id grp_id ); /** - * \brief This function retrieves curve information from a TLS + * \brief This function retrieves curve information from a TLS * NamedCurve value. * * \param tls_id An \c MBEDTLS_ECP_DP_XXX value. @@ -309,7 +308,7 @@ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_gr const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_id ); /** - * \brief This function retrieves curve information from a + * \brief This function retrieves curve information from a * human-readable name. * * \param name The human-readable name. @@ -328,7 +327,7 @@ void mbedtls_ecp_point_init( mbedtls_ecp_point *pt ); /** * \brief This function initializes an ECP group context - * without loading any domain parameters. + * without loading any domain parameters. * * \note After this function is called, domain parameters * for various ECP groups can be loaded through the @@ -364,7 +363,7 @@ void mbedtls_ecp_group_free( mbedtls_ecp_group *grp ); void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key ); /** - * \brief This function copies the contents of point \p Q into + * \brief This function copies the contents of point \p Q into * point \p P. * * \param P The destination point. @@ -376,7 +375,7 @@ void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key ); int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q ); /** - * \brief This function copies the contents of group \p src into + * \brief This function copies the contents of group \p src into * group \p dst. * * \param dst The destination group. @@ -423,7 +422,7 @@ int mbedtls_ecp_point_cmp( const mbedtls_ecp_point *P, const mbedtls_ecp_point *Q ); /** - * \brief This function imports a non-zero point from two ASCII + * \brief This function imports a non-zero point from two ASCII * strings. * * \param P The destination point. @@ -459,7 +458,7 @@ int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ * \brief This function imports a point from unsigned binary data. * * \note This function does not check that the point actually - * belongs to the given group, see mbedtls_ecp_check_pubkey() + * belongs to the given group, see mbedtls_ecp_check_pubkey() * for that. * * \param grp The group to which the point should belong. @@ -518,7 +517,7 @@ int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp * \brief This function sets a group using standardized domain parameters. * * \note The index should be a value of the NamedCurve enum, - * as defined in RFC-4492: Elliptic Curve Cryptography + * as defined in RFC-4492: Elliptic Curve Cryptography * (ECC) Cipher Suites for Transport Layer Security (TLS), * usually in the form of an \c MBEDTLS_ECP_DP_XXX macro. * @@ -528,7 +527,7 @@ int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp * \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 ); @@ -563,7 +562,7 @@ int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen, unsigned char *buf, size_t blen ); /** - * \brief This function performs multiplication of a point by + * \brief This function performs multiplication of a point by * an integer: \p R = \p m * \p P. * * It is not thread-safe to use same group in multiple threads. @@ -595,12 +594,12 @@ int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); /** - * \brief This function performs multiplication and addition of two + * \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 + * \note In contrast to mbedtls_ecp_mul(), this function does not * guarantee a constant execution flow and timing. * * \param grp The ECP group. @@ -611,8 +610,8 @@ int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, * \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 + * \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. */ @@ -621,20 +620,20 @@ int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, const mbedtls_mpi *n, const mbedtls_ecp_point *Q ); /** - * \brief This function checks that a point is a valid public key + * \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 + * 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 + * 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 + * \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. @@ -646,12 +645,12 @@ int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt ); /** - * \brief This function checks that an \p mbedtls_mpi is a valid private + * \brief This function checks that an \p mbedtls_mpi is a valid private * 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 + * \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 group used. @@ -663,12 +662,12 @@ int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_po int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d ); /** - * \brief This function generates a keypair with a configurable base + * \brief This function generates a keypair with a configurable base * 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 + * \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. @@ -691,9 +690,9 @@ int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp, /** * \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 + * \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. @@ -726,7 +725,7 @@ 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 This function checks that the keypair objects + * \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. @@ -735,9 +734,9 @@ int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key, * If it contains a private key, that part is ignored. * \param prv The keypair structure holding the full keypair. * - * \return \c 0 on success, meaning that the keys are valid and match. + * \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 + * \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 ); From 3dd8abd037f9b5a0a7b543fc38e18d0f349b0a42 Mon Sep 17 00:00:00 2001 From: Jaeden Amero Date: Tue, 24 Apr 2018 10:56:55 +0100 Subject: [PATCH 9/9] Regenerate errors after ecp.h updates The error descriptions were updated in ecp.h (PR #1578), so also update the strings in error.c. --- library/error.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/library/error.c b/library/error.c index 96ab20376..222d85b62 100644 --- a/library/error.c +++ b/library/error.c @@ -256,19 +256,19 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen ) if( use_ret == -(MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL) ) mbedtls_snprintf( buf, buflen, "ECP - The buffer is too small to write to" ); if( use_ret == -(MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE) ) - mbedtls_snprintf( buf, buflen, "ECP - Requested curve not available" ); + mbedtls_snprintf( buf, buflen, "ECP - The requested feature is not available, for example, the requested curve is not supported" ); if( use_ret == -(MBEDTLS_ERR_ECP_VERIFY_FAILED) ) mbedtls_snprintf( buf, buflen, "ECP - The signature is not valid" ); if( use_ret == -(MBEDTLS_ERR_ECP_ALLOC_FAILED) ) mbedtls_snprintf( buf, buflen, "ECP - Memory allocation failed" ); if( use_ret == -(MBEDTLS_ERR_ECP_RANDOM_FAILED) ) - mbedtls_snprintf( buf, buflen, "ECP - Generation of random value, such as (ephemeral) key, failed" ); + mbedtls_snprintf( buf, buflen, "ECP - Generation of random value, such as ephemeral key, failed" ); if( use_ret == -(MBEDTLS_ERR_ECP_INVALID_KEY) ) mbedtls_snprintf( buf, buflen, "ECP - Invalid private or public key" ); if( use_ret == -(MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH) ) mbedtls_snprintf( buf, buflen, "ECP - The buffer contains a valid signature followed by more data" ); if( use_ret == -(MBEDTLS_ERR_ECP_HW_ACCEL_FAILED) ) - mbedtls_snprintf( buf, buflen, "ECP - ECP hardware accelerator failed" ); + mbedtls_snprintf( buf, buflen, "ECP - The ECP hardware accelerator failed" ); #endif /* MBEDTLS_ECP_C */ #if defined(MBEDTLS_MD_C)