lib/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-07-29 11:41:15 +03:00
Code Activity

Merge pull request #4377 from mpg/psa-pbkdf2-api

Browse Source 
PSA API for PBKDF2-HMAC
This commit is contained in:
Gilles Peskine
2021-05-12 18:00:30 +02:00
committed by GitHub
parent 7dbcc3c794 4e02f01815
commit 5d1f747d85
11 changed files with 568 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

202
include/psa/crypto.h
View File

@ -3337,6 +3337,50 @@ psa_status_t psa_key_derivation_input_bytes(
const uint8_t *data,
size_t data_length);
/** Provide a numeric input for key derivation or key agreement.
*
* Which inputs are required and in what order depends on the algorithm.
* However, when an algorithm requires a particular order, numeric inputs
* usually come first as they tend to be configuration parameters.
* Refer to the documentation of each key derivation or key agreement
* algorithm for information.
*
* This function is used for inputs which are fixed-size non-negative
* integers.
*
* If this function returns an error status, the operation enters an error
* state and must be aborted by calling psa_key_derivation_abort().
*
* \param[in,out] operation The key derivation operation object to use.
* It must have been set up with
* psa_key_derivation_setup() and must not
* have produced any output yet.
* \param step Which step the input data is for.
* \param[in] value The value of the numeric input.
*
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \c step is not compatible with the operation's algorithm.
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \c step does not allow numeric inputs.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid for this input \p step.
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
psa_status_t psa_key_derivation_input_integer(
psa_key_derivation_operation_t *operation,
psa_key_derivation_step_t step,
uint64_t value);
/** Provide an input for key derivation in the form of a key.
*
* Which inputs are required and in what order depends on the algorithm.
@ -3361,12 +3405,29 @@ psa_status_t psa_key_derivation_input_bytes(
* \param step Which step the input data is for.
* \param key Identifier of the key. It must have an
* appropriate type for step and must allow the
* usage #PSA_KEY_USAGE_DERIVE.
* usage #PSA_KEY_USAGE_DERIVE or
* #PSA_KEY_USAGE_VERIFY_DERIVATION (see note)
* and the algorithm used by the operation.
*
* \note Once all inputs steps are completed, the operations will allow:
* - psa_key_derivation_output_bytes() if each input was either a direct input
* or a key with #PSA_KEY_USAGE_DERIVE set;
* - psa_key_derivation_output_key() if the input for step
* #PSA_KEY_DERIVATION_INPUT_SECRET or #PSA_KEY_DERIVATION_INPUT_PASSWORD
* was from a key slot with #PSA_KEY_USAGE_DERIVE and each other input was
* either a direct input or a key with #PSA_KEY_USAGE_DERIVE set;
* - psa_key_derivation_verify_bytes() if each input was either a direct input
* or a key with #PSA_KEY_USAGE_VERIFY_DERIVATION set;
* - psa_key_derivation_verify_key() under the same conditions as
* psa_key_derivation_verify_bytes().
*
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* The key allows neither #PSA_KEY_USAGE_DERIVE nor
* #PSA_KEY_USAGE_VERIFY_DERIVATION, or it doesn't allow this
* algorithm.
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \c step is not compatible with the operation's algorithm.
* \retval #PSA_ERROR_INVALID_ARGUMENT
@ -3479,6 +3540,9 @@ psa_status_t psa_key_derivation_key_agreement(
* \param output_length Number of bytes to output.
*
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_NOT_PERMITTED
* One of the inputs was a key whose policy didn't allow
* #PSA_KEY_USAGE_DERIVE.
* \retval #PSA_ERROR_INSUFFICIENT_DATA
* The operation's capacity was less than
* \p output_length bytes. Note that in this case,
@ -3539,7 +3603,8 @@ psa_status_t psa_key_derivation_output_bytes(
* - #PSA_KEY_TYPE_ARC4;
* - #PSA_KEY_TYPE_CAMELLIA;
* - #PSA_KEY_TYPE_DERIVE;
* - #PSA_KEY_TYPE_HMAC.
* - #PSA_KEY_TYPE_HMAC;
* - #PSA_KEY_TYPE_PASSWORD_HASH.
*
* - For ECC keys on a Montgomery elliptic curve
* (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
@ -3601,6 +3666,10 @@ psa_status_t psa_key_derivation_output_bytes(
* on the derived key based on the attributes and strength of the secret key.
*
* \param[in] attributes The attributes for the new key.
* If the key type to be created is
* #PSA_KEY_TYPE_PASSWORD_HASH then the algorithm in
* the policy must be the same as in the current
* operation.
* \param[in,out] operation The key derivation operation object to read from.
* \param[out] key On success, an identifier for the newly created
* key. For persistent keys, this is the key
@ -3625,8 +3694,10 @@ psa_status_t psa_key_derivation_output_bytes(
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The provided key attributes are not valid for the operation.
* \retval #PSA_ERROR_NOT_PERMITTED
* The #PSA_KEY_DERIVATION_INPUT_SECRET input was not provided through
* a key.
* The #PSA_KEY_DERIVATION_INPUT_SECRET or
* #PSA_KEY_DERIVATION_INPUT_PASSWORD input was not provided through a
* key; or one of the inputs was a key whose policy didn't allow
* #PSA_KEY_USAGE_DERIVE.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (it must be active and completed
* all required input steps).
@ -3648,6 +3719,129 @@ psa_status_t psa_key_derivation_output_key(
psa_key_derivation_operation_t *operation,
mbedtls_svc_key_id_t *key);
/** Compare output data from a key derivation operation to an expected value.
*
* 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
* stream before comparing them.
* The operation's capacity decreases by the number of bytes read.
*
* This is functionally equivalent to the following code:
* \code
* psa_key_derivation_output_bytes(operation, tmp, output_length);
* if (memcmp(output, tmp, output_length) != 0)
* return PSA_ERROR_INVALID_SIGNATURE;
* \endcode
* except (1) it works even if the key's policy does not allow outputting the
* bytes, and (2) the comparison will be done in constant time.
*
* If this function returns an error status other than
* #PSA_ERROR_INSUFFICIENT_DATA or #PSA_ERROR_INVALID_SIGNATURE,
* the operation enters an error state and must be aborted by calling
* 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 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
* output.
* \retval #PSA_ERROR_NOT_PERMITTED
* One of the inputs was a key whose policy didn't allow
* #PSA_KEY_USAGE_VERIFY_DERIVATION.
* \retval #PSA_ERROR_INSUFFICIENT_DATA
* The operation's capacity was less than
* \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.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (it must be active and completed
* all required input steps).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
psa_status_t psa_key_derivation_verify_bytes(
psa_key_derivation_operation_t *operation,
const uint8_t *expected_output,
size_t output_length);
/** Compare output data from a key derivation operation to an expected value
* stored in a key object.
*
* 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 you view the key derivation's output as a stream of bytes, this
* function destructively reads the number of bytes corresponding the the
* length of the expected value from the stream before comparing them.
* The operation's capacity decreases by the number of bytes read.
*
* This is functionally equivalent to exporting the key and calling
* psa_key_derivation_verify_bytes() on the result, except that it
* works even if the key cannot be exported.
*
* If this function returns an error status other than
* #PSA_ERROR_INSUFFICIENT_DATA or #PSA_ERROR_INVALID_SIGNATURE,
* the operation enters an error state and must be aborted by calling
* psa_key_derivation_abort().
*
* \param[in,out] operation The key derivation operation object to read from.
* \param[in] expected A key of type #PSA_KEY_TYPE_PASSWORD_HASH
* containing the expected output. Its policy must
* include the #PSA_KEY_USAGE_VERIFY_DERIVATION flag
* and the permitted algorithm must match the
* operation. The value of this key was likely
* computed by a previous call to
* psa_key_derivation_output_key().
*
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_INVALID_SIGNATURE
* The output was read successfully, but if differs from the expected
* output.
* \retval #PSA_ERROR_INVALID_HANDLE
* The key passed as the expected value does not exist.
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The key passed as the expected value has an invalid type.
* \retval #PSA_ERROR_NOT_PERMITTED
* The key passed as the expected value does not allow this usage or
* this algorithm; or one of the inputs was a key whose policy didn't
* allow #PSA_KEY_USAGE_VERIFY_DERIVATION.
* \retval #PSA_ERROR_INSUFFICIENT_DATA
* The operation's capacity was less than
* 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.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (it must be active and completed
* all required input steps).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
* results in this error code.
*/
psa_status_t psa_key_derivation_verify_key(
psa_key_derivation_operation_t *operation,
psa_key_id_t expected);
/** Abort a key derivation operation.
*
* Aborting an operation frees all associated resources except for the \c