From 76d7bfeb0c09e816b5be289af79bc068592db00d Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 10 Jan 2019 11:47:49 +0100 Subject: [PATCH 1/2] Terminology: consistently use "set up" for multipart operations hash_setup and mac_setup used to be called hash_start and mac_start, but we've now converged on _setup as names. Finish making the terminology in the documentation consistent. --- include/psa/crypto.h | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 683feb83f..9c596883a 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -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: @@ -805,7 +805,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 @@ -842,7 +842,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) @@ -882,7 +882,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 @@ -973,7 +973,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. @@ -1031,7 +1031,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. @@ -1103,7 +1103,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 @@ -1142,7 +1142,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(). @@ -1181,7 +1181,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 @@ -1412,7 +1412,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 @@ -1446,7 +1446,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. @@ -1482,7 +1482,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. @@ -1520,7 +1520,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. From 8e1addc7109484fc0df67b90d901206d62a6d61b Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 10 Jan 2019 11:51:17 +0100 Subject: [PATCH 2/2] Document BAD_STATE errors for multipart operation setup functions Future commits will implement this and add tests. --- include/psa/crypto.h | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 9c596883a..ce35e07c7 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -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 @@ -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. @@ -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. @@ -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. @@ -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.