yuzu-emu/mbedtls
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Document some MAC functions: psa_mac_start

Browse source 
Adapt the documentation of hash functions.

State that the key object does not need to remain valid throughout the
operation.
This commit is contained in:
Gilles Peskine 2018-02-16 21:24:11 +01:00 committed by itayzafrir
parent 8c9def3e7f
commit 7e4acc5ef8
1 changed files with 57 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
include/psa/crypto.h
View file

@ -447,7 +447,7 @@ typedef struct psa_hash_operation_s psa_hash_operation_t;
* -# Allocate an operation object which will be passed to all the functions
* listed here.
* -# Call psa_hash_start() to specify the algorithm.
* -# Call psa_hash_update() zero, one or more time, passing a fragment
* -# Call psa_hash_update() zero, one or more times, passing a fragment
* of the message each time. The hash that is calculated is the hash
* of the concatenation of these messages in order.
* -# To calculate the hash, call psa_hash_finish().
@ -606,13 +606,69 @@ psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
* @{
*/
/** The type of the state data structure for multipart MAC operations.
*
* This is an implementation-define \c struct. Applications should not
* make any assumptions about the content of this structure except
* as directed by the documentation of a specific implementation. */
typedef struct psa_mac_operation_s psa_mac_operation_t;
/** The size of the output of psa_mac_finish(), in bytes.
*
* This is also the MAC size that psa_mac_verify() expects.
*
* \param alg A MAC algorithm (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_MAC(alg) is true).
*
* \return The MAC size for the specified algorithm.
* If the MAC algorithm is not recognized, return 0.
* An implementation may return either 0 or the correct size
* for a MAC algorithm that it recognizes, but does not support.
*/
#define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) \
(PSA_ALG_IS_HMAC(alg) ? PSA_HASH_FINAL_SIZE(PSA_ALG_HMAC_HASH(alg)) : \
PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
0)
/** Start a multipart MAC operation.
*
* The sequence of operations to calculate a MAC (message authentication code)
* is as follows:
* -# Allocate an operation object which will be passed to all the functions
* listed here.
* -# Call psa_mac_start() to specify the algorithm and key.
* The key remains associated with the operation even if the content
* of the key slot changes.
* -# Call psa_mac_update() zero, one or more times, passing a fragment
* of the message each time. The MAC that is calculated is the MAC
* of the concatenation of these messages in order.
* -# To calculate the MAC, call psa_mac_finish().
* To compare the MAC with an expected value, call psa_mac_verify().
*
* The application may call psa_mac_abort() at any time after the operation
* has been initialized with psa_mac_start().
*
* After a successful call to psa_mac_start(), the application must
* eventually destroy the operation through one of the following means:
* - A failed call to psa_mac_update().
* - A call to psa_mac_final(), psa_mac_verify() or psa_mac_abort().
*
* \param operation
* \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
* such that #PSA_ALG_IS_MAC(alg) is true).
*
* \retval PSA_SUCCESS
* Success.
* \retval PSA_ERROR_EMPTY_SLOT
* \retval PSA_ERROR_INVALID_ARGUMENT
* \c key is not compatible with \c alg.
* \retval PSA_ERROR_NOT_SUPPORTED
* \c alg is not supported or is not a MAC algorithm.
* \retval PSA_ERROR_INSUFFICIENT_MEMORY
* \retval PSA_ERROR_COMMUNICATION_FAILURE
* \retval PSA_ERROR_HARDWARE_FAILURE
* \retval PSA_ERROR_TAMPERING_DETECTED
*/
psa_status_t psa_mac_start(psa_mac_operation_t *operation,
psa_key_slot_t key,
psa_algorithm_t alg);