yuzu-emu/mbedtls
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #11 from gilles-peskine-arm/psa-setup_bad_state-document

Browse source 
Document that multipart operation setup can return BAD_STATE
This commit is contained in:
Jaeden Amero 2019-02-19 10:24:23 +00:00 committed by GitHub
commit 7e2cda1d67
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 28 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
include/psa/crypto.h
View file

@ -782,7 +782,7 @@ typedef struct psa_hash_operation_s psa_hash_operation_t;
*/ */
static psa_hash_operation_t psa_hash_operation_init(void); static psa_hash_operation_t psa_hash_operation_init(void);
/** Start a multipart hash operation. /** Set up a multipart hash operation.
* *
* The sequence of operations to calculate a hash (message digest) * The sequence of operations to calculate a hash (message digest)
* is as follows: * is as follows:
@ -816,6 +816,9 @@ static psa_hash_operation_t psa_hash_operation_init(void);
* Success. * Success.
* \retval #PSA_ERROR_NOT_SUPPORTED * \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a hash algorithm. * \p alg is not supported or is not a hash algorithm.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (already set up and not
* subsequently completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE
@ -837,7 +840,7 @@ psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* Success. * Success.
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or already completed). * The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE
@ -874,7 +877,7 @@ psa_status_t psa_hash_update(psa_hash_operation_t *operation,
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* Success. * Success.
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or already completed). * The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL * \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p hash buffer is too small. You can determine a * The size of the \p hash buffer is too small. You can determine a
* sufficient buffer size by calling #PSA_HASH_SIZE(\c alg) * sufficient buffer size by calling #PSA_HASH_SIZE(\c alg)
@ -914,7 +917,7 @@ psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
* The hash of the message was calculated successfully, but it * The hash of the message was calculated successfully, but it
* differs from the expected hash. * differs from the expected hash.
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or already completed). * The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE
@ -1032,7 +1035,7 @@ typedef struct psa_mac_operation_s psa_mac_operation_t;
*/ */
static psa_mac_operation_t psa_mac_operation_init(void); static psa_mac_operation_t psa_mac_operation_init(void);
/** Start a multipart MAC calculation operation. /** Set up a multipart MAC calculation operation.
* *
* This function sets up the calculation of the MAC * This function sets up the calculation of the MAC
* (message authentication code) of a byte string. * (message authentication code) of a byte string.
@ -1082,6 +1085,9 @@ static psa_mac_operation_t psa_mac_operation_init(void);
* \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED * \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (already set up and not
* subsequently completed).
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init(). * The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize * It is implementation-dependent whether a failure to initialize
* results in this error code. * results in this error code.
@ -1090,7 +1096,7 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
psa_key_handle_t handle, psa_key_handle_t handle,
psa_algorithm_t alg); psa_algorithm_t alg);
/** Start a multipart MAC verification operation. /** Set up a multipart MAC verification operation.
* *
* This function sets up the verification of the MAC * This function sets up the verification of the MAC
* (message authentication code) of a byte string against an expected value. * (message authentication code) of a byte string against an expected value.
@ -1139,6 +1145,9 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
* \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED * \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (already set up and not
* subsequently completed).
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init(). * The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize * It is implementation-dependent whether a failure to initialize
* results in this error code. * results in this error code.
@ -1162,7 +1171,7 @@ psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* Success. * Success.
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or already completed). * The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE
@ -1201,7 +1210,7 @@ psa_status_t psa_mac_update(psa_mac_operation_t *operation,
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* Success. * Success.
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or already completed). * The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL * \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p mac buffer is too small. You can determine a * The size of the \p mac buffer is too small. You can determine a
* sufficient buffer size by calling PSA_MAC_FINAL_SIZE(). * sufficient buffer size by calling PSA_MAC_FINAL_SIZE().
@ -1240,7 +1249,7 @@ psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
* The MAC of the message was calculated successfully, but it * The MAC of the message was calculated successfully, but it
* differs from the expected MAC. * differs from the expected MAC.
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or already completed). * The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE
@ -1384,6 +1393,9 @@ static psa_cipher_operation_t psa_cipher_operation_init(void);
* \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED * \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (already set up and not
* subsequently completed).
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init(). * The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize * It is implementation-dependent whether a failure to initialize
* results in this error code. * results in this error code.
@ -1443,6 +1455,9 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
* \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED * \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (already set up and not
* subsequently completed).
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init(). * The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize * It is implementation-dependent whether a failure to initialize
* results in this error code. * results in this error code.
@ -1471,7 +1486,7 @@ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* Success. * Success.
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or IV already set). * The operation state is not valid (not set up, or IV already set).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL * \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p iv buffer is too small. * The size of the \p iv buffer is too small.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@ -1505,7 +1520,7 @@ psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* Success. * Success.
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or IV already set). * The operation state is not valid (not set up, or IV already set).
* \retval #PSA_ERROR_INVALID_ARGUMENT * \retval #PSA_ERROR_INVALID_ARGUMENT
* The size of \p iv is not acceptable for the chosen algorithm, * The size of \p iv is not acceptable for the chosen algorithm,
* or the chosen algorithm does not use an IV. * or the chosen algorithm does not use an IV.
@ -1541,7 +1556,7 @@ psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* Success. * Success.
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, IV required but * The operation state is not valid (not set up, IV required but
* not set, or already completed). * not set, or already completed).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL * \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p output buffer is too small. * The size of the \p output buffer is too small.
@ -1579,7 +1594,7 @@ psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* Success. * Success.
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, IV required but * The operation state is not valid (not set up, IV required but
* not set, or already completed). * not set, or already completed).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL * \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p output buffer is too small. * The size of the \p output buffer is too small.