diff --git a/doc/crypto/api/ops/key-derivation.rst b/doc/crypto/api/ops/key-derivation.rst index 6c17a626..5311ccb9 100644 --- a/doc/crypto/api/ops/key-derivation.rst +++ b/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. diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index 772524bf..2f0205de 100644 --- a/doc/crypto/appendix/history.rst +++ b/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 ~~~~~~~~~~~~~