From 153ae464db633edd427339cbbcf529626b40d46d Mon Sep 17 00:00:00 2001 From: Chien Wong Date: Tue, 31 Jan 2023 23:27:03 +0800 Subject: [PATCH 1/3] 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]); From aa9a15833e713f66da53c2a857082697b1a7eddc Mon Sep 17 00:00:00 2001 From: Chien Wong Date: Wed, 9 Aug 2023 12:33:40 +0800 Subject: [PATCH 2/3] Fix doc Signed-off-by: Chien Wong --- include/mbedtls/ecp.h | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index cd7fd26e2..a89d4d23c 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -196,21 +196,25 @@ 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: + * case you need to load \p A by yourself when using domain parameters directly, + * for example: * \code + * mbedtls_mpi_init(&A); * 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); + * CHECK_RETURN(mbedtls_mpi_sub_int(&A, &grp.P, 3)); + * } else { + * CHECK_RETURN(mbedtls_mpi_copy(&A, &grp.A)); * } * - * access_grp_A_etc(&grp); + * do_something_with_a(&A); * * cleanup: - * mbedtls_mpi_free(&grp.A); + * mbedtls_mpi_free(&A); * mbedtls_ecp_group_free(&grp); * \endcode * @@ -242,9 +246,9 @@ typedef struct mbedtls_ecp_group { mbedtls_mpi P; /*!< The prime modulus of the base field. */ 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. */ + Refer to detailed description of ::mbedtls_ecp_group if + using domain parameters in the structure. + 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. */ From a559c05a5b55033bab3267d577f388268a0e7729 Mon Sep 17 00:00:00 2001 From: Chien Wong Date: Wed, 9 Aug 2023 21:49:58 +0800 Subject: [PATCH 3/3] Add changelog Signed-off-by: Chien Wong --- .../improve-doc-on-ecp-curve-optimized-representation.txt | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 ChangeLog.d/improve-doc-on-ecp-curve-optimized-representation.txt diff --git a/ChangeLog.d/improve-doc-on-ecp-curve-optimized-representation.txt b/ChangeLog.d/improve-doc-on-ecp-curve-optimized-representation.txt new file mode 100644 index 000000000..8fdc588b1 --- /dev/null +++ b/ChangeLog.d/improve-doc-on-ecp-curve-optimized-representation.txt @@ -0,0 +1,3 @@ +Features + * The documentation of mbedtls_ecp_group now describes the optimized + representation of A for some curves. Fixes #8045.