HAL AES How to Use

group AES_How_To_Use

How to use the AES HAL module driver

The AES main features:

This AES HAL driver is a generic driver which contains a set of APIs allowing to configure the AES/SAES peripheral to an advanced encryption standard compliant algorithm in order to perform data encryption or decryption.

The AES HAL driver can be used as follows:

Initialization/De-initialization

  • Declare a hal_aes_handle_t handle structure, for example: hal_aes_handle_t haes

  • Initialize the AES low level resources:

    • Enable the AES/SAES peripheral clock:

    • NVIC configuration to use interrupt process APIs ( HAL_AES_Encrypt_IT() and HAL_AES_Decrypt_IT() ):

      • Configure the AES interrupt priority

      • Enable the NVIC AES IRQ Channel

    • DMA Configuration to use DMA process APIs( HAL_AES_Encrypt_DMA() and HAL_AES_Decrypt_DMA() ):

      • Declare a hal_dma_handle_t handle structure for the transfer input or transfer output channel

      • Enable the DMAx interface clock using

      • Configure the DMA handle parameters

      • Configure the DMA Inx or Outx channel

      • Associate the initialized DMA handle to the haes DMA In or Out handle

      • Configure the priority and enable the NVIC for the transfer complete interrupt on the DMA In or Out channel

  • Initialize the AES handle by calling the HAL_AES_Init() API that performs these operations:

    • The association of the instance to the handle

    • The initialization of the handle state to the HAL_AES_STATE_INIT

  • De-initialize the AES/SAES peripheral by calling the HAL_AES_DeInit() API that performs these operations:

    • The disable of the AES/SAES peripheral

    • The abort of the DMA input and output transfers

    • The de-initialization of the current handle object

    • The reset of the handle state to the HAL_AES_STATE_RESET

Configuration

  • The Configuration of the AES/SAES peripheral is ensured through three steps:

    • Step1 (Chaining mode(algorithm) configuration according to the defined compilation algorithm flag):

      • By default, all the compilation algorithm flags are defined but the user can undefine the not needed ones to well optimize his code and gain footprint.

      • The AES compilation algorithm flags are:

        • USE_HAL_AES_ECB_CBC_ALGO flag: The AES/SAES peripheral can be configured with one of the two following chaining modes:

        • USE_HAL_AES_CTR_ALGO flag: The AES peripheral is configured to Counter chaining mode(CTR) by using HAL_AES_CTR_SetConfig() API where the user must provide the initial vector

        • USE_HAL_AES_GCM_GMAC_ALGO flag: The AES peripheral is configured to Galois/counter chaining mode(GCM/GMAC) by using HAL_AES_GCM_GMAC_SetConfig() API where the user must provide the header, its size and the initial vector

        • USE_HAL_AES_CCM_ALGO flag: The AES peripheral is configured to Counter with Cipher Block Chaining-Message(CCM) by using HAL_AES_CCM_SetConfig() API where the user must provide the header, its size and the B0

    • Step2 (Key configuration according to one of the following use cases):

      • Use the application normal key:

        • Call HAL_AES_SetNormalKey() API where the user must provide the key and its size

        • This API is available with AES/SAES peripheral

      • Use the SAES Hardware key:

        • Call HAL_AES_SetHWKey() API where the user must set the SAES hardware key and set its size and the key mode:

          • The normal key mode is set when to use the HW key to encrypt/decrypt application messages

          • The wrap key mode is set when to use the HW key to wrap/unwrap the application key

          • The share key mode is set when to use the HW key to share/unshare the application key

        • This API is only available with SAES peripheral

        • When the selected HW key is either the BHK or the DHUK_XOR_BHK, the user application must read it from TAMP backup registers before doing any encryption/decryption

      • Use the application key shared by SAES peripheral: This key mode aims to let the AES instance receive the key shared by SAES peripheral via secure hardware buses:

      • Use the application wrapped key: This key mode aims to let the SAES instance secure an application key by encrypting it with SAES Hardware key (wrapper key) and when the user intends to use it, he must decrypt it with the same wrapper key. This mode is ensured by applying the following sequence:

        • Call HAL_AES_SetHWKey() API where the user must select the SAES hardware key and set its size(Wrapper key),and set the key mode to wrapped mode

        • Call HAL_AES_WrapKey() API where the user must provide his application key to be encrypted with the configured wrapper key and an output key buffer where to write the encrypted key.

        • When the process ends, the user application must delete the original key to be secure.

        • When need to use the original key, the SAES peripheral must configure the same wrapper key by calling the HAL_AES_SetHWKey() API and unwrap the encrypted key by calling HAL_AES_UnwrapKey() API, when the process ends the decrypted key can’t be read and it’s loaded automatically into keys registers to be used for further encrypt/decrypt operations.

        • This API is only available with SAES peripheral The key size provided by the user as a parameter of HAL_AES_SetHWKey() API must be the same one provided for the HAL_AES_WrapKey() and HAL_AES_UnwrapKey() APIs When the selected wrapper key is either the BHK or the DHUK_XOR_BHK, the user application must read it from TAMP backup registers before calling both APIs HAL_AES_WrapKey() and HAL_AES_UnwrapKey()

    • Step3 (Configure the data swapping):

      • By default, the AES is configured to no swap. If the user provides swapped data he must configure the swap mode by using the HAL_AES_SetDataSwapping() API

  • Skipping configuration steps use cases:

    • The step1 Configuration is always required before each one-shot message encrypt or decrypt, but when to encrypt or decrypt a single message with consecutive calls of processing API, the user must apply the configuration only before processing the first piece of this message.

    • The step2 Configuration is not required as long as the configured key has not been changed (step 2 must be redo after ECB or CBC decrypt as those algorithms decryption derivate the original key)

    • The step3 is always required before each one- shot message Encrypt/Decrypt when the provided data are swapped

