MAC operations

General Description

Macros
#define	CY_P64_PSA_MAC_OPERATION_INIT   {0}
	The initial value of the MAC operation context.

Typedefs
typedef struct cy_p64_psa_mac_operation_s	cy_p64_psa_mac_operation_t
	The type of the state data structure for multipart MAC operations. More...

Functions
cy_p64_psa_status_t	cy_p64_psa_mac_verify_setup (cy_p64_psa_mac_operation_t *operation, cy_p64_psa_key_handle_t handle, cy_p64_psa_algorithm_t alg)
	Sets up a multipart MAC verification operation. More...
cy_p64_psa_status_t	cy_p64_psa_mac_update (cy_p64_psa_mac_operation_t *operation, const uint8_t *input, size_t input_length)
	Adds a message fragment to a multipart MAC operation. More...
cy_p64_psa_status_t	cy_p64_psa_mac_verify_finish (cy_p64_psa_mac_operation_t *operation, const uint8_t *mac, size_t mac_length)
	Finishes the calculation of the MAC of a message and compares it with the expected value. More...
static struct cy_p64_psa_mac_operation_s	cy_p64_psa_mac_operation_init (void)
	Initialize the MAC operation context.

Typedef Documentation

cy_p64_psa_mac_operation_t

typedef struct cy_p64_psa_mac_operation_s cy_p64_psa_mac_operation_t

The type of the state data structure for multipart MAC operations.

Before calling any function on a MAC operation object, the application must initialize it by any of the following means:

• Set the structure to all-bits-zero, for example:

  cy_p64_psa_mac_operation_t operation;
  memset(&operation, 0, sizeof(operation));

• Initialize the structure to logical zero values, for example:

  cy_p64_psa_mac_operation_t operation = {0};

This is an implementation-defined struct. Applications should not make any assumptions about the content of this structure except as directed by the documentation of a specific implementation.

Function Documentation

cy_p64_psa_mac_verify_setup()

cy_p64_psa_status_t cy_p64_psa_mac_verify_setup	(	cy_p64_psa_mac_operation_t *	operation,
		cy_p64_psa_key_handle_t	handle,
		cy_p64_psa_algorithm_t	alg
	)

Sets up a multipart MAC verification operation.

This function sets up the verification of the MAC (message authentication code) of a byte string against an expected value.

The sequence of operations to verify a MAC is as follows:

1. Allocate an operation object which will be passed to all the functions listed here.
2. Initialize the operation object with one of the methods described in the documentation for cy_p64_psa_mac_operation_t, e.g. CY_P64_PSA_MAC_OPERATION_INIT.
3. Call cy_p64_psa_mac_verify_setup() to specify the algorithm and key.
4. Call cy_p64_psa_mac_update() zero, one or more times, passing a fragment of the message each time. The MAC that is calculated is the MAC of the concatenation of these messages in order.
5. At the end of the message, call cy_p64_psa_mac_verify_finish() to finish calculating the actual MAC of the message and verify it against the expected value.

If an error occurs at any step after a call to cy_p64_psa_mac_verify_setup(), the operation will need to be reset by a call to cy_p64_psa_mac_abort(). The application may call cy_p64_psa_mac_abort() at any time after the operation has been initialized.

After a successful call to cy_p64_psa_mac_verify_setup(), the application must eventually terminate the operation through one of the following methods:

• A successful call to cy_p64_psa_mac_verify_finish().
• A call to cy_p64_psa_mac_abort().

Parameters

[in,out]	operation	The operation object to set up. It must have been initialized as per the documentation for cy_p64_psa_mac_operation_t and not yet in use.
	handle	Handle to the key to use for the operation. It must remain valid until the operation terminates.
	alg	The MAC algorithm to compute (CY_P64_PSA_ALG_XXX value such that CY_P64_PSA_ALG_IS_MAC(alg) is true).

Return values

CY_P64_PSA_SUCCESS	Success.
CY_P64_PSA_ERROR_INVALID_HANDLE
CY_P64_PSA_ERROR_NOT_PERMITTED
CY_P64_PSA_ERROR_INVALID_ARGUMENT	key is not compatible with alg.
CY_P64_PSA_ERROR_NOT_SUPPORTED	alg is not supported or is not a MAC algorithm.
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED
CY_P64_PSA_ERROR_STORAGE_FAILURE	The key could not be retrieved from storage
CY_P64_PSA_ERROR_BAD_STATE	The operation state is not valid (it must be inactive).

cy_p64_psa_mac_update()

cy_p64_psa_status_t cy_p64_psa_mac_update	(	cy_p64_psa_mac_operation_t *	operation,
		const uint8_t *	input,
		size_t	input_length
	)

Adds a message fragment to a multipart MAC operation.

The application must call cy_p64_psa_mac_sign_setup() or cy_p64_psa_mac_verify_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling cy_p64_psa_mac_abort().

Parameters

[in,out]	operation	Active MAC operation.
[in]	input	The buffer that contains the message fragment to add to the MAC calculation.
	input_length	Size of the input buffer in bytes.

Return values

CY_P64_PSA_SUCCESS	Success.
CY_P64_PSA_ERROR_BAD_STATE	The operation state is not valid (it must be active).
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED
CY_P64_PSA_ERROR_STORAGE_FAILURE

cy_p64_psa_mac_verify_finish()

cy_p64_psa_status_t cy_p64_psa_mac_verify_finish	(	cy_p64_psa_mac_operation_t *	operation,
		const uint8_t *	mac,
		size_t	mac_length
	)

Finishes the calculation of the MAC of a message and compares it with the expected value.

The application must call cy_p64_psa_mac_verify_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to cy_p64_psa_mac_update(). It then compares the calculated MAC with the expected MAC passed as a parameter to this function.

When this function returns success, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling cy_p64_psa_mac_abort().

Note

Implementations shall make the best effort to ensure that the comparison between the actual MAC and the expected MAC is performed in constant time.

Parameters

[in,out]	operation	Active MAC operation.
[in]	mac	Buffer containing the expected MAC value.
	mac_length	Size of the mac buffer in bytes.

Return values

CY_P64_PSA_SUCCESS	The expected MAC is identical to the actual MAC of the message.
CY_P64_PSA_ERROR_INVALID_SIGNATURE	The MAC of the message was calculated successfully, but it differs from the expected MAC.
CY_P64_PSA_ERROR_BAD_STATE	The operation state is not valid (it must be an active mac verify operation).
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED
CY_P64_PSA_ERROR_STORAGE_FAILURE