HAL AES Functions

HAL AES Functions

group AES_Exported_Functions

Functions

hal_status_t HAL_AES_CBC_GetLastOutputIV ( const hal_aes_handle_t * haes , const uint8_t * p_last_iv , uint8_t last_iv_size )

Get the last output IV for CBC mode.

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_last_iv – Pointer to the user buffer to be updated with the last output IV

  • last_iv_size – Size of the p_last_iv buffer

Return values :

  • HAL_INVALID_PARAM – Invalid param return when the provided last output IV pointer is null or the handle pointer is null

  • HAL_ERROR – Error return when the selected algorithm is not CBC algorithm or when the data_size_sum_byte is null

  • HAL_OK – AES process is successfully accomplished

hal_status_t HAL_AES_CTR_GetLastOutputIV ( const hal_aes_handle_t * haes , const uint8_t * p_last_iv , uint8_t last_iv_size )

Get the last output IV for CTR mode.

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_last_iv – Pointer to the user buffer to be updated with the last output IV

  • last_iv_size – Size of the p_last_iv buffer

Return values :

  • HAL_INVALID_PARAM – Invalid param return when the provided last output IV pointer is null or the handle pointer is null

  • HAL_ERROR – Error return when the selected algorithm is not CTR algorithm or when the data_size_sum_byte is null

  • HAL_OK – AES process is successfully accomplished

Initialization and De-initialization functions

group AES_Exported_Functions_Group1

This subsection provides a set of functions allowing to initialize and de-initialize the AES/SAES peripheral:

  • The HAL_AES_Init() API: Allows initializing the HAL AES driver so it can be configured and used to encrypt a plaintext or decrypt a ciphertext This API is the first API to call when using the HAL AES, it takes 2 parameters as input:

  • The HAL_AES_DeInit() API: Allows de-initializing the HAL AES driver by:

    • Disabling the AES/SAES peripheral

    • Abort DMA input and output transfers

    • De-initializing the current handle object

    • Resetting the handle global state to the HAL_AES_STATE_RESET

Functions

hal_status_t HAL_AES_Init ( hal_aes_handle_t * haes , hal_aes_t instance )

Initialize the HAL AES handle and associate it to an instance.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid param return when the AES handle is NULL

  • HAL_OK – The HAL AES driver is initialized according to the given handle and instance

void HAL_AES_DeInit ( hal_aes_handle_t * haes )

De-initialize the AES/SAES peripheral.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Configuration functions

group AES_Exported_Functions_Group2

This subsection provides a set of functions allowing to configure the AES/SAES peripheral through three steps:

Functions

hal_status_t HAL_AES_ECB_SetConfig ( hal_aes_handle_t * haes )

Configure the AES/SAES peripheral with ECB algorithm.

Note

The user has not to set any parameter

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

  • HAL_INVALID_PARAM – Invalid param return when the AES handle is NULL

  • HAL_ERROR – Error detected while fetching a random number from RNG peripheral (only for SAES instance)

  • HAL_OK – AES/SAES peripheral has been correctly configured with ECB algorithm

hal_status_t HAL_AES_CBC_SetConfig ( hal_aes_handle_t * haes , const uint32_t * p_init_vect )

Configure the AES/SAES peripheral with CBC algorithm.

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_init_vect – Pointer to const uint32_t four words buffer provided by the user. For CBC algorithm, the init vector is used to process only the first data block

Return values :

  • HAL_INVALID_PARAM – Invalid param return when the provided init vector pointer or handle pointer is null

  • HAL_ERROR – Error detected while fetching a random number from RNG peripheral (only for SAES instance)

  • HAL_OK – AES/SAES peripheral has been correctly configured with CBC algorithm

hal_status_t HAL_AES_SetHWKey ( hal_aes_handle_t * haes , hal_aes_key_size_t key_size , hal_aes_key_select_t key_select , hal_aes_key_mode_t key_mode )

Configure the SAES Hardware key.

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • key_size – AES key size with a hal_aes_key_size_t type

  • key_select – key selection with a hal_aes_key_select_t type

  • key_mode – key mode with a hal_aes_key_mode_t type

Return values :

  • HAL_INVALID_PARAM – Invalid param return when the handle instance is other than SAES or the handle pointer is null

  • HAL_ERROR – Error when loading the key into registers exceeds the dedicated timeout

  • HAL_OK – Hardware key has been configured

hal_status_t HAL_AES_EnableKeyProtection ( hal_aes_handle_t * haes )

