psa_util: update documentation of EC conversion functions
Signed-off-by: Valerio Setti <valerio.setti@nordicsemi.no>
diff --git a/include/mbedtls/psa_util.h b/include/mbedtls/psa_util.h
index cfb4bce..d0d95ae 100644
--- a/include/mbedtls/psa_util.h
+++ b/include/mbedtls/psa_util.h
@@ -112,11 +112,16 @@
*
* \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_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);