doxygen: merge multiple descriptions of the same return codes

Organize some of the errors in a better way. Signed-off-by: Andrzej Kurek <andrzej.kurek@arm.com>
2022-02-03 11:30:54 -05:00 · 2022-02-03 11:30:54 -05:00 · f7c1f747e2
commit f7c1f747e2
parent 1ab2d6966c
2 changed files with 146 additions and 208 deletions
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@ -493,17 +493,14 @@ psa_status_t psa_purge_key(mbedtls_svc_key_id_t key);
 *         This is an attempt to create a persistent key, and there is
 *         already a persistent key with the given identifier.
 * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         The lifetime or identifier in \p attributes are invalid.
+ *         The lifetime or identifier in \p attributes are invalid, or
- * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         the policy constraints on the source and specified in
- *         The policy constraints on the source and specified in
+ *         \p attributes are incompatible, or
 *         \p attributes are incompatible.
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         \p attributes specifies a key type or key size
 *         which does not match the attributes of the source key.
 * \retval #PSA_ERROR_NOT_PERMITTED
- *         The source key does not have the #PSA_KEY_USAGE_COPY usage flag.
+ *         The source key does not have the #PSA_KEY_USAGE_COPY usage flag, or
- * \retval #PSA_ERROR_NOT_PERMITTED
+ *         the source key is not exportable and its lifetime does not
 *         The source key is not exportable and its lifetime does not
 *         allow copying it to the target's lifetime.
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
@ -630,11 +627,9 @@ psa_status_t psa_destroy_key(mbedtls_svc_key_id_t key);
 *         The key type or key size is not supported, either by the
 *         implementation in general or in this particular persistent location.
 * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         The key attributes, as a whole, are invalid.
+ *         The key attributes, as a whole, are invalid, or
- * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         the key data is not correctly formatted, or
- *         The key data is not correctly formatted.
+ *         the size in \p attributes is nonzero and does not match the size
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         The size in \p attributes is nonzero and does not match the size
 *         of the key data.
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
@ -858,7 +853,6 @@ psa_status_t psa_export_public_key(mbedtls_svc_key_id_t key,
 * \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 library has not been previously initialized by psa_crypto_init().
 *         It is implementation-dependent whether a failure to initialize
@ -894,7 +888,6 @@ psa_status_t psa_hash_compute(psa_algorithm_t alg,
 * \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 library has not been previously initialized by psa_crypto_init().
 *         It is implementation-dependent whether a failure to initialize
@ -984,14 +977,13 @@ static psa_hash_operation_t psa_hash_operation_init(void);
 *         \p alg is not a supported hash algorithm.
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         \p alg is not a hash algorithm.
 * \retval #PSA_ERROR_BAD_STATE
 *         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
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be inactive), or
 *         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.
 */
@ -1011,14 +1003,13 @@ 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 (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 library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active), or
 *         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.
 */
@ -1054,8 +1045,6 @@ 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 (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_LENGTH(\c alg)
@ -1065,7 +1054,8 @@ 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 library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active), or
 *         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.
 */
@ -1100,14 +1090,13 @@ psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
 * \retval #PSA_ERROR_INVALID_SIGNATURE
 *         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 (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 library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active), or
 *         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.
 */
@ -1158,16 +1147,14 @@ psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
 *                                  It must be initialized but not active.
 *
 * \retval #PSA_SUCCESS
 * \retval #PSA_ERROR_BAD_STATE
 *         The \p source_operation state is not valid (it must be active).
 * \retval #PSA_ERROR_BAD_STATE
 *         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 library has not been previously initialized by psa_crypto_init().
+ *         The \p source_operation state is not valid (it must be active), or
 *         the \p target_operation state is not valid (it must be inactive), or
 *         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.
 */
@ -1364,9 +1351,8 @@ 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 (it must be inactive).
+ *         The operation state is not valid (it must be inactive), or
- * \retval #PSA_ERROR_BAD_STATE
+ *         the library has not been previously initialized by psa_crypto_init().
 *         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.
 */
@ -1425,11 +1411,10 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
 * \retval #PSA_ERROR_HARDWARE_FAILURE
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
- *         The key could not be retrieved from storage
+ *         The key could not be retrieved from storage.
 * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid (it must be inactive).
+ *         The operation state is not valid (it must be inactive), or
- * \retval #PSA_ERROR_BAD_STATE
+ *         the library has not been previously initialized by psa_crypto_init().
 *         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.
 */
@ -1452,15 +1437,14 @@ 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 (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_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active), or
 *         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.
 */
@ -1498,9 +1482,6 @@ 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 (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_LENGTH().
@ -1510,7 +1491,9 @@ psa_status_t psa_mac_update(psa_mac_operation_t *operation,
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be an active mac sign
 *         operation), or 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.
 */
@ -1545,16 +1528,15 @@ psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
 * \retval #PSA_ERROR_INVALID_SIGNATURE
 *         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 (it must be an active mac verify
 *         operation).
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
 * \retval #PSA_ERROR_HARDWARE_FAILURE
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be an active mac verify
 *         operation), or 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.
 */
@ -1783,9 +1765,8 @@ 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 (it must be inactive).
+ *         The operation state is not valid (it must be inactive), or
- * \retval #PSA_ERROR_BAD_STATE
+ *         the library has not been previously initialized by psa_crypto_init().
 *         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.
 */
@ -1847,9 +1828,8 @@ 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 (it must be inactive).
+ *         The operation state is not valid (it must be inactive), or
- * \retval #PSA_ERROR_BAD_STATE
+ *         the library has not been previously initialized by psa_crypto_init().
 *         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.
 */
@ -1877,8 +1857,6 @@ 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 (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
@ -1887,7 +1865,9 @@ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active, with no IV set),
 *         or 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.
 */
@ -1917,9 +1897,6 @@ 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 (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.
@ -1929,7 +1906,9 @@ psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be an active cipher
 *         encrypt operation, with no IV set), or 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.
 */
@ -1960,9 +1939,6 @@ 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 (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
@ -1971,7 +1947,9 @@ psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active, with an IV set
 *         if required for the algorithm), or 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.
 */
@ -2013,9 +1991,6 @@ psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
 * \retval #PSA_ERROR_INVALID_PADDING
 *         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 (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
@ -2024,7 +1999,9 @@ psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active, with an IV set
 *         if required for the algorithm), or 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.
 */
@ -2301,7 +2278,8 @@ 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 (it must be inactive).
+ *         The operation state is not valid (it must be inactive), or
 *         the library has not been previously initialized by psa_crypto_init().
 * \retval #PSA_ERROR_INVALID_HANDLE
 * \retval #PSA_ERROR_NOT_PERMITTED
 * \retval #PSA_ERROR_INVALID_ARGUMENT
@ -2313,7 +2291,6 @@ static psa_aead_operation_t psa_aead_operation_init(void);
 * \retval #PSA_ERROR_HARDWARE_FAILURE
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \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.
@ -2367,8 +2344,6 @@ 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 (it must be inactive).
 * \retval #PSA_ERROR_INVALID_HANDLE
 * \retval #PSA_ERROR_NOT_PERMITTED
 * \retval #PSA_ERROR_INVALID_ARGUMENT
@ -2381,7 +2356,8 @@ psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be inactive), or 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.
 */
@ -2410,9 +2386,6 @@ 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 (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
@ -2421,7 +2394,9 @@ psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be an active aead encrypt
 *         operation, with no nonce set), or 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.
 */
@ -2451,9 +2426,6 @@ 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 (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
@ -2462,7 +2434,9 @@ psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active, with no nonce
 *         set), or 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.
 */
@ -2496,10 +2470,6 @@ 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, 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.
@ -2508,7 +2478,10 @@ psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
 * \retval #PSA_ERROR_HARDWARE_FAILURE
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         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), or 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.
 */
@ -2544,10 +2517,6 @@ 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, 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().
@ -2557,7 +2526,10 @@ psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         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), or 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.
 */
@ -2622,9 +2594,6 @@ 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, 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.
 *         #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c key_type, \c alg, \p input_length) or
@ -2633,9 +2602,8 @@ psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         The total length of input to psa_aead_update_ad() so far is
 *         less than the additional data length that was previously
- *         specified with psa_aead_set_lengths().
+ *         specified with psa_aead_set_lengths(), or
- * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         the total input length overflows the plaintext length that
 *         The total input length overflows the plaintext length that
 *         was previously specified with psa_aead_set_lengths().
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
@ -2643,7 +2611,9 @@ psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active, have a nonce
 *         set, and have lengths set if required by the algorithm), or 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.
 */
@ -2707,9 +2677,6 @@ 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 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.
 *         #PSA_AEAD_FINISH_OUTPUT_SIZE(\c key_type, \c alg) or
@ -2720,9 +2687,8 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation,
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         The total length of input to psa_aead_update_ad() so far is
 *         less than the additional data length that was previously
- *         specified with psa_aead_set_lengths().
+ *         specified with psa_aead_set_lengths(), or
- * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         the total length of input to psa_aead_update() so far is
 *         The total length of input to psa_aead_update() so far is
 *         less than the plaintext length that was previously
 *         specified with psa_aead_set_lengths().
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@ -2731,7 +2697,9 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation,
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be an active encryption
 *         operation with a nonce set), or 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.
 */
@ -2794,9 +2762,6 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
 * \retval #PSA_ERROR_INVALID_SIGNATURE
 *         The calculations were successful, but the authentication tag is
 *         not correct.
 * \retval #PSA_ERROR_BAD_STATE
 *         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.
 *         #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c key_type, \c alg) or
@ -2805,9 +2770,8 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         The total length of input to psa_aead_update_ad() so far is
 *         less than the additional data length that was previously
- *         specified with psa_aead_set_lengths().
+ *         specified with psa_aead_set_lengths(), or
- * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         the total length of input to psa_aead_update() so far is
 *         The total length of input to psa_aead_update() so far is
 *         less than the plaintext length that was previously
 *         specified with psa_aead_set_lengths().
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@ -2816,7 +2780,9 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be an active decryption
 *         operation with a nonce set), or 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.
 */
@ -3303,9 +3269,8 @@ 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 not valid (it must be inactive).
+ *         The operation state is not valid (it must be inactive), or
- * \retval #PSA_ERROR_BAD_STATE
+ *         the library has not been previously initialized by psa_crypto_init().
 *         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.
 */
@ -3324,12 +3289,11 @@ 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 (it must be active).
 * \retval #PSA_ERROR_HARDWARE_FAILURE
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active), or
 *         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.
 */
@ -3352,13 +3316,12 @@ psa_status_t psa_key_derivation_get_capacity(
 *         \p capacity is larger than the operation's current 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 (it must be active).
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
 * \retval #PSA_ERROR_HARDWARE_FAILURE
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active), or 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.
 */
