HAL HASH How to Use ¶

group HASH_How_To_Use

How to use this driver ¶

The HASH HAL driver can be used as follows:

1. Initialize and de-initialize the logical HASH object :

   • To initialize the HASH peripheral, Use the HAL_HASH_Init() function to initialize the HAL HASH driver for the given handle object

     • The HAL_HASH_Init() API allow to associate physical instance to logical object(handle) and initialize the internal parameters of the handle.

     • The HAL_HASH_Init() API allows to enable the peripheral clock when USE_HASH_CLK_ENABLE_MODEL is different from HAL_CLK_ENABLE_NO. In case of the USE_HASH_CLK_ENABLE_MODEL compilation is not defined or define to HAL_CLK_ENABLE_NO, the application needs to explicitly call the HAL RCC API HAL_RCC_HASH_EnableClock() in order to enable the clock of HASH peripheral.

   • To de-initiliaze the HASH peripheral, use the HAL_HASH_DeInit() function that stop any ongoing process and set the HASH handle state to reset.

2. Set and Get HASH configuration:

   • To apply the HASH peripheral configuration, use the HAL_HASH_SetConfig() . HASH Parameters are :

     • Data Swapping : no swap or half word swap or bit swap or byte swap.

     • algorithm : MD5 or SHA1 or SHA224 or SHA256.

   • To get the HASH peripheral configuration, use the HAL_HASH_GetConfig() to retrieve the current HASH configuration.

3. Set and Get HASH HMAC configuration:

   • To apply the HASH HMAC peripheral configuration, use the HAL_HASH_HMAC_SetConfig() . HASH HMAC Parameters are :

     • Data Swapping : no swap or half word swap or bit swap or byte swap.

     • algorithm : MD5 or SHA1 or SHA224 or SHA256.

     • Key : Identifier of the key to use for the HMAC operation.

     • key size in bytes.

   • To get the HASH HMAC peripheral configuration, use the HAL_HASH_HMAC_GetConfig() to retrieve the current HASH HMAC configuration.

4. There are 2 families of API:

   • OneShot API: handling one single/complete buffer and providing the HASH result.

   • Update APIs: allowing the user to update several buffers then provide the HASH result corresponding to the data provided by the sum of these updated buffers.

5. Three processing modes are available:

   • OneShot APIs:

     • Polling mode: Processing APIs are blocking functions. These APIs process the data and wait till the digest computation is finished. Use function HAL_HASH_Compute() for HASH or HAL_HASH_HMAC_Compute() for HMAC.

     • Interrupt mode: processing APIs are not blocking functions. It process the data under interruption. Use the function HAL_HASH_Compute_IT() for HASH or HAL_HASH_HMAC_Compute_IT() for HMAC.

     • DMA mode: processing APIs are not blocking functions and the CPU is not used for data transfer. The data transfer is ensured by DMA. Use the function HAL_HASH_Compute_DMA() for HASH or HAL_HASH_HMAC_Compute_DMA() for HMAC.

   • Update APIs:

     • Polling mode:

       • HASH context mode : API HAL_HASH_Update() must be called to start hashing and update several input buffers. User must resort to HAL_HASH_Finish() to retrieve as well the computed digest.

       • HMAC context mode : The key and the key size are entered in config API HAL_HASH_HMAC_SetConfig() . API HAL_HASH_HMAC_Update() must be called to start hashing and update several input buffers. User must resort to HAL_HASH_HMAC_Finish() to retrieve as well the computed digest.

     • Interrupt mode:

       • HASH context mode : API HAL_HASH_Update_IT() must be called to start hashing and update several input buffers. User must resort to HAL_HASH_Finish() to retrieve as well the computed digest.

       • HMAC context mode : The key and the key size are entered in config API HAL_HASH_HMAC_SetConfig() . API HAL_HASH_HMAC_Update_IT() must be called to start hashing and update several input buffers. User must resort to HAL_HASH_HMAC_Finish() to retrieve as well the computed digest.

     • DMA mode:

       • HASH context mode : API HAL_HASH_Update_DMA() must be called to start hashing and update several input buffers. User must resort to HAL_HASH_Finish() to retrieve as well the computed digest.

       • HMAC context mode : The key and the key size are entered in config API HAL_HASH_HMAC_SetConfig() . API HAL_HASH_HMAC_Update_DMA() must be called to start hashing and update several input buffers. User must resort to HAL_HASH_HMAC_Finish() to retrieve as well the computed digest.

