yuzu-emu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-11-23 17:45:38 +01:00
Code Issues Packages Projects Releases Wiki Activity

Copyedit the documentation of multipart operation functions

Browse Source 
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.
This commit is contained in:
Gilles Peskine 2019-01-14 18:29:18 +01:00
parent 5f25dd00c0
commit f45adda9ac
1 changed files with 17 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
include/psa/crypto.h
View File

@ -756,7 +756,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:
@ -811,7 +811,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
@ -848,7 +848,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)
@ -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 * 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
@ -979,7 +979,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.
@ -1037,7 +1037,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.
@ -1109,7 +1109,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
@ -1148,7 +1148,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().
@ -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 * 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
@ -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 * After a successful call to psa_cipher_encrypt_setup(), the application must
* eventually terminate the operation. The following events terminate an * eventually terminate the operation. The following events terminate an
* operation: * operation:
* - A failed call to psa_cipher_generate_iv(), psa_cipher_set_iv() * - A failed call to any of the \c psa_cipher_xxx functions.
* or psa_cipher_update().
* - A call to psa_cipher_finish() or psa_cipher_abort(). * - A call to psa_cipher_finish() or psa_cipher_abort().
* *
* \param[in,out] operation The operation object to set up. It must have * \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. * documentation for #psa_cipher_operation_t, e.g.
* PSA_CIPHER_OPERATION_INIT. * PSA_CIPHER_OPERATION_INIT.
* -# Call psa_cipher_decrypt_setup() to specify the algorithm and key. * -# 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 * decryption. If the IV is prepended to the ciphertext, you can call
* psa_cipher_update() on a buffer containing the IV followed by the * psa_cipher_update() on a buffer containing the IV followed by the
* beginning of the message. * 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 * After a successful call to psa_cipher_decrypt_setup(), the application must
* eventually terminate the operation. The following events terminate an * eventually terminate the operation. The following events terminate an
* operation: * 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(). * - A call to psa_cipher_finish() or psa_cipher_abort().
* *
* \param[in,out] operation The operation object to set up. It must have * \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 * \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
@ -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. /** 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. * or initial counter value for the encryption or decryption operation.
* *
* The application must call psa_cipher_encrypt_setup() before * 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 * \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.
@ -1488,7 +1487,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.
@ -1526,7 +1525,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.