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.
diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h
index 0e678a3eb..a89d4d23c 100644
--- a/include/mbedtls/ecp.h
+++ b/include/mbedtls/ecp.h
@@ -197,6 +197,27 @@ mbedtls_ecp_point;
* 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 \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(&A, &grp.P, 3));
+ * } else {
+ * CHECK_RETURN(mbedtls_mpi_copy(&A, &grp.A));
+ * }
+ *
+ * do_something_with_a(&A);
+ *
+ * cleanup:
+ * mbedtls_mpi_free(&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
* not the size of \p N but the required size for private keys.
@@ -223,8 +244,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.
+ 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. */
@@ -991,6 +1015,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]);