From 9deb54900eb5d9f21724f9f016bba1b87e7f143c Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 18 Dec 2023 21:01:18 +0100 Subject: [PATCH 1/3] Document the domain_parameters_size==SIZE_MAX hack It was introduced in https://github.com/Mbed-TLS/mbedtls/pull/8616 but not documented. Signed-off-by: Gilles Peskine --- include/psa/crypto_struct.h | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/include/psa/crypto_struct.h b/include/psa/crypto_struct.h index 5639ad05d4..1eb2463cee 100644 --- a/include/psa/crypto_struct.h +++ b/include/psa/crypto_struct.h @@ -254,6 +254,18 @@ struct psa_key_attributes_s { #if defined(MBEDTLS_PSA_CRYPTO_SE_C) psa_key_slot_number_t MBEDTLS_PRIVATE(slot_number); #endif /* MBEDTLS_PSA_CRYPTO_SE_C */ + /* Unlike normal buffers, there are three cases for domain_parameters + * and domain_parameters_size: + * - domain_parameters_size == SIZE_MAX && domain_parameters == NULL: + * Access to domain parameters is not supported for this key. + * This is a hack which should not exist, intended for keys managed + * by a driver that doesn't support domain parameters. + * - domain_parameters_size == 0 && domain_parameters == NULL: + * The domain parameters are empty. + * - domain_parameters_size > 0 && + * domain_parameters == valid pointer to domain_parameters_size bytes: + * The domain parameters are non-empty. + */ void *MBEDTLS_PRIVATE(domain_parameters); size_t MBEDTLS_PRIVATE(domain_parameters_size); }; From 5ad95393636cf06627eecef9effd397f9e39e376 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 19 Dec 2023 12:22:46 +0100 Subject: [PATCH 2/3] Remove DSA and DH domain parameters from the documentation Mbed TLS doesn't support DSA at all, and doesn't support domain parameters for FFDH (only predefined groups). Signed-off-by: Gilles Peskine --- include/psa/crypto_extra.h | 27 +-------------------------- 1 file changed, 1 insertion(+), 26 deletions(-) diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h index f7207a1be2..f39d1eb0be 100644 --- a/include/psa/crypto_extra.h +++ b/include/psa/crypto_extra.h @@ -428,6 +428,7 @@ psa_status_t mbedtls_psa_inject_entropy(const uint8_t *seed, * of psa_set_key_type() when you need to specify domain parameters. * * The format for the required domain parameters varies based on the key type. + * Mbed TLS supports the following key type with domain parameters: * * - For RSA keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY or #PSA_KEY_TYPE_RSA_KEY_PAIR), * the domain parameter data consists of the public exponent, @@ -437,32 +438,6 @@ psa_status_t mbedtls_psa_inject_entropy(const uint8_t *seed, * key data and the exponent recorded in the attribute structure is ignored. * As an exception, the public exponent 65537 is represented by an empty * byte string. - * - For DSA keys (#PSA_KEY_TYPE_DSA_PUBLIC_KEY or #PSA_KEY_TYPE_DSA_KEY_PAIR), - * the `Dss-Params` format as defined by RFC 3279 §2.3.2. - * ``` - * Dss-Params ::= SEQUENCE { - * p INTEGER, - * q INTEGER, - * g INTEGER - * } - * ``` - * - For Diffie-Hellman key exchange keys - * (#PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_FAMILY_CUSTOM) or - * #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_FAMILY_CUSTOM)), the - * `DomainParameters` format as defined by RFC 3279 §2.3.3. - * ``` - * DomainParameters ::= SEQUENCE { - * p INTEGER, -- odd prime, p=jq +1 - * g INTEGER, -- generator, g - * q INTEGER, -- factor of p-1 - * j INTEGER OPTIONAL, -- subgroup factor - * validationParams ValidationParams OPTIONAL - * } - * ValidationParams ::= SEQUENCE { - * seed BIT STRING, - * pgenCounter INTEGER - * } - * ``` * * \note This function may allocate memory or other resources. * Once you have called this function on an attribute structure, From 1a9e05bf080e9ce770fd56ba88c25c52b4c38498 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 19 Dec 2023 12:23:22 +0100 Subject: [PATCH 3/3] Note that domain parameters are not supported with drivers Signed-off-by: Gilles Peskine --- include/psa/crypto_extra.h | 8 ++++++++ include/psa/crypto_struct.h | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h index f39d1eb0be..f132f7ed99 100644 --- a/include/psa/crypto_extra.h +++ b/include/psa/crypto_extra.h @@ -446,6 +446,9 @@ psa_status_t mbedtls_psa_inject_entropy(const uint8_t *seed, * \note This is an experimental extension to the interface. It may change * in future versions of the library. * + * \note Due to an implementation limitation, domain parameters are ignored + * for keys that are managed by a driver. + * * \param[in,out] attributes Attribute structure where the specified domain * parameters will be stored. * If this function fails, the content of @@ -476,6 +479,9 @@ psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes, * \note This is an experimental extension to the interface. It may change * in future versions of the library. * + * \note Due to an implementation limitation, domain parameters are not + * supported with keys that are managed by a driver. + * * \param[in] attributes The key attribute structure to query. * \param[out] data On success, the key domain parameters. * \param data_size Size of the \p data buffer in bytes. @@ -488,6 +494,8 @@ psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes, * * \retval #PSA_SUCCESS \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL \emptydescription + * \retval #PSA_ERROR_NOT_SUPPORTED + * The key is managed by a driver. */ psa_status_t psa_get_key_domain_parameters( const psa_key_attributes_t *attributes, diff --git a/include/psa/crypto_struct.h b/include/psa/crypto_struct.h index 1eb2463cee..5e52ffde06 100644 --- a/include/psa/crypto_struct.h +++ b/include/psa/crypto_struct.h @@ -259,7 +259,7 @@ struct psa_key_attributes_s { * - domain_parameters_size == SIZE_MAX && domain_parameters == NULL: * Access to domain parameters is not supported for this key. * This is a hack which should not exist, intended for keys managed - * by a driver that doesn't support domain parameters. + * by a driver, because drivers don't support domain parameters. * - domain_parameters_size == 0 && domain_parameters == NULL: * The domain parameters are empty. * - domain_parameters_size > 0 &&