stm32f4xx_hal_hash.c File Reference

HASH HAL module driver. This file provides firmware functions to manage the following functionalities of the HASH peripheral: + Initialization and de-initialization methods + HASH or HMAC processing in polling mode + HASH or HMAC processing in interrupt mode + HASH or HMAC processing in DMA mode + Peripheral State methods + HASH or HMAC processing suspension/resumption. More...

#include "stm32f4xx_hal.h"

Go to the source code of this file.

Defines
#define	HASH_DIGEST_CALCULATION_NOT_STARTED   ((uint32_t)0x00000000U)
#define	HASH_DIGEST_CALCULATION_STARTED   ((uint32_t)0x00000001U)
#define	HASH_NUMBER_OF_CSR_REGISTERS   54U
#define	HASH_TIMEOUTVALUE   1000U
#define	HASH_DMA_SUSPENSION_WORDS_LIMIT   20U
Functions
static void	HASH_DMAXferCplt (DMA_HandleTypeDef *hdma)
	DMA HASH Input Data transfer completion callback.
static void	HASH_DMAError (DMA_HandleTypeDef *hdma)
	DMA HASH communication error callback.
static void	HASH_GetDigest (uint8_t *pMsgDigest, uint8_t Size)
	Retrieve the message digest.
static HAL_StatusTypeDef	HASH_WaitOnFlagUntilTimeout (HASH_HandleTypeDef *hhash, uint32_t Flag, FlagStatus Status, uint32_t Timeout)
	Handle HASH processing Timeout.
static HAL_StatusTypeDef	HASH_WriteData (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size)
	Feed the input buffer to the HASH Peripheral.
static HAL_StatusTypeDef	HASH_IT (HASH_HandleTypeDef *hhash)
	HASH processing in interruption mode.
static uint32_t	HASH_Write_Block_Data (HASH_HandleTypeDef *hhash)
	Write a block of data in HASH Peripheral in interruption mode.
static HAL_StatusTypeDef	HMAC_Processing (HASH_HandleTypeDef *hhash, uint32_t Timeout)
	HMAC processing in polling mode.
HAL_StatusTypeDef	HAL_HASH_Init (HASH_HandleTypeDef *hhash)
	Initialize the HASH according to the specified parameters in the HASH_HandleTypeDef and create the associated handle.
HAL_StatusTypeDef	HAL_HASH_DeInit (HASH_HandleTypeDef *hhash)
	DeInitialize the HASH peripheral.
__weak void	HAL_HASH_MspInit (HASH_HandleTypeDef *hhash)
	Initialize the HASH MSP.
__weak void	HAL_HASH_MspDeInit (HASH_HandleTypeDef *hhash)
	DeInitialize the HASH MSP.
__weak void	HAL_HASH_InCpltCallback (HASH_HandleTypeDef *hhash)
	Input data transfer complete call back.
__weak void	HAL_HASH_DgstCpltCallback (HASH_HandleTypeDef *hhash)
	Digest computation complete call back.
__weak void	HAL_HASH_ErrorCallback (HASH_HandleTypeDef *hhash)
	Error callback.
HAL_StatusTypeDef	HAL_HASH_RegisterCallback (HASH_HandleTypeDef *hhash, HAL_HASH_CallbackIDTypeDef CallbackID, pHASH_CallbackTypeDef pCallback)
	Register a User HASH Callback To be used instead of the weak (surcharged) predefined callback.
HAL_StatusTypeDef	HAL_HASH_UnRegisterCallback (HASH_HandleTypeDef *hhash, HAL_HASH_CallbackIDTypeDef CallbackID)
	Unregister a HASH Callback HASH Callback is redirected to the weak (surcharged) predefined callback.
HAL_StatusTypeDef	HAL_HASH_MD5_Start (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer, uint32_t Timeout)
	Initialize the HASH peripheral in MD5 mode, next process pInBuffer then read the computed digest.
HAL_StatusTypeDef	HAL_HASH_MD5_Accmlt (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size)
	If not already done, initialize the HASH peripheral in MD5 mode then processes pInBuffer.
HAL_StatusTypeDef	HAL_HASH_MD5_Accmlt_End (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer, uint32_t Timeout)
	End computation of a single HASH signature after several calls to HAL_HASH_MD5_Accmlt() API.
