Fixes for PBKDF2 documentation

Fix typos in the PBKDF2 documentation

Correct the constraints on PSA_KEY_USAGE_DERIVE and PSA_KEY_USAGE_VERIFY_DERIVATION, aligning them with the note against psa_key_derivation_input_key(). All key inputs must have the required usage flag to permit output or verification.

Correct the constraints on PSA_KEY_DERIVATION_INPUT_SECRET and PSA_KEY_DERIVATION_INPUT_PASSWORD, aligning them with 4feb611. psa_key_derivation_verify_key() does not require the secret/password input to be a key.

Signed-off-by: Andrew Thoelke <andrew.thoelke@arm.com>

include/psa/crypto.h

@@ -3805,7 +3805,7 @@ psa_status_t psa_key_derivation_output_key(
  * This function calculates output bytes from a key derivation algorithm and
  * compares those bytes to an expected value in constant time.
  * If you view the key derivation's output as a stream of bytes, this
- * function destructively reads the requested number of bytes from the
+ * function destructively reads the expected number of bytes from the
  * stream before comparing them.
  * The operation's capacity decreases by the number of bytes read.
  *
@@ -3824,13 +3824,13 @@ psa_status_t psa_key_derivation_output_key(
  * psa_key_derivation_abort().
  *
  * \param[in,out] operation The key derivation operation object to read from.
- * \param[in] expected_output Buffer where the output will be written.
+ * \param[in] expected_output Buffer containing the expected derivation output.
  * \param output_length     Length ot the expected output; this is also the
  *                          number of bytes that will be read.
  *
  * \retval #PSA_SUCCESS
  * \retval #PSA_ERROR_INVALID_SIGNATURE
- *         The output was read successfully, but if differs from the expected
+ *         The output was read successfully, but it differs from the expected
  *         output.
  * \retval #PSA_ERROR_NOT_PERMITTED
  *         One of the inputs was a key whose policy didn't allow
@@ -3840,7 +3840,7 @@ psa_status_t psa_key_derivation_output_key(
  *                          \p output_length bytes. Note that in this case,
  *                          the operation's capacity is set to 0, thus
  *                          subsequent calls to this function will not
- *                          succeed, even with a smaller output buffer.
+ *                          succeed, even with a smaller expected output.
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid (it must be active and completed
  *         all required input steps).
@@ -3905,7 +3905,7 @@ psa_status_t psa_key_derivation_verify_bytes(
  *                          the length of the expected value. In this case,
  *                          the operation's capacity is set to 0, thus
  *                          subsequent calls to this function will not
- *                          succeed, even with a smaller output buffer.
+ *                          succeed, even with a smaller expected output.
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid (it must be active and completed
  *         all required input steps).

include/psa/crypto_values.h

@@ -835,7 +835,7 @@
  *
  * \param alg An algorithm identifier (value of type #psa_algorithm_t).
  *
- * \return 1 if \p alg is a key stretching / passowrd hashing algorithm, 0
+ * \return 1 if \p alg is a key stretching / password hashing algorithm, 0
  *         otherwise. This macro may return either 0 or 1 if \p alg is not a
  *         supported algorithm identifier.
  */
@@ -2266,12 +2266,14 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key )
 /** Whether the key may be used to derive other keys or produce a password
  * hash.
  * 
- * This flag allows the key to be used as the input of
- * psa_key_derivation_input_key() at the step
- * #PSA_KEY_DERIVATION_INPUT_SECRET of #PSA_KEY_DERIVATION_INPUT_PASSWORD
- * depending on the algorithm, and allows the use of
- * psa_key_derivation_output_bytes() or psa_key_derivation_output_key()
- * at the end of the operation.
+ * This flag allows the key to be used for a key derivation operation or for
+ * a key agreement operation, if otherwise permitted by by the key's type and
+ * policy.
+ *
+ * If this flag is present on all keys used in calls to
+ * psa_key_derivation_input_key() for a key derivation operation, then it
+ * permits calling psa_key_derivation_output_bytes() or
+ * psa_key_derivation_output_key() at the end of the operation.
  */
 #define PSA_KEY_USAGE_DERIVE                    ((psa_key_usage_t)0x00004000)
 
@@ -2280,14 +2282,13 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key )
  *
  * This flag allows the key to be used:
  *
- * - for a key of type #PSA_KEY_TYPE_PASSWORD_HASH, as the \c key argument of
- *   psa_key_derivation_verify_key();
- * - for a key of type #PSA_KEY_TYPE_PASSWORD (or #PSA_KEY_TYPE_DERIVE), as
- *   the input to psa_key_derivation_input_key() at the step
- *   #PSA_KEY_DERIVATION_INPUT_PASSWORD (or #PSA_KEY_DERIVATION_INPUT_SECRET);
- *   then at the end of the operation use of psa_key_derivation_verify_bytes()
- *   or psa_key_derivation_verify_key() will be permitted (but not
- *   psa_key_derivation_output_xxx() unless #PSA_KEY_USAGE_DERIVE is set).
+ * This flag allows the key to be used in a key derivation operation, if
+ * otherwise permitted by by the key's type and policy.
+ *
+ * If this flag is present on all keys used in calls to
+ * psa_key_derivation_input_key() for a key derivation operation, then it
+ * permits calling psa_key_derivation_verify_bytes() or
+ * psa_key_derivation_verify_key() at the end of the operation.
  */
 #define PSA_KEY_USAGE_VERIFY_DERIVATION         ((psa_key_usage_t)0x00008000)
 
@@ -2306,11 +2307,11 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key )
  *
  * The secret can also be a direct input (passed to
  * key_derivation_input_bytes()). In this case, the derivation operation
- * may not be used to derive or verify keys: the operation will only allow
- * psa_key_derivation_output_bytes() or
- * psa_key_derivation_verify_bytes() but not
- * psa_key_derivation_output_key() or
- * psa_key_derivation_verify_key().
+ * may not be used to derive keys: the operation will only allow
+ * psa_key_derivation_output_bytes(),
+ * psa_key_derivation_verify_bytes(), or
+ * psa_key_derivation_verify_key(), but not
+ * psa_key_derivation_output_key().
  */
 #define PSA_KEY_DERIVATION_INPUT_SECRET     ((psa_key_derivation_step_t)0x0101)
 
@@ -2324,11 +2325,11 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key )
  *
  * The secret can also be a direct input (passed to
  * key_derivation_input_bytes()). In this case, the derivation operation
- * may not be used to derive or verify keys: the operation will only allow
- * psa_key_derivation_output_bytes() or
- * psa_key_derivation_verify_bytes(), not
- * psa_key_derivation_output_key() or
- * psa_key_derivation_verify_key().
+ * may not be used to derive keys: the operation will only allow
+ * psa_key_derivation_output_bytes(),
+ * psa_key_derivation_verify_bytes(), or
+ * psa_key_derivation_verify_key(), but not
+ * psa_key_derivation_output_key().
  */
 #define PSA_KEY_DERIVATION_INPUT_PASSWORD   ((psa_key_derivation_step_t)0x0102)