6. Switch context:

   • Two APIs are available to suspend HASH or HMAC processing:

     • For computation process : The user need to call the function HAL_HASH_RequestSuspendComputation() when a computation process is ongoing.

     • For update process: The user need to call the function HAL_HASH_RequestSuspendUpdate() when an update process is ongoing.

   • Two APIs are available to resume HASH or HMAC processing:

     • For computation process : The user need to call the function HAL_HASH_ResumeComputation() to resume the prior computation process and set the HAL HASH handle state to HAL_HASH_STATE_ACTIVE_COMPUTE.

     • For update process: The user need to call the function HAL_HASH_ResumeUpdate() to resume the prior update process and set the HAL HASH handle state to HAL_HASH_STATE_ACTIVE_UPDATE.

   • When HASH or HMAC processing is suspended, the user can use the function HAL_HASH_SaveContext() to save the peripheral context. This context can be restored afterwards.

   • Before resuming the HASH or HMAC processing user can call HAL_HASH_RestoreContext() to restore the saved context needed if the HASH peripheral was used by another applicative process to perform some other hashing tasks.

   • Once the HASH Peripheral context has been restored to the same configuration as that at suspension time, processing can be Resumed thanks to the APIs HAL_HASH_ResumeComputation() /HAL_HASH_ResumeUpdate() from the proper location reached at suspend time and with the same parameters (the required parameters to resume the operation are saved into the handle).

7. Remarks on message length:

   • HAL in interruption mode (interruptions driven):

     • Due to HASH peripheral hardware design, the peripheral interruption is triggered every 64 bytes.

   • HAL in DMA mode

     • Again, due to hardware design, the DMA transfer to feed the data can only be done on a word-basis. The same field described above in HASH_STR is used to specify which bits to discard at the end of the DMA transfer to process only the message bits and not extra bits. Due to hardware implementation, this is possible only at the end of the complete message. When several DMA transfers are needed to enter the message, this is not applicable at the end of the intermediary transfers.

8. Callback registration:

   • By default, after the HAL_HASH_Init, all callbacks are reset to the corresponding legacy weak functions:

     • HAL_HASH_InputCpltCallback() : A Callback when an input data transfer complete has occurred.

     • HAL_HASH_DigestCpltCallback() : A Callback when a digest computation complete has occurred.

     • HAL_HASH_ErrorCallback() : A Callback when an error has occurred.

     • HAL_HASH_SuspendCallback() : A callback when a suspend operation has occurred.

     • HAL_HASH_AbortCallback() : A callback when an abort operation has occurred.

   • The compilation define USE_HAL_HASH_REGISTER_CALLBACKS when set to 1 allows the user to configure dynamically the driver callbacks.

   • Use function HAL_HASH_RegisterInputCpltCallback() to register a user callback for input completion.

   • Use function HAL_HASH_RegisterDigestComputationCpltCallback() to register a user callback for input completion.

   • Use function HAL_HASH_RegisterErrorCpltCallback() to register a user callback for error callback.

   • Use function HAL_HASH_RegisterSuspendCpltCallback() to register a user callback for suspend callback.

   • Use function HAL_HASH_RegisterAbortCpltCallback() to register a user callback for abort callback.

   • When The compilation define USE_HAL_HASH_REGISTER_CALLBACKS is set to 0 or not defined, the callback registering feature is not available and weak (surcharged) callbacks are used.