Merge pull request #8644 from gilles-peskine-arm/domain_parameters_document_size_hack

Document the domain_parameters_size==SIZE_MAX hack

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,
@@ -471,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
@@ -501,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.
@@ -513,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,

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, 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);
 };