HAL AES Use Cases

Starting an AES Process in Polling Mode

@startuml ' To add a number by line 'autonumber ' Fix order of each column == Initialization == "User Application"->"System" : HAL_Init() note right: ** Configure the Flash prefetch, the time base source and the NVIC ** "System" --> "User Application": hal status : HAL_OK or HAL_ERROR note right: ** Return ** "User Application"->"System" : Configure system clock "System" --> "User Application" "User Application"->"HAL AES Driver" : HAL_AES_Init() note right: Initialize the AES handle and associate an instance \nThe AES clock is enabled by the driver when USE_HAL_AES_CLK_ENABLE_MODEL is set to HAL_CLK_ENABLE_PERIPH_ONLY \nOtherwise it can be enabled outside the driver using RCC APIs "HAL AES Driver" --> "User Application" : hal status : HAL_OK or HAL_INVALID_PARAM note right: ** Return ** == Configuration == "User Application"->"HAL AES Driver" : HAL_AES_ECB_SetConfig \n or HAL_AES_CBC_SetConfig \n or HAL_AES_CTR_SetConfig \n or HAL_AES_GCM_GMAC_SetConfig \n or HAL_AES_CCM_SetConfig note right: ** Configure the AES/SAES peripheral with the user parameters ** "HAL AES Driver" --> "User Application" : hal status : HAL_OK or HAL_INVALID_PARAM note right: ** Return ** "User Application"->"HAL AES Driver" : HAL_AES_SetNormalKey \n or HAL_AES_SetHWKey(SAES ONLY) note right: ** Configure the AES/SAES key ** "HAL AES Driver" --> "User Application" : hal status : HAL_OK or HAL_INVALID_PARAM note right: ** Return ** == Process : Polling mode == "User Application"->"HAL AES Driver" : HAL_AES_Encrypt() \nHAL_AES_Decrypt() note right: ** AES/SAES computation completed ** "HAL AES Driver" --> "User Application": HAL_OK \nHAL_INVALID_PARAM \nHAL_BUSY \nHAL_TIMEOUT note right: ** return ** @enduml

Functions called:

Starting an AES Process in IT Mode

@startuml ' To add a number by line 'autonumber ' Fix order of each column == Initialization == == Configuration == == Process : Interrupt mode == "User Application"->"HAL AES Driver" : HAL_AES_Encrypt_IT() \nor HAL_AES_Decrypt_IT() "HAL AES Driver"<-"NVIC" : HAL_AES_IRQHandler() note right: ** AES/SAES computation completed ** "HAL AES Driver" --> "User Application": HAL_AES_InCpltCallback() \n HAL_AES_OutCpltCallback "HAL AES Driver"<-"NVIC" : HAL_AES_IRQHandler() note right: ** Or AES/SAES error occured ** "HAL AES Driver" --> "User Application": HAL_AES_ErrorCallback() @enduml

Functions called:

Starting an AES Process in DMA Mode

@startuml ' To add a number by line 'autonumber ' Fix order of each column == Initialization == "User Application"->"System" : HAL_Init() note right: ** Configure the Flash prefetch, the time base source and the NVIC ** "System" --> "User Application": hal status : HAL_OK or HAL_ERROR note right: ** Return ** "User Application"->"System" : Configure system clock "System" --> "User Application" "User Application"->"HAL AES Driver" : HAL_AES_Init() note right: Initialize the AES handle and associate an instance \nThe AES clock is enabled by the driver when USE_HAL_AES_CLK_ENABLE_MODEL is set to HAL_CLK_ENABLE_PERIPH_ONLY \nOtherwise it can be enabled outside the driver using RCC APIs "HAL AES Driver" --> "User Application" : hal status : HAL_OK or HAL_INVALID_PARAM note right: ** Return ** "User Application"->"HAL AES Driver" : HAL_AES_SetInDMA() note right: ** Link In DMA handle to AES handle ** "HAL AES Driver" --> "User Application" "User Application"->"HAL AES Driver" : HAL_AES_SetOutDMA() note right: ** Link Out DMA handle to AES handle ** "HAL AES Driver" --> "User Application" == Configuration == == Process : DMA mode == "User Application"->"HAL AES Driver" : HAL_AES_Encrypt_DMA() \nor HAL_AES_Decrypt_DMA() "HAL DMA Driver"<-"NVIC" : HAL_DMA_IRQHandler(&hdma) "HAL DMA Driver"->"HAL AES Driver" : DMA transfer complete "HAL AES Driver" --> "User Application": HAL_AES_InCpltCallback() \n HAL_AES_OutCpltCallback "HAL DMA Driver"<-"NVIC" : HAL_DMA_IRQHandler(&hdma) "HAL DMA Driver"->"HAL AES Driver" : Or DMA error occured "HAL AES Driver" --> "User Application": HAL_AES_ErrorCallback() @enduml

Functions called:

Suspending an AES Process in IT Mode then Resuming It