Enable the protection of the SAES key from being accessed by another security context application.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

  • HAL_INVALID_PARAM – Invalid param return when the handle instance is other than SAES or the handle pointer is null

  • HAL_OK – SAES key protection has been enabled

hal_status_t HAL_AES_DisableKeyProtection ( hal_aes_handle_t * haes )

Disable the SAES key protection.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

  • HAL_INVALID_PARAM – Invalid param return when the handle instance is other than SAES or the handle pointer is null

  • HAL_OK – SAES key protection has been disabled

hal_aes_key_protection_status_t HAL_AES_IsEnabledKeyProtection ( const hal_aes_handle_t * haes )

Check whether the SAES key protection is already enabled or not.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

  • HAL_AES_KEY_PROTECTION_ENABLED – The SAES key protection is enabled

  • HAL_AES_KEY_PROTECTION_DISABLED – The SAES key protection is disabled

hal_status_t HAL_AES_CTR_SetConfig ( hal_aes_handle_t * haes , const uint32_t * p_init_vect )

Configure the AES peripheral with the CTR algorithm, available only with AES instance.

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_init_vect – Pointer to const uint32_t four words buffer provided by the user. For CTR algorithm, the init vector is used to process each data block

Return values :

  • HAL_INVALID_PARAM – Invalid param return when the provided init vector pointer is null or the handle pointer is null or the handle instance is not HAL_AES

  • HAL_OK – AES peripheral has been correctly configured with the CTR algorithm

hal_status_t HAL_AES_GCM_GMAC_SetConfig ( hal_aes_handle_t * haes , const hal_aes_gcm_config_t * p_config )

Configure the AES peripheral with the GCM_GMAC algorithm, available only with AES instance.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid param return when:

    • The configuration structure pointer is null

    • The provided init vector pointer within the configuration structure is null

    • The provided header within the configuration structure is null but its size is not null

    • The handle pointer is null

    • The handle instance is not HAL_AES

  • HAL_OK – AES peripheral has been correctly configured with the GCM_GMAC algorithm

hal_status_t HAL_AES_CCM_SetConfig ( hal_aes_handle_t * haes , const hal_aes_ccm_config_t * p_config )

Configure the AES with the CCM algorithm, available only with AES instance.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid param return when:

    • The configuration structure pointer is null

    • The provided b0 within the configuration structure is null

    • The provided header within the configuration structure is null but its size is not null

    • The handle pointer is null

    • The handle instance is not HAL_AES

  • HAL_OK – AES peripheral has been correctly configured with the CCM algorithm

hal_status_t HAL_AES_SetNormalKey ( hal_aes_handle_t * haes , hal_aes_key_size_t key_size , const uint32_t * p_key )

Configure the AES Normal key(key size, key value), supports both AES and SAES instances.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid param return when the provided pointer key is null or the handle pointer is null

  • HAL_ERROR – Error when loading the key into registers exceeds the dedicated timeout

  • HAL_OK – Normal key has been configured

hal_status_t HAL_AES_SetSharedKey ( hal_aes_handle_t * haes , hal_aes_key_size_t key_size )

Configure the AES shared key mode to acquire the key shared by the SAES peripheral.

Warning

The configured size must be the same as the size of the shared key

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid param return when the handle instance is other than AES or the handle pointer is null

  • HAL_ERROR – Error when loading the key into registers exceeds the dedicated timeout

  • HAL_OK – Normal key has been configured

hal_status_t HAL_AES_SetDataSwapping ( hal_aes_handle_t * haes , hal_aes_data_swapping_t data_swapping )

Configure the AES data swapping.

Parameters :
Return values :

HAL_OK – The AES data swapping mode is set

hal_aes_data_swapping_t HAL_AES_GetDataSwapping ( const hal_aes_handle_t * haes )

Retrieve the AES configured data swapping.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

  • HAL_AES_NO_SWAP – The bit order of the input and output data is not affected

  • HAL_AES_HALFWORD_SWAP – The bit- reversal is done by halfword Ex: 0011 1100 0100 1101 –> 0100 1101 0011 1100

  • HAL_AES_BYTE_SWAP – The bit- reversal is done by byte Ex: 0011 1100 0100 1101 –> 1101 0100 1100 0011

  • HAL_AES_BIT_SWAP – The bit- reversal is done by bit Ex: 0011 1100 0100 1101 –> 1011 0010 0011 1100

Process functions

group AES_Exported_Functions_Group3

This subsection provides a set of functions allowing to perform AES processing and manage suspension/resumption:

Functions

