Merge pull request #11 from gilles-peskine-arm/psa-setup_bad_state-document
Document that multipart operation setup can return BAD_STATE
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 25c3cb4..b62788b 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -782,7 +782,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:
@@ -816,6 +816,9 @@
* Success.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a hash algorithm.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (already set up and not
+ * subsequently completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
@@ -837,7 +840,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
@@ -874,7 +877,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)
@@ -914,7 +917,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
@@ -1032,7 +1035,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.
@@ -1082,6 +1085,9 @@
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (already set up and not
+ * subsequently completed).
+ * \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.
@@ -1090,7 +1096,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.
@@ -1139,6 +1145,9 @@
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (already set up and not
+ * subsequently completed).
+ * \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.
@@ -1162,7 +1171,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
@@ -1201,7 +1210,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().
@@ -1240,7 +1249,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
@@ -1384,6 +1393,9 @@
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (already set up and not
+ * subsequently completed).
+ * \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.
@@ -1443,6 +1455,9 @@
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (already set up and not
+ * subsequently completed).
+ * \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.
@@ -1471,7 +1486,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
@@ -1505,7 +1520,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.
@@ -1541,7 +1556,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.
@@ -1579,7 +1594,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.