Secure Element Message Authentication Codes#

Generation and authentication of Message Authentication Codes (MACs) using a secure element can be done either as a single function call (via the psa_drv_se_mac_generate_t or psa_drv_se_mac_verify_t functions), or in parts using the following sequence:

psa_drv_se_mac_setup_t
psa_drv_se_mac_update_t
psa_drv_se_mac_update_t
...
psa_drv_se_mac_finish_t or psa_drv_se_mac_finish_verify_t

If a previously started secure element MAC operation needs to be terminated, it should be done so by the psa_drv_se_mac_abort_t. Failure to do so may result in allocated resources not being freed or in other undefined behavior.

Modules#

psa_drv_se_mac_t

Typedefs#

typedef psa_status_t(*

psa_drv_se_mac_setup_t)(psa_drv_se_context_t *drv_context, void *op_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm)

A function that starts a secure element MAC operation for a PSA Crypto Driver implementation.

typedef psa_status_t(*

psa_drv_se_mac_update_t)(void *op_context, const uint8_t *p_input, size_t input_length)

A function that continues a previously started secure element MAC operation.

typedef psa_status_t(*

psa_drv_se_mac_finish_t)(void *op_context, uint8_t *p_mac, size_t mac_size, size_t *p_mac_length)

a function that completes a previously started secure element MAC operation by returning the resulting MAC.

typedef psa_status_t(*

psa_drv_se_mac_finish_verify_t)(void *op_context, const uint8_t *p_mac, size_t mac_length)

A function that completes a previously started secure element MAC operation by comparing the resulting MAC against a provided value.

typedef psa_status_t(*

psa_drv_se_mac_abort_t)(void *op_context)

A function that aborts a previous started secure element MAC operation.

typedef psa_status_t(*

psa_drv_se_mac_generate_t)(psa_drv_se_context_t *drv_context, const uint8_t *p_input, size_t input_length, psa_key_slot_number_t key_slot, psa_algorithm_t alg, uint8_t *p_mac, size_t mac_size, size_t *p_mac_length)

A function that performs a secure element MAC operation in one command and returns the calculated MAC.

typedef psa_status_t(*

psa_drv_se_mac_verify_t)(psa_drv_se_context_t *drv_context, const uint8_t *p_input, size_t input_length, psa_key_slot_number_t key_slot, psa_algorithm_t alg, const uint8_t *p_mac, size_t mac_length)

A function that performs a secure element MAC operation in one command and compares the resulting MAC against a provided value.

Typedef Documentation#

psa_drv_se_mac_setup_t#

typedef psa_status_t(* psa_drv_se_mac_setup_t) (psa_drv_se_context_t *drv_context, void *op_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm) )(psa_drv_se_context_t *drv_context, void *op_context, psa_key_slot_number_t key_slot, psa_algorithm_t algorithm)

A function that starts a secure element MAC operation for a PSA Crypto Driver implementation.

Parameters

[inout]	drv_context	The driver context structure.
[inout]	op_context	A structure that will contain the hardware-specific MAC context
[in]	key_slot	The slot of the key to be used for the operation
[in]	algorithm	The algorithm to be used to underly the MAC operation

Definition at line 185 of file util/third_party/mbedtls/include/psa/crypto_se_driver.h

psa_drv_se_mac_update_t#

typedef psa_status_t(* psa_drv_se_mac_update_t) (void *op_context, const uint8_t *p_input, size_t input_length) )(void *op_context, const uint8_t *p_input, size_t input_length)

A function that continues a previously started secure element MAC operation.

Parameters

[inout]	op_context	A hardware-specific structure for the previously-established MAC operation to be updated
[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 200 of file util/third_party/mbedtls/include/psa/crypto_se_driver.h

psa_drv_se_mac_finish_t#

typedef psa_status_t(* psa_drv_se_mac_finish_t) (void *op_context, uint8_t *p_mac, size_t mac_size, size_t *p_mac_length) )(void *op_context, uint8_t *p_mac, size_t mac_size, size_t *p_mac_length)

