mbed TLS v2.23.0: Secure Element Message Authentication Codes

mbed TLS v2.23.0

Data Structures | Typedefs
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: More...

## Data Structures
struct | psa_drv_se_mac_t
| A struct containing all of the function pointers needed to perform secure element MAC operations. More...

## 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. More...
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. More...
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. More...
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. More...
typedef psa_status_t(* | psa_drv_se_mac_abort_t) (void *op_context)
| A function that aborts a previous started secure element MAC operation. More...
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. More...
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. More...

## Detailed 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.

## Typedef Documentation

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

Definition at line 250 of file 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)

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.

Definition at line 219 of file 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)

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

Definition at line 240 of file 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)

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.

Definition at line 270 of file crypto_se_driver.h.

## ◆ 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.

Definition at line 184 of file 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)

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

Definition at line 199 of file 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)

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

Definition at line 299 of file crypto_se_driver.h.