hal_status_t HAL_AES_Encrypt ( hal_aes_handle_t * haes , const void * p_input , uint16_t size_byte , void * p_output , uint32_t timeout_ms )

Encrypt user data in polling mode.

  • For ECB, CBC or CTR algorithms:

    • the padding is not supported

    • only the encryption of the plaintext is available (no preparation for tag generation)

  • For GCM algorithm:- HAL_AES_Encrypt() is used either to:

    • Encrypt a plaintext and use the header to prepare for the tag generation

    • or just do the encryption (header null)

    • or just prepare for tag generation (plaintext null)

  • For GMAC algorithm: Prepare for the tag generation only (plaintext null)

  • For CCM algorithm:- HAL_AES_Encrypt() is used either to:

    • Encrypt a plaintext and use the header to prepare for the tag generation

    • or just do the encryption (header null)

    • or just prepare for tag generation (plaintext null)(not recommended by NIST)

Warning

No swapped user data must be provided in big-endian. When data are provided in little-endian, the user must configure the swapping mode before starting the process (ex when data are provided as little- endian bytes the swap mode must be set to HAL_AES_BYTE_SWAP or when data are provided as little- endian halfwords, the ,swap mode must be set to HAL_AES_HALFWORD_SWAP)

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_input – Pointer to aligned const void plaintext

  • size_byte – Length of the plaintext buffer that must be in byte

  • p_output – Pointer to aligned void data buffer to be filled with the encrypted text

  • timeout_ms – Specify timeout value in milliseconds

Return values :

  • HAL_INVALID_PARAM – For ECB, CBC or CTR algorithms Invalid param return when:

    • The provided input data buffer pointer is null

    • Or the output data buffer pointer is null

    • Or the input buffer is empty

      For GCM_GMAC or CCM algorithms Invalid param return when:

    • The provided input data buffer pointer is null but its size is # 0U The handle pointer is null The provided timeout is null

  • HAL_BUSY – Another AES process is ongoing

  • HAL_ERROR – Error return when the loaded key is invalid

  • HAL_TIMEOUT – AES encryption exceeds user timeout

  • HAL_OK – AES encryption is successfully accomplished

hal_status_t HAL_AES_Decrypt ( hal_aes_handle_t * haes , const void * p_input , uint16_t size_byte , void * p_output , uint32_t timeout_ms )

Decrypt user data in polling mode.

  • For ECB, CBC or CTR algorithms:

    • The padding is not supported

    • Only the decryption of the ciphertext is available (no preparation for tag generation)

  • For GCM algorithm:- HAL_AES_Decrypt() is used either to:

    • Decrypt a ciphertext and use the header to prepare for the tag generation

    • or just do the decryption (header null)

    • or just prepare for tag generation (ciphertext null)

  • For GMAC algorithm: Prepare for the tag generation only (ciphertext null)

  • For CCM algorithm:- HAL_AES_Decrypt() is used either to:

    • Decrypt a ciphertext and use the header to prepare for the tag generation

    • or just do the decryption (header null)

    • or just prepare for tag generation (ciphertext null)(not recommended by NIST)

Warning

No swapped user data must be provided in big-endian. When data are provided in little-endian, the user must configure the swapping mode before starting the process (ex when data are provided as little- endian bytes ,the swap mode must be set to HAL_AES_BYTE_SWAP or when data are provided as little- endian halfwords, the swap mode must be set to HAL_AES_HALFWORD_SWAP)

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_input – Pointer to aligned const void ciphertext

  • size_byte – Length of the ciphertext buffer that must be in byte

  • p_output – Pointer to aligned void data buffer to be filled with the decrypted text

  • timeout_ms – Specify timeout value in milliseconds

Return values :

  • HAL_INVALID_PARAM – For ECB, CBC or CTR algorithms Invalid param return when:

    • The provided input data buffer pointer is null

    • Or the output data buffer pointer is null

    • Or the input buffer is empty

      For GCM_GMAC or CCM algorithms Invalid param return when:

    • The provided input data buffer pointer is null but its size is # 0U The handle pointer is null The provided timeout is null

  • HAL_BUSY – Another AES process is ongoing

  • HAL_ERROR – Error return when the loaded key is invalid or when the key derivation exceeds the dedicated timeout

  • HAL_TIMEOUT – AES decryption exceeds user timeout

  • HAL_OK – AES decryption is successfully accomplished

hal_status_t HAL_AES_Encrypt_IT ( hal_aes_handle_t * haes , const void * p_input , uint16_t size_byte , void * p_output )

