Secure Element Message Authentication Codes

Description

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.

Data Structures

struct psa_drv_se_mac_t
A struct containing all of the function pointers needed to perform secure element MAC operations.

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)

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

Parameters
[in,out] drv_context The driver context structure.
[in,out] 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
Return values
PSA_SUCCESS Success.

◆ 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)

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

Parameters
[in,out] 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

◆ 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)

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

Parameters
[in,out] 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
Return values
PSA_SUCCESS Success.

◆ 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)

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

Parameters
[in,out] op_context A hardware-specific structure for the previously started MAC operation to be fiinished
[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
Return values
PSA_SUCCESS The operation completed successfully and the MACs matched each other
PSA_ERROR_INVALID_SIGNATURE The operation completed successfully, but the calculated MAC did not match the provided MAC

◆ psa_drv_se_mac_abort_t

typedef psa_status_t (* psa_drv_se_mac_abort_t) (void *op_context)

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

Parameters
[in,out] op_context A hardware-specific structure for the previously started MAC operation to be aborted

◆ 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)

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

Parameters
[in,out] 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
Return values
PSA_SUCCESS Success.

◆ 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)

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

Parameters
[in,out] 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
Return values
PSA_SUCCESS The operation completed successfully and the MACs matched each other
PSA_ERROR_INVALID_SIGNATURE The operation completed successfully, but the calculated MAC did not match the provided MAC