a function that completes a previously started secure element MAC operation by returning the resulting MAC.

Parameters

[inout]	op_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_size	The size in bytes of the buffer that has been allocated for the `output` buffer
[out]	p_mac_length	After completion, will contain the number of bytes placed in the `p_mac` buffer

Definition at line 220 of file util/third_party/mbedtls/include/psa/crypto_se_driver.h

psa_drv_se_mac_finish_verify_t#

typedef psa_status_t(* psa_drv_se_mac_finish_verify_t) (void *op_context, const uint8_t *p_mac, size_t mac_length) )(void *op_context, const uint8_t *p_mac, size_t mac_length)

A function that completes a previously started secure element MAC operation by comparing the resulting MAC against a provided value.

Parameters

[inout]	op_context	A hardware-specific structure for the previously started MAC operation to be finished
[in]	p_mac	The MAC value against which the resulting MAC will be compared against
[in]	mac_length	The size in bytes of the value stored in `p_mac`

Definition at line 241 of file util/third_party/mbedtls/include/psa/crypto_se_driver.h

psa_drv_se_mac_abort_t#

typedef psa_status_t(* psa_drv_se_mac_abort_t) (void *op_context) )(void *op_context)

A function that aborts a previous started secure element MAC operation.

Parameters

[inout]

op_context

A hardware-specific structure for the previously started MAC operation to be aborted

Definition at line 251 of file util/third_party/mbedtls/include/psa/crypto_se_driver.h

psa_drv_se_mac_generate_t#

typedef psa_status_t(* psa_drv_se_mac_generate_t) (psa_drv_se_context_t *drv_context, const uint8_t *p_input, size_t input_length, psa_key_slot_number_t key_slot, psa_algorithm_t alg, uint8_t *p_mac, size_t mac_size, size_t *p_mac_length) )(psa_drv_se_context_t *drv_context, const uint8_t *p_input, size_t input_length, psa_key_slot_number_t key_slot, psa_algorithm_t alg, uint8_t *p_mac, size_t mac_size, size_t *p_mac_length)

A function that performs a secure element MAC operation in one command and returns the calculated MAC.

Parameters

[inout]	drv_context	The driver context structure.
[in]	p_input	A buffer containing the message to be MACed
[in]	input_length	The size in bytes of `p_input`
[in]	key_slot	The slot of the key to be used
[in]	alg	The algorithm to be used to underlie the MAC operation
[out]	p_mac	A buffer where the generated MAC will be placed
[in]	mac_size	The size in bytes of the `p_mac` buffer
[out]	p_mac_length	After completion, will contain the number of bytes placed in the `output` buffer

Definition at line 271 of file util/third_party/mbedtls/include/psa/crypto_se_driver.h

psa_drv_se_mac_verify_t#

typedef psa_status_t(* psa_drv_se_mac_verify_t) (psa_drv_se_context_t *drv_context, const uint8_t *p_input, size_t input_length, psa_key_slot_number_t key_slot, psa_algorithm_t alg, const uint8_t *p_mac, size_t mac_length) )(psa_drv_se_context_t *drv_context, const uint8_t *p_input, size_t input_length, psa_key_slot_number_t key_slot, psa_algorithm_t alg, const uint8_t *p_mac, size_t mac_length)

A function that performs a secure element MAC operation in one command and compares the resulting MAC against a provided value.

Parameters

[inout]	drv_context	The driver context structure.
[in]	p_input	A buffer containing the message to be MACed
[in]	input_length	The size in bytes of `input`
[in]	key_slot	The slot of the key to be used
[in]	alg	The algorithm to be used to underlie the MAC operation
[in]	p_mac	The MAC value against which the resulting MAC will be compared against
[in]	mac_length	The size in bytes of `mac`

Definition at line 300 of file util/third_party/mbedtls/include/psa/crypto_se_driver.h