mcuxClCipher_Functions

Interfaces to perform Cipher operations. More...

Functions
mcuxClCipher_Status_t	mcuxClCipher_encrypt (mcuxClSession_Handle_t session, mcuxClKey_Handle_t key, mcuxClCipher_Mode_t mode, mcuxCl_InputBuffer_t pIv, uint32_t ivLength, mcuxCl_InputBuffer_t pIn, uint32_t inLength, mcuxCl_Buffer_t pOut, uint32_t *const pOutLength)
	One-shot encryption function.
mcuxClCipher_Status_t	mcuxClCipher_decrypt (mcuxClSession_Handle_t session, mcuxClKey_Handle_t key, mcuxClCipher_Mode_t mode, mcuxCl_InputBuffer_t pIv, uint32_t ivLength, mcuxCl_InputBuffer_t pIn, uint32_t inLength, mcuxCl_Buffer_t pOut, uint32_t *const pOutLength)
	One-shot decryption function.
mcuxClCipher_Status_t	mcuxClCipher_init_encrypt (mcuxClSession_Handle_t session, mcuxClCipher_Context_t *const pContext, mcuxClKey_Handle_t key, mcuxClCipher_Mode_t mode, mcuxCl_InputBuffer_t pIv, uint32_t ivLength)
	Multi-part encryption initialization function.
mcuxClCipher_Status_t	mcuxClCipher_init_decrypt (mcuxClSession_Handle_t session, mcuxClCipher_Context_t *const pContext, mcuxClKey_Handle_t key, mcuxClCipher_Mode_t mode, mcuxCl_InputBuffer_t pIv, uint32_t ivLength)
	Multi-part decryption initialization function.
mcuxClCipher_Status_t	mcuxClCipher_process (mcuxClSession_Handle_t session, mcuxClCipher_Context_t *const pContext, mcuxCl_InputBuffer_t pIn, uint32_t inLength, mcuxCl_Buffer_t pOut, uint32_t *const pOutLength)
	Multi-part encryption/decryption processing function.
mcuxClCipher_Status_t	mcuxClCipher_finish (mcuxClSession_Handle_t session, mcuxClCipher_Context_t *const pContext, mcuxCl_Buffer_t pOut, uint32_t *const pOutLength)
	Multi-part encryption/decryption finalization function.

Detailed Description

Interfaces to perform Cipher operations.

Function Documentation

mcuxClCipher_encrypt()

mcuxClCipher_Status_t mcuxClCipher_encrypt	(	mcuxClSession_Handle_t	session,
		mcuxClKey_Handle_t	key,
		mcuxClCipher_Mode_t	mode,
		mcuxCl_InputBuffer_t	pIv,
		uint32_t	ivLength,
		mcuxCl_InputBuffer_t	pIn,
		uint32_t	inLength,
		mcuxCl_Buffer_t	pOut,
		uint32_t *const	pOutLength )

One-shot encryption function.

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

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

• AES128 key
• CBC mode, without padding
• IV, same size as the AES block size
• Plain input data, size must be a multiple of the AES block size
• Output data buffer, with the same size as the input data
• Output size buffer, to store the amount of written bytes 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

  	session	Handle for the current CL session.
  	key	Key to be used to encrypt the data (word-aligned).
  	mode	Cipher mode that should be used during the encryption operation.
  [in]	pIv	Pointer to the buffer that contains the IV or salt, if needed for the chosen mode, otherwise ignored.
  	ivLength	Number of bytes of data in the pIv buffer.
  [in]	pIn	Pointer to the input buffer that contains the plain data that needs to be encrypted.
  	inLength	Number of bytes of plain data in the pIn buffer.
  [out]	pOut	Pointer to the output buffer where the encrypted data needs to be written.
  [out]	pOutLength	Will be set to the number of bytes of encrypted data that have been written to the pOut buffer.

  Returns

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

  Return values

  MCUXCLCIPHER_STATUS_OK	Cipher operation successful
  MCUXCLCIPHER_STATUS_ERROR	Error occurred during Cipher operation
  MCUXCLCIPHER_STATUS_FAILURE	Functional failure ocurred during Cipher operation
  MCUXCLCIPHER_STATUS_INVALID_INPUT	An invalid parameter was given to the function
  MCUXCLCIPHER_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.

  Return values

  MCUXCLCIPHER_STATUS_JOB_STARTED	Non-blocking Cipher operation started successfully
  MCUXCLCIPHER_STATUS_JOB_COMPLETED	Non-blocking Cipher 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 Cipher status code shall be used as an indicator, where only MCUXCLCIPHER_STATUS_JOB_STARTED indicates that a non-blocking operation has started.

  When used with stream modes or RSA modes, the function uses PRNG, which has to be initialized prior to calling the function.

