One-shot MAC interfaces

Interfaces to perform MAC operations in one shot. More...

Functions
mcuxClMac_Status_t	mcuxClMac_compute (mcuxClSession_Handle_t session, mcuxClKey_Handle_t key, mcuxClMac_Mode_t mode, mcuxCl_InputBuffer_t pIn, uint32_t inLength, mcuxCl_Buffer_t pMac, uint32_t *const pMacLength)
	One-shot message authentication code (MAC) computation function.

Detailed Description

Interfaces to perform MAC operations in one shot.

Function Documentation

mcuxClMac_compute()

mcuxClMac_Status_t mcuxClMac_compute	(	mcuxClSession_Handle_t	session,
		mcuxClKey_Handle_t	key,
		mcuxClMac_Mode_t	mode,
		mcuxCl_InputBuffer_t	pIn,
		uint32_t	inLength,
		mcuxCl_Buffer_t	pMac,
		uint32_t *const	pMacLength )

One-shot message authentication code (MAC) computation function.

This function performs a MAC computation in one shot. The algorithm to be used will be determined based on the key that is provided.

For example, to perform an AES MAC computation with a 128-bit key in CMAC mode on padded data, the following needs to be provided:

• AES128 key
• CMAC mode
• Input data
• Output data buffer, at least the size of a single AES block

Attention

In some cases restrictions may apply, e.g. the input buffer must be prepared for padding. Please refer to mcuxClMacModes_Modes.h to find further details and restrictions for each specific mode. This function supports non-blocking operation modes. If a non-blocking mode is used, this function starts the operation and returns while coprocessors are still operating, unblocking the CPU in the meantime. Interrupt handlers need to be installed appropriately to retrieve the information that the coprocessors finished processing the data. Call mcuxClResource_handle_interrupt to complete this operation.

Parameters

[in]	session	Handle for the current CL session.
[in]	key	Key to be used to authenticate the data (word-aligned).
[in]	mode	Mode that should be used during the MAC operation.
[in]	pIn	Pointer to the input buffer that contains the data that needs to be authenticated.
[in]	inLength	Number of bytes of data in the pIn buffer.
[out]	pMac	Pointer to the output buffer where the MAC needs to be written.
[out]	pMacLength	Will be set to the number of bytes of data that have been written to the pMac buffer.

Returns

A code-flow protected error code (see Flow Protection API)

Return values

MCUXCLMAC_STATUS_OK	Mac operation successful
MCUXCLMAC_STATUS_ERROR	Error occurred during Mac operation
MCUXCLMAC_STATUS_INVALID_PARAM	An invalid parameter was given to the function
MCUXCLMAC_STATUS_FAULT_ATTACK	Fault attack detected
MCUXCLSGI_STATUS_UNWRAP_ERROR	Error during RFC3394 Key Unwrap detected. An SGI reset or FULL_FLUSH needs to be performed.

Attention

If the given key handle contains a RFC3394 wrapped key which was not pre-loaded yet, this operation will unwrap the key material. This can potentially lead to a MCUXCLSGI_STATUS_UNWRAP_ERROR.

For GMAC, the H-key is created and always loaded to SGI KEY2. It is caller's responsibility to not have a preloaded key in SGI KEY2 when calling a GMAC operation.

Return values

MCUXCLMAC_STATUS_JOB_STARTED	Non-blocking operation started successfully
MCUXCLMAC_STATUS_JOB_COMPLETED	Non-blocking operation successful

Attention

For non-blocking modes: The inLength has an upper limit of 0x7fff0 bytes. Also, if the inLength is small (only a few blocks of data), this function is not guaranteed to return in a non-blocking matter, but might return after all data was already processed. The status code shall be used as an indicator, where only MCUXCLMAC_STATUS_JOB_STARTED indicates that a non-blocking operation has started.

Examples

mcuxClHmac_Sw_Oneshot_example.c, mcuxClMacModes_Cmac_Aes128_Compute_Dma_NonBlocking_example.c, mcuxClMacModes_Cmac_Aes128_Compute_PreloadedKey_example.c, mcuxClMacModes_Cmac_Aes128_Compute_example.c, and mcuxClMacModes_Cmac_Aes256_Compute_example.c.