HAL_StatusTypeDef	HAL_HASH_SHA1_Start (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer, uint32_t Timeout)
	Initialize the HASH peripheral in SHA1 mode, next process pInBuffer then read the computed digest.
HAL_StatusTypeDef	HAL_HASH_SHA1_Accmlt (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size)
	If not already done, initialize the HASH peripheral in SHA1 mode then processes pInBuffer.
HAL_StatusTypeDef	HAL_HASH_SHA1_Accmlt_End (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer, uint32_t Timeout)
	End computation of a single HASH signature after several calls to HAL_HASH_SHA1_Accmlt() API.
HAL_StatusTypeDef	HAL_HASH_MD5_Start_IT (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer)
	Initialize the HASH peripheral in MD5 mode, next process pInBuffer then read the computed digest in interruption mode.
HAL_StatusTypeDef	HAL_HASH_MD5_Accmlt_IT (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size)
	If not already done, initialize the HASH peripheral in MD5 mode then processes pInBuffer in interruption mode.
HAL_StatusTypeDef	HAL_HASH_MD5_Accmlt_End_IT (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer)
	End computation of a single HASH signature after several calls to HAL_HASH_MD5_Accmlt_IT() API.
HAL_StatusTypeDef	HAL_HASH_SHA1_Start_IT (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer)
	Initialize the HASH peripheral in SHA1 mode, next process pInBuffer then read the computed digest in interruption mode.
HAL_StatusTypeDef	HAL_HASH_SHA1_Accmlt_IT (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size)
	If not already done, initialize the HASH peripheral in SHA1 mode then processes pInBuffer in interruption mode.
HAL_StatusTypeDef	HAL_HASH_SHA1_Accmlt_End_IT (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer)
	End computation of a single HASH signature after several calls to HAL_HASH_SHA1_Accmlt_IT() API.
void	HAL_HASH_IRQHandler (HASH_HandleTypeDef *hhash)
	Handle HASH interrupt request.
HAL_StatusTypeDef	HAL_HASH_MD5_Start_DMA (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size)
	Initialize the HASH peripheral in MD5 mode then initiate a DMA transfer to feed the input buffer to the Peripheral.
HAL_StatusTypeDef	HAL_HASH_MD5_Finish (HASH_HandleTypeDef *hhash, uint8_t *pOutBuffer, uint32_t Timeout)
	Return the computed digest in MD5 mode.
HAL_StatusTypeDef	HAL_HASH_SHA1_Start_DMA (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size)
	Initialize the HASH peripheral in SHA1 mode then initiate a DMA transfer to feed the input buffer to the Peripheral.
HAL_StatusTypeDef	HAL_HASH_SHA1_Finish (HASH_HandleTypeDef *hhash, uint8_t *pOutBuffer, uint32_t Timeout)
	Return the computed digest in SHA1 mode.
HAL_StatusTypeDef	HAL_HMAC_MD5_Start (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer, uint32_t Timeout)
	Initialize the HASH peripheral in HMAC MD5 mode, next process pInBuffer then read the computed digest.
HAL_StatusTypeDef	HAL_HMAC_SHA1_Start (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer, uint32_t Timeout)
	Initialize the HASH peripheral in HMAC SHA1 mode, next process pInBuffer then read the computed digest.
HAL_StatusTypeDef	HAL_HMAC_MD5_Start_IT (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer)
	Initialize the HASH peripheral in HMAC MD5 mode, next process pInBuffer then read the computed digest in interrupt mode.
HAL_StatusTypeDef	HAL_HMAC_SHA1_Start_IT (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer)
	Initialize the HASH peripheral in HMAC SHA1 mode, next process pInBuffer then read the computed digest in interrupt mode.
HAL_StatusTypeDef	HAL_HMAC_MD5_Start_DMA (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size)
	Initialize the HASH peripheral in HMAC MD5 mode then initiate the required DMA transfers to feed the key and the input buffer to the Peripheral.
HAL_StatusTypeDef	HAL_HMAC_SHA1_Start_DMA (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size)
	Initialize the HASH peripheral in HMAC SHA1 mode then initiate the required DMA transfers to feed the key and the input buffer to the Peripheral.
HAL_HASH_StateTypeDef	HAL_HASH_GetState (HASH_HandleTypeDef *hhash)
	Return the HASH handle state.
