Merge pull request #4726 from athoelke/at-pbkdf2-doc-fixes

Fixes for PBKDF2 documentation
This commit is contained in:
Janos Follath 2021-06-28 09:47:57 +01:00 committed by GitHub
commit 8a88f6274c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 31 additions and 30 deletions

View file

@ -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).

View file

@ -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)