mirror/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-04-01 04:20:45 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Improve documentation of abort functions

Browse Source 
Explicitly state that calling abort is safe after initializing to
zero.

Explicitly state that calling abort on an inactive operation is safe,
and replace "active" by "initialized" in the description of the
parameter.

Get rid of the recommendation for implementers to try to handle
uninitialized structures safely. It's good advice in principle but
cannot be achieved in a robust way and the wording was confusing.
This commit is contained in:
Gilles Peskine 2018-07-13 15:33:43 +02:00 committed by itayzafrir
parent be42f312a8
commit b82ab6f402
1 changed files with 44 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
include/psa/crypto.h
View File

@ -1524,17 +1524,23 @@ psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
/** Abort a hash operation. /** Abort a hash operation.
* *
* This function may be called at any time after psa_hash_setup().
* Aborting an operation frees all associated resources except for the * Aborting an operation frees all associated resources except for the
* \p operation structure itself. * \p operation structure itself. Once aborted, the operation object
* can be reused for another operation by calling
* psa_hash_setup() again.
* *
* Implementation should strive to be robust and handle inactive hash * You may call this function any time after the operation object has
* operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However, * been initialized by any of the following methods:
* application writers should beware that uninitialized memory may happen * - A call to psa_hash_setup(), whether it succeeds or not.
* to be indistinguishable from an active hash operation, and the behavior * - Initializing the \c struct to all-bits-zero.
* of psa_hash_abort() is undefined in this case. * - Initializing the \c struct to logical zeros, e.g.
* `psa_hash_operation_t operation = {0}`.
* *
* \param[in,out] operation Active hash operation. * In particular, calling psa_hash_abort() after the operation has been
* terminated by a call to psa_hash_abort(), psa_hash_finish() or
* psa_hash_verify() is safe and has no effect.
*
* \param[in,out] operation Initialized hash operation.
* *
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
@ -1760,18 +1766,24 @@ psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
/** Abort a MAC operation. /** Abort a MAC operation.
* *
* This function may be called at any time after psa_mac_sign_setup()
* or psa_mac_verify_setup().
* Aborting an operation frees all associated resources except for the * Aborting an operation frees all associated resources except for the
* \p operation structure itself. * \p operation structure itself. Once aborted, the operation object
* can be reused for another operation by calling
* psa_mac_sign_setup() or psa_mac_verify_setup() again.
* *
* Implementation should strive to be robust and handle inactive MAC * You may call this function any time after the operation object has
* operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However, * been initialized by any of the following methods:
* application writers should beware that uninitialized memory may happen * - A call to psa_mac_sign_setup() or psa_mac_verify_setup(), whether
* to be indistinguishable from an active MAC operation, and the behavior * it succeeds or not.
* of psa_mac_abort() is undefined in this case. * - Initializing the \c struct to all-bits-zero.
* - Initializing the \c struct to logical zeros, e.g.
* `psa_mac_operation_t operation = {0}`.
* *
* \param[in,out] operation Active MAC operation. * In particular, calling psa_mac_abort() after the operation has been
* terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or
* psa_mac_verify_finish() is safe and has no effect.
*
* \param[in,out] operation Initialized MAC operation.
* *
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE
@ -2038,18 +2050,24 @@ psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
/** Abort a cipher operation. /** Abort a cipher operation.
* *
* This function may be called at any time after
* psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup().
* Aborting an operation frees all associated resources except for the * Aborting an operation frees all associated resources except for the
* \p operation structure itself. * \p operation structure itself. Once aborted, the operation object
* can be reused for another operation by calling
* psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.
* *
* Implementation should strive to be robust and handle inactive cipher * You may call this function any time after the operation object has
* operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However, * been initialized by any of the following methods:
* application writers should beware that uninitialized memory may happen * - A call to psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(),
* to be indistinguishable from an active cipher operation, and the behavior * whether it succeeds or not.
* of psa_cipher_abort() is undefined in this case. * - Initializing the \c struct to all-bits-zero.
* - Initializing the \c struct to logical zeros, e.g.
* `psa_cipher_operation_t operation = {0}`.
* *
* \param[in,out] operation Active cipher operation. * In particular, calling psa_cipher_abort() after the operation has been
* terminated by a call to psa_cipher_abort() or psa_cipher_finish()
* is safe and has no effect.
*
* \param[in,out] operation Initialized cipher operation.
* *
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* \retval #PSA_ERROR_BAD_STATE * \retval #PSA_ERROR_BAD_STATE