Merge pull request #8644 from gilles-peskine-arm/domain_parameters_document_size_hack
Document the domain_parameters_size==SIZE_MAX hack
diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index f7207a1..f132f7e 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -428,6 +428,7 @@
* 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 @@
* 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,
@@ -471,6 +446,9 @@
* \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
@@ -501,6 +479,9 @@
* \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.
@@ -513,6 +494,8 @@
*
* \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 5639ad0..5e52ffd 100644
--- a/include/psa/crypto_struct.h
+++ b/include/psa/crypto_struct.h
@@ -254,6 +254,18 @@
#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, because drivers don'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);
};