yuzu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2025-03-24 22:15:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation for multipart cipher operations

Browse source
This commit is contained in:
Andrew Thoelke 2019-09-11 23:33:30 +01:00
parent 9f208cc8c2
commit db6f44f875
1 changed files with 33 additions and 31 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

64
include/psa/crypto.h
View file

@ -1593,7 +1593,8 @@ psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
/** Encrypt a message using a symmetric cipher. /** Encrypt a message using a symmetric cipher.
* *
* This function encrypts a message with a random IV (initialization * This function encrypts a message with a random IV (initialization
* vector). * vector). Use the multipart #psa_cipher_operation_t object to provide
* other foms of IV.
* *
* \param handle Handle to the key to use for the operation. * \param handle Handle to the key to use for the operation.
* It must remain valid until the operation * It must remain valid until the operation
@ -1737,7 +1738,7 @@ static psa_cipher_operation_t psa_cipher_operation_init(void);
* listed here. * listed here.
* -# Initialize the operation object with one of the methods described in the * -# Initialize the operation object with one of the methods described in the
* 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_encrypt_setup() to specify the algorithm and key. * -# Call psa_cipher_encrypt_setup() to specify the algorithm and key.
* -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to * -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to
* generate or set the IV (initialization vector). You should use * generate or set the IV (initialization vector). You should use
@ -1747,14 +1748,16 @@ static psa_cipher_operation_t psa_cipher_operation_init(void);
* of the message each time. * of the message each time.
* -# Call psa_cipher_finish(). * -# Call psa_cipher_finish().
* *
* The application may call psa_cipher_abort() at any time after the operation * If an error occurs at any step after a call to psa_cipher_encrypt_setup(),
* the operation will need to be reset by a call to psa_cipher_abort(). The
* application may call psa_cipher_abort() at any time after the operation
* has been initialized. * has been initialized.
* *
* 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 any of the \c psa_cipher_xxx functions. * - A successful call to psa_cipher_finish().
* - A call to psa_cipher_finish() or psa_cipher_abort(). * - A call to 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
* been initialized as per the documentation for * been initialized as per the documentation for
@ -1780,8 +1783,7 @@ static psa_cipher_operation_t psa_cipher_operation_init(void);
* \retval #PSA_ERROR_CORRUPTION_DETECTED * \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE * \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (already set up and not * The operation state is not valid (it must be inactive).
* subsequently completed).
* \retval #PSA_ERROR_BAD_STATE * \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
@ -1799,7 +1801,7 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
* listed here. * listed here.
* -# Initialize the operation object with one of the methods described in the * -# Initialize the operation object with one of the methods described in the
* 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_set_iv() 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
@ -1809,14 +1811,16 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
* of the message each time. * of the message each time.
* -# Call psa_cipher_finish(). * -# Call psa_cipher_finish().
* *
* The application may call psa_cipher_abort() at any time after the operation * If an error occurs at any step after a call to psa_cipher_decrypt_setup(),
* the operation will need to be reset by a call to psa_cipher_abort(). The
* application may call psa_cipher_abort() at any time after the operation
* has been initialized. * has been initialized.
* *
* 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 any of the \c psa_cipher_xxx functions. * - A successful call to psa_cipher_finish().
* - A call to psa_cipher_finish() or psa_cipher_abort(). * - A call to 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
* been initialized as per the documentation for * been initialized as per the documentation for
@ -1842,8 +1846,7 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
* \retval #PSA_ERROR_CORRUPTION_DETECTED * \retval #PSA_ERROR_CORRUPTION_DETECTED
* \retval #PSA_ERROR_STORAGE_FAILURE * \retval #PSA_ERROR_STORAGE_FAILURE
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (already set up and not * The operation state is not valid (it must be inactive).
* subsequently completed).
* \retval #PSA_ERROR_BAD_STATE * \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
@ -1862,7 +1865,8 @@ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
* The application must call psa_cipher_encrypt_setup() before * The application must call psa_cipher_encrypt_setup() before
* calling this function. * calling this function.
* *
* If this function returns an error status, the operation becomes inactive. * If this function returns an error status, the operation enters an error
* state and must be aborted by calling psa_cipher_abort().
* *
* \param[in,out] operation Active cipher operation. * \param[in,out] operation Active cipher operation.
* \param[out] iv Buffer where the generated IV is to be written. * \param[out] iv Buffer where the generated IV is to be written.
@ -1873,7 +1877,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 set up, or IV already set). * The operation state is not valid (it must be active, with no IV 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
@ -1899,7 +1903,8 @@ psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
* The application must call psa_cipher_encrypt_setup() before * The application must call psa_cipher_encrypt_setup() before
* calling this function. * calling this function.
* *
* If this function returns an error status, the operation becomes inactive. * If this function returns an error status, the operation enters an error
* state and must be aborted by calling psa_cipher_abort().
* *
* \note When encrypting, applications should use psa_cipher_generate_iv() * \note When encrypting, applications should use psa_cipher_generate_iv()
* instead of this function, unless implementing a protocol that requires * instead of this function, unless implementing a protocol that requires
@ -1912,7 +1917,8 @@ 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 set up, or IV already set). * The operation state is not valid (it must be an active cipher
* encrypt operation, with no IV 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.
@ -1939,7 +1945,8 @@ psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
* 2. If the algorithm requires an IV, call psa_cipher_generate_iv() * 2. If the algorithm requires an IV, call psa_cipher_generate_iv()
* (recommended when encrypting) or psa_cipher_set_iv(). * (recommended when encrypting) or psa_cipher_set_iv().
* *
* If this function returns an error status, the operation becomes inactive. * If this function returns an error status, the operation enters an error
* state and must be aborted by calling psa_cipher_abort().
* *
* \param[in,out] operation Active cipher operation. * \param[in,out] operation Active cipher operation.
* \param[in] input Buffer containing the message fragment to * \param[in] input Buffer containing the message fragment to
@ -1953,8 +1960,8 @@ 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 set up, IV required but * The operation state is not valid (it must be active, with an IV set
* not set, or already completed). * if required for the algorithm).
* \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.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@ -1985,7 +1992,9 @@ psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
* formed by concatenating the inputs passed to preceding calls to * formed by concatenating the inputs passed to preceding calls to
* psa_cipher_update(). * psa_cipher_update().
* *
* When this function returns, the operation becomes inactive. * When this function returns successfuly, the operation becomes inactive.
* If this function returns an error status, the operation enters an error
* state and must be aborted by calling psa_cipher_abort().
* *
* \param[in,out] operation Active cipher operation. * \param[in,out] operation Active cipher operation.
* \param[out] output Buffer where the output is to be written. * \param[out] output Buffer where the output is to be written.
@ -2004,8 +2013,8 @@ psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
* This is a decryption operation for an algorithm that includes * This is a decryption operation for an algorithm that includes
* padding, and the ciphertext does not contain valid padding. * padding, and the ciphertext does not contain valid padding.
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not set up, IV required but * The operation state is not valid (it must be active, with an IV set
* not set, or already completed). * if required for the algorithm).
* \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.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@ -2031,12 +2040,7 @@ psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
* psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again. * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.
* *
* You may call this function any time after the operation object has * You may call this function any time after the operation object has
* been initialized by any of the following methods: * been initialized as described in #psa_cipher_operation_t.
* - A call to psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(),
* whether it succeeds or not.
* - Initializing the \c struct to all-bits-zero.
* - Initializing the \c struct to logical zeros, e.g.
* `psa_cipher_operation_t operation = {0}`.
* *
* In particular, calling psa_cipher_abort() after the operation has been * In particular, calling psa_cipher_abort() after the operation has been
* terminated by a call to psa_cipher_abort() or psa_cipher_finish() * terminated by a call to psa_cipher_abort() or psa_cipher_finish()
@ -2045,8 +2049,6 @@ psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
* \param[in,out] operation Initialized cipher operation. * \param[in,out] operation Initialized cipher operation.
* *
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* \retval #PSA_ERROR_BAD_STATE
* \p operation is not an active cipher operation.
* \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED * \retval #PSA_ERROR_CORRUPTION_DETECTED