mcuxClAead_Functions

Interfaces to perform AEAD operations. More...

Functions
mcuxClAead_Status_t	mcuxClAead_encrypt (mcuxClSession_Handle_t session, mcuxClKey_Handle_t key, mcuxClAead_Mode_t mode, mcuxCl_InputBuffer_t pNonce, uint32_t nonceLength, mcuxCl_InputBuffer_t pIn, uint32_t inLength, mcuxCl_InputBuffer_t pAdata, uint32_t adataLength, mcuxCl_Buffer_t pOut, uint32_t *const pOutLength, mcuxCl_Buffer_t pTag, uint32_t tagLength)
	One-shot authenticated encryption function.
mcuxClAead_Status_t	mcuxClAead_decrypt (mcuxClSession_Handle_t session, mcuxClKey_Handle_t key, mcuxClAead_Mode_t mode, mcuxCl_InputBuffer_t pNonce, uint32_t nonceLength, mcuxCl_InputBuffer_t pIn, uint32_t inLength, mcuxCl_InputBuffer_t pAdata, uint32_t adataLength, mcuxCl_InputBuffer_t pTag, uint32_t tagLength, mcuxCl_Buffer_t pOut, uint32_t *const pOutLength)
	One-shot authenticated decryption function.
mcuxClAead_Status_t	mcuxClAead_init_encrypt (mcuxClSession_Handle_t session, mcuxClAead_Context_t *const pContext, mcuxClKey_Handle_t key, mcuxClAead_Mode_t mode, mcuxCl_InputBuffer_t pNonce, uint32_t nonceLength, uint32_t inLength, uint32_t adataLength, uint32_t tagLength)
	Multi-part authenticated encryption initialization function.
mcuxClAead_Status_t	mcuxClAead_init_decrypt (mcuxClSession_Handle_t session, mcuxClAead_Context_t *const pContext, mcuxClKey_Handle_t key, mcuxClAead_Mode_t mode, mcuxCl_InputBuffer_t pNonce, uint32_t nonceLength, uint32_t inLength, uint32_t adataLength, uint32_t tagLength)
	Multi-part authenticated decryption initialization function.
mcuxClAead_Status_t	mcuxClAead_process (mcuxClSession_Handle_t session, mcuxClAead_Context_t *const pContext, mcuxCl_InputBuffer_t pIn, uint32_t inLength, mcuxCl_Buffer_t pOut, uint32_t *const pOutLength)
	Multi-part authenticated encryption/decryption processing function for the regular data (authenticated and encrypted).
mcuxClAead_Status_t	mcuxClAead_process_adata (mcuxClSession_Handle_t session, mcuxClAead_Context_t *const pContext, mcuxCl_InputBuffer_t pAdata, uint32_t adataLength)
	Multi-part authenticated encryption/decryption processing function for the associated data (authenticated only).
mcuxClAead_Status_t	mcuxClAead_finish (mcuxClSession_Handle_t session, mcuxClAead_Context_t *const pContext, mcuxCl_Buffer_t pOut, uint32_t *const pOutLength, mcuxCl_Buffer_t pTag)
	Multi-part authenticated encryption/decryption finalization function.
mcuxClAead_Status_t	mcuxClAead_verify (mcuxClSession_Handle_t session, mcuxClAead_Context_t *const pContext, mcuxCl_InputBuffer_t pTag, mcuxCl_Buffer_t pOut, uint32_t *const pOutLength)
	Multi-part authenticated decryption verification function.

Detailed Description

Interfaces to perform AEAD operations.

Function Documentation

mcuxClAead_encrypt()

mcuxClAead_Status_t mcuxClAead_encrypt	(	mcuxClSession_Handle_t	session,
		mcuxClKey_Handle_t	key,
		mcuxClAead_Mode_t	mode,
		mcuxCl_InputBuffer_t	pNonce,
		uint32_t	nonceLength,
		mcuxCl_InputBuffer_t	pIn,
		uint32_t	inLength,
		mcuxCl_InputBuffer_t	pAdata,
		uint32_t	adataLength,
		mcuxCl_Buffer_t	pOut,
		uint32_t *const	pOutLength,
		mcuxCl_Buffer_t	pTag,
		uint32_t	tagLength )

