Update documentation for multipart cipher operations
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 0ec67d7..bf7fd18 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1593,7 +1593,8 @@
/** Encrypt a message using a symmetric cipher.
*
* This function encrypts a message with a random IV (initialization
- * vector).
+ * vector). Use the multipart #psa_cipher_operation_t object to provide
+ * other foms of IV.
*
* \param handle Handle to the key to use for the operation.
* It must remain valid until the operation
@@ -1737,7 +1738,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
@@ -1747,14 +1748,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
@@ -1780,8 +1783,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
@@ -1799,7 +1801,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
@@ -1809,14 +1811,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
@@ -1842,8 +1846,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
@@ -1862,7 +1865,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.
@@ -1873,7 +1877,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
@@ -1899,7 +1903,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
@@ -1912,7 +1917,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.
@@ -1939,7 +1945,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
@@ -1953,8 +1960,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
@@ -1985,7 +1992,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.
@@ -2004,8 +2013,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
@@ -2031,12 +2040,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()
@@ -2045,8 +2049,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