From 340984b003c4a9e047a19442a4b5a81b0197231e Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Wed, 11 Sep 2019 21:33:41 +0100
Subject: [PATCH 1/8] Fix PSA_ERROR_BAD_STATE messages

Remove some duplicated entries and added some missing ones.
---
 include/psa/crypto.h | 29 +++++++++++------------------
 1 file changed, 11 insertions(+), 18 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 5288815c3..2529a0a11 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -642,8 +642,6 @@ psa_status_t psa_destroy_key(psa_key_handle_t handle);
  * \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.
@@ -985,8 +983,6 @@ static psa_hash_operation_t psa_hash_operation_init(void);
  * \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.
@@ -1013,8 +1009,6 @@ psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
  * \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.
@@ -1060,8 +1054,6 @@ psa_status_t psa_hash_update(psa_hash_operation_t *operation,
  * \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.
@@ -1102,8 +1094,6 @@ psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
  * \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.
@@ -1139,8 +1129,6 @@ psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
  * \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.
@@ -1172,10 +1160,6 @@ psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
  * \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.
@@ -2288,7 +2272,10 @@ static psa_aead_operation_t psa_aead_operation_init(void);
  *
  * \retval #PSA_SUCCESS
  *         Success.
- * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is not valid (already set up and not
+ *         subsequently completed).
+  * \retval #PSA_ERROR_INVALID_HANDLE
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \p handle is not compatible with \p alg.
@@ -2350,7 +2337,10 @@ psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
  *
  * \retval #PSA_SUCCESS
  *         Success.
- * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is not valid (already set up and not
+ *         subsequently completed).
+  * \retval #PSA_ERROR_INVALID_HANDLE
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \p handle is not compatible with \p alg.
@@ -3304,6 +3294,9 @@ psa_status_t psa_key_derivation_input_key(
  *
  * \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.
  * \retval #PSA_ERROR_INVALID_HANDLE
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT

From 272ba1dd965a528c112223884c635b9036aa56d0 Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Wed, 11 Sep 2019 22:53:21 +0100
Subject: [PATCH 2/8] Update documentation for multipart hash operations

---
 include/psa/crypto.h | 42 +++++++++++++++++++++---------------------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 2529a0a11..d3ba75e75 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -946,7 +946,7 @@ static psa_hash_operation_t psa_hash_operation_init(void);
  * -# 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
@@ -954,14 +954,16 @@ static psa_hash_operation_t psa_hash_operation_init(void);
  * -# 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
@@ -976,8 +978,7 @@ static psa_hash_operation_t psa_hash_operation_init(void);
  * \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
@@ -994,7 +995,8 @@ psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
  *
  * 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.
@@ -1003,7 +1005,7 @@ psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
  * \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
@@ -1023,7 +1025,9 @@ psa_status_t psa_hash_update(psa_hash_operation_t *operation,
  * 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.
@@ -1044,7 +1048,7 @@ psa_status_t psa_hash_update(psa_hash_operation_t *operation,
  * \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)
@@ -1072,7 +1076,9 @@ psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
  * 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
@@ -1088,7 +1094,7 @@ psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
  *         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
@@ -1110,11 +1116,7 @@ psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
  * 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
@@ -1123,8 +1125,6 @@ psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
  * \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
@@ -1152,9 +1152,9 @@ psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
  *
  * \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

From 9f208cc8c24a6dc3b1e861a6d3c1bd97dc444c83 Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Wed, 11 Sep 2019 23:04:42 +0100
Subject: [PATCH 3/8] Update documentation for multipart mac operations

---
 include/psa/crypto.h | 54 +++++++++++++++++++++++---------------------
 1 file changed, 28 insertions(+), 26 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index d3ba75e75..0ec67d7fc 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1318,7 +1318,7 @@ static psa_mac_operation_t psa_mac_operation_init(void);
  * -# 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
@@ -1326,13 +1326,15 @@ static psa_mac_operation_t psa_mac_operation_init(void);
  * -# 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
@@ -1358,8 +1360,7 @@ static psa_mac_operation_t psa_mac_operation_init(void);
  * \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
@@ -1378,7 +1379,7 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
  * -# 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
@@ -1387,13 +1388,15 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
  *    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
@@ -1419,8 +1422,7 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
  * \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
@@ -1435,7 +1437,8 @@ psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
  * 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
@@ -1445,7 +1448,7 @@ psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
  * \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
@@ -1466,7 +1469,9 @@ psa_status_t psa_mac_update(psa_mac_operation_t *operation,
  * 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.
@@ -1489,7 +1494,8 @@ psa_status_t psa_mac_update(psa_mac_operation_t *operation,
  * \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().
@@ -1517,7 +1523,9 @@ psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
  * 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
@@ -1533,7 +1541,8 @@ psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
  *         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
@@ -1556,12 +1565,7 @@ psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
  * 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
@@ -1570,8 +1574,6 @@ psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
  * \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

From db6f44f875dbdc19a16aaaba3a504c2ee53702e2 Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Wed, 11 Sep 2019 23:33:30 +0100
Subject: [PATCH 4/8] Update documentation for multipart cipher operations

---
 include/psa/crypto.h | 64 +++++++++++++++++++++++---------------------
 1 file changed, 33 insertions(+), 31 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 0ec67d7fc..bf7fd18fa 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1593,7 +1593,8 @@ psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
 /** 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 @@ static psa_cipher_operation_t psa_cipher_operation_init(void);
  *    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 @@ static psa_cipher_operation_t psa_cipher_operation_init(void);
  *    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 @@ static psa_cipher_operation_t psa_cipher_operation_init(void);
  * \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 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
  *    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 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
  *    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 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
  * \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 @@ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
  * 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 @@ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
  * \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 @@ psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
  * 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 @@ psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
  * \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 @@ psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
  * 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 @@ psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
  * \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 @@ psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
  * 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 @@ psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
  *         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_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
  * 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 @@ psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
  * \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

From 414415a45707dd49b7e30cb163516483a348a8a6 Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Thu, 12 Sep 2019 00:02:45 +0100
Subject: [PATCH 5/8] Update documentation for multipart aead operations

---
 include/psa/crypto.h | 92 ++++++++++++++++++++++++--------------------
 1 file changed, 50 insertions(+), 42 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index bf7fd18fa..f677afe60 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2239,7 +2239,7 @@ static psa_aead_operation_t psa_aead_operation_init(void);
  *    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
@@ -2255,14 +2255,16 @@ static psa_aead_operation_t psa_aead_operation_init(void);
  *    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
@@ -2277,8 +2279,7 @@ static psa_aead_operation_t psa_aead_operation_init(void);
  * \retval #PSA_SUCCESS
  *         Success.
  * \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_INVALID_HANDLE
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
@@ -2307,7 +2308,7 @@ psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
  *    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
@@ -2320,14 +2321,16 @@ psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
  *    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
@@ -2342,8 +2345,7 @@ psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
  * \retval #PSA_SUCCESS
  *         Success.
  * \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_INVALID_HANDLE
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
@@ -2373,7 +2375,8 @@ psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
  * 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
@@ -2385,7 +2388,8 @@ psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
  * \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
@@ -2408,10 +2412,11 @@ psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
  * 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
@@ -2424,7 +2429,8 @@ psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
  * \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
@@ -2457,6 +2463,9 @@ psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
  *   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.
@@ -2465,8 +2474,8 @@ psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
  * \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, but before
+ *         psa_aead_update_ad() or psa_aead_update() are called).
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         At least one of the lengths is not acceptable for the chosen
  *         algorithm.
@@ -2495,7 +2504,8 @@ psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
  * 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
@@ -2511,8 +2521,8 @@ psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
  * \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 and ready to
+ *         receive additional data).
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         The total input length overflows the additional data length that
  *         was previously specified with psa_aead_set_lengths().
@@ -2539,7 +2549,8 @@ psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
  * 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
@@ -2579,8 +2590,8 @@ psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
  * \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 and ready to
+ *         recieve message data).
  * \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
@@ -2626,7 +2637,9 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation,
  *   #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
@@ -2650,8 +2663,8 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation,
  * \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 aead encrypt
+ *         operation, with all data provided).
  * \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
@@ -2694,7 +2707,9 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
  * psa_aead_update_ad() with the ciphertext formed by concatenating the
  * inputs passed to preceding calls to psa_aead_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_aead_abort().
  *
  * \param[in,out] operation     Active AEAD operation.
  * \param[out] plaintext        Buffer where the last part of the plaintext
@@ -2715,8 +2730,8 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
  * \retval #PSA_SUCCESS
  *         Success.
  * \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 aead decrypt
+ *         operation, with all data provided).
  * \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
@@ -2755,22 +2770,15 @@ psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
  * 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

From beb97ba0663d05a3cc946cb877f4ed6c6864e0d9 Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Fri, 13 Sep 2019 15:27:46 +0100
Subject: [PATCH 6/8] Update documentation for multipart key derivation
 operations

---
 include/psa/crypto.h | 90 +++++++++++++++++++++++++++-----------------
 1 file changed, 56 insertions(+), 34 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index f677afe60..d2788caab 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -3071,23 +3071,29 @@ static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
  * 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 @@ static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
  * \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 @@ psa_status_t psa_key_derivation_setup(
  * \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 @@ psa_status_t psa_key_derivation_get_capacity(
  *         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 @@ psa_status_t psa_key_derivation_set_capacity(
  * 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 @@ psa_status_t psa_key_derivation_set_capacity(
  * \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 @@ psa_status_t psa_key_derivation_input_bytes(
  * 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 @@ psa_status_t psa_key_derivation_input_bytes(
  * \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 @@ psa_status_t psa_key_derivation_input_key(
  * 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 @@ psa_status_t psa_key_derivation_input_key(
  * \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 @@ psa_status_t psa_key_derivation_key_agreement(
  * 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 @@ psa_status_t psa_key_derivation_key_agreement(
  *                          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 @@ psa_status_t psa_key_derivation_output_bytes(
  * 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 @@ psa_status_t psa_key_derivation_output_bytes(
  * \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 @@ psa_status_t psa_key_derivation_output_key(
 /** 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

From 4104afb7708785ee8950a65d82eabf009f44e069 Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Wed, 18 Sep 2019 17:47:25 +0100
Subject: [PATCH 7/8] Clarify valid state descriptions

---
 include/psa/crypto.h | 26 ++++++++++++++------------
 1 file changed, 14 insertions(+), 12 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index d2788caab..bce8e2be4 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1593,8 +1593,8 @@ psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
 /** Encrypt a message using a symmetric cipher.
  *
  * This function encrypts a message with a random IV (initialization
- * vector). Use the multipart #psa_cipher_operation_t object to provide
- * other foms of IV.
+ * 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
@@ -2474,8 +2474,9 @@ psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid (it must be active, but before
- *         psa_aead_update_ad() or psa_aead_update() are 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.
@@ -2521,8 +2522,9 @@ psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid (it must be active and ready to
- *         receive additional data).
+ *         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().
@@ -2590,8 +2592,8 @@ psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid (it must be active and ready to
- *         recieve message data).
+ *         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
@@ -2663,8 +2665,8 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation,
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid (it must be an active aead encrypt
- *         operation, with all data provided).
+ *         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
@@ -2730,8 +2732,8 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid (it must be an active aead decrypt
- *         operation, with all data provided).
+ *         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

From 51514f57e914db438b48575edf4797c9e169f0bd Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Wed, 18 Sep 2019 17:50:01 +0100
Subject: [PATCH 8/8] Resolve inconsistent descipriton of operation state after
 exhausting a key derivation operation

---
 include/psa/crypto.h | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index bce8e2be4..f0ad9b267 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -3359,10 +3359,11 @@ psa_status_t psa_key_derivation_key_agreement(
  * stream.
  * The operation's capacity decreases by the number of bytes read.
  *
- * If this function returns an error status, the operation enters an error
+ * 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[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.
  *
@@ -3401,7 +3402,8 @@ psa_status_t psa_key_derivation_output_bytes(
  * stream.
  * The operation's capacity decreases by the number of bytes read.
  *
- * If this function returns an error status, the operation enters an error
+ * 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
@@ -3521,7 +3523,6 @@ psa_status_t psa_key_derivation_output_key(
 
 /** 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. Once aborted, the operation object can be reused
  * for another operation by calling psa_key_derivation_setup() again.