From f45adda9ac7519124d754199cd3fd134c873f079 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 14 Jan 2019 18:29:18 +0100 Subject: [PATCH] Copyedit the documentation of multipart operation functions Finish changing "start" to "set up". Correct the way to set an IV for decryption: it's set_iv(), not update(). When decrypting, the IV is given, not random. --- include/psa/crypto.h | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 931a768a4..cbb6cfb0c 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -756,7 +756,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: @@ -811,7 +811,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 @@ -848,7 +848,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) @@ -888,7 +888,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 @@ -979,7 +979,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. @@ -1037,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. @@ -1109,7 +1109,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 @@ -1148,7 +1148,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(). @@ -1187,7 +1187,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 @@ -1303,8 +1303,7 @@ static psa_cipher_operation_t psa_cipher_operation_init(void); * After a successful call to psa_cipher_encrypt_setup(), the application must * eventually terminate the operation. The following events terminate an * operation: - * - A failed call to psa_cipher_generate_iv(), psa_cipher_set_iv() - * or psa_cipher_update(). + * - A failed call to any of the \c psa_cipher_xxx functions. * - A call to psa_cipher_finish() or psa_cipher_abort(). * * \param[in,out] operation The operation object to set up. It must have @@ -1349,7 +1348,7 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, * documentation for #psa_cipher_operation_t, e.g. * PSA_CIPHER_OPERATION_INIT. * -# Call psa_cipher_decrypt_setup() to specify the algorithm and key. - * -# Call psa_cipher_update() with the IV (initialization vector) for the + * -# Call psa_cipher_set_iv() with the IV (initialization vector) for the * decryption. If the IV is prepended to the ciphertext, you can call * psa_cipher_update() on a buffer containing the IV followed by the * beginning of the message. @@ -1363,7 +1362,7 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, * After a successful call to psa_cipher_decrypt_setup(), the application must * eventually terminate the operation. The following events terminate an * operation: - * - A failed call to psa_cipher_update(). + * - A failed call to any of the \c psa_cipher_xxx functions. * - A call to psa_cipher_finish() or psa_cipher_abort(). * * \param[in,out] operation The operation object to set up. It must have @@ -1418,7 +1417,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 @@ -1433,7 +1432,7 @@ psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation, /** Set the IV for a symmetric encryption or decryption operation. * - * This function sets the random IV (initialization vector), nonce + * This function sets the IV (initialization vector), nonce * or initial counter value for the encryption or decryption operation. * * The application must call psa_cipher_encrypt_setup() before @@ -1452,7 +1451,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. @@ -1488,7 +1487,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. @@ -1526,7 +1525,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.