Clarified the constraints on key derivation output and verification functions

doc/crypto/api/ops/key-derivation.rst

@@ -758,7 +758,10 @@ Key derivation functions
     .. retval:: PSA_ERROR_INVALID_HANDLE
         ``key`` is not a valid key identifier.
     .. retval:: PSA_ERROR_NOT_PERMITTED
-        The key has neither the `PSA_KEY_USAGE_DERIVE` nor the `PSA_KEY_USAGE_VERIFY_DERIVATION` usage flag, or it does not permit the operation's algorithm.
+        The following conditions can result in this error:
+
+        *   The key has neither the `PSA_KEY_USAGE_DERIVE` nor the `PSA_KEY_USAGE_VERIFY_DERIVATION` usage flag.
+        *   The key does not permit the operation's algorithm.
     .. retval:: PSA_ERROR_INVALID_ARGUMENT
         The following conditions can result in this error:
 
@@ -790,10 +793,10 @@ Key derivation functions
     .. note::
         Once all inputs steps are completed, the following operations are permitted:
 
-        *   `psa_key_derivation_output_bytes()` --- if each input was either a direct input or a key with usage flag `PSA_KEY_USAGE_DERIVE`.
+        *   `psa_key_derivation_output_bytes()` --- if each input was either a direct input, or a key with usage flag `PSA_KEY_USAGE_DERIVE`.
         *   `psa_key_derivation_output_key()` or `psa_key_derivation_output_key_custom()` --- if the input for step `PSA_KEY_DERIVATION_INPUT_SECRET` or `PSA_KEY_DERIVATION_INPUT_PASSWORD` was a key with usage flag `PSA_KEY_USAGE_DERIVE`, and every other input was either a direct input or a key with usage flag `PSA_KEY_USAGE_DERIVE`.
-        *   `psa_key_derivation_verify_bytes()` --- if each input was either a direct input, a key with usage flag `PSA_KEY_USAGE_DERIVE`, or a key with usage flag `PSA_KEY_USAGE_VERIFY_DERIVATION`.
-        *   `psa_key_derivation_verify_key()` --- under the same conditions as `psa_key_derivation_verify_bytes()`.
+        *   `psa_key_derivation_verify_bytes()`
+        *   `psa_key_derivation_verify_key()`
 
     If this function returns an error status, the operation enters an error state and must be aborted by calling `psa_key_derivation_abort()`.
 
@@ -903,7 +906,7 @@ Key derivation functions
     .. retval:: PSA_ERROR_NOT_PERMITTED
         The following conditions can result in this error:
 
-        *   The `PSA_KEY_DERIVATION_INPUT_SECRET` input step was neither provided through a key, nor the result of a key agreement.
+        *   A `PSA_KEY_DERIVATION_INPUT_SECRET` or `PSA_KEY_DERIVATION_INPUT_PASSWORD` input step was neither provided through a key, nor the result of a key agreement.
         *   One of the inputs was a key whose policy did not permit `PSA_KEY_USAGE_DERIVE`.
         *   The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy.
     .. retval:: PSA_ERROR_BAD_STATE
@@ -933,7 +936,7 @@ Key derivation functions
 
         Permitting implementation defined methods for algorithms not specified in the |API| permits implementations to use other appropriate procedures in cases where interoperability with other implementations is not required.
 
-    For algorithms that take an input step `PSA_KEY_DERIVATION_INPUT_SECRET`, the input to that step must be provided with `psa_key_derivation_input_key()`. Future versions of this specification might include additional restrictions on the derived key based on the attributes and strength of the secret key.
+    For algorithms that take a `PSA_KEY_DERIVATION_INPUT_SECRET` or `PSA_KEY_DERIVATION_INPUT_PASSWORD` input step, the input to that step must be provided with `psa_key_derivation_input_key()`. Future versions of this specification might include additional restrictions on the derived key based on the attributes and strength of the secret key.
 
      .. note::
 
@@ -1014,7 +1017,7 @@ Key derivation functions
     .. retval:: PSA_ERROR_NOT_PERMITTED
         The following conditions can result in this error:
 
-        *   The `PSA_KEY_DERIVATION_INPUT_SECRET` input step was neither provided through a key, nor the result of a key agreement.
+        *   A `PSA_KEY_DERIVATION_INPUT_SECRET` or `PSA_KEY_DERIVATION_INPUT_PASSWORD` input step was neither provided through a key, nor the result of a key agreement.
         *   One of the inputs was a key whose policy did not permit `PSA_KEY_USAGE_DERIVE`.
         *   The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy.
     .. retval:: PSA_ERROR_BAD_STATE