One-shot authenticated encryption function.

This function performs an authenticated encryption operation in one shot. The algorithm to be used will be determined based on the key that is provided.

For example, to perform an AES authenticated encryption operation with a 128-bit key in CCM mode on padded data, the following needs to be provided:

• AES128 key
• CCM mode
• Nonce
• Plain input data
• Associated data
• Output data buffer
• Output length buffer, to store the amount of written bytes
• Tag buffer, to store the authentication tag

Parameters

	session	Handle for the current CL session.
	key	Key to be used to encrypt the data (word-aligned).
	mode	AEAD mode that should be used during the encryption operation.
[in]	pNonce	Pointer to the buffer that contains the nonce.
	nonceLength	Number of bytes of nonce data in the nonce buffer.
[in]	pIn	Pointer to the input buffer that contains the plain data that need to be authenticated and encrypted.
	inLength	Number of bytes of plain data in the in buffer.
[in]	pAdata	Associated data for the authenticated encryption operation. Data format depends on the chosen mode.
	adataLength	Number of bytes of associated data in the adata buffer.
[out]	pOut	Pointer to the output buffer where the authenticated encrypted data needs to be written.
[out]	pOutLength	Will be set to the number of bytes of authenticated encrypted data that have been written to the out buffer.
[out]	pTag	Pointer to the output buffer where the tag needs to be written.
	tagLength	Number of bytes of tag data that will be written to the tag buffer.

Returns

status

Return values

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 GCM, the GMAC 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 an AEAD-GCM operation.

Examples

mcuxClAeadModes_Ccm_Aes128_Oneshot_Nist1_example.c, mcuxClAeadModes_Ccm_Aes128_Oneshot_Nist2_example.c, mcuxClAeadModes_Ccm_Aes128_Oneshot_PreloadedKey_example.c, mcuxClAeadModes_Gcm_Aes128_Oneshot_LongNonce_example.c, and mcuxClAeadModes_Gcm_Aes128_Oneshot_example.c.

mcuxClAead_decrypt()

mcuxClAead_Status_t mcuxClAead_decrypt	(	mcuxClSession_Handle_t	session,
		mcuxClKey_Handle_t	key,
		mcuxClAead_Mode_t	mode,
		mcuxCl_InputBuffer_t	pNonce,
		uint32_t	nonceLength,
		mcuxCl_InputBuffer_t	pIn,
		uint32_t	inLength,
		mcuxCl_InputBuffer_t	pAdata,
		uint32_t	adataLength,
		mcuxCl_InputBuffer_t	pTag,
		uint32_t	tagLength,
		mcuxCl_Buffer_t	pOut,
		uint32_t *const	pOutLength )

One-shot authenticated decryption function.

This function performs an authenticated decryption operation in one shot. The algorithm to be used will be determined based on the key that is provided.

For example, to perform an AES authenticated decryption operation with a 128-bit key in CCM mode on padded data, the following needs to be provided:

• AES128 key
• CCM mode
• Nonce
• Encrypted input data, length must be a multiple of the AES block size
• Associated data
• Authentication tag
• Output data buffer
• Output length buffer

Parameters

	session	Handle for the current CL session.
	key	Key to be used to decrypt the data (word-aligned).
	mode	AEAD mode that should be used during the decryption operation.
[in]	pNonce	Pointer to the buffer that contains the nonce.
	nonceLength	Number of bytes of nonce data in the nonce buffer.
[in]	pIn	Pointer to the input buffer that contains the encrypted data that need to be authenticated and decrypted.
	inLength	Number of bytes of encrypted data in the in buffer.
[in]	pAdata	Associated data for the authenticated decryption operation. Data format depends on the chosen mode.
	adataLength	Number of bytes of associated data in the adata buffer.
[in]	pTag	Pointer to the buffer that contains the tag.
	tagLength	Number of bytes of tag data in the tag buffer.
[out]	pOut	Pointer to the output buffer where the plain data needs to be written.
[out]	pOutLength	Will be set to the number of bytes of plain data that have been written to the out buffer.

Returns

status

Return values

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 GCM, the GMAC 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 an AEAD-GCM operation.

Examples

mcuxClAeadModes_Ccm_Aes128_Oneshot_Nist1_example.c, mcuxClAeadModes_Ccm_Aes128_Oneshot_Nist2_example.c, mcuxClAeadModes_Ccm_Aes128_Oneshot_PreloadedKey_example.c, mcuxClAeadModes_Gcm_Aes128_Oneshot_LongNonce_example.c, and mcuxClAeadModes_Gcm_Aes128_Oneshot_example.c.

mcuxClAead_init_encrypt()

mcuxClAead_Status_t mcuxClAead_init_encrypt	(	mcuxClSession_Handle_t	session,
		mcuxClAead_Context_t *const	pContext,
		mcuxClKey_Handle_t	key,
		mcuxClAead_Mode_t	mode,
		mcuxCl_InputBuffer_t	pNonce,
		uint32_t	nonceLength,
		uint32_t	inLength,
		uint32_t	adataLength,
		uint32_t	tagLength )

Multi-part authenticated encryption initialization function.

This function performs the initialization for a multi part authenticated encryption operation. 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 mcuxClAead_finish/mcuxClAead_verify phase of aead multipart operation.

Parameters

	session	Handle for the current CL session.
	pContext	AEAD context which is used to maintain the state and store other relevant information about the operation (word-aligned).
	key	Key to be used to encrypt the data (word-aligned).
	mode	AEAD mode that should be used during the encryption operation.
[in]	pNonce	Pointer to the buffer that contains the nonce.
	nonceLength	Number of bytes of nonce data in the nonce buffer.
	inLength	Number of bytes of plain data that will be processed.
	adataLength	Number of bytes of associated data that will be processed.
	tagLength	Number of bytes to be used for the authentication tag.

Returns

status

Return values

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 GCM, the GMAC 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 an AEAD-GCM operation.

Examples

mcuxClAeadModes_Ccm_Aes128_Multipart_example.c, and mcuxClAeadModes_Gcm_Aes128_Multipart_example.c.

mcuxClAead_init_decrypt()

mcuxClAead_Status_t mcuxClAead_init_decrypt	(	mcuxClSession_Handle_t	session,
		mcuxClAead_Context_t *const	pContext,
		mcuxClKey_Handle_t	key,
		mcuxClAead_Mode_t	mode,
		mcuxCl_InputBuffer_t	pNonce,
		uint32_t	nonceLength,
		uint32_t	inLength,
		uint32_t	adataLength,
		uint32_t	tagLength )

Multi-part authenticated decryption initialization function.

This function performs the initialization for a multi part authenticated decryption operation. 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 mcuxClAead_finish/mcuxClAead_verify phase of aead multipart operation.

Parameters

	session	Handle for the current CL session.
	pContext	AEAD context which is used to maintain the state and store other relevant information about the operation (word-aligned).
	key	Key to be used to encrypt the data (word-aligned).
	mode	AEAD mode that should be used during the encryption operation.
[in]	pNonce	Pointer to the buffer that contains the nonce.
	nonceLength	Number of bytes of nonce data in the nonce buffer.
	inLength	Number of bytes of encrypted data that will be processed.
	adataLength	Number of bytes of associated data that will be processed.
	tagLength	Number of bytes used for the authentication tag.

Returns

status

Return values

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 GCM, the GMAC 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 an AEAD-GCM operation.

Examples

mcuxClAeadModes_Ccm_Aes128_Multipart_example.c, and mcuxClAeadModes_Gcm_Aes128_Multipart_example.c.

mcuxClAead_process()

mcuxClAead_Status_t mcuxClAead_process	(	mcuxClSession_Handle_t	session,
		mcuxClAead_Context_t *const	pContext,
		mcuxCl_InputBuffer_t	pIn,
		uint32_t	inLength,
		mcuxCl_Buffer_t	pOut,
		uint32_t *const	pOutLength )

Multi-part authenticated encryption/decryption processing function for the regular data (authenticated and encrypted).

