From 153ae464db633edd427339cbbcf529626b40d46d Mon Sep 17 00:00:00 2001 From: Chien Wong Date: Tue, 31 Jan 2023 23:27:03 +0800 Subject: [PATCH] Improve doc on special use of A in ecp group structure Signed-off-by: Chien Wong --- include/mbedtls/ecp.h | 44 +++++++++++++++++++++++++++++++++++++++++-- library/ecp.c | 4 ++-- 2 files changed, 44 insertions(+), 4 deletions(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index 0e678a3eb..cd7fd26e2 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -196,6 +196,23 @@ mbedtls_ecp_point; * cardinality is denoted by \p N. Our code requires that \p N is an * odd prime as mbedtls_ecp_mul() requires an odd number, and * mbedtls_ecdsa_sign() requires that it is prime for blinding purposes. + * The default implementation only initializes \p A without setting it to the + * authentic value for curves with A = -3(SECP256R1, etc), in which + * case you need to load and free \p A by yourself when using domain parameters + * directly, for example: + * \code + * mbedtls_ecp_group_init(&grp); + * CHECK_RETURN(mbedtls_ecp_group_load(&grp, grp_id)); + * if (mbedtls_ecp_group_a_is_minus_3(&grp)) { + * CHECK_RETURN(mbedtls_mpi_sub_int(&grp.A, &grp.P, 3); + * } + * + * access_grp_A_etc(&grp); + * + * cleanup: + * mbedtls_mpi_free(&grp.A); + * mbedtls_ecp_group_free(&grp); + * \endcode * * 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 @@ -223,8 +240,11 @@ mbedtls_ecp_point; typedef struct mbedtls_ecp_group { mbedtls_ecp_group_id id; /*!< An internal group identifier. */ mbedtls_mpi P; /*!< The prime modulus of the base field. */ - mbedtls_mpi A; /*!< For Short Weierstrass: \p A in the equation. For - Montgomery curves: (A + 2) / 4. */ + mbedtls_mpi A; /*!< For Short Weierstrass: \p A in the equation. Note that + \p A is not set to the authentic value in some cases. + For Montgomery curves: (A + 2) / 4. + Refer to detailed description of mbedtls_ecp_group if + using domain parameters in the structure. */ 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. */ @@ -991,6 +1011,26 @@ int mbedtls_ecp_mul_restartable(mbedtls_ecp_group *grp, mbedtls_ecp_point *R, mbedtls_ecp_restart_ctx *rs_ctx); #if defined(MBEDTLS_ECP_SHORT_WEIERSTRASS_ENABLED) +/** + * \brief This function checks if domain parameter A of the curve is + * \c -3. + * + * \note This function is only defined for short Weierstrass curves. + * It may not be included in builds without any short + * Weierstrass curve. + * + * \param grp The ECP group to use. + * This must be initialized and have group parameters + * set, for example through mbedtls_ecp_group_load(). + * + * \return \c 1 if A = -3. + * \return \c 0 Otherwise. + */ +static inline int mbedtls_ecp_group_a_is_minus_3(const mbedtls_ecp_group *grp) +{ + return grp->A.MBEDTLS_PRIVATE(p) == NULL; +} + /** * \brief This function performs multiplication and addition of two * points by integers: \p R = \p m * \p P + \p n * \p Q diff --git a/library/ecp.c b/library/ecp.c index 870773c13..f9b6672e9 100644 --- a/library/ecp.c +++ b/library/ecp.c @@ -1255,7 +1255,7 @@ static int ecp_sw_rhs(const mbedtls_ecp_group *grp, MPI_ECP_SQR(rhs, X); /* Special case for A = -3 */ - if (grp->A.p == NULL) { + if (mbedtls_ecp_group_a_is_minus_3(grp)) { MPI_ECP_SUB_INT(rhs, rhs, 3); } else { MPI_ECP_ADD(rhs, rhs, &grp->A); @@ -1526,7 +1526,7 @@ static int ecp_double_jac(const mbedtls_ecp_group *grp, mbedtls_ecp_point *R, int ret = MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED; /* Special case for A = -3 */ - if (grp->A.p == NULL) { + if (mbedtls_ecp_group_a_is_minus_3(grp)) { /* tmp[0] <- M = 3(X + Z^2)(X - Z^2) */ MPI_ECP_SQR(&tmp[1], &P->Z); MPI_ECP_ADD(&tmp[2], &P->X, &tmp[1]);