@startuml ' To add a number by line 'autonumber ' Fix order of each column == Initialization == "User Application"->"HAL AES Driver" : HAL_AES_Init() "HAL AES Driver" --> "User Application" : Return hal status == Configuration == "User Application"->"HAL AES Driver" : HAL_AES_SetConfig() "HAL AES Driver" --> "User Application" : Return hal status == Process : interrupt mode == "User Application"->"HAL AES Driver" : HAL_AES_Encrypt_IT() \nor HAL_AES_Decrypt_IT() == Process : Suspending IT process == "User Application"->"HAL AES Driver" : HAL_AES_RequestSuspend() note right: ** AES/SAES computation suspended when a block is entiry processed ** "HAL AES Driver" --> "User Application": HAL_AES_SuspendCallback() ... == Process : Resuming IT process == "User Application"->"HAL AES Driver" : HAL_AES_Resume() note right: ** The previous interrupt is resumed ** "HAL AES Driver"<-"NVIC" : HAL_AES_IRQHandler() note right: ** AES/SAES computation completed ** "HAL AES Driver" --> "User Application": HAL_AES_InCpltCallback() \n HAL_AES_OutCpltCallback @enduml

Functions called:

Suspending an AES Process in IT Mode to Start Another AES Process with a Different Configuration

@startuml ' To add a number by line 'autonumber ' Fix order of each column == First Process AES Initialization == "User Application"->"HAL AES Driver" : HAL_AES_Init() "HAL AES Driver" --> "User Application" : Return hal status == Configuration == "User Application"->"HAL AES Driver" : HAL_AES_SetConfig() "HAL AES Driver" --> "User Application" : Return hal status == First Process : interrupt mode == "User Application"->"HAL AES Driver" : HAL_AES_Encrypt_IT() \nor HAL_AES_Decrypt_IT() == First process Suspending == "User Application"->"HAL AES Driver" : HAL_AES_RequestSuspend() note right: ** AES/SAES computation suspended when a block is entiry processed ** "HAL AES Driver" --> "User Application": HAL_AES_SuspendCallback() "User Application"->"HAL AES Driver" : HAL_AES_SaveContext() note right: ** AES/SAES context saved ** == New process Configuration == "User Application"->"HAL AES Driver" : HAL_AES_SetConfig() "HAL AES Driver" --> "User Application" : Return hal status == New process Starting == "User Application"->"HAL AES Driver" : HAL_AES_Encrypt() \nor HAL_AES_Decrypt() note right: ** AES/SAES computation completed ** "HAL AES Driver" --> "User Application": HAL_OK \nHAL_INVALID_PARAM \nHAL_BUSY \nHAL_TIMEOUT == Process : Resuming the previous process == "User Application"->"HAL AES Driver" : HAL_AES_RestoreContext() "User Application"->"HAL AES Driver" : HAL_AES_Resume() note right: ** The previous interrupt is resumed ** "HAL AES Driver"<-"NVIC" : HAL_AES_IRQHandler() note right: ** AES/SAES computation completed ** "HAL AES Driver" --> "User Application": HAL_AES_InCpltCallback() \n HAL_AES_OutCpltCallback @enduml

Functions called:

Start an AES Process in Polling Mode to Generate a TAG

@startuml ' To add a number by line 'autonumber ' Fix order of each column == Initialization == == Configuration == == Process : Polling mode: Encryption, Decryption and TAG generation == "User Application"->"HAL AES Driver" : HAL_AES_Encrypt() note right: ** AES computation completed ** "HAL AES Driver" --> "User Application": HAL_OK \nHAL_INVALID_PARAM \nHAL_BUSY \nHAL_TIMEOUT note right: ** return ** "User Application"->"HAL AES Driver" : HAL_AES_GCM_GenerateAuthTAG() \nor HAL_AES_CCM_GenerateAuthTAG() note right: ** AES tag generated ** "HAL AES Driver" --> "User Application": HAL_OK \nHAL_INVALID_PARAM \nHAL_BUSY \nHAL_TIMEOUT note right: ** return ** "User Application"->"HAL AES Driver" : HAL_AES_Decrypt() note right: ** AES computation completed ** "HAL AES Driver" --> "User Application": HAL_OK \nHAL_INVALID_PARAM \nHAL_BUSY \nHAL_TIMEOUT note right: ** return ** @enduml

Functions called:

Start an AES Process to Share a Key