Examples

mcuxClCipherModes_Cbc_Aes128_Oneshot_Dma_NonBlocking_example.c, mcuxClCipherModes_Cbc_Aes128_Oneshot_PaddingISO_example.c, mcuxClCipherModes_Cbc_Aes128_Oneshot_PaddingZero_example.c, mcuxClCipherModes_Cbc_Aes128_Oneshot_example.c, mcuxClCipherModes_Ctr_Aes128_Oneshot_Dma_NonBlocking_example.c, mcuxClCipherModes_Ctr_Aes128_Oneshot_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_Dma_NonBlocking_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_PaddingISO_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_PaddingPKCS7_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_PaddingZero_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_PreloadedKey_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_example.c, mcuxClKey_Load_Flush_Sgi_example.c, and mcuxClKey_Unwrap_Rfc3394_Sgi_example.c.

mcuxClCipher_decrypt()

mcuxClCipher_Status_t mcuxClCipher_decrypt	(	mcuxClSession_Handle_t	session,
		mcuxClKey_Handle_t	key,
		mcuxClCipher_Mode_t	mode,
		mcuxCl_InputBuffer_t	pIv,
		uint32_t	ivLength,
		mcuxCl_InputBuffer_t	pIn,
		uint32_t	inLength,
		mcuxCl_Buffer_t	pOut,
		uint32_t *const	pOutLength )

One-shot decryption function.

This function performs a decryption operation in one shot. The algorithm to be used will be determined based on the key and mode that are provided.

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

• AES128 key
• CBC mode, without padding
• IV, same size as the AES block size
• Encrypted input data, size must be a multiple of the AES block size
• Output data buffer, with the same size as the input data
• Output size buffer, to store the amount of written bytes 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

  	session	Handle for the current CL session.
  	key	Key to be used to decrypt the data (word-aligned).
  	mode	Cipher mode that should be used during the decryptionu operation.
  [in]	pIv	Pointer to the buffer that contains the IV or salt, if needed for the chosen mode, otherwise ignored.
  	ivLength	Number of bytes of data in the pIv buffer.
  [in]	pIn	Pointer to the input buffer that contains the encrypted data that needs to be decrypted.
  	inLength	Number of bytes of encrypted data in the pIn 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 pOut buffer.

  Returns

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

  Return values

  MCUXCLCIPHER_STATUS_OK	Cipher operation successful
  MCUXCLCIPHER_STATUS_ERROR	Error occurred during Cipher operation
  MCUXCLCIPHER_STATUS_FAILURE	Functional failure ocurred during Cipher operation
  MCUXCLCIPHER_STATUS_INVALID_INPUT	An invalid parameter was given to the function
  MCUXCLCIPHER_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.

  Return values

  MCUXCLCIPHER_STATUS_JOB_STARTED	Non-blocking Cipher operation started successfully
  MCUXCLCIPHER_STATUS_JOB_COMPLETED	Non-blocking Cipher 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 Cipher status code shall be used as an indicator, where only MCUXCLCIPHER_STATUS_JOB_STARTED indicates that a non-blocking operation has started.

  When used with stream modes or RSA modes, the function uses PRNG, which has to be initialized prior to calling the function.

Examples

mcuxClCipherModes_Cbc_Aes128_Oneshot_Dma_NonBlocking_example.c, mcuxClCipherModes_Cbc_Aes128_Oneshot_PaddingISO_example.c, mcuxClCipherModes_Cbc_Aes128_Oneshot_PaddingZero_example.c, mcuxClCipherModes_Cbc_Aes128_Oneshot_example.c, mcuxClCipherModes_Ctr_Aes128_Oneshot_Dma_NonBlocking_example.c, mcuxClCipherModes_Ctr_Aes128_Oneshot_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_Dma_NonBlocking_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_PaddingISO_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_PaddingPKCS7_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_PaddingZero_example.c, mcuxClCipherModes_Ecb_Aes128_Oneshot_PreloadedKey_example.c, and mcuxClCipherModes_Ecb_Aes128_Oneshot_example.c.

mcuxClCipher_init_encrypt()

mcuxClCipher_Status_t mcuxClCipher_init_encrypt	(	mcuxClSession_Handle_t	session,
		mcuxClCipher_Context_t *const	pContext,
		mcuxClKey_Handle_t	key,
		mcuxClCipher_Mode_t	mode,
		mcuxCl_InputBuffer_t	pIv,
		uint32_t	ivLength )

Multi-part encryption initialization function.

This function performs the initialization for a multi part 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 mcuxClCipher_finish phase of cipher multipart operation.

Parameters

	session	Handle for the current CL session.
	pContext	Cipher 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	Cipher mode that should be used during the encryption operation.
[in]	pIv	Pointer to the buffer that contains the IV, if needed for the chosen mode, otherwise ignored.
	ivLength	Number of bytes of data in the pIv buffer.

Returns

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

Return values

MCUXCLCIPHER_STATUS_OK	Cipher operation successful
MCUXCLCIPHER_STATUS_ERROR	Error occurred during Cipher operation
MCUXCLCIPHER_STATUS_FAILURE	Functional failure ocurred during Cipher operation
MCUXCLCIPHER_STATUS_INVALID_INPUT	An invalid parameter was given to the function
MCUXCLCIPHER_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.

Examples

mcuxClCipherModes_Cbc_Aes128_Multipart_KeyRfc3394Encoding_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_PaddingISO_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_PaddingZero_Dma_NonBlocking_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_PaddingZero_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_example.c, mcuxClCipherModes_Ctr_Aes128_Multipart_Dma_NonBlocking_example.c, mcuxClCipherModes_Ctr_Aes128_Multipart_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingISO_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingZero_Dma_NonBlocking_MultipleProcess_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingZero_Dma_NonBlocking_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingZero_example.c, and mcuxClCipherModes_Ecb_Aes128_Multipart_example.c.

mcuxClCipher_init_decrypt()

mcuxClCipher_Status_t mcuxClCipher_init_decrypt	(	mcuxClSession_Handle_t	session,
		mcuxClCipher_Context_t *const	pContext,
		mcuxClKey_Handle_t	key,
		mcuxClCipher_Mode_t	mode,
		mcuxCl_InputBuffer_t	pIv,
		uint32_t	ivLength )

Multi-part decryption initialization function.

This function performs the initialization for a multi part 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 mcuxClCipher_finish phase of cipher multipart operation.

Parameters

	session	Handle for the current CL session.
	pContext	Cipher 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	Cipher mode that should be used during the encryption operation.
[in]	pIv	Pointer to the buffer that contains the IV, if needed for the chosen mode, otherwise ignored.
	ivLength	Number of bytes of data in the pIv buffer.

Returns

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

Return values

MCUXCLCIPHER_STATUS_OK	Cipher operation successful
MCUXCLCIPHER_STATUS_ERROR	Error occurred during Cipher operation
MCUXCLCIPHER_STATUS_FAILURE	Functional failure ocurred during Cipher operation
MCUXCLCIPHER_STATUS_INVALID_INPUT	An invalid parameter was given to the function
MCUXCLCIPHER_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.

Examples

mcuxClCipherModes_Cbc_Aes128_Multipart_KeyRfc3394Encoding_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_PaddingISO_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_PaddingZero_Dma_NonBlocking_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_PaddingZero_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_example.c, mcuxClCipherModes_Ctr_Aes128_Multipart_Dma_NonBlocking_example.c, mcuxClCipherModes_Ctr_Aes128_Multipart_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingISO_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingZero_Dma_NonBlocking_MultipleProcess_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingZero_Dma_NonBlocking_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingZero_example.c, and mcuxClCipherModes_Ecb_Aes128_Multipart_example.c.

