11 HAL CRYP Extension Driver

11.1CRYPEx Firmware driver API description

11.1.1How to use this driver

The CRYP Extension HAL driver can be used as follows:

1.Initialize the CRYP low level resources by implementing the HAL_CRYP_MspInit():

a.Enable the CRYP interface clock using __HAL_RCC_CRYP_CLK_ENABLE()

b.In case of using interrupts (e.g. HAL_CRYPEx_AESGCM_Encrypt_IT())

Configure the CRYP interrupt priority using HAL_NVIC_SetPriority()

Enable the CRYP IRQ handler using HAL_NVIC_EnableIRQ() (+) In CRYP IRQ handler, call HAL_CRYP_IRQHandler()

c.In case of using DMA to control data transfer (e.g.

HAL_AES_ECB_Encrypt_DMA())

Enable the DMAx interface clock using __DMAx_CLK_ENABLE()

Configure and enable two DMA streams one for managing data transfer from memory to peripheral (input stream) and another stream for managing data transfer from peripheral to memory (output stream)

Associate the initialized DMA handle to the CRYP DMA handle using

__HAL_LINKDMA()

Configure the priority and enable the NVIC for the transfer complete interrupt on the two DMA Streams. The output stream should have higher priority than the input stream HAL_NVIC_SetPriority() and HAL_NVIC_EnableIRQ()

2.Initialize the CRYP HAL using HAL_CRYP_Init(). This function configures mainly:

a.The data type: 1-bit, 8-bit, 16-bit and 32-bit

b.The key size: 128, 192 and 256. This parameter is relevant only for AES

c.The encryption/decryption key. Its size depends on the algorithm used for encryption/decryption

d.The initialization vector (counter). It is not used ECB mode.

3.Three processing (encryption/decryption) functions are available:

a.Polling mode: encryption and decryption APIs are blocking functions i.e. they process the data and wait till the processing is finished e.g. HAL_CRYPEx_AESGCM_Encrypt()

b.Interrupt mode: encryption and decryption APIs are not blocking functions i.e. they process the data under interrupt e.g. HAL_CRYPEx_AESGCM_Encrypt_IT()

c.DMA mode: encryption and decryption APIs are not blocking functions i.e. the data transfer is ensured by DMA e.g. HAL_CRYPEx_AESGCM_Encrypt_DMA()

4.When the processing function is called at first time after HAL_CRYP_Init() the CRYP peripheral is initialized and processes the buffer in input. At second call, the processing function performs an append of the already processed buffer. When a new data block is to be processed, call HAL_CRYP_Init() then the processing function.

5.In AES-GCM and AES-CCM modes are an authenticated encryption algorithms which provide authentication messages. HAL_AES_GCM_Finish() and HAL_AES_CCM_Finish() are used to provide those authentication messages. Call those functions after the processing ones (polling, interrupt or DMA). e.g. in AES-CCM mode call HAL_CRYPEx_AESCCM_Encrypt() to encrypt the plain data then call HAL_CRYPEx_AESCCM_Finish() to get the authentication message @note: For CCM Encrypt/Decrypt API's, only DataType = 8-bit is supported by this version. @note: The HAL_CRYPEx_AESGCM_xxxx() implementation is limited to 32bits

inputs data length (Plain/Cyphertext, Header) compared with GCM standards specifications (800-38D).

6.Call HAL_CRYP_DeInit() to deinitialize the CRYP peripheral.

