Update documentation for multipart key derivation operations
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index f677afe..d2788ca 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -3071,23 +3071,29 @@
* cryptographic material.
*
* To derive a key:
- * - Start with an initialized object of type #psa_key_derivation_operation_t.
- * - Call psa_key_derivation_setup() to select the algorithm.
- * - Provide the inputs for the key derivation by calling
- * psa_key_derivation_input_bytes() or psa_key_derivation_input_key()
- * 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.
- * - Optionally set the operation's maximum capacity with
- * 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
- * because the output depends on the maximum capacity.
- * - To derive a key, call psa_key_derivation_output_key().
- * To derive a byte string for a different purpose, call
- * - psa_key_derivation_output_bytes().
- * Successive calls to these functions use successive output bytes
- * calculated by the key derivation algorithm.
- * - Clean up the key derivation operation object with
- * psa_key_derivation_abort().
+ * -# Start with an initialized object of type #psa_key_derivation_operation_t.
+ * -# Call psa_key_derivation_setup() to select the algorithm.
+ * -# Provide the inputs for the key derivation by calling
+ * psa_key_derivation_input_bytes() or psa_key_derivation_input_key()
+ * 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.
+ * -# Optionally set the operation's maximum capacity with
+ * 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
+ * because the output depends on the maximum capacity.
+ * -# To derive a key, call psa_key_derivation_output_key().
+ * To derive a byte string for a different purpose, call
+ * psa_key_derivation_output_bytes().
+ * Successive calls to these functions use successive output bytes
+ * calculated by the key derivation algorithm.
+ * -# Clean up the key derivation operation object with
+ * 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
* to set up. It must
@@ -3108,7 +3114,7 @@
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE
* \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
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
@@ -3130,7 +3136,7 @@
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \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_CORRUPTION_DETECTED
* \retval #PSA_ERROR_BAD_STATE
@@ -3158,7 +3164,7 @@
* In this case, the operation object remains valid and its capacity
* remains unchanged.
* \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_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
@@ -3190,6 +3196,9 @@
* using psa_key_derivation_input_key() instead of this function. Refer to
* 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.
* It must have been set up with
* psa_key_derivation_setup() and must not
@@ -3210,7 +3219,7 @@
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE
* \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
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
@@ -3233,6 +3242,9 @@
* passed as direct inputs using psa_key_derivation_input_bytes(). Refer to
* 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.
* It must have been set up with
* psa_key_derivation_setup() and must not
@@ -3256,7 +3268,7 @@
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE
* \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
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
@@ -3276,6 +3288,9 @@
* The output of this key derivation can be extracted by reading from the
* 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.
* It must have been set up with
* psa_key_derivation_setup() with a
@@ -3307,8 +3322,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The value of \p step is not valid for a key agreement given the
- * state of \p operation.
+ * The operation state is not valid for this key agreement \p step.
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
@@ -3343,7 +3357,10 @@
* stream.
* 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 output_length Number of bytes to output.
*
@@ -3356,6 +3373,8 @@
* 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
@@ -3380,6 +3399,9 @@
* stream.
* 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
* the key is derived, depends on the key type:
*
@@ -3477,6 +3499,8 @@
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The provided key attributes are not valid for the operation.
* \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_STORAGE
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
@@ -3496,21 +3520,19 @@
/** Abort a key derivation operation.
*
* Once a key derivation operation has been aborted, its capacity is zero.
- * Aborting an operation frees all associated resources except for the
- * \c operation structure itself.
+ * Aborting an operation frees all associated resources except for the \c
+ * 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
- * object has been initialized to #PSA_KEY_DERIVATION_OPERATION_INIT, to
- * 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.
+ * This function may be called at any time after the operation
+ * object has been initialized as described in #psa_key_derivation_operation_t.
*
- * 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.
*
* \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_BAD_STATE
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED