diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 1643b2e352..5f4a9bef2b 100644 --- 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. - * \retval #PSA_ERROR_INVALID_ARGUMENT - * The policy constraints on the source and specified in - * \p attributes are incompatible. - * \retval #PSA_ERROR_INVALID_ARGUMENT + * The lifetime or identifier in \p attributes are invalid, or + * the policy constraints on the source and specified in + * \p attributes are incompatible, or * \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. - * \retval #PSA_ERROR_NOT_PERMITTED - * The source key is not exportable and its lifetime does not + * The source key does not have the #PSA_KEY_USAGE_COPY usage flag, or + * 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. - * \retval #PSA_ERROR_INVALID_ARGUMENT - * The key data is not correctly formatted. - * \retval #PSA_ERROR_INVALID_ARGUMENT - * The size in \p attributes is nonzero and does not match the size + * The key attributes, as a whole, are invalid, or + * the key data is not correctly formatted, or + * 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). - * \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. */ @@ -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). - * \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. */ @@ -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). - * \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. */ @@ -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). - * \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. */ @@ -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(). - * \retval #PSA_ERROR_INVALID_ARGUMENT - * The total input length overflows the plaintext length that + * specified with psa_aead_set_lengths(), or + * 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(). - * \retval #PSA_ERROR_INVALID_ARGUMENT - * The total length of input to psa_aead_update() so far is + * specified with psa_aead_set_lengths(), or + * 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(). - * \retval #PSA_ERROR_INVALID_ARGUMENT - * The total length of input to psa_aead_update() so far is + * specified with psa_aead_set_lengths(), or + * 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). - * \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. */ @@ -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. - * \retval #PSA_ERROR_INVALID_ARGUMENT + * \c step is not compatible with the operation's algorithm, or * \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. - * \retval #PSA_ERROR_BAD_STATE - * The library has not been previously initialized by psa_crypto_init(). + * The operation state is not valid for this input \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. */ @@ -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. - * \retval #PSA_ERROR_INVALID_ARGUMENT + * \c step is not compatible with the operation's algorithm, or * \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. - * \retval #PSA_ERROR_BAD_STATE - * The library has not been previously initialized by psa_crypto_init(). + * The operation state is not valid for this input \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. */ @@ -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. - * \retval #PSA_ERROR_INVALID_ARGUMENT + * \c step is not compatible with the operation's algorithm, or * \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. - * \retval #PSA_ERROR_BAD_STATE - * The library has not been previously initialized by psa_crypto_init(). + * The operation state is not valid for this input \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. */ @@ -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 - * \retval #PSA_ERROR_INVALID_ARGUMENT + * \p alg is not a key agreement algorithm, or * \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. diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h index 1f68925ff6..df28fefa60 100644 --- 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. - * \retval #PSA_ERROR_INVALID_ARGUMENT + * not in the user range, or * \p attributes specifies a lifetime which is not located - * in a secure element. - * \retval #PSA_ERROR_INVALID_ARGUMENT - * No slot number is specified in \p attributes, + * in a secure element, or 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 - * The operation state is not valid (it must have been set up.) + * \retval #PSA_ERROR_INVALID_ARGUMENT + * \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 - * The operation state is not valid. + * \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. */ @@ -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 - * The operation state is not valid (it must be active, but beyond that - * validity is specific to the algorithm). + * \retval #PSA_ERROR_INVALID_ARGUMENT + * The input is not valid for the algorithm, ciphersuite or \p step. * \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. */