Message digests#
Functions#
Calculate the hash (digest) of a message.
Calculate the hash (digest) of a message and compare it with a reference value.
Return an initial value for a hash operation object.
Set up a multipart hash operation.
Add a message fragment to a multipart hash operation.
Finish the calculation of the hash of a message.
Finish the calculation of the hash of a message and compare it with an expected value.
Abort a hash operation.
Clone a hash operation.
Function Documentation#
psa_hash_compute#
psa_status_t psa_hash_compute (psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *hash, size_t hash_size, size_t *hash_length)
Calculate the hash (digest) of a message.
N/A | alg | The hash algorithm to compute ( |
[in] | input | Buffer containing the message to hash. |
N/A | input_length | Size of the |
[out] | hash | Buffer where the hash is to be written. |
N/A | hash_size | Size of the |
[out] | hash_length | On success, the number of bytes that make up the hash value. This is always #PSA_HASH_LENGTH( |
Note
To verify the hash of a message against an expected value, use psa_hash_compare() instead.
Note
To verify the hash of a message against an expected value, use psa_hash_compare() instead.
836
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_hash_compare#
psa_status_t psa_hash_compare (psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *hash, size_t hash_length)
Calculate the hash (digest) of a message and compare it with a reference value.
N/A | alg | The hash algorithm to compute ( |
[in] | input | Buffer containing the message to hash. |
N/A | input_length | Size of the |
[out] | hash | Buffer containing the expected hash value. |
N/A | hash_length | Size of the |
872
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_hash_operation_init#
static psa_hash_operation_t psa_hash_operation_init (void)
Return an initial value for a hash operation object.
N/A |
910
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_hash_setup#
psa_status_t psa_hash_setup (psa_hash_operation_t *operation, psa_algorithm_t alg)
Set up a multipart hash operation.
[inout] | operation | The operation object to set up. It must have been initialized as per the documentation for #psa_hash_operation_t and not yet in use. |
N/A | alg | The hash algorithm to compute ( |
The sequence of operations to calculate a hash (message digest) is as follows:
Allocate an operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for #psa_hash_operation_t, e.g. #PSA_HASH_OPERATION_INIT.
Call psa_hash_setup() to specify the algorithm.
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(). To compare the hash with an expected value, call psa_hash_verify().
If an error occurs at any step after a call to psa_hash_setup(), the operation will need to be reset by a call to psa_hash_abort(). The application may call psa_hash_abort() at any time after the operation has been initialized.
After a successful call to psa_hash_setup(), the application must eventually terminate the operation. The following events terminate an operation:
A successful call to psa_hash_finish() or psa_hash_verify().
A call to psa_hash_abort().
The sequence of operations to calculate a hash (message digest) is as follows:
Allocate an operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for #psa_hash_operation_t, e.g. #PSA_HASH_OPERATION_INIT.
Call psa_hash_setup() to specify the algorithm.
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(). To compare the hash with an expected value, call psa_hash_verify().
If an error occurs at any step after a call to psa_hash_setup(), the operation will need to be reset by a call to psa_hash_abort(). The application may call psa_hash_abort() at any time after the operation has been initialized.
After a successful call to psa_hash_setup(), the application must eventually terminate the operation. The following events terminate an operation:
A successful call to psa_hash_finish() or psa_hash_verify().
A call to psa_hash_abort().
961
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_hash_update#
psa_status_t psa_hash_update (psa_hash_operation_t *operation, const uint8_t *input, size_t input_length)
Add a message fragment to a multipart hash operation.
[inout] | operation | Active hash operation. |
[in] | input | Buffer containing the message fragment to hash. |
N/A | input_length | Size of the |
The application must call psa_hash_setup() before calling this function.
If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().
The application must call psa_hash_setup() before calling this function.
If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().
988
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_hash_finish#
psa_status_t psa_hash_finish (psa_hash_operation_t *operation, uint8_t *hash, size_t hash_size, size_t *hash_length)
Finish the calculation of the hash of a message.
[inout] | operation | Active hash operation. |
[out] | hash | Buffer where the hash is to be written. |
N/A | hash_size | Size of the |
[out] | hash_length | On success, the number of bytes that make up the hash value. This is always #PSA_HASH_LENGTH( |
The application must call psa_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to psa_hash_update().
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_hash_abort().
Warnings
Applications should not call this function if they expect a specific value for the hash. Call psa_hash_verify() instead. Beware that comparing integrity or authenticity data such as hash values with a function such as
memcmp
is risky because the time taken by the comparison may leak information about the hashed data which could allow an attacker to guess a valid hash and thereby bypass security controls.
The application must call psa_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to psa_hash_update().
When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().
Warnings
Applications should not call this function if they expect a specific value for the hash. Call psa_hash_verify() instead. Beware that comparing integrity or authenticity data such as hash values with a function such as
memcmp
is risky because the time taken by the comparison may leak information about the hashed data which could allow an attacker to guess a valid hash and thereby bypass security controls.
1035
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_hash_verify#
psa_status_t psa_hash_verify (psa_hash_operation_t *operation, const uint8_t *hash, size_t hash_length)
Finish the calculation of the hash of a message and compare it with an expected value.
[inout] | operation | Active hash operation. |
[in] | hash | Buffer containing the expected hash value. |
N/A | hash_length | Size of the |
The application must call psa_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to psa_hash_update(). It then compares the calculated hash with the expected hash passed as a parameter to this function.
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_hash_abort().
Note
Implementations shall make the best effort to ensure that the comparison between the actual hash and the expected hash is performed in constant time.
The application must call psa_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to psa_hash_update(). It then compares the calculated hash with the expected hash passed as a parameter to this function.
When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().
Note
Implementations shall make the best effort to ensure that the comparison between the actual hash and the expected hash is performed in constant time.
1077
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_hash_abort#
psa_status_t psa_hash_abort (psa_hash_operation_t *operation)
Abort a hash operation.
[inout] | operation | Initialized hash operation. |
Aborting an operation frees all associated resources except for the operation
structure itself. Once aborted, the operation object can be reused for another operation by calling psa_hash_setup() again.
You may call this function any time after the operation object has been initialized by one of the methods described in #psa_hash_operation_t.
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.
1106
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_hash_clone#
psa_status_t psa_hash_clone (const psa_hash_operation_t *source_operation, psa_hash_operation_t *target_operation)
Clone a hash operation.
[in] | source_operation | The active hash operation to clone. |
[inout] | target_operation | The operation object to set up. It must be initialized but not active. |
This function copies the state of an ongoing hash operation to a new operation object. In other words, this function is equivalent to calling psa_hash_setup() on target_operation
with the same algorithm that source_operation
was set up for, then psa_hash_update() on target_operation
with the same input that that was passed to source_operation
. After this function returns, the two objects are independent, i.e. subsequent calls involving one of the objects do not affect the other object.
This function copies the state of an ongoing hash operation to a new operation object. In other words, this function is equivalent to calling psa_hash_setup() on target_operation
with the same algorithm that source_operation
was set up for, then psa_hash_update() on target_operation
with the same input that that was passed to source_operation
. After this function returns, the two objects are independent, i.e. subsequent calls involving one of the objects do not affect the other object.
1137
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h