Encrypt user data in interrupt mode.

  • For ECB, CBC or CTR algorithms:

    • the padding is not supported

    • only the encryption of the plaintext is available (no preparation for tag generation)

  • For GCM algorithm:- HAL_AES_Encrypt_IT() is used either to:

    • Encrypt a plaintext and use the header to prepare for the tag generation

    • or just do the encryption (header null)

    • or just prepare for tag generation (plaintext null)

  • For GMAC algorithm: Prepare for the tag generation only (plaintext null)

  • For CCM algorithm:- HAL_AES_Encrypt_IT() is used either to:

    • Encrypt a plaintext and use the header to prepare for the tag generation

    • or just do the encryption (header null)

    • or just prepare for tag generation (plaintext null)(not recommended by NIST)

Warning

No swapped user data must be provided in big-endian. When data are provided in little-endian, the user must configure the swapping mode before starting the process ( ex when data are provided as little- endian bytes , the swap mode must be set to HAL_AES_BYTE_SWAP or when data are provided as little- endian halfwords, the swap mode must be set to HAL_AES_HALFWORD_SWAP)

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_input – Pointer to aligned const void plaintext

  • size_byte – Length of the plaintext buffer that must be in byte

  • p_output – Pointer to aligned void data buffer to be filled with the encrypted text

Return values :

  • HAL_INVALID_PARAM – For ECB, CBC or CTR algorithms Invalid param return when:

    • The provided input data buffer pointer is null

    • Or the output data buffer pointer is null

    • Or the input buffer is empty

      For GCM_GMAC or CCM algorithms Invalid param return when:

    • The provided input data buffer pointer is null but its size is # 0U The handle pointer is null

  • HAL_BUSY – Another AES process is ongoing

  • HAL_ERROR – Error return when the loaded key is invalid

  • HAL_OK – AES encryption is successfully accomplished

hal_status_t HAL_AES_Decrypt_IT ( hal_aes_handle_t * haes , const void * p_input , uint16_t size_byte , void * p_output )

Decrypt user data in interrupt mode.

  • For ECB, CBC or CTR algorithms:

    • the padding is not supported

    • only the decryption of the ciphertext is available (no preparation for tag generation)

  • For GCM algorithm:- HAL_AES_Decrypt_IT() is used either to:

    • Decrypt a ciphertext and use the header to prepare for the tag generation

    • or just do the decryption (header null)

    • or just prepare for tag generation (ciphertext null)

  • For GMAC algorithm: Prepare for the tag generation only (ciphertext null)

  • For CCM algorithm:- HAL_AES_Decrypt_IT() is used either to:

    • Decrypt a ciphertext and use the header to prepare for the tag generation

    • or just do the decryption (header null)

    • or just prepare for tag generation (ciphertext null)( not recommended by NIST)

Warning

No swapped user data must be provided in big-endian. When data are provided in little-endian, the user must configure the swapping mode before starting the process ( ex when data are provided as little- endian bytes , the swap mode must be set to HAL_AES_BYTE_SWAP or when data are provided as little- endian halfwords, the swap mode must be set to HAL_AES_HALFWORD_SWAP)

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_input – Pointer to aligned const void ciphertext

  • size_byte – Length of the ciphertext buffer that must be in byte

  • p_output – Pointer to aligned void data buffer to be filled with the decrypted text

Return values :

  • HAL_INVALID_PARAM – For ECB, CBC or CTR algorithms Invalid param return when:

    • The provided input data buffer pointer is null

    • Or the output data buffer pointer is null

    • Or the input buffer is empty

      For GCM_GMAC or CCM algorithms Invalid param return when:

    • The provided input data buffer pointer is null but its size is # 0U The handle pointer is null

  • HAL_BUSY – Another AES process is ongoing

  • HAL_ERROR – Error return when the loaded key is invalid or when the key derivation exceeds the dedicated timeout

  • HAL_OK – AES decryption is successfully accomplished

hal_status_t HAL_AES_Encrypt_DMA ( hal_aes_handle_t * haes , const void * p_input , uint16_t size_byte , void * p_output )

Encrypt user data in DMA mode.

  • For ECB, CBC or CTR algorithms:

    • the padding is not supported

    • only the encryption of the plaintext is available (no preparation for tag generation)

  • For GCM algorithm:- HAL_AES_Encrypt_DMA() is used either to:

    • Encrypt a plaintext and use the header to prepare for the tag generation

    • or just do the encryption (header null)

    • or just prepare for tag generation (plaintext null)

  • For GMAC algorithm: Prepare for the tag generation only (plaintext null)

  • For CCM algorithm:- HAL_AES_Encrypt_DMA() is used either to:

    • Encrypt a plaintext and use the header to prepare for the tag generation

    • or just do the encryption (header null)

    • or just prepare for tag generation (plaintext null)(not recommended by NIST)

