From eca07140f3c160eba07cf63c34c1d2495c925b40 Mon Sep 17 00:00:00 2001 From: Valerio Setti Date: Thu, 4 Jan 2024 13:17:31 +0100 Subject: [PATCH] psa_util: update documentation of EC conversion functions Signed-off-by: Valerio Setti --- include/mbedtls/psa_util.h | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/include/mbedtls/psa_util.h b/include/mbedtls/psa_util.h index cfb4bce58c..d0d95ae19a 100644 --- a/include/mbedtls/psa_util.h +++ b/include/mbedtls/psa_util.h @@ -112,11 +112,16 @@ extern mbedtls_psa_drbg_context_t *const mbedtls_psa_random_state; * * \param grpid An Mbed TLS elliptic curve identifier * (`MBEDTLS_ECP_DP_xxx`). - * \param[out] bits On success, the bit size of the curve. + * \param[out] bits On success the bit size of the curve; 0 on failure. * - * \return The corresponding PSA elliptic curve identifier + * \return On success the corresponding PSA elliptic curve identifier * (`PSA_ECC_FAMILY_xxx`). - * \return \c 0 on failure (\p grpid is not recognized). + * \return \c 0 if \p grpid is not supported. + * + * \note A successful conversion means that the curve is supported + * in PSA. Legacy support (`mbedtls_ecp_xxx`) is only + * enabled if the curve is builtin (see + * `config_adjust_legacy_from_psa.h` for details). */ psa_ecc_family_t mbedtls_ecc_group_to_psa(mbedtls_ecp_group_id grpid, size_t *bits); @@ -127,10 +132,23 @@ psa_ecc_family_t mbedtls_ecc_group_to_psa(mbedtls_ecp_group_id grpid, * (`PSA_ECC_FAMILY_xxx`). * \param bits The bit-length of a private key on \p curve. * - * \return The corresponding Mbed TLS elliptic curve identifier - * (`MBEDTLS_ECP_DP_xxx`). + * \return On success the corresponding Mbed TLS elliptic curve + * identifier (`MBEDTLS_ECP_DP_xxx`). * \return #MBEDTLS_ECP_DP_NONE if the combination of \c curve - * and \p bits is not recognized. + * and \p bits is not supported or invalid: + * - not supported means that the proper `PSA_WANT_ECC_xxx` + * symbol is not enabled for the requested curve. + * - invalid if `PSA_WANT_ECC_xxx` is enabled, but the + * combination of \p curve and \p bits are not correct + * for that curve. + * \return #MBEDTLS_ECP_DP_NONE for secp224k1 curve, no matter + * what the status of `PSA_WANT_ECC_SECP_K1_224` is, because + * this curve is not and will not be supported in PSA (#3541). + * + * \note A successful conversion means that the curve is supported + * in PSA. Legacy support (`mbedtls_ecp_xxx`) is only + * enabled if the curve is builtin (see + * `config_adjust_legacy_from_psa.h` for details). */ mbedtls_ecp_group_id mbedtls_ecc_group_from_psa(psa_ecc_family_t curve, size_t bits);