Group se_mac

group se_mac

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.

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.

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

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.

Param op_context: [inout] A hardware-specific structure for the previously-established MAC operation to be updated
Param p_input: [in] A buffer containing the message to be appended to the MAC operation
Param input_length: [in] The size in bytes of the input message buffer

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.

Param op_context: [inout] A hardware-specific structure for the previously started MAC operation to be finished
Param p_mac: [out] A buffer where the generated MAC will be placed
Param mac_size: [in] The size in bytes of the buffer that has been allocated for the output buffer
Param p_mac_length: [out] After completion, will contain the number of bytes placed in the p_mac buffer
Retval PSA_SUCCESS: Success.

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.

Param op_context: [inout] A hardware-specific structure for the previously started MAC operation to be finished
Param p_mac: [in] The MAC value against which the resulting MAC will be compared against
Param mac_length: [in] The size in bytes of the value stored in p_mac
Retval PSA_SUCCESS: The operation completed successfully and the MACs matched each other
Retval PSA_ERROR_INVALID_SIGNATURE: The operation completed successfully, but the calculated MAC did not match the provided MAC

typedef psa_status_t (*psa_drv_se_mac_abort_t)(void *op_context)

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

Param op_context: [inout] A hardware-specific structure for the previously started MAC operation to be aborted

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.

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

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.

Param drv_context: [inout] The driver context structure.
Param p_input: [in] A buffer containing the message to be MACed
Param input_length: [in] The size in bytes of input
Param key_slot: [in] The slot of the key to be used
Param alg: [in] The algorithm to be used to underlie the MAC operation
Param p_mac: [in] The MAC value against which the resulting MAC will be compared against
Param mac_length: [in] The size in bytes of mac
Retval PSA_SUCCESS: The operation completed successfully and the MACs matched each other
Retval PSA_ERROR_INVALID_SIGNATURE: The operation completed successfully, but the calculated MAC did not match the provided MAC

struct psa_drv_se_mac_t

#include <crypto_se_driver.h>

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

PSA Crypto API implementations should populate the table as appropriate upon startup.

If one of the functions is not implemented (such as psa_drv_se_mac_generate_t), it should be set to NULL.

Driver implementers should ensure that they implement all of the functions that make sense for their hardware, and that they provide a full solution (for example, if they support p_setup, they should also support p_update and at least one of p_finish or p_finish_verify).