@startuml ' To add a number by line 'autonumber ' Fix order of each column == SAES Initialization == "User Application"->"HAL AES Driver:SAES Instance" : HAL_AES_Init() "HAL AES Driver:SAES Instance" --> "User Application" : hal status : HAL_OK or HAL_INVALID_PARAM note right: ** Return ** == SAES Configuration == "User Application"->"HAL AES Driver:SAES Instance" : HAL_AES_ECB_SetConfig() \n or HAL_AES_CBC_SetConfig note right: ** Configure the SAES peripheral with the user parameters ** "HAL AES Driver:SAES Instance" --> "User Application" : hal status : HAL_OK or HAL_INVALID_PARAM note right: ** Return ** == SAES Key processing == "User Application"->"HAL AES Driver:SAES Instance" : HAL_AES_SetHWKey() note right: ** Configure the hw key in shared mode ** "User Application"->"HAL AES Driver:SAES Instance" : HAL_AES_EncryptSharedKey() note right: ** Encrypt SAES user key with HW private key ** "HAL AES Driver:SAES Instance" --> "User Application" : hal status : HAL_OK or HAL_INVALID_PARAM or HAL_BUSY or HAL_ERROR or HAL_TIMEOUT note right: ** Return ** "User Application"->"HAL AES Driver:SAES Instance" : HAL_AES_DecryptSharedKey() note right: ** Decrypt SAES user key with the same HW private key to load it in AES registers without being exposed ** "HAL AES Driver:SAES Instance" --> "User Application" : hal status : HAL_OK or HAL_INVALID_PARAM or HAL_BUSY or HAL_ERROR or HAL_TIMEOUT note right: ** Return ** == AES Initialization == "User Application"->"HAL AES Driver:AES Instance" : HAL_AES_Init() "HAL AES Driver:AES Instance" --> "User Application" : hal status : HAL_OK or HAL_INVALID_PARAM note right: ** Return ** == AES Configuration == "User Application"->"HAL AES Driver:AES Instance" : HAL_AES_ECB_SetConfig() \n or HAL_AES_CBC_SetConfig \n or HAL_AES_CTR_SetConfig \n or HAL_AES_GCM_GMAC_SetConfig \n or HAL_AES_CCM_SetConfig note right: ** Configure the AES peripheral with the user parameters ** "HAL AES Driver:AES Instance" --> "User Application" : hal status : HAL_OK or HAL_INVALID_PARAM note right: ** Return ** "User Application"->"HAL AES Driver:AES Instance" : HAL_AES_SetSharedKey() note right: ** Sharing the key from SAES ** "HAL AES Driver:AES Instance" --> "User Application" : hal status : HAL_OK or HAL_INVALID_PARAM note right: ** Return ** == AES Process : Polling mode == "User Application"->"HAL AES Driver:AES Instance" : HAL_AES_Encrypt() \nor HAL_AES_Decrypt() note right: ** AES computation completed ** "HAL AES Driver:AES Instance" --> "User Application": HAL_OK \nHAL_INVALID_PARAM \nHAL_BUSY \nHAL_TIMEOUT note right: ** return ** @enduml

Functions called:

Start an AES Process to Wrap/Unwrap a Key

@startuml ' To add a number by line 'autonumber ' Fix order of each column == SAES Initialization == == SAES Configuration == "User Application"->"HAL AES Driver" :HAL_AES_ECB_SetConfig \n or HAL_AES_CBC_SetConfig note right: ** Configure the SAES peripheral with the user parameters ** "HAL AES Driver" --> "User Application" : hal status : HAL_OK or HAL_INVALID_PARAM note right: ** Return ** == SAES Process : Encrypt application key with HW private key== "User Application"->"HAL AES Driver" : HAL_AES_SetHWKey() note right: ** Configure the hw key in wrapped mode ** "User Application"->"HAL AES Driver" : HAL_AES_WrapKey() == Process : Decrypt wraped key to load it immediately in AES/SAES key registers without being exposed == "User Application"->"HAL AES Driver" :HAL_AES_ECB_SetConfig \n or HAL_AES_CBC_SetConfig "User Application"->"HAL AES Driver" : HAL_AES_UnwrapKey() == Process : Polling mode == "User Application"->"HAL AES Driver" :HAL_AES_ECB_SetConfig \n or HAL_AES_CBC_SetConfig "User Application"->"HAL AES Driver" : HAL_AES_SetDataSwapping() "User Application"->"HAL AES Driver" : HAL_AES_Encrypt() \n or HAL_AES_Decrypt() note right: ** AES/SAES computation completed ** "HAL AES Driver" --> "User Application": HAL_OK \nHAL_INVALID_PARAM \nHAL_BUSY \nHAL_TIMEOUT note right: ** return ** @enduml

Functions called:

Start an AES Process to Unwrap a Key using CTR algorithm

@startuml ' To add a number by line 'autonumber ' Fix order of each column == SAES Initialization == == SAES Process : Encrypt application key with HW private key== "User Application"->"HAL AES Driver" :HAL_AES_CTR_SetConfig "User Application"->"HAL AES Driver" : HAL_AES_SetHWKey() == Process : Decrypt the wrapped key by deriving the key from the IV using the CTR algo == "User Application"->"HAL AES Driver" : HAL_AES_UnwrapKey() == Process : Polling mode == == SAES Configuration == "User Application"->"HAL AES Driver" :HAL_AES_ECB_SetConfig \n or HAL_AES_CBC_SetConfig \n HAL_AES_CTR_SetConfig "User Application"->"HAL AES Driver" : HAL_AES_SetDataSwapping() "User Application"->"HAL AES Driver" : HAL_AES_Encrypt() \n or HAL_AES_Decrypt() note right: ** SAES computation completed ** "HAL AES Driver" --> "User Application": HAL_OK \nHAL_INVALID_PARAM \nHAL_BUSY \nHAL_TIMEOUT note right: ** return ** @enduml

Functions called: