Merge pull request #260 from athoelke/at-operations
Update multipart operation documentation
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 89392da..9c303cb 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -660,8 +660,6 @@
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_BAD_STATE
- * \p operation is either not initialized or is in use
- * \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.
@@ -966,7 +964,7 @@
* -# Allocate an operation object which will be passed to all the functions
* listed here.
* -# Initialize the operation object with one of the methods described in the
- * documentation for #psa_hash_operation_t, e.g. PSA_HASH_OPERATION_INIT.
+ * documentation for #psa_hash_operation_t, e.g. #PSA_HASH_OPERATION_INIT.
* -# Call psa_hash_setup() to specify the algorithm.
* -# Call psa_hash_update() zero, one or more times, passing a fragment
* of the message each time. The hash that is calculated is the hash
@@ -974,14 +972,16 @@
* -# To calculate the hash, call psa_hash_finish().
* To compare the hash with an expected value, call psa_hash_verify().
*
- * The application may call psa_hash_abort() at any time after the operation
+ * If an error occurs at any step after a call to psa_hash_setup(), the
+ * operation will need to be reset by a call to psa_hash_abort(). The
+ * application may call psa_hash_abort() at any time after the operation
* has been initialized.
*
* After a successful call to psa_hash_setup(), the application must
* eventually terminate the operation. The following events terminate an
* operation:
- * - A failed call to psa_hash_update().
- * - A call to psa_hash_finish(), psa_hash_verify() or psa_hash_abort().
+ * - A successful call to psa_hash_finish() or psa_hash_verify().
+ * - A call to psa_hash_abort().
*
* \param[in,out] operation The operation object to set up. It must have
* been initialized as per the documentation for
@@ -996,15 +996,12 @@
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p alg is not a hash algorithm.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (already set up and not
- * subsequently completed).
+ * The operation state is not valid (it must be inactive).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_BAD_STATE
- * \p operation is either not initialized or is in use
- * \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.
@@ -1016,7 +1013,8 @@
*
* The application must call psa_hash_setup() before calling this function.
*
- * If this function returns an error status, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_hash_abort().
*
* \param[in,out] operation Active hash operation.
* \param[in] input Buffer containing the message fragment to hash.
@@ -1025,14 +1023,12 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, or already completed).
+ * The operation state is not valid (it muct be active).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid.
- * \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.
@@ -1047,7 +1043,9 @@
* This function calculates the hash of the message formed by concatenating
* the inputs passed to preceding calls to psa_hash_update().
*
- * When this function returns, the operation becomes inactive.
+ * When this function returns successfuly, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_hash_abort().
*
* \warning Applications should not call this function if they expect
* a specific value for the hash. Call psa_hash_verify() instead.
@@ -1068,7 +1066,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, or already completed).
+ * The operation state is not valid (it must be active).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p hash buffer is too small. You can determine a
* sufficient buffer size by calling #PSA_HASH_SIZE(\c alg)
@@ -1078,8 +1076,6 @@
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid.
- * \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.
@@ -1098,7 +1094,9 @@
* compares the calculated hash with the expected hash passed as a
* parameter to this function.
*
- * When this function returns, the operation becomes inactive.
+ * When this function returns successfuly, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_hash_abort().
*
* \note Implementations shall make the best effort to ensure that the
* comparison between the actual hash and the expected hash is performed
@@ -1114,14 +1112,12 @@
* The hash of the message was calculated successfully, but it
* differs from the expected hash.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, or already completed).
+ * The operation state is not valid (it must be active).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid.
- * \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.
@@ -1138,11 +1134,7 @@
* psa_hash_setup() again.
*
* You may call this function any time after the operation object has
- * been initialized by any of the following methods:
- * - A call to psa_hash_setup(), whether it succeeds or not.
- * - Initializing the \c struct to all-bits-zero.
- * - Initializing the \c struct to logical zeros, e.g.
- * `psa_hash_operation_t operation = {0}`.
+ * been initialized by one of the methods described in #psa_hash_operation_t.
*
* In particular, calling psa_hash_abort() after the operation has been
* terminated by a call to psa_hash_abort(), psa_hash_finish() or
@@ -1151,14 +1143,10 @@
* \param[in,out] operation Initialized hash operation.
*
* \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_BAD_STATE
- * \p operation is not an active hash operation.
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid.
- * \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.
@@ -1182,18 +1170,14 @@
*
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_BAD_STATE
- * \p source_operation is not an active hash operation.
+ * The \p source_operation state is not valid (it must be active).
* \retval #PSA_ERROR_BAD_STATE
- * \p target_operation is active.
+ * The \p target_operation state is not valid (it must be inactive).
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is either not initialized or has already been setup.
- * \retval #PSA_ERROR_BAD_STATE
- * The operation state is either not initialized or has already been setup.
- * \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.
@@ -1352,7 +1336,7 @@
* -# Allocate an operation object which will be passed to all the functions
* listed here.
* -# Initialize the operation object with one of the methods described in the
- * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
+ * documentation for #psa_mac_operation_t, e.g. #PSA_MAC_OPERATION_INIT.
* -# Call psa_mac_sign_setup() to specify the algorithm and key.
* -# Call psa_mac_update() zero, one or more times, passing a fragment
* of the message each time. The MAC that is calculated is the MAC
@@ -1360,13 +1344,15 @@
* -# At the end of the message, call psa_mac_sign_finish() to finish
* calculating the MAC value and retrieve it.
*
- * The application may call psa_mac_abort() at any time after the operation
+ * If an error occurs at any step after a call to psa_mac_sign_setup(), the
+ * operation will need to be reset by a call to psa_mac_abort(). The
+ * application may call psa_mac_abort() at any time after the operation
* has been initialized.
*
* After a successful call to psa_mac_sign_setup(), the application must
* eventually terminate the operation through one of the following methods:
- * - A failed call to psa_mac_update().
- * - A call to psa_mac_sign_finish() or psa_mac_abort().
+ * - A successful call to psa_mac_sign_finish().
+ * - A call to psa_mac_abort().
*
* \param[in,out] operation The operation object to set up. It must have
* been initialized as per the documentation for
@@ -1392,8 +1378,7 @@
* \retval #PSA_ERROR_STORAGE_FAILURE
* The key could not be retrieved from storage.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (already set up and not
- * subsequently completed).
+ * 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
@@ -1412,7 +1397,7 @@
* -# Allocate an operation object which will be passed to all the functions
* listed here.
* -# Initialize the operation object with one of the methods described in the
- * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
+ * documentation for #psa_mac_operation_t, e.g. #PSA_MAC_OPERATION_INIT.
* -# Call psa_mac_verify_setup() to specify the algorithm and key.
* -# Call psa_mac_update() zero, one or more times, passing a fragment
* of the message each time. The MAC that is calculated is the MAC
@@ -1421,13 +1406,15 @@
* calculating the actual MAC of the message and verify it against
* the expected value.
*
- * The application may call psa_mac_abort() at any time after the operation
+ * If an error occurs at any step after a call to psa_mac_verify_setup(), the
+ * operation will need to be reset by a call to psa_mac_abort(). The
+ * application may call psa_mac_abort() at any time after the operation
* has been initialized.
*
* After a successful call to psa_mac_verify_setup(), the application must
* eventually terminate the operation through one of the following methods:
- * - A failed call to psa_mac_update().
- * - A call to psa_mac_verify_finish() or psa_mac_abort().
+ * - A successful call to psa_mac_verify_finish().
+ * - A call to psa_mac_abort().
*
* \param[in,out] operation The operation object to set up. It must have
* been initialized as per the documentation for
@@ -1453,8 +1440,7 @@
* \retval #PSA_ERROR_STORAGE_FAILURE
* The key could not be retrieved from storage
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (already set up and not
- * subsequently completed).
+ * 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
@@ -1469,7 +1455,8 @@
* The application must call psa_mac_sign_setup() or psa_mac_verify_setup()
* before calling this function.
*
- * If this function returns an error status, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_mac_abort().
*
* \param[in,out] operation Active MAC operation.
* \param[in] input Buffer containing the message fragment to add to
@@ -1479,7 +1466,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, or already completed).
+ * The operation state is not valid (it must be active).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
@@ -1500,7 +1487,9 @@
* This function calculates the MAC of the message formed by concatenating
* the inputs passed to preceding calls to psa_mac_update().
*
- * When this function returns, the operation becomes inactive.
+ * When this function returns successfuly, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_mac_abort().
*
* \warning Applications should not call this function if they expect
* a specific value for the MAC. Call psa_mac_verify_finish() instead.
@@ -1523,7 +1512,8 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, or already completed).
+ * The operation state is not valid (it must be an active mac sign
+ * operation).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p mac buffer is too small. You can determine a
* sufficient buffer size by calling PSA_MAC_FINAL_SIZE().
@@ -1551,7 +1541,9 @@
* compares the calculated MAC with the expected MAC passed as a
* parameter to this function.
*
- * When this function returns, the operation becomes inactive.
+ * When this function returns successfuly, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_mac_abort().
*
* \note Implementations shall make the best effort to ensure that the
* comparison between the actual MAC and the expected MAC is performed
@@ -1567,7 +1559,8 @@
* The MAC of the message was calculated successfully, but it
* differs from the expected MAC.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, or already completed).
+ * The operation state is not valid (it must be an active mac verify
+ * operation).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
@@ -1590,12 +1583,7 @@
* psa_mac_sign_setup() or psa_mac_verify_setup() again.
*
* You may call this function any time after the operation object has
- * been initialized by any of the following methods:
- * - A call to psa_mac_sign_setup() or psa_mac_verify_setup(), whether
- * it succeeds or not.
- * - Initializing the \c struct to all-bits-zero.
- * - Initializing the \c struct to logical zeros, e.g.
- * `psa_mac_operation_t operation = {0}`.
+ * been initialized by one of the methods described in #psa_mac_operation_t.
*
* In particular, calling psa_mac_abort() after the operation has been
* terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or
@@ -1604,8 +1592,6 @@
* \param[in,out] operation Initialized MAC operation.
*
* \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_BAD_STATE
- * \p operation is not an active MAC operation.
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
@@ -1625,7 +1611,8 @@
/** Encrypt a message using a symmetric cipher.
*
* This function encrypts a message with a random IV (initialization
- * vector).
+ * vector). Use the multipart operation interface with a
+ * #psa_cipher_operation_t object to provide other forms of IV.
*
* \param handle Handle to the key to use for the operation.
* It must remain valid until the operation
@@ -1769,7 +1756,7 @@
* listed here.
* -# Initialize the operation object with one of the methods described in the
* documentation for #psa_cipher_operation_t, e.g.
- * PSA_CIPHER_OPERATION_INIT.
+ * #PSA_CIPHER_OPERATION_INIT.
* -# Call psa_cipher_encrypt_setup() to specify the algorithm and key.
* -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to
* generate or set the IV (initialization vector). You should use
@@ -1779,14 +1766,16 @@
* of the message each time.
* -# Call psa_cipher_finish().
*
- * The application may call psa_cipher_abort() at any time after the operation
+ * If an error occurs at any step after a call to psa_cipher_encrypt_setup(),
+ * the operation will need to be reset by a call to psa_cipher_abort(). The
+ * application may call psa_cipher_abort() at any time after the operation
* has been initialized.
*
* After a successful call to psa_cipher_encrypt_setup(), the application must
* eventually terminate the operation. The following events terminate an
* operation:
- * - A failed call to any of the \c psa_cipher_xxx functions.
- * - A call to psa_cipher_finish() or psa_cipher_abort().
+ * - A successful call to psa_cipher_finish().
+ * - A call to psa_cipher_abort().
*
* \param[in,out] operation The operation object to set up. It must have
* been initialized as per the documentation for
@@ -1812,8 +1801,7 @@
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (already set up and not
- * subsequently completed).
+ * 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
@@ -1831,7 +1819,7 @@
* listed here.
* -# Initialize the operation object with one of the methods described in the
* documentation for #psa_cipher_operation_t, e.g.
- * PSA_CIPHER_OPERATION_INIT.
+ * #PSA_CIPHER_OPERATION_INIT.
* -# Call psa_cipher_decrypt_setup() to specify the algorithm and key.
* -# Call psa_cipher_set_iv() with the IV (initialization vector) for the
* decryption. If the IV is prepended to the ciphertext, you can call
@@ -1841,14 +1829,16 @@
* of the message each time.
* -# Call psa_cipher_finish().
*
- * The application may call psa_cipher_abort() at any time after the operation
+ * If an error occurs at any step after a call to psa_cipher_decrypt_setup(),
+ * the operation will need to be reset by a call to psa_cipher_abort(). The
+ * application may call psa_cipher_abort() at any time after the operation
* has been initialized.
*
* After a successful call to psa_cipher_decrypt_setup(), the application must
* eventually terminate the operation. The following events terminate an
* operation:
- * - A failed call to any of the \c psa_cipher_xxx functions.
- * - A call to psa_cipher_finish() or psa_cipher_abort().
+ * - A successful call to psa_cipher_finish().
+ * - A call to psa_cipher_abort().
*
* \param[in,out] operation The operation object to set up. It must have
* been initialized as per the documentation for
@@ -1874,8 +1864,7 @@
* \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (already set up and not
- * subsequently completed).
+ * 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
@@ -1894,7 +1883,8 @@
* The application must call psa_cipher_encrypt_setup() before
* calling this function.
*
- * If this function returns an error status, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_cipher_abort().
*
* \param[in,out] operation Active cipher operation.
* \param[out] iv Buffer where the generated IV is to be written.
@@ -1905,7 +1895,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, or IV already set).
+ * The operation state is not valid (it must be active, with no IV set).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p iv buffer is too small.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -1931,7 +1921,8 @@
* The application must call psa_cipher_encrypt_setup() before
* calling this function.
*
- * If this function returns an error status, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_cipher_abort().
*
* \note When encrypting, applications should use psa_cipher_generate_iv()
* instead of this function, unless implementing a protocol that requires
@@ -1944,7 +1935,8 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, or IV already set).
+ * The operation state is not valid (it must be an active cipher
+ * encrypt operation, with no IV set).
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The size of \p iv is not acceptable for the chosen algorithm,
* or the chosen algorithm does not use an IV.
@@ -1971,7 +1963,8 @@
* 2. If the algorithm requires an IV, call psa_cipher_generate_iv()
* (recommended when encrypting) or psa_cipher_set_iv().
*
- * If this function returns an error status, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_cipher_abort().
*
* \param[in,out] operation Active cipher operation.
* \param[in] input Buffer containing the message fragment to
@@ -1985,8 +1978,8 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, IV required but
- * not set, or already completed).
+ * The operation state is not valid (it must be active, with an IV set
+ * if required for the algorithm).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p output buffer is too small.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2017,7 +2010,9 @@
* formed by concatenating the inputs passed to preceding calls to
* psa_cipher_update().
*
- * When this function returns, the operation becomes inactive.
+ * When this function returns successfuly, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_cipher_abort().
*
* \param[in,out] operation Active cipher operation.
* \param[out] output Buffer where the output is to be written.
@@ -2036,8 +2031,8 @@
* This is a decryption operation for an algorithm that includes
* padding, and the ciphertext does not contain valid padding.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, IV required but
- * not set, or already completed).
+ * The operation state is not valid (it must be active, with an IV set
+ * if required for the algorithm).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p output buffer is too small.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2063,12 +2058,7 @@
* psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.
*
* You may call this function any time after the operation object has
- * been initialized by any of the following methods:
- * - A call to psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(),
- * whether it succeeds or not.
- * - Initializing the \c struct to all-bits-zero.
- * - Initializing the \c struct to logical zeros, e.g.
- * `psa_cipher_operation_t operation = {0}`.
+ * been initialized as described in #psa_cipher_operation_t.
*
* In particular, calling psa_cipher_abort() after the operation has been
* terminated by a call to psa_cipher_abort() or psa_cipher_finish()
@@ -2077,8 +2067,6 @@
* \param[in,out] operation Initialized cipher operation.
*
* \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_BAD_STATE
- * \p operation is not an active cipher operation.
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
@@ -2269,7 +2257,7 @@
* listed here.
* -# Initialize the operation object with one of the methods described in the
* documentation for #psa_aead_operation_t, e.g.
- * PSA_AEAD_OPERATION_INIT.
+ * #PSA_AEAD_OPERATION_INIT.
* -# Call psa_aead_encrypt_setup() to specify the algorithm and key.
* -# If needed, call psa_aead_set_lengths() to specify the length of the
* inputs to the subsequent calls to psa_aead_update_ad() and
@@ -2285,14 +2273,16 @@
* of the message to encrypt each time.
* -# Call psa_aead_finish().
*
- * The application may call psa_aead_abort() at any time after the operation
+ * If an error occurs at any step after a call to psa_aead_encrypt_setup(),
+ * the operation will need to be reset by a call to psa_aead_abort(). The
+ * application may call psa_aead_abort() at any time after the operation
* has been initialized.
*
* After a successful call to psa_aead_encrypt_setup(), the application must
* eventually terminate the operation. The following events terminate an
* operation:
- * - A failed call to any of the \c psa_aead_xxx functions.
- * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
+ * - A successful call to psa_aead_finish().
+ * - A call to psa_aead_abort().
*
* \param[in,out] operation The operation object to set up. It must have
* been initialized as per the documentation for
@@ -2306,7 +2296,9 @@
*
* \retval #PSA_SUCCESS
* Success.
- * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (it must be inactive).
+ * \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p handle is not compatible with \p alg.
@@ -2334,7 +2326,7 @@
* listed here.
* -# Initialize the operation object with one of the methods described in the
* documentation for #psa_aead_operation_t, e.g.
- * PSA_AEAD_OPERATION_INIT.
+ * #PSA_AEAD_OPERATION_INIT.
* -# Call psa_aead_decrypt_setup() to specify the algorithm and key.
* -# If needed, call psa_aead_set_lengths() to specify the length of the
* inputs to the subsequent calls to psa_aead_update_ad() and
@@ -2347,14 +2339,16 @@
* of the ciphertext to decrypt each time.
* -# Call psa_aead_verify().
*
- * The application may call psa_aead_abort() at any time after the operation
+ * If an error occurs at any step after a call to psa_aead_decrypt_setup(),
+ * the operation will need to be reset by a call to psa_aead_abort(). The
+ * application may call psa_aead_abort() at any time after the operation
* has been initialized.
*
* After a successful call to psa_aead_decrypt_setup(), the application must
* eventually terminate the operation. The following events terminate an
* operation:
- * - A failed call to any of the \c psa_aead_xxx functions.
- * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
+ * - A successful call to psa_aead_verify().
+ * - A call to psa_aead_abort().
*
* \param[in,out] operation The operation object to set up. It must have
* been initialized as per the documentation for
@@ -2368,7 +2362,9 @@
*
* \retval #PSA_SUCCESS
* Success.
- * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (it must be inactive).
+ * \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p handle is not compatible with \p alg.
@@ -2397,7 +2393,8 @@
* The application must call psa_aead_encrypt_setup() before
* calling this function.
*
- * If this function returns an error status, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_aead_abort().
*
* \param[in,out] operation Active AEAD operation.
* \param[out] nonce Buffer where the generated nonce is to be
@@ -2409,7 +2406,8 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, or nonce already set).
+ * The operation state is not valid (it must be an active aead encrypt
+ operation, with no nonce set).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p nonce buffer is too small.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2432,10 +2430,11 @@
* This function sets the nonce for the authenticated
* encryption or decryption operation.
*
- * The application must call psa_aead_encrypt_setup() before
- * calling this function.
+ * The application must call psa_aead_encrypt_setup() or
+ * psa_aead_decrypt_setup() before calling this function.
*
- * If this function returns an error status, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_aead_abort().
*
* \note When encrypting, applications should use psa_aead_generate_nonce()
* instead of this function, unless implementing a protocol that requires
@@ -2448,7 +2447,8 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, or nonce already set).
+ * The operation state is not valid (it must be active, with no nonce
+ * set).
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The size of \p nonce is not acceptable for the chosen algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2481,6 +2481,9 @@
* this function is not required.
* - For vendor-defined algorithm, refer to the vendor documentation.
*
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_aead_abort().
+ *
* \param[in,out] operation Active AEAD operation.
* \param ad_length Size of the non-encrypted additional
* authenticated data in bytes.
@@ -2489,8 +2492,9 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, already completed,
- * or psa_aead_update_ad() or psa_aead_update() already called).
+ * The operation state is not valid (it must be active, and
+ * psa_aead_update_ad() and psa_aead_update() must not have been
+ * called yet).
* \retval #PSA_ERROR_INVALID_ARGUMENT
* At least one of the lengths is not acceptable for the chosen
* algorithm.
@@ -2519,7 +2523,8 @@
* 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
* 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
*
- * If this function returns an error status, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_aead_abort().
*
* \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
* there is no guarantee that the input is valid. Therefore, until
@@ -2535,8 +2540,9 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, nonce not set,
- * psa_aead_update() already called, or operation already completed).
+ * The operation state is not valid (it must be active, have a nonce
+ * set, have lengths set if required by the algorithm, and
+ * psa_aead_update() must not have been called yet).
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The total input length overflows the additional data length that
* was previously specified with psa_aead_set_lengths().
@@ -2563,7 +2569,8 @@
* 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
* 3. Call psa_aead_update_ad() to pass all the additional data.
*
- * If this function returns an error status, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_aead_abort().
*
* \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
* there is no guarantee that the input is valid. Therefore, until
@@ -2603,8 +2610,8 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, nonce not set
- * or already completed).
+ * The operation state is not valid (it must be active, have a nonce
+ * set, and have lengths set if required by the algorithm).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p output buffer is too small.
* You can determine a sufficient buffer size by calling
@@ -2650,7 +2657,9 @@
* #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is the AEAD algorithm
* that the operation performs.
*
- * When this function returns, the operation becomes inactive.
+ * When this function returns successfuly, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_aead_abort().
*
* \param[in,out] operation Active AEAD operation.
* \param[out] ciphertext Buffer where the last part of the ciphertext
@@ -2674,8 +2683,8 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, nonce not set,
- * decryption, or already completed).
+ * The operation state is not valid (it must be an active encryption
+ * operation with a nonce set).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p ciphertext or \p tag buffer is too small.
* You can determine a sufficient buffer size for \p ciphertext by
@@ -2726,7 +2735,9 @@
* plaintext and reports success. If the authentication tag is not correct,
* this function returns #PSA_ERROR_INVALID_SIGNATURE.
*
- * When this function returns, the operation becomes inactive.
+ * When this function returns successfuly, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_aead_abort().
*
* \note Implementations shall make the best effort to ensure that the
* comparison between the actual tag and the expected tag is performed
@@ -2754,8 +2765,8 @@
* The calculations were successful, but the authentication tag is
* not correct.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not set up, nonce not set,
- * encryption, or already completed).
+ * The operation state is not valid (it must be an active decryption
+ * operation with a nonce set).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p plaintext buffer is too small.
* You can determine a sufficient buffer size for \p plaintext by
@@ -2794,22 +2805,15 @@
* psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again.
*
* You may call this function any time after the operation object has
- * been initialized by any of the following methods:
- * - A call to psa_aead_encrypt_setup() or psa_aead_decrypt_setup(),
- * whether it succeeds or not.
- * - Initializing the \c struct to all-bits-zero.
- * - Initializing the \c struct to logical zeros, e.g.
- * `psa_aead_operation_t operation = {0}`.
+ * been initialized as described in #psa_aead_operation_t.
*
* In particular, calling psa_aead_abort() after the operation has been
- * terminated by a call to psa_aead_abort() or psa_aead_finish()
- * is safe and has no effect.
+ * terminated by a call to psa_aead_abort(), psa_aead_finish() or
+ * psa_aead_verify() is safe and has no effect.
*
* \param[in,out] operation Initialized AEAD operation.
*
* \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_BAD_STATE
- * \p operation is not an active AEAD operation.
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
@@ -3102,23 +3106,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().
*
* Implementations must reject an attempt to derive a key of size 0.
*
@@ -3141,7 +3151,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
@@ -3163,7 +3173,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
@@ -3191,7 +3201,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
@@ -3223,6 +3233,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
@@ -3243,7 +3256,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
@@ -3266,6 +3279,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
@@ -3289,7 +3305,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
@@ -3309,6 +3325,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
@@ -3339,6 +3358,8 @@
*
* \retval #PSA_SUCCESS
* Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * 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
@@ -3373,6 +3394,10 @@
* stream.
* The operation's capacity decreases by the number of bytes read.
*
+ * If this function returns an error status other than
+ * #PSA_ERROR_INSUFFICIENT_DATA, 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.
@@ -3386,6 +3411,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
@@ -3413,6 +3440,10 @@
* stream.
* The operation's capacity decreases by the number of bytes read.
*
+ * If this function returns an error status other than
+ * #PSA_ERROR_INSUFFICIENT_DATA, 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:
*
@@ -3510,6 +3541,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
@@ -3528,22 +3561,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