@ -3402,8 +3365,7 @@ psa_status_t psa_key_derivation_set_capacity(
 * \retval #PSA_SUCCESS
 *         Success.
 * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \c step is not compatible with the operation's algorithm.
+ *         \c step is not compatible with the operation's algorithm, or
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         \c step does not allow direct inputs.
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
@ -3411,9 +3373,8 @@ psa_status_t psa_key_derivation_set_capacity(
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid for this input \p step.
+ *         The operation state is not valid for this input \p step, or
- * \retval #PSA_ERROR_BAD_STATE
+ *         the library has not been previously initialized by psa_crypto_init().
 *         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.
 */
@ -3447,8 +3408,7 @@ psa_status_t psa_key_derivation_input_bytes(
 * \retval #PSA_SUCCESS
 *         Success.
 * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \c step is not compatible with the operation's algorithm.
+ *         \c step is not compatible with the operation's algorithm, or
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         \c step does not allow numeric inputs.
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
@ -3456,9 +3416,8 @@ psa_status_t psa_key_derivation_input_bytes(
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid for this input \p step.
+ *         The operation state is not valid for this input \p step, or
- * \retval #PSA_ERROR_BAD_STATE
+ *         the library has not been previously initialized by psa_crypto_init().
 *         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.
 */
@ -3515,8 +3474,7 @@ psa_status_t psa_key_derivation_input_integer(
 *         #PSA_KEY_USAGE_VERIFY_DERIVATION, or it doesn't allow this
 *         algorithm.
 * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \c step is not compatible with the operation's algorithm.
+ *         \c step is not compatible with the operation's algorithm, or
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         \c step does not allow key inputs of the given type
 *         or does not allow key inputs at all.
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@ -3525,9 +3483,8 @@ psa_status_t psa_key_derivation_input_integer(
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid for this input \p step.
+ *         The operation state is not valid for this input \p step, or
- * \retval #PSA_ERROR_BAD_STATE
+ *         the library has not been previously initialized by psa_crypto_init().
 *         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.
 */
@ -3579,25 +3536,23 @@ psa_status_t psa_key_derivation_input_key(
 *
 * \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
 *         \c private_key is not compatible with \c alg,
 *         or \p peer_key is not valid for \c alg or not compatible with
- *         \c private_key.
+ *         \c private_key, or \c step does not allow an input resulting
 *         from a key agreement.
 * \retval #PSA_ERROR_NOT_SUPPORTED
 *         \c alg is not supported or is not a key derivation algorithm.
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         \c step does not allow an input resulting from a key agreement.
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
 * \retval #PSA_ERROR_HARDWARE_FAILURE
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid for this key agreement \p step,
 *         or 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.
 */
@ -3636,16 +3591,15 @@ psa_status_t psa_key_derivation_key_agreement(
 *                          The operation's capacity is set to 0, thus
 *                          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
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active and completed
 *         all required input steps), or 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.
 */
@ -3784,9 +3738,6 @@ psa_status_t psa_key_derivation_output_bytes(
 *         #PSA_KEY_DERIVATION_INPUT_PASSWORD input was not provided through a
 *         key; or one of the inputs was a key whose policy didn't allow
 *         #PSA_KEY_USAGE_DERIVE.
 * \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
@ -3796,7 +3747,9 @@ psa_status_t psa_key_derivation_output_bytes(
 * \retval #PSA_ERROR_DATA_CORRUPT
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active and completed
 *         all required input steps), or 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.
 */
@ -3846,16 +3799,15 @@ psa_status_t psa_key_derivation_output_key(
 *                          the operation's capacity is set to 0, thus
 *                          subsequent calls to this function will not
 *                          succeed, even with a smaller expected output.
 * \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
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active and completed
 *         all required input steps), or 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.
 */
@ -3911,16 +3863,15 @@ psa_status_t psa_key_derivation_verify_bytes(
 *                          the operation's capacity is set to 0, thus
 *                          subsequent calls to this function will not
 *                          succeed, even with a smaller expected output.
 * \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
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active and completed
 *         all required input steps), or 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.
 */
@ -3986,8 +3937,7 @@ psa_status_t psa_key_derivation_abort(
 * \retval #PSA_ERROR_INVALID_HANDLE
 * \retval #PSA_ERROR_NOT_PERMITTED
 * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p alg is not a key agreement algorithm
+ *         \p alg is not a key agreement algorithm, or
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         \p private_key is not compatible with \p alg,
 *         or \p peer_key is not valid for \p alg or not compatible with
 *         \p private_key.
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@ -182,12 +182,9 @@ static inline void psa_clear_key_slot_number(
 *         support registering a key.
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         The identifier in \p attributes is invalid, namely the identifier is
- *         not in the user range.
+ *         not in the user range, or
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         \p attributes specifies a lifetime which is not located
- *         in a secure element.
+ *         in a secure element, or no slot number is specified in \p attributes,
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         No slot number is specified in \p attributes,
 *         or the specified slot number is not valid.
 * \retval #PSA_ERROR_NOT_PERMITTED
 *         The caller is not authorized to register the specified key slot.
@ -1349,15 +1346,14 @@ static psa_pake_operation_t psa_pake_operation_init(void);
 *
 * \retval #PSA_SUCCESS
 *         Success.
 * \retval #PSA_ERROR_BAD_STATE
 *         The operation state is not valid.
 * \retval #PSA_ERROR_NOT_SUPPORTED
 *         The \p cipher_suite is not supported or is not valid.
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
 * \retval #PSA_ERROR_HARDWARE_FAILURE
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid, or
 *         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.
 */
@ -1386,18 +1382,17 @@ psa_status_t psa_pake_setup(psa_pake_operation_t *operation,
 *
 * \retval #PSA_SUCCESS
 *         Success.
- * \retval #PSA_ERROR_BAD_STATE
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         The operation state is not valid (it must have been set up.)
+ *         \p key is not compatible with the algorithm or the cipher suite.
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_INVALID_HANDLE
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
 * \retval #PSA_ERROR_HARDWARE_FAILURE
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_NOT_PERMITTED
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         \p key is not compatible with the algorithm or the cipher suite.
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must have been set up.), or
 *         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.
 */
@ -1427,16 +1422,15 @@ psa_status_t psa_pake_set_password_key(psa_pake_operation_t *operation,
 *
 * \retval #PSA_SUCCESS
 *         Success.
- * \retval #PSA_ERROR_BAD_STATE
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         The operation state is not valid.
+ *         \p user_id is NULL.
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
 * \retval #PSA_ERROR_HARDWARE_FAILURE
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         \p user_id is NULL.
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid, or
 *         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.
 */
@ -1467,18 +1461,17 @@ psa_status_t psa_pake_set_user(psa_pake_operation_t *operation,
 *
 * \retval #PSA_SUCCESS
 *         Success.
 * \retval #PSA_ERROR_BAD_STATE
 *         The operation state is not valid.
 * \retval #PSA_ERROR_NOT_SUPPORTED
 *         The algorithm doesn't associate a second identity with the session.
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         \p user_id is NULL.
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
 * \retval #PSA_ERROR_HARDWARE_FAILURE
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         \p user_id is NULL.
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid, or 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.
 */
@ -1510,15 +1503,14 @@ psa_status_t psa_pake_set_peer(psa_pake_operation_t *operation,
 *
 * \retval #PSA_SUCCESS
 *         Success.
 * \retval #PSA_ERROR_BAD_STATE
 *         The operation state is not valid.
 * \retval #PSA_ERROR_NOT_SUPPORTED
 *         The \p side for this algorithm is not supported or is not valid.
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
 * \retval #PSA_ERROR_HARDWARE_FAILURE
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid, or
 *         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.
 */
@ -1556,9 +1548,6 @@ psa_status_t psa_pake_set_side(psa_pake_operation_t *operation,
 *
 * \retval #PSA_SUCCESS
 *         Success.
 * \retval #PSA_ERROR_BAD_STATE
 *         The operation state is not valid (it must be active, but beyond that
 *         validity is specific to the algorithm).
 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
 *         The size of the \p output buffer is too small.
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@ -1567,7 +1556,9 @@ psa_status_t psa_pake_set_side(psa_pake_operation_t *operation,
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active, but beyond that
 *         validity is specific to the algorithm), or
 *         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.
 */
@ -1602,18 +1593,17 @@ psa_status_t psa_pake_output(psa_pake_operation_t *operation,
 *
 * \retval #PSA_SUCCESS
 *         Success.
- * \retval #PSA_ERROR_BAD_STATE
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         The operation state is not valid (it must be active, but beyond that
+ *         The input is not valid for the algorithm, ciphersuite or \p step.
 *         validity is specific to the algorithm).
 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
 * \retval #PSA_ERROR_HARDWARE_FAILURE
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         The input is not valid for the algorithm, ciphersuite or \p step.
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The operation state is not valid (it must be active, but beyond that
 *         validity is specific to the algorithm), or
 *         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.
 */
@ -1657,14 +1647,6 @@ psa_status_t psa_pake_input(psa_pake_operation_t *operation,
 *
 * \retval #PSA_SUCCESS
 *         Success.
 * \retval #PSA_ERROR_BAD_STATE
 *         The PAKE operation state is not valid (it must be active, but beyond
 *         that validity is specific to the algorithm).
 * \retval #PSA_ERROR_BAD_STATE
 *         The state of \p output is not valid for
 *         the #PSA_KEY_DERIVATION_INPUT_SECRET step. This can happen if the
 *         step is out of order or the application has done this step already
 *         and it may not be repeated.
 * \retval #PSA_ERROR_INVALID_ARGUMENT
 *         #PSA_KEY_DERIVATION_INPUT_SECRET is not compatible with the output’s
 *         algorithm.
@ -1674,7 +1656,13 @@ psa_status_t psa_pake_input(psa_pake_operation_t *operation,
 * \retval #PSA_ERROR_CORRUPTION_DETECTED
 * \retval #PSA_ERROR_STORAGE_FAILURE
 * \retval #PSA_ERROR_BAD_STATE
- *         The library has not been previously initialized by psa_crypto_init().
+ *         The PAKE operation state is not valid (it must be active, but beyond
 *         that validity is specific to the algorithm), or
 *         the library has not been previously initialized by psa_crypto_init(),
 *         or the state of \p output is not valid for
 *         the #PSA_KEY_DERIVATION_INPUT_SECRET step. This can happen if the
 *         step is out of order or the application has done this step already
 *         and it may not be repeated.
 *         It is implementation-dependent whether a failure to initialize
 *         results in this error code.
 */