yuzu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2025-01-25 21:31:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation for multipart key derivation operations

Browse source
This commit is contained in:
Andrew Thoelke 2019-09-13 15:27:46 +01:00
parent 414415a457
commit beb97ba066
1 changed files with 56 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

90
include/psa/crypto.h
View file

@ -3071,23 +3071,29 @@ static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
* cryptographic material. * cryptographic material.
* *
* To derive a key: * To derive a key:
* - Start with an initialized object of type #psa_key_derivation_operation_t. * -# Start with an initialized object of type #psa_key_derivation_operation_t.
* - Call psa_key_derivation_setup() to select the algorithm. * -# Call psa_key_derivation_setup() to select the algorithm.
* - Provide the inputs for the key derivation by calling * -# Provide the inputs for the key derivation by calling
* psa_key_derivation_input_bytes() or psa_key_derivation_input_key() * psa_key_derivation_input_bytes() or psa_key_derivation_input_key()
* as appropriate. Which inputs are needed, in what order, and whether * as appropriate. Which inputs are needed, in what order, and whether
* they may be keys and if so of what type depends on the algorithm. * they may be keys and if so of what type depends on the algorithm.
* - Optionally set the operation's maximum capacity with * -# Optionally set the operation's maximum capacity with
* psa_key_derivation_set_capacity(). You may do this before, in the middle * psa_key_derivation_set_capacity(). You may do this before, in the middle
* of or after providing inputs. For some algorithms, this step is mandatory * of or after providing inputs. For some algorithms, this step is mandatory
* because the output depends on the maximum capacity. * because the output depends on the maximum capacity.
* - To derive a key, call psa_key_derivation_output_key(). * -# To derive a key, call psa_key_derivation_output_key().
* To derive a byte string for a different purpose, call * To derive a byte string for a different purpose, call
* - psa_key_derivation_output_bytes(). * psa_key_derivation_output_bytes().
* Successive calls to these functions use successive output bytes * Successive calls to these functions use successive output bytes
* calculated by the key derivation algorithm. * calculated by the key derivation algorithm.
* - Clean up the key derivation operation object with * -# Clean up the key derivation operation object with
* psa_key_derivation_abort(). * psa_key_derivation_abort().
*
* If this function returns an error, the key derivation operation object is
* not changed.
*
* If an error occurs at any step after a call to psa_key_derivation_setup(),
* the operation will need to be reset by a call to psa_key_derivation_abort().
* *
* \param[in,out] operation The key derivation operation object * \param[in,out] operation The key derivation operation object
* to set up. It must * to set up. It must
@ -3108,7 +3114,7 @@ static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
* \retval #PSA_ERROR_CORRUPTION_DETECTED * \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE * \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is either not initialized or has already been setup. * The operation state is not valid (it must be inactive).
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init(). * The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize * It is implementation-dependent whether a failure to initialize
@ -3130,7 +3136,7 @@ psa_status_t psa_key_derivation_setup(
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid. * The operation state is not valid (it must be active).
* \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED * \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
@ -3158,7 +3164,7 @@ psa_status_t psa_key_derivation_get_capacity(
* In this case, the operation object remains valid and its capacity * In this case, the operation object remains valid and its capacity
* remains unchanged. * remains unchanged.
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid. * The operation state is not valid (it must be active).
* \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED * \retval #PSA_ERROR_CORRUPTION_DETECTED
@ -3190,6 +3196,9 @@ psa_status_t psa_key_derivation_set_capacity(
* using psa_key_derivation_input_key() instead of this function. Refer to * using psa_key_derivation_input_key() instead of this function. Refer to
* the documentation of individual step types for information. * the documentation of individual step types for information.
* *
* 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. * \param[in,out] operation The key derivation operation object to use.
* It must have been set up with * It must have been set up with
* psa_key_derivation_setup() and must not * psa_key_derivation_setup() and must not
@ -3210,7 +3219,7 @@ psa_status_t psa_key_derivation_set_capacity(
* \retval #PSA_ERROR_CORRUPTION_DETECTED * \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE * \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The value of \p step is not valid given the state of \p operation. * The operation state is not valid for this input \p step.
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init(). * The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize * It is implementation-dependent whether a failure to initialize
@ -3233,6 +3242,9 @@ psa_status_t psa_key_derivation_input_bytes(
* passed as direct inputs using psa_key_derivation_input_bytes(). Refer to * passed as direct inputs using psa_key_derivation_input_bytes(). Refer to
* the documentation of individual step types for information. * the documentation of individual step types for information.
* *
* 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. * \param[in,out] operation The key derivation operation object to use.
* It must have been set up with * It must have been set up with
* psa_key_derivation_setup() and must not * psa_key_derivation_setup() and must not
@ -3256,7 +3268,7 @@ psa_status_t psa_key_derivation_input_bytes(
* \retval #PSA_ERROR_CORRUPTION_DETECTED * \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE * \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The value of \p step is not valid given the state of \p operation. * The operation state is not valid for this input \p step.
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init(). * The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize * It is implementation-dependent whether a failure to initialize
@ -3276,6 +3288,9 @@ psa_status_t psa_key_derivation_input_key(
* The output of this key derivation can be extracted by reading from the * The output of this key derivation can be extracted by reading from the
* resulting operation to produce keys and other cryptographic material. * resulting operation to produce keys and other cryptographic material.
* *
* 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. * \param[in,out] operation The key derivation operation object to use.
* It must have been set up with * It must have been set up with
* psa_key_derivation_setup() with a * psa_key_derivation_setup() with a
@ -3307,8 +3322,7 @@ psa_status_t psa_key_derivation_input_key(
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* Success. * Success.
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The value of \p step is not valid for a key agreement given the * The operation state is not valid for this key agreement \p step.
* state of \p operation.
* \retval #PSA_ERROR_INVALID_HANDLE * \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED * \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT * \retval #PSA_ERROR_INVALID_ARGUMENT
@ -3343,7 +3357,10 @@ psa_status_t psa_key_derivation_key_agreement(
* stream. * stream.
* The operation's capacity decreases by the number of bytes read. * The operation's capacity decreases by the number of bytes read.
* *
* \param[in,out] operation The key derivation operation object to read from. * 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 read from.
* \param[out] output Buffer where the output will be written. * \param[out] output Buffer where the output will be written.
* \param output_length Number of bytes to output. * \param output_length Number of bytes to output.
* *
@ -3356,6 +3373,8 @@ psa_status_t psa_key_derivation_key_agreement(
* subsequent calls to this function will not * subsequent calls to this function will not
* succeed, even with a smaller output buffer. * succeed, even with a smaller output buffer.
* \retval #PSA_ERROR_BAD_STATE * \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_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE
@ -3380,6 +3399,9 @@ psa_status_t psa_key_derivation_output_bytes(
* stream. * stream.
* The operation's capacity decreases by the number of bytes read. * The operation's capacity decreases by the number of bytes read.
* *
* If this function returns an error status, the operation enters an error
* state and must be aborted by calling psa_key_derivation_abort().
*
* How much output is produced and consumed from the operation, and how * How much output is produced and consumed from the operation, and how
* the key is derived, depends on the key type: * the key is derived, depends on the key type:
* *
@ -3477,6 +3499,8 @@ psa_status_t psa_key_derivation_output_bytes(
* \retval #PSA_ERROR_INVALID_ARGUMENT * \retval #PSA_ERROR_INVALID_ARGUMENT
* The provided key attributes are not valid for the operation. * The provided key attributes are not valid for the operation.
* \retval #PSA_ERROR_BAD_STATE * \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_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
* \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_COMMUNICATION_FAILURE
@ -3496,21 +3520,19 @@ psa_status_t psa_key_derivation_output_key(
/** Abort a key derivation operation. /** Abort a key derivation operation.
* *
* Once a key derivation operation has been aborted, its capacity is zero. * Once a key derivation operation has been aborted, its capacity is zero.
* Aborting an operation frees all associated resources except for the * Aborting an operation frees all associated resources except for the \c
* \c operation structure itself. * operation structure itself. Once aborted, the operation object can be reused
* for another operation by calling psa_key_derivation_setup() again.
* *
* This function may be called at any time as long as the operation * This function may be called at any time after the operation
* object has been initialized to #PSA_KEY_DERIVATION_OPERATION_INIT, to * object has been initialized as described in #psa_key_derivation_operation_t.
* psa_key_derivation_operation_init() or a zero value. In particular,
* it is valid to call psa_key_derivation_abort() twice, or to call
* psa_key_derivation_abort() on an operation that has not been set up.
* *
* Once aborted, the key derivation operation object may be called. * In particular, it is valid to call psa_key_derivation_abort() twice, or to
* call psa_key_derivation_abort() on an operation that has not been set up.
* *
* \param[in,out] operation The operation to abort. * \param[in,out] operation The operation to abort.
* *
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* \retval #PSA_ERROR_BAD_STATE
* \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED * \retval #PSA_ERROR_CORRUPTION_DETECTED