The CRYP Extension HAL driver can be used as follows: (#)Initialize the CRYP low level resources by implementing the HAL_CRYP_MspInit(): (##) Enable the CRYP interface clock using __HAL_RCC_CRYP_CLK_ENABLE() (##) In case of using interrupts (e.g. HAL_CRYPEx_AESGCM_Encrypt_IT()) (+++) Configure the CRYP interrupt priority using HAL_NVIC_SetPriority() (+++) Enable the CRYP IRQ handler using HAL_NVIC_EnableIRQ()

In CRYP IRQ handler, call HAL_CRYP_IRQHandler() a. In case of using DMA to control data transfer (e.g.

HAL_AES_ECB_Encrypt_DMA())

Enable the DMAx interface clock using __DMAx_CLK_ENABLE()

Configure and enable two DMA streams one for managing data transfer from memory to peripheral (input stream) and another stream for managing data transfer from peripheral to memory (output stream)

Associate the initialized DMA handle to the CRYP DMA handle using

__HAL_LINKDMA()

Configure the priority and enable the NVIC for the transfer complete interrupt on the two DMA Streams. The output stream should have higher priority than the input stream HAL_NVIC_SetPriority() and HAL_NVIC_EnableIRQ() (#)Initialize the CRYP HAL using HAL_CRYP_Init(). This function configures mainly:

b.The data type: 1-bit, 8-bit, 16-bit and 32-bit

c.The key size: 128, 192 and 256. This parameter is relevant only for AES

d.The encryption/decryption key. Its size depends on the algorithm used for encryption/decryption

e.The initialization vector (counter). It is not used ECB mode. (#)Three processing (encryption/decryption) functions are available:

f.Polling mode: encryption and decryption APIs are blocking functions i.e. they process the data and wait till the processing is finished e.g. HAL_CRYPEx_AESGCM_Encrypt()

g.Interrupt mode: encryption and decryption APIs are not blocking functions i.e. they process the data under interrupt e.g. HAL_CRYPEx_AESGCM_Encrypt_IT()

h.DMA mode: encryption and decryption APIs are not blocking functions i.e. the data transfer is ensured by DMA e.g. HAL_CRYPEx_AESGCM_Encrypt_DMA() (#)When the processing function is called at first time after HAL_CRYP_Init() the CRYP peripheral is initialized and processes the buffer in input. At second call, the processing function performs an append of the already processed buffer. When a new data block is to be processed, call HAL_CRYP_Init() then the processing function. (#)In AES-GCM and AES-CCM modes are an authenticated encryption algorithms which provide authentication messages. HAL_AES_GCM_Finish() and HAL_AES_CCM_Finish() are used to provide those authentication messages. Call those functions after the processing ones (polling, interrupt or DMA). e.g. in AES-CCM mode call HAL_CRYPEx_AESCCM_Encrypt() to encrypt the plain data then call HAL_CRYPEx_AESCCM_Finish() to get the authentication message @note: For CCM Encrypt/Decrypt API's, only DataType = 8-bit is supported by this version. @note: The HAL_CRYPEx_AESGCM_xxxx() implementation is limited to 32bits inputs data length (Plain/Cyphertext, Header) compared with GCM standards specifications (800-38D). (#)Call HAL_CRYP_DeInit() to deinitialize the CRYP peripheral.

11.1.2Extended AES processing functions

This section provides functions allowing to:

Encrypt plaintext using AES-128/192/256 using GCM and CCM chaining modes

Decrypt cyphertext using AES-128/192/256 using GCM and CCM chaining modes

Finish the processing. This function is available only for GCM and CCM

Three processing methods are available:

Polling mode

Interrupt mode

DMA mode

This section contains the following APIs:

HAL_CRYPEx_AESCCM_Encrypt()

HAL_CRYPEx_AESGCM_Encrypt()

HAL_CRYPEx_AESGCM_Decrypt()

HAL_CRYPEx_AESGCM_Finish()

HAL_CRYPEx_AESCCM_Finish()

HAL_CRYPEx_AESCCM_Decrypt()

HAL_CRYPEx_AESGCM_Encrypt_IT()

HAL_CRYPEx_AESCCM_Encrypt_IT()

HAL_CRYPEx_AESGCM_Decrypt_IT()

HAL_CRYPEx_AESCCM_Decrypt_IT()

HAL_CRYPEx_AESGCM_Encrypt_DMA()

HAL_CRYPEx_AESCCM_Encrypt_DMA()

HAL_CRYPEx_AESGCM_Decrypt_DMA()

HAL_CRYPEx_AESCCM_Decrypt_DMA()

11.1.3CRYPEx IRQ handler management

This section provides CRYPEx IRQ handler function.

This section contains the following APIs:

HAL_CRYPEx_GCMCCM_IRQHandler()

11.1.4HAL_CRYPEx_AESCCM_Encrypt

11.1.5HAL_CRYPEx_AESGCM_Encrypt

11.1.6HAL_CRYPEx_AESGCM_Decrypt

11.1.7HAL_CRYPEx_AESGCM_Finish

11.1.8HAL_CRYPEx_AESCCM_Finish