HAL_StatusTypeDef	HAL_HASH_GetStatus (HASH_HandleTypeDef *hhash)
	Return the HASH HAL status.
void	HAL_HASH_ContextSaving (HASH_HandleTypeDef *hhash, uint8_t *pMemBuffer)
	Save the HASH context in case of processing suspension.
void	HAL_HASH_ContextRestoring (HASH_HandleTypeDef *hhash, uint8_t *pMemBuffer)
	Restore the HASH context in case of processing resumption.
void	HAL_HASH_SwFeed_ProcessSuspend (HASH_HandleTypeDef *hhash)
	Initiate HASH processing suspension when in polling or interruption mode.
HAL_StatusTypeDef	HAL_HASH_DMAFeed_ProcessSuspend (HASH_HandleTypeDef *hhash)
	Suspend the HASH processing when in DMA mode.
uint32_t	HAL_HASH_GetError (HASH_HandleTypeDef *hhash)
	Return the HASH handle error code.
HAL_StatusTypeDef	HASH_Start (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer, uint32_t Timeout, uint32_t Algorithm)
	Initialize the HASH peripheral, next process pInBuffer then read the computed digest.
HAL_StatusTypeDef	HASH_Accumulate (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint32_t Algorithm)
	If not already done, initialize the HASH peripheral then processes pInBuffer.
HAL_StatusTypeDef	HASH_Accumulate_IT (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint32_t Algorithm)
	If not already done, initialize the HASH peripheral then processes pInBuffer in interruption mode.
HAL_StatusTypeDef	HASH_Start_IT (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer, uint32_t Algorithm)
	Initialize the HASH peripheral, next process pInBuffer then read the computed digest in interruption mode.
HAL_StatusTypeDef	HASH_Start_DMA (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint32_t Algorithm)
	Initialize the HASH peripheral then initiate a DMA transfer to feed the input buffer to the Peripheral.
HAL_StatusTypeDef	HASH_Finish (HASH_HandleTypeDef *hhash, uint8_t *pOutBuffer, uint32_t Timeout)
	Return the computed digest.
HAL_StatusTypeDef	HMAC_Start (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer, uint32_t Timeout, uint32_t Algorithm)
	Initialize the HASH peripheral in HMAC mode, next process pInBuffer then read the computed digest.
HAL_StatusTypeDef	HMAC_Start_IT (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint8_t *pOutBuffer, uint32_t Algorithm)
	Initialize the HASH peripheral in HMAC mode, next process pInBuffer then read the computed digest in interruption mode.
HAL_StatusTypeDef	HMAC_Start_DMA (HASH_HandleTypeDef *hhash, uint8_t *pInBuffer, uint32_t Size, uint32_t Algorithm)
	Initialize the HASH peripheral in HMAC mode then initiate the required DMA transfers to feed the key and the input buffer to the Peripheral.

---

Detailed Description

HASH HAL module driver. This file provides firmware functions to manage the following functionalities of the HASH peripheral: + Initialization and de-initialization methods + HASH or HMAC processing in polling mode + HASH or HMAC processing in interrupt mode + HASH or HMAC processing in DMA mode + Peripheral State methods + HASH or HMAC processing suspension/resumption.

Author:

