Multi part MAC interfaces

Interfaces to perform MAC operations in multi part. More...

Functions
mcuxClMac_Status_t	mcuxClMac_init (mcuxClSession_Handle_t session, mcuxClMac_Context_t *const pContext, mcuxClKey_Handle_t key, mcuxClMac_Mode_t mode)
	Initialization for a multipart MAC computation.
mcuxClMac_Status_t	mcuxClMac_process (mcuxClSession_Handle_t session, mcuxClMac_Context_t *const pContext, mcuxCl_InputBuffer_t pIn, uint32_t inLength)
	Data processing for a multipart MAC computation.
mcuxClMac_Status_t	mcuxClMac_finish (mcuxClSession_Handle_t session, mcuxClMac_Context_t *const pContext, mcuxCl_Buffer_t pMac, uint32_t *const pMacLength)
	Finalize a MAC generation for a multipart MAC computation.

Detailed Description

Interfaces to perform MAC operations in multi part.

Function Documentation

mcuxClMac_init()

mcuxClMac_Status_t mcuxClMac_init	(	mcuxClSession_Handle_t	session,
		mcuxClMac_Context_t *const	pContext,
		mcuxClKey_Handle_t	key,
		mcuxClMac_Mode_t	mode )

Initialization for a multipart MAC computation.

This function performs the initialization of a context for a multipart MAC computation. The algorithm to be used will be determined based on the key that is provided. After init operation, a pointer to the whole key handle is stored in context. The user of the Crypto Library needs to keep the keyHandle alive until the mcuxClMac_finish/mcuxClMac_verify phase of mac multipart operation.

This function should only be called once, as the first step for a multipart computation.

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

• AES128 key
• CMAC mode

The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).

Parameters

[in]	session	Handle for the current CL session.
[in]	pContext	MAC context which is used to maintain the state and store other relevant information about the operation (word-aligned).
[in]	key	Key to be used to MAC the data (word-aligned).
[in]	mode	Mode that should be used during the MAC operation.

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.

Examples

mcuxClHmac_Sw_Multipart_example.c, mcuxClMacModes_Cmac_Aes128_Multipart_Dma_NonBlocking_example.c, and mcuxClMacModes_Cmac_Aes128_Multipart_example.c.

mcuxClMac_process()

mcuxClMac_Status_t mcuxClMac_process	(	mcuxClSession_Handle_t	session,
		mcuxClMac_Context_t *const	pContext,
		mcuxCl_InputBuffer_t	pIn,
		uint32_t	inLength )

Data processing for a multipart MAC computation.

This function performs the data processing for a multipart MAC computation. The algorithm and key to be used will be determined based on the context that is provided. The user of the Crypto Library needs to keep the keyHandle alive until the mcuxClMac_finish/ mcuxClMac_verify phase of mac multipart operation.

This function can be called multiple times, after the multipart context initialization.

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

• Input data This function supports non-blocking operation modes. If a non-blocking mode was used during mcuxClMac_init, 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. The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).

See also

mcuxClMac_init

Parameters

	session	Handle for the current CL session.
[in]	pContext	MAC context which is used to maintain the state and store other relevant information about the operation (word-aligned).
[in]	pIn	Pointer to the input buffer that contains the data that need to be processed.
[in]	inLength	Number of bytes of data in the in 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
MCUXCLMAC_STATUS_JOB_STARTED	Non-blocking Mac operation started successfully
MCUXCLMAC_STATUS_JOB_COMPLETED	Non-blocking Mac 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_Multipart_example.c, mcuxClMacModes_Cmac_Aes128_Multipart_Dma_NonBlocking_example.c, and mcuxClMacModes_Cmac_Aes128_Multipart_example.c.

mcuxClMac_finish()

mcuxClMac_Status_t mcuxClMac_finish	(	mcuxClSession_Handle_t	session,
		mcuxClMac_Context_t *const	pContext,
		mcuxCl_Buffer_t	pMac,
		uint32_t *const	pMacLength )

Finalize a MAC generation for a multipart MAC computation.

This function performs the final MAC generation step for a multipart MAC computation. The algorithm and key to be used will be determined based on the context that is provided. The user of the Crypto Library needs to keep the keyHandle alive until the mcuxClMac_finish phase of mac multipart operation.

This function should only be called once, as the last step for a multipart computation.

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

• Output data buffer, at least the size of a single AES block

The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).

See also

mcuxClMac_init

mcuxClMac_process

Parameters

[in]	session	Handle for the current CL session.
[in]	pContext	MAC context which is used to maintain the state and store other relevant information about the operation (word-aligned).
[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

Examples

mcuxClHmac_Sw_Multipart_example.c, mcuxClMacModes_Cmac_Aes128_Multipart_Dma_NonBlocking_example.c, and mcuxClMacModes_Cmac_Aes128_Multipart_example.c.