Warning

No swapped user data must be provided in big-endian. When data are provided in little-endian, the user must configure the swapping mode before starting the process (ex when data are provided as little- endian bytes , the swap mode must be set to HAL_AES_BYTE_SWAP or when data are provided as little- endian halfwords, the swap mode must be set to HAL_AES_HALFWORD_SWAP)

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_input – Pointer to aligned const void plaintext

  • size_byte – Length of the plaintext buffer that must be in byte

  • p_output – Pointer to aligned void data buffer to be filled with the encrypted text

Return values :

  • HAL_INVALID_PARAM – For ECB, CBC or CTR algorithms Invalid param return when:

    • The provided input data buffer pointer is null

    • Or the output data buffer pointer is null

    • Or the input buffer is empty

      For GCM_GMAC or CCM algorithms Invalid param return when:

    • The provided input data buffer pointer is null but its size is # 0U The handle pointer is null

  • HAL_BUSY – Another AES process is ongoing

  • HAL_ERROR – Error return when the loaded key is invalid

  • HAL_OK – AES encryption is successfully accomplished

hal_status_t HAL_AES_Decrypt_DMA ( hal_aes_handle_t * haes , const void * p_input , uint16_t size_byte , void * p_output )

Decrypt user data in DMA mode.

  • For ECB, CBC or CTR algorithms:

    • the padding is not supported

    • only the decryption of the ciphertext is available (no preparation for tag generation)

  • For GCM algorithm:- HAL_AES_Decrypt_DMA() is used either to:

    • Decrypt a ciphertext and use the header to prepare for the tag generation

    • or just do the decryption (header null)

    • or just prepare for tag generation (ciphertext null)

  • For GMAC algorithm: Prepare for the tag generation only (ciphertext null)

  • For CCM algorithm:- HAL_AES_Decrypt_DMA() is used either to:

    • Decrypt a ciphertext and use the header to prepare for the tag generation

    • or just do the decryption (header null)

    • or just prepare for tag generation (ciphertext null)(not recommended by NIST)

Warning

No swapped user data must be provided in big-endian. When data are provided in little-endian, the user must configure the swapping mode before starting the process (ex when data are provided as little- endian bytes , the swap mode must be set to HAL_AES_BYTE_SWAP or when data are provided as little- endian halfwords, the swap mode must be set to HAL_AES_HALFWORD_SWAP)

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_input – Pointer to aligned const void ciphertext

  • size_byte – Length of the ciphertext buffer that must be in byte

  • p_output – Pointer to aligned void data buffer to be filled with the decrypted text

Return values :

  • HAL_INVALID_PARAM – For ECB, CBC or CTR algorithms Invalid param return when:

    • The provided input data buffer pointer is null

    • Or the output data buffer pointer is null

    • Or the input buffer is empty

      For GCM_GMAC or CCM algorithms Invalid param return when:

    • The provided input data buffer pointer is null but its size is # 0U The handle pointer is null

  • HAL_BUSY – Another AES process is ongoing

  • HAL_ERROR – Error return when the loaded key is invalid or when the key derivation exceeds the dedicated timeout

  • HAL_OK – AES decryption is successfully accomplished

hal_status_t HAL_AES_RequestSuspend ( hal_aes_handle_t * haes )

Request suspension for AES interrupt mode processing.

Note

Set the handle field suspend_request to HAL_AES_SUSPEND so that the on-going AES processing is suspended as soon as the required conditions are met (The current block is entirely processed and it’s not the last one)

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

  • HAL_INVALID_PARAM – When the handle pointer is NULL.

  • HAL_OK – The AES processing suspension is well requested

hal_status_t HAL_AES_Resume ( hal_aes_handle_t * haes )

Resumption of the suspended AES processing.

Note

Processing restarts at the exact point where it was suspended, if the AES context has been changed HAL_AES_SaveContext and HAL_AES_RestoreContext must be used before resumption.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

  • HAL_INVALID_PARAM – When the handle pointer is NULL.

  • HAL_BUSY – Another AES process is ongoing

  • HAL_OK – AES suspended processing is resumed

hal_status_t HAL_AES_SaveContext ( hal_aes_handle_t * haes , hal_aes_save_context_t * p_context )

Save parameters of the suspended AES processing.

Parameters :
Return values :

  • HAL_INVALID_PARAM – The provided save context pointer structure or the handle pointer is null

  • HAL_OK – AES suspended processing parameters are saved

hal_status_t HAL_AES_RestoreContext ( hal_aes_handle_t * haes , const hal_aes_save_context_t * p_context )

Resumption for the saved parameters of the suspended AES processing.

Parameters :
Return values :

  • HAL_INVALID_PARAM – When the handle pointer is NULL.

  • HAL_ERROR – AES key derivation exceeds the dedicated timeout

  • HAL_OK – AES suspended processing parameters are restored

Peripheral State, Error and Get last IV functions

group AES_Exported_Functions_Group5

This subsection provides a set of functions allowing to get the AES error information and state:

Functions

hal_aes_state_t HAL_AES_GetState ( const hal_aes_handle_t * haes )

Retrieve the HAL AES Global State.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

  • HAL_AES_STATE_RESET – AES/SAES peripheral is not yet initialized

  • HAL_AES_STATE_INIT – AES/SAES peripheral is initialized but not yet configured

  • HAL_AES_STATE_IDLE – AES/SAES peripheral is initialized and configured

  • HAL_AES_STATE_ACTIVE – AES internal processing is ongoing

  • HAL_AES_STATE_SUSPENDED – AES internal processing is suspended

uint32_t HAL_AES_GetLastErrorCodes ( const hal_aes_handle_t * haes )

Get last error codes.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

uint32_t – Last error codes which can be a combination of Error Code definition reflecting the processes asynchronous errors

void HAL_AES_SetUserData ( hal_aes_handle_t * haes , const void * p_user_data )

Store application user data pointer into the handle.

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_user_data – Pointer to the user data

const void * HAL_AES_GetUserData ( const hal_aes_handle_t * haes )

Retrieve the application user data pointer from the handle.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

Pointer – to the user data

hal_status_t HAL_AES_CBC_GetLastOutputIV ( const hal_aes_handle_t * haes , const uint8_t * p_last_iv , uint8_t last_iv_size )

Get the last output IV for CBC mode.

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_last_iv – Pointer to the user buffer to be updated with the last output IV

  • last_iv_size – Size of the p_last_iv buffer

Return values :

  • HAL_INVALID_PARAM – Invalid param return when the provided last output IV pointer is null or the handle pointer is null

  • HAL_ERROR – Error return when the selected algorithm is not CBC algorithm or when the data_size_sum_byte is null

  • HAL_OK – AES process is successfully accomplished

hal_status_t HAL_AES_CTR_GetLastOutputIV ( const hal_aes_handle_t * haes , const uint8_t * p_last_iv , uint8_t last_iv_size )

Get the last output IV for CTR mode.

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_last_iv – Pointer to the user buffer to be updated with the last output IV

  • last_iv_size – Size of the p_last_iv buffer

Return values :

  • HAL_INVALID_PARAM – Invalid param return when the provided last output IV pointer is null or the handle pointer is null

  • HAL_ERROR – Error return when the selected algorithm is not CTR algorithm or when the data_size_sum_byte is null

  • HAL_OK – AES process is successfully accomplished

Tag Generating functions

group AES_Exported_Functions_Group6

This subsection provides a set of functions allowing TAG generation for GCM and CCM algorithms:

Functions

hal_status_t HAL_AES_GCM_GenerateAuthTAG ( hal_aes_handle_t * haes , uint32_t * p_auth_tag , uint32_t timeout_ms )

Generate the GCM authentication TAG, available only with AES instance.

This API can only be called after accomplishing either an encryption or a decryption process.

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_auth_tag – Pointer to the authentication buffer the p_auth_tag generated here is 128bits length, if the TAG length is less than 128bits, user must consider only the valid part of p_auth_tag buffer which corresponds exactly to TAG length.

  • timeout_ms – Specify Timeout value in milliseconds

Return values :

  • HAL_INVALID_PARAM – The provided input tag pointer is null

  • HAL_BUSY – Another AES process is ongoing

  • HAL_TIMEOUT – AES tag generation exceeds user timeout

  • HAL_ERROR – AES tag generation sequence is not well performed

  • HAL_OK – AES tag is successfully generated

hal_status_t HAL_AES_CCM_GenerateAuthTAG ( hal_aes_handle_t * haes , uint32_t * p_auth_tag , uint32_t timeout_ms )

Generate the CCM authentication TAG, available only with AES instance.