@@ -1030,10 +1033,13 @@ Key derivation functions
     .. retval:: PSA_ERROR_DATA_CORRUPT
     .. retval:: PSA_ERROR_DATA_INVALID
 
-    Use this function to provide explicit production parameters when deriving a key.
-    See the description of `psa_key_derivation_output_key()` for the operation of this function with the default production parameters.
+    This function calculates output bytes from a key derivation algorithm and uses those bytes to generate a key deterministically. The key's location, policy, type and size are taken from ``attributes``.
+
+    This function operates in a similar way to `psa_key_derivation_output_key()`, but enables explicit production parameters to be provided when deriving a key.
+    For example, the production parameters can be used to select an alternative key derivation process, or configure additional key parameters.
+    See `psa_key_derivation_output_key()` for the operation of this function with the default production parameters.
 
-    See the documentation of `psa_custom_key_parameters_t` for a list of non-default production parameters. See the key type definitions in :secref:`key-types` for details of the custom production parameters used for key derivation.
+    See `psa_custom_key_parameters_t` for a list of non-default production parameters. See the key type definitions in :secref:`key-types` for details of the custom production parameters used for key derivation.
 
 .. function:: psa_key_derivation_verify_bytes
 
@@ -1051,8 +1057,6 @@ Key derivation functions
     .. retval:: PSA_SUCCESS
         Success.
         The output of the key derivation operation matches ``expected_output``.
-    .. retval:: PSA_ERROR_NOT_PERMITTED
-        One of the inputs is a key whose policy permits neither `PSA_KEY_USAGE_DERIVE` nor `PSA_KEY_USAGE_VERIFY_DERIVATION`.
     .. retval:: PSA_ERROR_INVALID_SIGNATURE
         The output of the key derivation operation does not match the value in ``expected_output``.
     .. retval:: PSA_ERROR_INSUFFICIENT_DATA
@@ -1090,7 +1094,7 @@ Key derivation functions
             if (memcmp(expected_output, tmp, output_length) != 0)
                 return PSA_ERROR_INVALID_SIGNATURE;
 
-        However, calling `psa_key_derivation_verify_bytes()` works even if the key's policy does not permit output of the bytes.
+        However, calling `psa_key_derivation_verify_bytes()` works even if an input key's policy does not include `PSA_KEY_USAGE_DERIVE`.
 
     .. admonition:: Implementation note
 
@@ -1118,10 +1122,7 @@ Key derivation functions
     .. retval:: PSA_ERROR_INVALID_ARGUMENT
         The key type is not `PSA_KEY_TYPE_PASSWORD_HASH`.
     .. retval:: PSA_ERROR_NOT_PERMITTED
-        The following conditions can result in this error:
-
-        *   The ``expected`` key does not have the `PSA_KEY_USAGE_VERIFY_DERIVATION` flag, or it does not permit the requested algorithm.
-        *   One of the inputs is a key whose policy permits neither `PSA_KEY_USAGE_DERIVE` nor `PSA_KEY_USAGE_VERIFY_DERIVATION`.
+        The ``expected`` key does not have the `PSA_KEY_USAGE_VERIFY_DERIVATION` flag, or it does not permit the requested algorithm.
     .. retval:: PSA_ERROR_INVALID_SIGNATURE
         The output of the key derivation operation does not match the value of the ``expected`` key.
     .. retval:: PSA_ERROR_INSUFFICIENT_DATA
@@ -1138,7 +1139,6 @@ Key derivation functions
         *   The operation state is not valid: it must be active, with all required input steps complete.
         *   The library requires initializing by a call to `psa_crypto_init()`.
 
-
     This function calculates output bytes from a key derivation algorithm and compares those bytes to an expected value, provided as key of type `PSA_KEY_TYPE_PASSWORD_HASH`.
     If the key derivation's output is viewed as a stream of bytes, this function destructively reads the number of bytes corresponding to the length of the ``expected`` key from the stream before comparing them with the key value.
     The operation's capacity decreases by the number of bytes read.

doc/crypto/appendix/history.rst

@@ -38,6 +38,9 @@ Clarifications and fixes
 
 *   Clarified the documentation of key attributes in key creation functions.
 
+*   Clarified the constraint on `psa_key_derivation_output_key()` for algorithms that have a `PSA_KEY_DERIVATION_INPUT_PASSWORD` input step.
+*   Removed the redundant key input constraints on `psa_key_derivation_verify_bytes()` and `psa_key_derivation_verify_key()`. These match the policy already checked in `psa_key_derivation_input_key()`.
+
 Other changes
 ~~~~~~~~~~~~~