This function performs the processing of (a part of) a data stream for an authenticated encryption/decryption operation. 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 mcuxClAead_finish/ mcuxClAead_verify phase of aead multipart operation.

Parameters

	session	Handle for the current CL session.
	pContext	AEAD 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 needs to be processed.
	inLength	Number of bytes of data in the in buffer.
[out]	pOut	Pointer to the output buffer where the processed data needs to be written.
[out]	pOutLength	Will be set to the number of bytes of processed data that have been written to the out buffer.

Returns

status

Examples

mcuxClAeadModes_Ccm_Aes128_Multipart_example.c, and mcuxClAeadModes_Gcm_Aes128_Multipart_example.c.

mcuxClAead_process_adata()

mcuxClAead_Status_t mcuxClAead_process_adata	(	mcuxClSession_Handle_t	session,
		mcuxClAead_Context_t *const	pContext,
		mcuxCl_InputBuffer_t	pAdata,
		uint32_t	adataLength )

Multi-part authenticated encryption/decryption processing function for the associated data (authenticated only).

This function performs the processing of (a part of) an associated data stream for an authenticated encryption/decryption operation. 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 mcuxClAead_finish/mcuxClAead_verify phase of aead multipart operation.

Parameters

	session	Handle for the current CL session.
	pContext	AEAD context which is used to maintain the state and store other relevant information about the operation (word-aligned).
[in]	pAdata	Associated data that needs to be proccessed.
	adataLength	Number of bytes of associated data in the adata buffer.

Returns

status

Examples

mcuxClAeadModes_Ccm_Aes128_Multipart_example.c, and mcuxClAeadModes_Gcm_Aes128_Multipart_example.c.

mcuxClAead_finish()

mcuxClAead_Status_t mcuxClAead_finish	(	mcuxClSession_Handle_t	session,
		mcuxClAead_Context_t *const	pContext,
		mcuxCl_Buffer_t	pOut,
		uint32_t *const	pOutLength,
		mcuxCl_Buffer_t	pTag )

Multi-part authenticated encryption/decryption finalization function.

This function performs the finalization of an authenticated encryption or decryption operation and produces the authentication tag. 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 mcuxClAead_finish phase of aead multipart operation.

Note: the taglength is already specified when the INIT function is called.

Parameters

	session	Handle for the current CL session.
	pContext	AEAD context which is used to maintain the state and store other relevant information about the operation (word-aligned).
[out]	pOut	Pointer to the output buffer where the processed data needs to be written.
[out]	pOutLength	Will be set to the number of bytes of processed data that have been written to the out buffer.
[out]	pTag	Pointer to the output buffer where the tag needs to be written.

Returns

status

Examples

mcuxClAeadModes_Ccm_Aes128_Multipart_example.c, and mcuxClAeadModes_Gcm_Aes128_Multipart_example.c.

mcuxClAead_verify()

mcuxClAead_Status_t mcuxClAead_verify	(	mcuxClSession_Handle_t	session,
		mcuxClAead_Context_t *const	pContext,
		mcuxCl_InputBuffer_t	pTag,
		mcuxCl_Buffer_t	pOut,
		uint32_t *const	pOutLength )

Multi-part authenticated decryption verification function.

This function performs the finalization of an authenticated decryption operation and verifies the authentication tag. 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 mcuxClAead_verify phase of aead multipart operation.

This function can be used as an alternative for mcuxClAead_finish when one also wants to perform the tag verification step.

Note: the taglength is already specified when the INIT function is called.

Parameters

	session	Handle for the current CL session.
	pContext	AEAD context which is used to maintain the state and store other relevant information about the operation (word-aligned).
[in]	pTag	Pointer to the buffer that contains the tag.
[out]	pOut	Pointer to the output buffer where the authenticated decrypted data needs to be written.
[out]	pOutLength	Will be set to the number of bytes of authenticated decrypted data that have been written to the out buffer.

Returns

status

Examples

mcuxClAeadModes_Ccm_Aes128_Multipart_example.c, and mcuxClAeadModes_Gcm_Aes128_Multipart_example.c.