Sharing SAES key

The SAES peripheral can share user application keys with AES peripheral without being exposed in clear text. The key sharing sequence involves both sides(The SAES sharing key peripheral and the AES target peripheral receiving the

shared key):

  • SAES peripheral sharing key:

    • Call HAL_AES_SetHWKey() API where the user must select the SAES hardware key and set its size(Wrapper key),and set the key mode to shared mode

    • Call HAL_AES_EncryptSharedKey() API where the user must provide his application key to be encrypted with the configured wrapper key and an output key buffer where to write the encrypted key in share mode. The user must specify the peripheral receiving the shared key by providing the target_id (target_id value is equal to 0 for U5 families)

    • When the process ends, the user application must delete the original key to be secure.

    • When need to share the original key with AES peripheral, the SAES peripheral must configure the same wrapper key by calling the HAL_AES_SetHWKey() API and decrypt the encrypted key in share mode using the HAL_AES_DecryptSharedKey() API when the decryption ends, the decrypted key can’t be read and it’s loaded automatically into hardware buses and shared with AES to be used for further AES encrypt/decrypt operations.

  • AES peripheral target receiving the shared key:

The key size provided by the user as a parameter of HAL_AES_SetHWKey() API must be the same one provided for the HAL_AES_EncryptSharedKey() and HAL_AES_DecryptSharedKey() APIs When the selected wrapper key is either the BHK or the DHUK_XOR_BHK, the user application must read it from TAMP backup registers before calling both APIs HAL_AES_EncryptSharedKey() and HAL_AES_DecryptSharedKey()

Polling mode IO operation

  • Encrypt an amount of data in blocking mode using HAL_AES_Encrypt()

  • Decrypt an amount of data in blocking mode using HAL_AES_Decrypt()

    • The driver only pads the missing words within a block (One block is equal to four words), when the user provides a data size not multiple of words, he must pad the missing bytes within his last word with zeros for GCM and CCM algorithms.

TAG Generation

Interrupt mode IO operation

DMA mode IO operation

  • Encrypt/decrypt an amount of data after transfer from input user buffer to AES/SAES peripheral and get encrypted / decrypted data from AES/SAES peripheral via DMA using HAL_AES_Encrypt_DMA() or HAL_AES_Decrypt_DMA()

    • The minimum data amount transferred with DMA must be equal to one block (four complete words), as the DMA transfer does not support the padding(the driver handles the padding with a direct transfer of the incomplete data without

      using the DMA)

    • At the end of a transfer of data from the user buffer to the AES/SAES peripheral, one of these callbacks is generated:

      • AES_ECB_CBC_CTR_DMAInCplt() which generates the HAL_AES_InCpltCallback() callback

      • AES_GCM_GMAC_CCM_DMAInCplt() is executed after the header phase blocks transfer to handle the padding if exist and to initiate the payload phase in case of plaintext not null. The HAL_AES_InCpltCallback() is then generated

    • At the end of a transfer of data from AES/SAES peripheral to the user buffer, one of these callbacks is generated:

      • AES_ECB_CBC_CTR_DMAOutCplt() where the operation is completed and the AES is disabled and which generates the HAL_AES_OutCpltCallback() callback

      • AES_GCM_GMAC_CCM_DMAOutCplt() is executed after the payload phase blocks transfer to handle the padding if exist and to end the operation by generating the HAL_AES_OutCpltCallback()

    • If a hardware AES DMA error happens during DMA transfer a AES_DMAError() callback is generated to end the operation and generates HAL_AES_ErrorCallback()

Suspend Resume management

The user can resort to the suspend/resume feature for two purposes and under the following conditions:

  • The USE_HAL_AES_SUSPEND_RESUME compilation flag must be defined

  • Suspend conditions:

    • Only IT mode processes can be suspended

    • The suspension is only possible after the completion of processing an entire block

    • The suspension is not possible when one block only lasts to be processed (It’s too late to suspend the operation)

  • Purpose1(without context modification): Suspend a process due to time constraints and resume it later

  • Purpose2(with context modification): Suspend a low priority message processing to process a high priority message instead

    • Call HAL_AES_RequestSuspend() API to request suspension

    • When suspended, a HAL_AES_SuspendCallback callback is generated

    • Call HAL_AES_SaveContext() API where the user must provide a structure to save in it all the internal data needed to restart later on, then the user application must change the context in order to process the high priority message (Change the peripheral, the configuration , the AES operation …)

    • When the high priority message processing is over, call the HAL_AES_RestoreContext() API with the already filled structure to restore the low priority suspended context

    • Call HAL_AES_Resume() API to restore the suspended process from the suspended endpoint

Callback registration

The USE_HAL_AES_REGISTER_CALLBACKS compilation flag when set to 1 allows the user to configure dynamically the driver following callbacks:

  • HAL_AES_RegisterInTransferCpltCallback: callback for end of transfer of data

  • HAL_AES_RegisterOutTransferCpltCallback: callback for end of transfer of data

  • HAL_AES_RegisterErrorCallback: callback for error.

  • HAL_AES_RegisterSuspendCallback: callback for suspend. When the compilation flag is set to 0 or not defined, the callback registration feature is not available and all callbacks are set to the corresponding weak functions.