Skip to content

Document that multipart operation setup can return BAD_STATE #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 19, 2019
Merged

Document that multipart operation setup can return BAD_STATE #11

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
76d7bfe
Terminology: consistently use "set up" for multipart operations
gilles-peskine-arm Jan 10, 2019
8e1addc
Document BAD_STATE errors for multipart operation setup functions
gilles-peskine-arm Jan 10, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 28 additions & 13 deletions include/psa/crypto.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -750,7 +750,7 @@ typedef struct psa_hash_operation_s psa_hash_operation_t;
*/
static psa_hash_operation_t psa_hash_operation_init(void);

/** Start a multipart hash operation.
/** Set up a multipart hash operation.
*
* The sequence of operations to calculate a hash (message digest)
* is as follows:
Expand Down Expand Up @@ -784,6 +784,9 @@ static psa_hash_operation_t psa_hash_operation_init(void);
* Success.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a hash algorithm.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (already set up and not
* subsequently completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
Expand All @@ -805,7 +808,7 @@ psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or already completed).
* The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
Expand Down Expand Up @@ -842,7 +845,7 @@ psa_status_t psa_hash_update(psa_hash_operation_t *operation,
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or already completed).
* The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p hash buffer is too small. You can determine a
* sufficient buffer size by calling #PSA_HASH_SIZE(\c alg)
Expand Down Expand Up @@ -882,7 +885,7 @@ psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
* The hash of the message was calculated successfully, but it
* differs from the expected hash.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or already completed).
* The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
Expand Down Expand Up @@ -973,7 +976,7 @@ typedef struct psa_mac_operation_s psa_mac_operation_t;
*/
static psa_mac_operation_t psa_mac_operation_init(void);

/** Start a multipart MAC calculation operation.
/** Set up a multipart MAC calculation operation.
*
* This function sets up the calculation of the MAC
* (message authentication code) of a byte string.
Expand Down Expand Up @@ -1023,6 +1026,9 @@ static psa_mac_operation_t psa_mac_operation_init(void);
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (already set up and not
* subsequently completed).
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
* results in this error code.
Expand All @@ -1031,7 +1037,7 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
psa_key_handle_t handle,
psa_algorithm_t alg);

/** Start a multipart MAC verification operation.
/** Set up a multipart MAC verification operation.
*
* This function sets up the verification of the MAC
* (message authentication code) of a byte string against an expected value.
Expand Down Expand Up @@ -1080,6 +1086,9 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (already set up and not
* subsequently completed).
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
* results in this error code.
Expand All @@ -1103,7 +1112,7 @@ psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or already completed).
* The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
Expand Down Expand Up @@ -1142,7 +1151,7 @@ psa_status_t psa_mac_update(psa_mac_operation_t *operation,
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or already completed).
* The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p mac buffer is too small. You can determine a
* sufficient buffer size by calling PSA_MAC_FINAL_SIZE().
Expand Down Expand Up @@ -1181,7 +1190,7 @@ psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
* The MAC of the message was calculated successfully, but it
* differs from the expected MAC.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or already completed).
* The operation state is not valid (not set up, or already completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
Expand Down Expand Up @@ -1325,6 +1334,9 @@ static psa_cipher_operation_t psa_cipher_operation_init(void);
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (already set up and not
* subsequently completed).
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
* results in this error code.
Expand Down Expand Up @@ -1384,6 +1396,9 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (already set up and not
* subsequently completed).
* \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
* results in this error code.
Expand Down Expand Up @@ -1412,7 +1427,7 @@ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or IV already set).
* The operation state is not valid (not set up, or IV already set).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p iv buffer is too small.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Expand Down Expand Up @@ -1446,7 +1461,7 @@ psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or IV already set).
* The operation state is not valid (not set up, or IV already set).
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The size of \p iv is not acceptable for the chosen algorithm,
* or the chosen algorithm does not use an IV.
Expand Down Expand Up @@ -1482,7 +1497,7 @@ psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, IV required but
* The operation state is not valid (not set up, IV required but
* not set, or already completed).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p output buffer is too small.
Expand Down Expand Up @@ -1520,7 +1535,7 @@ psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, IV required but
* The operation state is not valid (not set up, IV required but
* not set, or already completed).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p output buffer is too small.
Expand Down