This API can only be called after accomplishing either an encryption or a decryption process.

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_auth_tag – Pointer to the authentication buffer the p_auth_tag generated here is 128bits length, if the TAG length is less than 128bits, user must consider only the valid part of p_auth_tag buffer which corresponds exactly to TAG length.

  • timeout_ms – Specify Timeout value in milliseconds

Return values :

  • HAL_INVALID_PARAM – The provided input tag pointer is null

  • HAL_BUSY – Another AES process is ongoing

  • HAL_TIMEOUT – AES tag generation exceeds user timeout

  • HAL_ERROR – AES tag generation sequence is not well performed

  • HAL_OK – AES tag is successfully generated

AES Processing Key functions

group AES_Exported_Functions_Group7

This subsection provides a set of functions allowing AES key processing:

Functions

hal_status_t HAL_AES_WrapKey ( hal_aes_handle_t * haes , const uint32_t * p_key_in , hal_aes_key_size_t key_size , uint32_t * p_key_output , uint32_t timeout_ms )

Encrypt an application key with SAES HW keys(wrapper key).

This API is only available with SAES instance,.

Note

This API aims to build a secure application context following this sequence:

  • Call HAL_AES_WrapKey() API which encrypts the application key and write it into the output key buffer

  • Delete the original key at the application level

  • When need to use the original application key to encrypt/decrypt messages, call the HAL_AES_UnwrapKey() API which unwraps the encrypted key using the same wrapper key and load the unexposed result into registers

Warning

The key size must be the same one as the wrapper key which is provided as a parameter of the HAL_AES_SetHWKey() API

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_key_in – Pointer to uint32_t input key provided by the user to be encrypted with a HW key

  • key_size – AES key size with a hal_aes_key_size_t type

  • p_key_output – Pointer to uint32_t output key provided by the user to be filled with the encrypted application key

  • timeout_ms – Specify Timeout value in milliseconds

Return values :

  • HAL_INVALID_PARAM – Invalid param return when:

    • The handle instance is not the SAES one

    • The provided application input key pointer is null

    • The provided application output key pointer is null

  • HAL_BUSY – Another AES process is ongoing

  • HAL_ERROR – Error return when the selected wrapper key is invalid

  • HAL_TIMEOUT – AES key wrapping exceeds user timeout

  • HAL_OK – AES key wrapping is successfully accomplished

hal_status_t HAL_AES_UnwrapKey ( hal_aes_handle_t * haes , const uint32_t * p_key_in , hal_aes_key_size_t key_size , uint32_t timeout_ms )

Decrypt an application key with the same SAES HW key(wrapper key) used by the HAL_AES_WrapKey()

API.

This API is only available with SAES instance,.

Note

This API aims to build a secure application context following this sequence:

  • Call HAL_AES_WrapKey() API which encrypts the application key and write it into the output key buffer

  • Delete the original key at the application level

  • When need to use the original application key to encrypt/decrypt messages, call the HAL_AES_UnwrapKey() API which unwraps the encrypted key using the same wrapper key and load the unexposed result into registers

Warning

The key size must be the same one as the wrapper key which is provided as a parameter of the HAL_AES_SetHWKey() API

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid param return when:

    • The handle instance is not the SAES one

    • The provided application input key pointer is null

  • HAL_BUSY – Another AES process is ongoing

  • HAL_ERROR – Error return when the selected wrapper key is invalid or when the key derivation exceeds the dedicated timeout

  • HAL_TIMEOUT – AES key unwrapping exceeds user timeout

  • HAL_OK – AES key unwrapping is successfully accomplished

hal_status_t HAL_AES_EncryptSharedKey ( hal_aes_handle_t * haes , const uint32_t * p_key_in , hal_aes_key_size_t key_size , uint32_t * p_key_output , uint32_t target_id , uint32_t timeout_ms )

Encrypt an application key to be shared with AES peripheral, using SAES HW key.

This API is only available with SAES instance,.

Note

This API aims to build a secure application context following this sequence:

  • Call HAL_AES_EncryptSharedKey() API to encrypt the application key and write it into the output key buffer

  • Delete the original key at the application level

  • When need to share the original application key with the specified AES target, call the HAL_AES_DecryptSharedKey() API which decrypts the encrypted key using the same SAES HW keys (wrapper key) and automatically transfers the unreadable result to the target via secure HW buses. This target must be configured with the HAL_AES_SetSharedKey() API, then the target keys registers are loaded automatically with the transferred key.

Warning

The key size must be the same one as the wrapper key which is provided as a parameter of the HAL_AES_SetHWKey() API

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_key_in – Pointer to uint32_t input key provided by the user to be encrypted

  • key_size – AES key size with a hal_aes_key_size_t type

  • p_key_output – Pointer to uint32_t output key provided by the user to be filled with the encrypted application key

  • target_id – Specify which AES target can receive the SAES shared key 00: AES peripheral

  • timeout_ms – Specify Timeout value in milliseconds

Return values :

  • HAL_INVALID_PARAM – Invalid param return when:

    • The handle instance is not the SAES one

    • The provided application input key pointer is null

    • The provided application output key pointer is null

  • HAL_BUSY – Another AES process is ongoing

  • HAL_ERROR – Error return when the selected wrapper key is invalid

  • HAL_TIMEOUT – AES key wrapping exceeds user timeout

  • HAL_OK – AES key wrapping is successfully accomplished

hal_status_t HAL_AES_DecryptSharedKey ( hal_aes_handle_t * haes , const uint32_t * p_key_in , hal_aes_key_size_t key_size , uint32_t target_id , uint32_t timeout_ms )

Decrypt an application key to be shared with AES peripheral with the same SAES HW key (wrapper key) used by the HAL_AES_EncryptSharedKey()

API.

This API is only available with SAES instance.

Note

This API aims to build a secure application context following this sequence:

  • Call HAL_AES_EncryptSharedKey() API to encrypt the application key and write it into the output key buffer

  • Delete the original key at the application level

  • When need to share the original application key with the specified AES target, call the HAL_AES_DecryptSharedKey() API which decrypts the encrypted key using the same SAES HW keys (wrapper key) and automatically transfers the unreadable result to the target via secure HW buses. This target must be configured with the HAL_AES_SetSharedKey() API, then the target keys registers are loaded automatically with the transferred key.

Warning

The key size must be the same one as the wrapper key which is provided as a parameter of the HAL_AES_SetHWKey() API

Parameters :

  • haes – Pointer to a hal_aes_handle_t structure

  • p_key_in – Pointer to uint32_t input key provided by the user to be encrypted parameters of the application key and the selected wrapper key (The key to be used to encrypt the key application)

  • key_size – AES key size with a hal_aes_key_size_t type

  • target_id – Specify which target can read the SAES key registers after a decryption 00: AES peripheral

  • timeout_ms – Specify Timeout value in milliseconds

Return values :

  • HAL_INVALID_PARAM – Invalid param return when:

    • The handle instance is not the SAES one

    • The provided application input key pointer is null

  • HAL_BUSY – Another AES process is ongoing

  • HAL_ERROR – Error return when the selected wrapper key is invalid or when the key derivation exceeds the dedicated timeout

  • HAL_TIMEOUT – AES key unwrapping exceeds user timeout

  • HAL_OK – AES key unwrapping is successfully accomplished

Static Inlines functions

group AES_Exported_Functions_Group8

This section provides functions allowing to manage AES interrupts and flags:

Functions

uint32_t HAL_AES_GetFlag ( const hal_aes_handle_t * haes , uint32_t flag )

Check whether the specified AES status flag is set or not.

Parameters :
Return values :

uint32_t – The state of flag (0 or 1).

void HAL_AES_ClearFlagERRC ( hal_aes_handle_t * haes )

Clear the AES error flag.

Parameters :

haes – Specifies the AES handle

Return values :

None –

void HAL_AES_ClearFlagCC ( hal_aes_handle_t * haes )

Clear the AES computation complete flag.

Parameters :

haes – Specifies the AES handle

Return values :

None –

uint32_t HAL_AES_GetITSource ( const hal_aes_handle_t * haes , uint32_t interrupt )

Check whether the specified AES interrupt source is enabled or not.

Parameters :

  • haes – Specifies the AES handle

  • interrupt – AES interrupt source to check This parameter can be one of the following values:

Return values :

uint32_t – State of interruption (0 or 1).

void HAL_AES_EnableIT ( hal_aes_handle_t * haes , uint32_t interrupt )

Enable the AES interrupt.

Parameters :

  • haes – Specifies the AES handle

  • interrupt – AES Interrupt This parameter can be a combination of the following values:

Return values :

None –

void HAL_AES_DisableIT ( hal_aes_handle_t * haes , uint32_t interrupt )

Disable the AES interrupt.

Parameters :

  • haes – Specifies the AES handle

  • interrupt – AES Interrupt This parameter can be a combination of the following values:

Return values :

None –