Copyedit the documentation of multipart operation functions
Finish changing "start" to "set up".
Correct the way to set an IV for decryption: it's set_iv(), not
update().
When decrypting, the IV is given, not random.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 931a768..cbb6cfb 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -756,7 +756,7 @@
*/
static psa_hash_operation_t psa_hash_operation_init(void);
-/** Start a multipart hash operation.
+/** Set up a multipart hash operation.
*
* The sequence of operations to calculate a hash (message digest)
* is as follows:
@@ -811,7 +811,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not started, or already completed).
+ * The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
@@ -848,7 +848,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not started, or already completed).
+ * The operation state is not valid (not set up, or already completed).
* \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)
@@ -888,7 +888,7 @@
* 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 started, or already completed).
+ * The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
@@ -979,7 +979,7 @@
*/
static psa_mac_operation_t psa_mac_operation_init(void);
-/** Start a multipart MAC calculation operation.
+/** Set up a multipart MAC calculation operation.
*
* This function sets up the calculation of the MAC
* (message authentication code) of a byte string.
@@ -1037,7 +1037,7 @@
psa_key_handle_t handle,
psa_algorithm_t alg);
-/** Start a multipart MAC verification operation.
+/** Set up a multipart MAC verification operation.
*
* This function sets up the verification of the MAC
* (message authentication code) of a byte string against an expected value.
@@ -1109,7 +1109,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not started, or already completed).
+ * The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
@@ -1148,7 +1148,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not started, or already completed).
+ * The operation state is not valid (not set up, or already completed).
* \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().
@@ -1187,7 +1187,7 @@
* 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 started, or already completed).
+ * The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
@@ -1303,8 +1303,7 @@
* 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 psa_cipher_generate_iv(), psa_cipher_set_iv()
- * or psa_cipher_update().
+ * - A failed call to any of the \c psa_cipher_xxx functions.
* - A call to psa_cipher_finish() or psa_cipher_abort().
*
* \param[in,out] operation The operation object to set up. It must have
@@ -1349,7 +1348,7 @@
* documentation for #psa_cipher_operation_t, e.g.
* PSA_CIPHER_OPERATION_INIT.
* -# Call psa_cipher_decrypt_setup() to specify the algorithm and key.
- * -# Call psa_cipher_update() with the IV (initialization vector) for the
+ * -# Call psa_cipher_set_iv() with the IV (initialization vector) for the
* decryption. If the IV is prepended to the ciphertext, you can call
* psa_cipher_update() on a buffer containing the IV followed by the
* beginning of the message.
@@ -1363,7 +1362,7 @@
* 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 psa_cipher_update().
+ * - A failed call to any of the \c psa_cipher_xxx functions.
* - A call to psa_cipher_finish() or psa_cipher_abort().
*
* \param[in,out] operation The operation object to set up. It must have
@@ -1418,7 +1417,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not started, or IV already set).
+ * The operation state is not valid (not set up, or IV already set).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p iv buffer is too small.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -1433,7 +1432,7 @@
/** Set the IV for a symmetric encryption or decryption operation.
*
- * This function sets the random IV (initialization vector), nonce
+ * This function sets the IV (initialization vector), nonce
* or initial counter value for the encryption or decryption operation.
*
* The application must call psa_cipher_encrypt_setup() before
@@ -1452,7 +1451,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not started, or IV already set).
+ * The operation state is not valid (not set up, or IV already 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.
@@ -1488,7 +1487,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not started, IV required but
+ * The operation state is not valid (not set up, IV required but
* not set, or already completed).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p output buffer is too small.
@@ -1526,7 +1525,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (not started, IV required but
+ * The operation state is not valid (not set up, IV required but
* not set, or already completed).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p output buffer is too small.