From 7ef8a8d0dac58f6a5df44dfa2e71e085177c471a Mon Sep 17 00:00:00 2001 From: Valerio Setti Date: Tue, 23 May 2023 18:39:54 +0200 Subject: [PATCH] pk: improve description for the new priv_id field Signed-off-by: Valerio Setti --- include/mbedtls/pk.h | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h index ffd1b73b2..ec99c8413 100644 --- a/include/mbedtls/pk.h +++ b/include/mbedtls/pk.h @@ -262,11 +262,24 @@ typedef struct mbedtls_pk_info_t mbedtls_pk_info_t; typedef struct mbedtls_pk_context { const mbedtls_pk_info_t *MBEDTLS_PRIVATE(pk_info); /**< Public key information */ void *MBEDTLS_PRIVATE(pk_ctx); /**< Underlying public key context */ - /* When MBEDTLS_PSA_CRYPTO_C is enabled then the following priv_id field is - * used to store the ID of the opaque key. - * This priv_id is guarded by MBEDTLS_PSA_CRYPTO_C and not by - * MBEDTLS_USE_PSA_CRYPTO because it can be used also in mbedtls_pk_sign_ext - * for RSA keys. */ + /* The following field is used to store the ID of a private key in the + * following cases: + * - opaque key when MBEDTLS_PSA_CRYPTO_C is defined + * - normal key when MBEDTLS_PK_USE_PSA_EC_DATA is defined. In this case: + * - the pk_ctx above is not not used to store the private key anymore. + * Actually that field not populated at all in this case because also + * the public key will be stored in raw format as explained below + * - this ID is used for all private key operations (ex: sign, check + * key pair, key write, etc) using PSA functions + * + * Note: this private key storing solution only affects EC keys, not the + * other ones. The latters still use the pk_ctx to store their own + * context. + * + * Note: this priv_id is guarded by MBEDTLS_PSA_CRYPTO_C and not by + * MBEDTLS_PK_USE_PSA_EC_DATA (as the public counterpart below) because, + * when working with opaque keys, it can be used also in + * mbedtls_pk_sign_ext for RSA keys. */ #if defined(MBEDTLS_PSA_CRYPTO_C) mbedtls_svc_key_id_t MBEDTLS_PRIVATE(priv_id); /**< Key ID for opaque keys */ #endif /* MBEDTLS_PSA_CRYPTO_C */ @@ -277,8 +290,7 @@ typedef struct mbedtls_pk_context { * * When MBEDTLS_PK_USE_PSA_EC_DATA is enabled: * - the pk_ctx above is not used anymore for storing the public key - * inside the ecp_keypair structure (only the private part, but also this - * one is going to change in the future) + * inside the ecp_keypair structure * - the following fields are used for all public key operations: signature * verify, key pair check and key write. * Of course, when MBEDTLS_PK_USE_PSA_EC_DATA is not enabled, the legacy