mcuxClCipher_process()

mcuxClCipher_Status_t mcuxClCipher_process	(	mcuxClSession_Handle_t	session,
		mcuxClCipher_Context_t *const	pContext,
		mcuxCl_InputBuffer_t	pIn,
		uint32_t	inLength,
		mcuxCl_Buffer_t	pOut,
		uint32_t *const	pOutLength )

Multi-part encryption/decryption processing function.

This function performs the processing of (a part of) a data stream for an 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 mcuxClCipher_finish phase of cipher multipart operation. Data is processed in full blocks only. Remaining data is stored in the context to be handled in later process or finish calls. This function supports non-blocking operation modes. If a non-blocking mode was used during mcuxClCipher_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.

Parameters

	session	Handle for the current CL session.
	pContext	Cipher 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 pIn 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 pOut buffer.

Returns

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

Return values

MCUXCLCIPHER_STATUS_OK	Cipher operation successful
MCUXCLCIPHER_STATUS_ERROR	Error occurred during Cipher operation
MCUXCLCIPHER_STATUS_FAILURE	Functional failure ocurred during Cipher operation
MCUXCLCIPHER_STATUS_INVALID_INPUT	An invalid parameter was given to the function
MCUXCLCIPHER_STATUS_FAULT_ATTACK	Fault attack detected
MCUXCLCIPHER_STATUS_JOB_STARTED	Non-blocking Cipher operation started successfully
MCUXCLCIPHER_STATUS_JOB_COMPLETED	Non-blocking Cipher 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 Cipher status code shall be used as an indicator, where only MCUXCLCIPHER_STATUS_JOB_STARTED indicates that a non-blocking operation has started.

Examples

mcuxClCipherModes_Cbc_Aes128_Multipart_KeyRfc3394Encoding_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_PaddingISO_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_PaddingZero_Dma_NonBlocking_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_PaddingZero_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_example.c, mcuxClCipherModes_Ctr_Aes128_Multipart_Dma_NonBlocking_example.c, mcuxClCipherModes_Ctr_Aes128_Multipart_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingISO_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingZero_Dma_NonBlocking_MultipleProcess_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingZero_Dma_NonBlocking_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingZero_example.c, and mcuxClCipherModes_Ecb_Aes128_Multipart_example.c.

mcuxClCipher_finish()

mcuxClCipher_Status_t mcuxClCipher_finish	(	mcuxClSession_Handle_t	session,
		mcuxClCipher_Context_t *const	pContext,
		mcuxCl_Buffer_t	pOut,
		uint32_t *const	pOutLength )

Multi-part encryption/decryption finalization function.

This function performs the finalization of an encryption or 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 mcuxClCipher_finish phase of cipher multipart operation. No new data is accepted but remaining data in the context is processed.

Parameters

	session	Handle for the current CL session.
	pContext	Cipher 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 pOut buffer.

Returns

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

Return values

MCUXCLCIPHER_STATUS_OK	Cipher operation successful
MCUXCLCIPHER_STATUS_ERROR	Error occurred during Cipher operation
MCUXCLCIPHER_STATUS_FAILURE	Functional failure ocurred during Cipher operation
MCUXCLCIPHER_STATUS_INVALID_INPUT	An invalid parameter was given to the function
MCUXCLCIPHER_STATUS_FAULT_ATTACK	Fault attack detected

Attention

When used with stream modes, the function uses PRNG, which has to be initialized prior to calling the function.

Examples

mcuxClCipherModes_Cbc_Aes128_Multipart_KeyRfc3394Encoding_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_PaddingISO_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_PaddingZero_Dma_NonBlocking_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_PaddingZero_example.c, mcuxClCipherModes_Cbc_Aes128_Multipart_example.c, mcuxClCipherModes_Ctr_Aes128_Multipart_Dma_NonBlocking_example.c, mcuxClCipherModes_Ctr_Aes128_Multipart_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingISO_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingZero_Dma_NonBlocking_MultipleProcess_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingZero_Dma_NonBlocking_example.c, mcuxClCipherModes_Ecb_Aes128_Multipart_PaddingZero_example.c, and mcuxClCipherModes_Ecb_Aes128_Multipart_example.c.