Hardware-Accelerated Message Authentication Code
Detailed Description
Generation and authentication of Message Authentication Codes (MACs) using cryptographic accelerators can be done either as a single function call (via the psa_drv_accel_mac_generate_t
or psa_drv_accel_mac_verify_t
functions), or in parts using the following sequence:
psa_drv_accel_mac_setup_t
psa_drv_accel_mac_update_t
psa_drv_accel_mac_update_t
- ...
psa_drv_accel_mac_finish_t
orpsa_drv_accel_mac_finish_verify_t
If a previously started MAC operation needs to be terminated, it should be done so by the psa_drv_accel_mac_abort_t
. Failure to do so may result in allocated resources not being freed or in other undefined behavior.
Typedefs | |
typedef struct psa_drv_accel_mac_context_s | psa_drv_accel_mac_context_t |
The hardware-accelerator-specific MAC context structure. | |
typedef psa_status_t(* | psa_drv_accel_mac_setup_t) (psa_drv_accel_mac_context_t *p_context, const uint8_t *p_key, size_t key_length) |
The function prototype for the setup operation of a hardware-accelerated MAC operation. | |
typedef psa_status_t(* | psa_drv_accel_mac_update_t) (psa_drv_accel_mac_context_t *p_context, const uint8_t *p_input, size_t input_length) |
The function prototype for the update operation of a hardware-accelerated MAC operation. | |
typedef psa_status_t(* | psa_drv_accel_mac_finish_t) (psa_drv_accel_mac_context_t *p_context, uint8_t *p_mac, size_t mac_length) |
The function prototype for the finish operation of a hardware-accelerated MAC operation. | |
typedef psa_status_t(* | psa_drv_accel_mac_finish_verify_t) (psa_drv_accel_mac_context_t *p_context, const uint8_t *p_mac, size_t mac_length) |
The function prototype for the finish and verify operation of a hardware-accelerated MAC operation. | |
typedef psa_status_t(* | psa_drv_accel_mac_abort_t) (psa_drv_accel_mac_context_t *p_context) |
The function prototype for the abort operation for a previously started hardware-accelerated MAC operation. | |
typedef psa_status_t(* | psa_drv_accel_mac_t) (const uint8_t *p_input, size_t input_length, const uint8_t *p_key, size_t key_length, psa_algorithm_t alg, uint8_t *p_mac, size_t mac_length) |
The function prototype for the one-shot operation of a hardware-accelerated MAC operation. | |
typedef psa_status_t(* | psa_drv_accel_mac_verify_t) (const uint8_t *p_input, size_t input_length, const uint8_t *p_key, size_t key_length, psa_algorithm_t alg, const uint8_t *p_mac, size_t mac_length) |
The function prototype for the one-shot hardware-accelerated MAC Verify operation. | |
Typedef Documentation
typedef psa_status_t(* psa_drv_accel_mac_abort_t) (psa_drv_accel_mac_context_t *p_context) |
The function prototype for the abort operation for a previously started hardware-accelerated MAC operation.
Functions that implement this prototype should be named in the following convention:
- ~~~~~~~~~~~~~{.c} psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_abort
~~~~~~~~~~~~~ Where
ALGO
is the name of the underlying algorithm, andMAC_VARIANT
is the specific variant of a MAC operation (such as HMAC or CMAC)- Parameters
-
[in,out] p_context
A hardware-specific structure for the previously started MAC operation to be aborted
Definition at line 287
of file crypto_accel_driver.h
.
typedef struct psa_drv_accel_mac_context_s psa_drv_accel_mac_context_t |
The hardware-accelerator-specific MAC context structure.
The contents of this structure are implementation dependent and are therefore not described here.
Definition at line 172
of file crypto_accel_driver.h
.
typedef psa_status_t(* psa_drv_accel_mac_finish_t) (psa_drv_accel_mac_context_t *p_context, uint8_t *p_mac, size_t mac_length) |
The function prototype for the finish operation of a hardware-accelerated MAC operation.
Functions that implement this prototype should be named in the following convention:
- ~~~~~~~~~~~~~{.c} psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_finish
~~~~~~~~~~~~~ Where
ALGO
is the name of the underlying algorithm, andMAC_VARIANT
is the specific variant of a MAC operation (such as HMAC or CMAC)- Parameters
-
[in,out] p_context
A hardware-specific structure for the previously started MAC operation to be finished [out] p_mac
A buffer where the generated MAC will be placed [in] mac_length
The size in bytes of the buffer that has been allocated for the p_mac
buffer
- Return values
-
PSA_SUCCESS
Success.
Definition at line 241
of file crypto_accel_driver.h
.
typedef psa_status_t(* psa_drv_accel_mac_finish_verify_t) (psa_drv_accel_mac_context_t *p_context, const uint8_t *p_mac, size_t mac_length) |
The function prototype for the finish and verify operation of a hardware-accelerated MAC operation.
Functions that implement this prototype should be named in the following convention:
- ~~~~~~~~~~~~~{.c} psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_finish_verify
~~~~~~~~~~~~~ Where
ALGO
is the name of the underlying algorithm, andMAC_VARIANT
is the specific variant of a MAC operation (such as HMAC or CMAC)- Parameters
-
[in,out] p_context
A hardware-specific structure for the previously started MAC operation to be verified and finished [in] p_mac
A buffer containing the MAC that will be used for verification [in] mac_length
The size in bytes of the data in the p_mac
buffer
- Return values
-
PSA_SUCCESS
The operation completed successfully and the comparison matched
Definition at line 267
of file crypto_accel_driver.h
.
typedef psa_status_t(* psa_drv_accel_mac_setup_t) (psa_drv_accel_mac_context_t *p_context, const uint8_t *p_key, size_t key_length) |
The function prototype for the setup operation of a hardware-accelerated MAC operation.
Functions that implement this prototype should be named in the following convention:
- ~~~~~~~~~~~~~{.c} psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_setup
~~~~~~~~~~~~~ Where
ALGO
is the name of the underlying primitive, andMAC_VARIANT
is the specific variant of a MAC operation (such as HMAC or CMAC)- Parameters
-
[in,out] p_context
A structure that will contain the hardware-specific MAC context [in] p_key
A buffer containing the cleartext key material to be used in the operation [in] key_length
The size in bytes of the key material
- Return values
-
PSA_SUCCESS
Success.
Definition at line 194
of file crypto_accel_driver.h
.
typedef psa_status_t(* psa_drv_accel_mac_t) (const uint8_t *p_input, size_t input_length, const uint8_t *p_key, size_t key_length, psa_algorithm_t alg, uint8_t *p_mac, size_t mac_length) |
The function prototype for the one-shot operation of a hardware-accelerated MAC operation.
Functions that implement this prototype should be named in the following convention:
- ~~~~~~~~~~~~~{.c} psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>
~~~~~~~~~~~~~ Where
ALGO
is the name of the underlying algorithm, andMAC_VARIANT
is the specific variant of a MAC operation (such as HMAC or CMAC)- Parameters
-
[in] p_input
A buffer containing the data to be MACed [in] input_length
The length in bytes of the p_input
data[in] p_key
A buffer containing the key material to be used for the MAC operation [in] key_length
The length in bytes of the p_key
data[in] alg
The algorithm to be performed [out] p_mac
The buffer where the resulting MAC will be placed upon success [in] mac_length
The length in bytes of the p_mac
buffer
Definition at line 310
of file crypto_accel_driver.h
.
typedef psa_status_t(* psa_drv_accel_mac_update_t) (psa_drv_accel_mac_context_t *p_context, const uint8_t *p_input, size_t input_length) |
The function prototype for the update operation of a hardware-accelerated MAC operation.
Functions that implement this prototype should be named in the following convention:
- ~~~~~~~~~~~~~{.c} psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_update
~~~~~~~~~~~~~ Where
ALGO
is the name of the underlying algorithm, andMAC_VARIANT
is the specific variant of a MAC operation (such as HMAC or CMAC)- Parameters
-
[in,out] p_context
A hardware-specific structure for the previously-established MAC operation to be continued [in] p_input
A buffer containing the message to be appended to the MAC operation [in] input_length
The size in bytes of the input message buffer
Definition at line 216
of file crypto_accel_driver.h
.
typedef psa_status_t(* psa_drv_accel_mac_verify_t) (const uint8_t *p_input, size_t input_length, const uint8_t *p_key, size_t key_length, psa_algorithm_t alg, const uint8_t *p_mac, size_t mac_length) |
The function prototype for the one-shot hardware-accelerated MAC Verify operation.
Functions that implement this prototype should be named in the following convention:
- ~~~~~~~~~~~~~{.c} psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_verify
~~~~~~~~~~~~~ Where
ALGO
is the name of the underlying algorithm, andMAC_VARIANT
is the specific variant of a MAC operation (such as HMAC or CMAC)- Parameters
-
[in] p_input
A buffer containing the data to be MACed [in] input_length
The length in bytes of the p_input
data[in] p_key
A buffer containing the key material to be used for the MAC operation [in] key_length
The length in bytes of the p_key
data[in] alg
The algorithm to be performed [in] p_mac
The MAC data to be compared [in] mac_length
The length in bytes of the p_mac
buffer
- Return values
-
PSA_SUCCESS
The operation completed successfully and the comparison matched
Definition at line 341
of file crypto_accel_driver.h
.