Message authentication codes#
Functions#
Calculate the MAC (message authentication code) of a message.
Calculate the MAC of a message and compare it with a reference value.
Return an initial value for a MAC operation object.
Set up a multipart MAC calculation operation.
Set up a multipart MAC verification operation.
Add a message fragment to a multipart MAC operation.
Finish the calculation of the MAC of a message.
Finish the calculation of the MAC of a message and compare it with an expected value.
Abort a MAC operation.
Function Documentation#
psa_mac_compute#
psa_status_t psa_mac_compute (psa_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *mac, size_t mac_size, size_t *mac_length)
Calculate the MAC (message authentication code) of a message.
N/A | key | Identifier of the key to use for the operation. It must allow the usage PSA_KEY_USAGE_SIGN_MESSAGE. |
N/A | alg | The MAC algorithm to compute ( |
[in] | input | Buffer containing the input message. |
N/A | input_length | Size of the |
[out] | mac | Buffer where the MAC value is to be written. |
N/A | mac_size | Size of the |
[out] | mac_length | On success, the number of bytes that make up the MAC value. |
Note
To verify the MAC of a message against an expected value, use psa_mac_verify() instead. Beware that comparing integrity or authenticity data such as MAC values with a function such as
memcmp
is risky because the time taken by the comparison may leak information about the MAC value which could allow an attacker to guess a valid MAC and thereby bypass security controls.
1188
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_mac_verify#
psa_status_t psa_mac_verify (psa_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *mac, size_t mac_length)
Calculate the MAC of a message and compare it with a reference value.
N/A | key | Identifier of the key to use for the operation. It must allow the usage PSA_KEY_USAGE_VERIFY_MESSAGE. |
N/A | alg | The MAC algorithm to compute ( |
[in] | input | Buffer containing the input message. |
N/A | input_length | Size of the |
[out] | mac | Buffer containing the expected MAC value. |
N/A | mac_length | Size of the |
1229
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_mac_operation_init#
static psa_mac_operation_t psa_mac_operation_init (void)
Return an initial value for a MAC operation object.
N/A |
1269
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_mac_sign_setup#
psa_status_t psa_mac_sign_setup (psa_mac_operation_t *operation, psa_key_id_t key, psa_algorithm_t alg)
Set up a multipart MAC calculation operation.
[inout] | operation | The operation object to set up. It must have been initialized as per the documentation for #psa_mac_operation_t and not yet in use. |
N/A | key | Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_SIGN_MESSAGE. |
N/A | alg | The MAC algorithm to compute ( |
This function sets up the calculation of the MAC (message authentication code) of a byte string. To verify the MAC of a message against an expected value, use psa_mac_verify_setup() instead.
The sequence of operations to calculate a MAC 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_mac_operation_t, e.g. #PSA_MAC_OPERATION_INIT.
Call psa_mac_sign_setup() to specify the algorithm and key.
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.
At the end of the message, call psa_mac_sign_finish() to finish calculating the MAC value and retrieve it.
If an error occurs at any step after a call to psa_mac_sign_setup(), the operation will need to be reset by a call to psa_mac_abort(). The application may call psa_mac_abort() at any time after the operation has been initialized.
After a successful call to psa_mac_sign_setup(), the application must eventually terminate the operation through one of the following methods:
A successful call to psa_mac_sign_finish().
A call to psa_mac_abort().
This function sets up the calculation of the MAC (message authentication code) of a byte string. To verify the MAC of a message against an expected value, use psa_mac_verify_setup() instead.
The sequence of operations to calculate a MAC 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_mac_operation_t, e.g. #PSA_MAC_OPERATION_INIT.
Call psa_mac_sign_setup() to specify the algorithm and key.
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.
At the end of the message, call psa_mac_sign_finish() to finish calculating the MAC value and retrieve it.
If an error occurs at any step after a call to psa_mac_sign_setup(), the operation will need to be reset by a call to psa_mac_abort(). The application may call psa_mac_abort() at any time after the operation has been initialized.
After a successful call to psa_mac_sign_setup(), the application must eventually terminate the operation through one of the following methods:
A successful call to psa_mac_sign_finish().
A call to psa_mac_abort().
1330
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_mac_verify_setup#
psa_status_t psa_mac_verify_setup (psa_mac_operation_t *operation, psa_key_id_t key, psa_algorithm_t alg)
Set up a multipart MAC verification operation.
[inout] | operation | The operation object to set up. It must have been initialized as per the documentation for #psa_mac_operation_t and not yet in use. |
N/A | key | Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_VERIFY_MESSAGE. |
N/A | alg | The MAC algorithm to compute ( |
This function sets up the verification of the MAC (message authentication code) of a byte string against an expected value.
The sequence of operations to verify a MAC 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_mac_operation_t, e.g. #PSA_MAC_OPERATION_INIT.
Call psa_mac_verify_setup() to specify the algorithm and key.
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.
At the end of the message, call psa_mac_verify_finish() to finish calculating the actual MAC of the message and verify it against the expected value.
If an error occurs at any step after a call to psa_mac_verify_setup(), the operation will need to be reset by a call to psa_mac_abort(). The application may call psa_mac_abort() at any time after the operation has been initialized.
After a successful call to psa_mac_verify_setup(), the application must eventually terminate the operation through one of the following methods:
A successful call to psa_mac_verify_finish().
A call to psa_mac_abort().
This function sets up the verification of the MAC (message authentication code) of a byte string against an expected value.
The sequence of operations to verify a MAC 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_mac_operation_t, e.g. #PSA_MAC_OPERATION_INIT.
Call psa_mac_verify_setup() to specify the algorithm and key.
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.
At the end of the message, call psa_mac_verify_finish() to finish calculating the actual MAC of the message and verify it against the expected value.
If an error occurs at any step after a call to psa_mac_verify_setup(), the operation will need to be reset by a call to psa_mac_abort(). The application may call psa_mac_abort() at any time after the operation has been initialized.
After a successful call to psa_mac_verify_setup(), the application must eventually terminate the operation through one of the following methods:
A successful call to psa_mac_verify_finish().
A call to psa_mac_abort().
1393
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_mac_update#
psa_status_t psa_mac_update (psa_mac_operation_t *operation, const uint8_t *input, size_t input_length)
Add a message fragment to a multipart MAC operation.
[inout] | operation | Active MAC operation. |
[in] | input | Buffer containing the message fragment to add to the MAC calculation. |
N/A | input_length | Size of the |
The application must call psa_mac_sign_setup() or psa_mac_verify_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_mac_abort().
The application must call psa_mac_sign_setup() or psa_mac_verify_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_mac_abort().
1424
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_mac_sign_finish#
psa_status_t psa_mac_sign_finish (psa_mac_operation_t *operation, uint8_t *mac, size_t mac_size, size_t *mac_length)
Finish the calculation of the MAC of a message.
[inout] | operation | Active MAC operation. |
[out] | mac | Buffer where the MAC value is to be written. |
N/A | mac_size | Size of the |
[out] | mac_length | On success, the number of bytes that make up the MAC value. This is always #PSA_MAC_LENGTH( |
The application must call psa_mac_sign_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to psa_mac_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_mac_abort().
Warnings
Applications should not call this function if they expect a specific value for the MAC. Call psa_mac_verify_finish() instead. Beware that comparing integrity or authenticity data such as MAC values with a function such as
memcmp
is risky because the time taken by the comparison may leak information about the MAC value which could allow an attacker to guess a valid MAC and thereby bypass security controls.
The application must call psa_mac_sign_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to psa_mac_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_mac_abort().
Warnings
Applications should not call this function if they expect a specific value for the MAC. Call psa_mac_verify_finish() instead. Beware that comparing integrity or authenticity data such as MAC values with a function such as
memcmp
is risky because the time taken by the comparison may leak information about the MAC value which could allow an attacker to guess a valid MAC and thereby bypass security controls.
1474
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_mac_verify_finish#
psa_status_t psa_mac_verify_finish (psa_mac_operation_t *operation, const uint8_t *mac, size_t mac_length)
Finish the calculation of the MAC of a message and compare it with an expected value.
[inout] | operation | Active MAC operation. |
[in] | mac | Buffer containing the expected MAC value. |
N/A | mac_length | Size of the |
The application must call psa_mac_verify_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to psa_mac_update(). It then compares the calculated MAC with the expected MAC 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_mac_abort().
Note
Implementations shall make the best effort to ensure that the comparison between the actual MAC and the expected MAC is performed in constant time.
The application must call psa_mac_verify_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to psa_mac_update(). It then compares the calculated MAC with the expected MAC 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_mac_abort().
Note
Implementations shall make the best effort to ensure that the comparison between the actual MAC and the expected MAC is performed in constant time.
1518
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h
psa_mac_abort#
psa_status_t psa_mac_abort (psa_mac_operation_t *operation)
Abort a MAC operation.
[inout] | operation | Initialized MAC 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_mac_sign_setup() or psa_mac_verify_setup() again.
You may call this function any time after the operation object has been initialized by one of the methods described in #psa_mac_operation_t.
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.
1547
of file util/third_party/trusted-firmware-m/interface/include/psa/crypto.h