MCD Application Team

 ===============================================================================
                     ##### How to use this driver #####
 ===============================================================================
    [..]
    The HASH HAL driver can be used as follows:

    (#)Initialize the HASH low level resources by implementing the HAL_HASH_MspInit():
        (##) Enable the HASH interface clock using __HASH_CLK_ENABLE()
        (##) When resorting to interrupt-based APIs (e.g. HAL_HASH_xxx_Start_IT())
            (+++) Configure the HASH interrupt priority using HAL_NVIC_SetPriority()
            (+++) Enable the HASH IRQ handler using HAL_NVIC_EnableIRQ()
            (+++) In HASH IRQ handler, call HAL_HASH_IRQHandler() API
        (##) When resorting to DMA-based APIs  (e.g. HAL_HASH_xxx_Start_DMA())
            (+++) Enable the DMAx interface clock using
                   __DMAx_CLK_ENABLE()
            (+++) Configure and enable one DMA stream to manage data transfer from
                memory to peripheral (input stream). Managing data transfer from
                peripheral to memory can be performed only using CPU.
            (+++) Associate the initialized DMA handle to the HASH DMA handle
                using  __HAL_LINKDMA()
            (+++) Configure the priority and enable the NVIC for the transfer complete
                interrupt on the DMA stream: use
                 HAL_NVIC_SetPriority() and
                 HAL_NVIC_EnableIRQ()

    (#)Initialize the HASH HAL using HAL_HASH_Init(). This function:
        (##) resorts to HAL_HASH_MspInit() for low-level initialization,
        (##) configures the data type: 1-bit, 8-bit, 16-bit or 32-bit.

    (#)Three processing schemes are available:
        (##) Polling mode: processing APIs are blocking functions
             i.e. they process the data and wait till the digest computation is finished,
             e.g. HAL_HASH_xxx_Start() for HASH or HAL_HMAC_xxx_Start() for HMAC
        (##) Interrupt mode: processing APIs are not blocking functions
                i.e. they process the data under interrupt,
                e.g. HAL_HASH_xxx_Start_IT() for HASH or HAL_HMAC_xxx_Start_IT() for HMAC
        (##) DMA mode: processing APIs are not blocking functions and the CPU is
             not used for data transfer i.e. the data transfer is ensured by DMA,
                e.g. HAL_HASH_xxx_Start_DMA() for HASH or HAL_HMAC_xxx_Start_DMA()
                for HMAC. Note that in DMA mode, a call to HAL_HASH_xxx_Finish()
                is then required to retrieve the digest.

    (#)When the processing function is called after HAL_HASH_Init(), the HASH peripheral is
       initialized and processes the buffer fed in input. When the input data have all been
       fed to the Peripheral, the digest computation can start.

    (#)Multi-buffer processing is possible in polling, interrupt and DMA modes.
        (##) In polling mode, only multi-buffer HASH processing is possible.
             API HAL_HASH_xxx_Accumulate() must be called for each input buffer, except for the last one.
             User must resort to HAL_HASH_xxx_Accumulate_End() to enter the last one and retrieve as
             well the computed digest.

        (##) In interrupt mode, API HAL_HASH_xxx_Accumulate_IT() must be called for each input buffer,
             except for the last one.
             User must resort to HAL_HASH_xxx_Accumulate_End_IT() to enter the last one and retrieve as
             well the computed digest.

        (##) In DMA mode, multi-buffer HASH and HMAC processing are possible.
              (+++) HASH processing: once initialization is done, MDMAT bit must be set
               through __HAL_HASH_SET_MDMAT() macro.
             From that point, each buffer can be fed to the Peripheral through HAL_HASH_xxx_Start_DMA() API.
             Before entering the last buffer, reset the MDMAT bit with __HAL_HASH_RESET_MDMAT()
             macro then wrap-up the HASH processing in feeding the last input buffer through the
             same API HAL_HASH_xxx_Start_DMA(). The digest can then be retrieved with a call to
             API HAL_HASH_xxx_Finish().
             (+++) HMAC processing (requires to resort to extended functions):
             after initialization, the key and the first input buffer are entered
             in the Peripheral with the API HAL_HMACEx_xxx_Step1_2_DMA(). This carries out HMAC step 1 and
             starts step 2.
             The following buffers are next entered with the API  HAL_HMACEx_xxx_Step2_DMA(). At this
             point, the HMAC processing is still carrying out step 2.
             Then, step 2 for the last input buffer and step 3 are carried out by a single call
             to HAL_HMACEx_xxx_Step2_3_DMA().

             The digest can finally be retrieved with a call to API HAL_HASH_xxx_Finish().


    (#)Context swapping.
        (##) Two APIs are available to suspend HASH or HMAC processing:
             (+++) HAL_HASH_SwFeed_ProcessSuspend() when data are entered by software (polling or IT mode),
             (+++) HAL_HASH_DMAFeed_ProcessSuspend() when data are entered by DMA.

        (##) When HASH or HMAC processing is suspended, HAL_HASH_ContextSaving() allows
            to save in memory the Peripheral context. This context can be restored afterwards
            to resume the HASH processing thanks to HAL_HASH_ContextRestoring().

        (##) Once the HASH Peripheral has been restored to the same configuration as that at suspension
             time, processing can be restarted with the same API call (same API, same handle,
             same parameters) as done before the suspension. Relevant parameters to restart at
             the proper location are internally saved in the HASH handle.

    (#)Call HAL_HASH_DeInit() to deinitialize the HASH peripheral.

     *** Remarks on message length ***
     ===================================
     [..]
      (#) HAL in interruption mode (interruptions driven)

        (##)Due to HASH peripheral hardware design, the peripheral interruption is triggered every 64 bytes.
        This is why, for driver implementation simplicity’s sake, user is requested to enter a message the
        length of which is a multiple of 4 bytes.

        (##) When the message length (in bytes) is not a multiple of words, a specific field exists in HASH_STR
        to specify which bits to discard at the end of the complete message to process only the message bits
        and not extra bits.

        (##) If user needs to perform a hash computation of a large input buffer that is spread around various places
        in memory and where each piece of this input buffer is not necessarily a multiple of 4 bytes in size, it becomes
        necessary to use a temporary buffer to format the data accordingly before feeding them to the Peripheral.
        It is advised to the user to
       (+++) achieve the first formatting operation by software then enter the data
       (+++) while the Peripheral is processing the first input set, carry out the second formatting
        operation by software, to be ready when DINIS occurs.
       (+++) repeat step 2 until the whole message is processed.

     [..]
      (#) 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.

        (##) Similarly to the interruption-driven mode, it is suggested to the user to format the consecutive
        chunks of data by software while the DMA transfer and processing is on-going for the first parts of
        the message. Due to the 32-bit alignment required for the DMA transfer, it is underlined that the
        software formatting operation is more complex than in the IT mode.

     *** Callback registration ***
     ===================================
     [..]
      (#) The compilation define  USE_HAL_HASH_REGISTER_CALLBACKS when set to 1
          allows the user to configure dynamically the driver callbacks.
          Use function @ref HAL_HASH_RegisterCallback() to register a user callback.

      (#) Function @ref HAL_HASH_RegisterCallback() allows to register following callbacks:
            (+) InCpltCallback    : callback for input completion.
            (+) DgstCpltCallback  : callback for digest computation completion.
            (+) ErrorCallback     : callback for error.
            (+) MspInitCallback   : HASH MspInit.
            (+) MspDeInitCallback : HASH MspDeInit.
          This function takes as parameters the HAL peripheral handle, the Callback ID
          and a pointer to the user callback function.

      (#) Use function @ref HAL_HASH_UnRegisterCallback() to reset a callback to the default
          weak (surcharged) function.
          @ref HAL_HASH_UnRegisterCallback() takes as parameters the HAL peripheral handle,
          and the Callback ID.
          This function allows to reset following callbacks:
            (+) InCpltCallback    : callback for input completion.
            (+) DgstCpltCallback  : callback for digest computation completion.
            (+) ErrorCallback     : callback for error.
            (+) MspInitCallback   : HASH MspInit.
            (+) MspDeInitCallback : HASH MspDeInit.

      (#) By default, after the @ref HAL_HASH_Init and if the state is HAL_HASH_STATE_RESET
          all callbacks are reset to the corresponding legacy weak (surcharged) functions:
          examples @ref HAL_HASH_InCpltCallback(), @ref HAL_HASH_DgstCpltCallback()
          Exception done for MspInit and MspDeInit callbacks that are respectively
          reset to the legacy weak (surcharged) functions in the @ref HAL_HASH_Init
          and @ref HAL_HASH_DeInit only when these callbacks are null (not registered beforehand)
          If not, MspInit or MspDeInit are not null, the @ref HAL_HASH_Init and @ref HAL_HASH_DeInit
          keep and use the user MspInit/MspDeInit callbacks (registered beforehand).

          Callbacks can be registered/unregistered in READY state only.
          Exception done for MspInit/MspDeInit callbacks that can be registered/unregistered
          in READY or RESET state, thus registered (user) MspInit/DeInit callbacks can be used
          during the Init/DeInit.
          In that case first register the MspInit/MspDeInit user callbacks
          using @ref HAL_HASH_RegisterCallback before calling @ref HAL_HASH_DeInit
          or @ref HAL_HASH_Init function.

          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.

  

Attention:

© Copyright (c) 2016 STMicroelectronics. All rights reserved.

This software component is licensed by ST under BSD 3-Clause license, the "License"; You may not use this file except in compliance with the License. You may obtain a copy of the License at: opensource.org/licenses/BSD-3-Clause

Definition in file stm32f4xx_hal_hash.c.