From 78f79d323d1d286587f72cb01d4cafdd35139494 Mon Sep 17 00:00:00 2001 From: Valerio Setti Date: Tue, 7 Feb 2023 08:33:26 +0100 Subject: [PATCH] ecp: add documentation for compressed points limitations Signed-off-by: Valerio Setti --- include/mbedtls/ecp.h | 22 ++++++++++++++++++---- include/mbedtls/pk.h | 3 +++ 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index 18b37a947..7a28a1957 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -419,11 +419,22 @@ typedef struct mbedtls_ecp_keypair { } mbedtls_ecp_keypair; -/* - * Point formats, from RFC 4492's enum ECPointFormat +/** + * The uncompressed point format for Short Weierstrass curves + * (MBEDTLS_ECP_DP_SECP_XXX and MBEDTLS_ECP_DP_BP_XXX). */ -#define MBEDTLS_ECP_PF_UNCOMPRESSED 0 /**< Uncompressed point format. */ -#define MBEDTLS_ECP_PF_COMPRESSED 1 /**< Compressed point format. */ +#define MBEDTLS_ECP_PF_UNCOMPRESSED 0 +/** + * The compressed point format for Short Weierstrass curves + * (MBEDTLS_ECP_DP_SECP_XXX and MBEDTLS_ECP_DP_BP_XXX). + * + * \warning While this format is supported for all concerned curves for + * writing, when it comes to parsing, it is not supported for all + * curves. Specifically, parsing compressed points on + * MBEDTLS_ECP_DP_SECP224R1 and MBEDTLS_ECP_DP_SECP224K1 is not + * supported. + */ +#define MBEDTLS_ECP_PF_COMPRESSED 1 /* * Some other constants from RFC 4492 @@ -752,6 +763,9 @@ int mbedtls_ecp_point_write_binary(const mbedtls_ecp_group *grp, * belongs to the given group, see mbedtls_ecp_check_pubkey() * for that. * + * \note For compressed points, see #MBEDTLS_ECP_PF_COMPRESSED for + * limitations. + * * \param grp The group to which the point should belong. * This must be initialized and have group parameters * set, for example through mbedtls_ecp_group_load(). diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h index 0392bd48e..e66a9f81f 100644 --- a/include/mbedtls/pk.h +++ b/include/mbedtls/pk.h @@ -804,6 +804,9 @@ int mbedtls_pk_parse_key(mbedtls_pk_context *ctx, * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a * specific key type, check the result with mbedtls_pk_can_do(). * + * \note For compressed points, see #MBEDTLS_ECP_PF_COMPRESSED for + * limitations. + * * \note The key is also checked for correctness. * * \return 0 if successful, or a specific PK or PEM error code