Initialization and deinitialization functions

Initialization and Configuration functions. More...

Functions
HAL_StatusTypeDef	HAL_CRYP_Init (CRYP_HandleTypeDef *hcryp)
	Initialize the CRYP according to the specified parameters in the CRYP_InitTypeDef and initialize the associated handle. More...
HAL_StatusTypeDef	HAL_CRYP_DeInit (CRYP_HandleTypeDef *hcryp)
	DeInitialize the CRYP peripheral. More...
void	HAL_CRYP_MspInit (CRYP_HandleTypeDef *hcryp)
	Initialize the CRYP MSP. More...
void	HAL_CRYP_MspDeInit (CRYP_HandleTypeDef *hcryp)
	DeInitialize CRYP MSP. More...

Detailed Description

Initialization and Configuration functions.

  ==============================================================================
              ##### Initialization and deinitialization functions #####
  ==============================================================================
    [..]  This section provides functions allowing to:
      (+) Initialize the CRYP according to the specified parameters
          in the CRYP_InitTypeDef and creates the associated handle
      (+) DeInitialize the CRYP peripheral
      (+) Initialize the CRYP MSP (MCU Specific Package)
      (+) De-Initialize the CRYP MSP

    [..]
    (@) Specific care must be taken to format the key and the Initialization Vector IV!

   [..] If the key is defined as a 128-bit long array key[127..0] = {b127 ... b0} where
        b127 is the MSB and b0 the LSB, the key must be stored in MCU memory
        (+) as a sequence of words where the MSB word comes first (occupies the
          lowest memory address)
        (+) where each word is byte-swapped:
         (++)   address n+0 : 0b b103 .. b96 b111 .. b104 b119 .. b112 b127 .. b120
         (++)   address n+4 : 0b b71 .. b64 b79 .. b72 b87 .. b80 b95 .. b88
         (++)   address n+8 : 0b b39 .. b32 b47 .. b40 b55 .. b48 b63 .. b56
         (++)   address n+C : 0b b7 .. b0 b15 .. b8 b23 .. b16 b31 .. b24
    [..] Hereafter, another illustration when considering a 128-bit long key made of 16 bytes {B15..B0}.
        The 4 32-bit words that make the key must be stored as follows in MCU memory:
         (+)    address n+0 : 0x B12 B13 B14 B15
         (+)    address n+4 : 0x B8 B9 B10 B11
         (+)    address n+8 : 0x B4 B5 B6 B7
         (+)    address n+C : 0x B0 B1 B2 B3
    [..]  which leads to the expected setting
      (+)       AES_KEYR3 = 0x B15 B14 B13 B12
      (+)       AES_KEYR2 = 0x B11 B10 B9 B8
      (+)       AES_KEYR1 = 0x B7 B6 B5 B4
      (+)       AES_KEYR0 = 0x B3 B2 B1 B0

   [..]  Same format must be applied for a 256-bit long key made of 32 bytes {B31..B0}.
         The 8 32-bit words that make the key must be stored as follows in MCU memory:
         (+)    address n+00 : 0x B28 B29 B30 B31
         (+)    address n+04 : 0x B24 B25 B26 B27
         (+)    address n+08 : 0x B20 B21 B22 B23
         (+)    address n+0C : 0x B16 B17 B18 B19
         (+)    address n+10 : 0x B12 B13 B14 B15
         (+)    address n+14 : 0x B8 B9 B10 B11
         (+)    address n+18 : 0x B4 B5 B6 B7
         (+)    address n+1C : 0x B0 B1 B2 B3
    [..]  which leads to the expected setting
      (+)       AES_KEYR7 = 0x B31 B30 B29 B28
      (+)       AES_KEYR6 = 0x B27 B26 B25 B24
      (+)       AES_KEYR5 = 0x B23 B22 B21 B20
      (+)       AES_KEYR4 = 0x B19 B18 B17 B16
      (+)       AES_KEYR3 = 0x B15 B14 B13 B12
      (+)       AES_KEYR2 = 0x B11 B10 B9 B8
      (+)       AES_KEYR1 = 0x B7 B6 B5 B4
      (+)       AES_KEYR0 = 0x B3 B2 B1 B0

   [..] Initialization Vector IV (4 32-bit words) format must follow the same as
        that of a 128-bit long key.

  [..]

Function Documentation

HAL_CRYP_DeInit()

HAL_StatusTypeDef HAL_CRYP_DeInit

(

CRYP_HandleTypeDef *

hcryp

)

DeInitialize the CRYP peripheral.

Parameters

hcryp

pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

Return values

HAL

status

Definition at line 442 of file stm32l4xx_hal_cryp.c.

{
  /* Check the CRYP handle allocation */
  if(hcryp == NULL)
  {
    return HAL_ERROR;
  }

  /* Change the CRYP state */
  hcryp->State = HAL_CRYP_STATE_BUSY;

  /* Set the default CRYP phase */
  hcryp->Phase = HAL_CRYP_PHASE_READY;

  /* Reset CrypInCount and CrypOutCount */
  hcryp->CrypInCount = 0;
  hcryp->CrypOutCount = 0;

  /* Disable the CRYP Peripheral Clock */
  __HAL_CRYP_DISABLE(hcryp);

#if (USE_HAL_CRYP_REGISTER_CALLBACKS == 1)
    if(hcryp->MspDeInitCallback == NULL)
    {
      hcryp->MspDeInitCallback = HAL_CRYP_MspDeInit;
    }

    /* DeInit the low level hardware */
    hcryp->MspDeInitCallback(hcryp);
#else
  /* DeInit the low level hardware: CLOCK, NVIC.*/
  HAL_CRYP_MspDeInit(hcryp);
#endif /* (USE_HAL_CRYP_REGISTER_CALLBACKS) */

  /* Change the CRYP state */
  hcryp->State = HAL_CRYP_STATE_RESET;

  /* Release Lock */
  __HAL_UNLOCK(hcryp);

  /* Return function status */
  return HAL_OK;
}

HAL_CRYP_Init()

HAL_StatusTypeDef HAL_CRYP_Init

(

CRYP_HandleTypeDef *

hcryp

)

Initialize the CRYP according to the specified parameters in the CRYP_InitTypeDef and initialize the associated handle.

Note

Specific care must be taken to format the key and the Initialization Vector IV stored in the MCU memory before calling HAL_CRYP_Init(). Refer to explanations hereabove.

Return values

HAL

status

Definition at line 240 of file stm32l4xx_hal_cryp.c.

{
  /* Check the CRYP handle allocation */
  if(hcryp == NULL)
  {
    return HAL_ERROR;
  }

  /* Check the instance */
  assert_param(IS_AES_ALL_INSTANCE(hcryp->Instance));

  /* Check the parameters */
  assert_param(IS_CRYP_KEYSIZE(hcryp->Init.KeySize));
  assert_param(IS_CRYP_DATATYPE(hcryp->Init.DataType));
  assert_param(IS_CRYP_ALGOMODE(hcryp->Init.OperatingMode));
  /* ChainingMode parameter is irrelevant when mode is set to Key derivation */
  if (hcryp->Init.OperatingMode != CRYP_ALGOMODE_KEYDERIVATION)
  {
    assert_param(IS_CRYP_CHAINMODE(hcryp->Init.ChainingMode));
  }
  assert_param(IS_CRYP_WRITE(hcryp->Init.KeyWriteFlag));

  /*========================================================*/
  /* Check the proper operating/chaining modes combinations */
  /*========================================================*/
  /* Check the proper chaining when the operating mode is key derivation and decryption */
#if defined(AES_CR_NPBLB)
  if ((hcryp->Init.OperatingMode == CRYP_ALGOMODE_KEYDERIVATION_DECRYPT) &&\
         ((hcryp->Init.ChainingMode == CRYP_CHAINMODE_AES_CTR)           \
       || (hcryp->Init.ChainingMode == CRYP_CHAINMODE_AES_GCM_GMAC)      \
       || (hcryp->Init.ChainingMode == CRYP_CHAINMODE_AES_CCM)))
#else
  if ((hcryp->Init.OperatingMode == CRYP_ALGOMODE_KEYDERIVATION_DECRYPT) &&\
         ((hcryp->Init.ChainingMode == CRYP_CHAINMODE_AES_CTR)           \
       || (hcryp->Init.ChainingMode == CRYP_CHAINMODE_AES_GCM_GMAC)      \
       || (hcryp->Init.ChainingMode == CRYP_CHAINMODE_AES_CMAC)))
#endif
  {
    return HAL_ERROR;
  }
  /* Check that key derivation is not set in CMAC mode or CCM mode when applicable */
#if defined(AES_CR_NPBLB)
  if ((hcryp->Init.OperatingMode == CRYP_ALGOMODE_KEYDERIVATION)
   && (hcryp->Init.ChainingMode == CRYP_CHAINMODE_AES_CCM))
#else
  if ((hcryp->Init.OperatingMode == CRYP_ALGOMODE_KEYDERIVATION)
   && (hcryp->Init.ChainingMode == CRYP_CHAINMODE_AES_CMAC))
#endif
  {
    return HAL_ERROR;
  }


  /*================*/
  /* Initialization */
  /*================*/
  /* Initialization start */
#if (USE_HAL_CRYP_REGISTER_CALLBACKS == 1)
  if (hcryp->State == HAL_CRYP_STATE_RESET)
  {
    /* Allocate lock resource and initialize it */
    hcryp->Lock = HAL_UNLOCKED;

    /* Reset Callback pointers in HAL_CRYP_STATE_RESET only */
    hcryp->InCpltCallback   =  HAL_CRYP_InCpltCallback;            /* Legacy weak (surcharged) input DMA transfer completion callback */
    hcryp->OutCpltCallback   =  HAL_CRYP_OutCpltCallback;           /* Legacy weak (surcharged) output DMA transfer completion callback */
    hcryp->CompCpltCallback =  HAL_CRYPEx_ComputationCpltCallback; /* Legacy weak (surcharged) computation completion callback */
    hcryp->ErrorCallback    =  HAL_CRYP_ErrorCallback;             /* Legacy weak (surcharged) error callback */
    if(hcryp->MspInitCallback == NULL)
    {
      hcryp->MspInitCallback = HAL_CRYP_MspInit;
    }

    /* Init the low level hardware */
    hcryp->MspInitCallback(hcryp);
  }
#else
  if(hcryp->State == HAL_CRYP_STATE_RESET)
  {
    /* Allocate lock resource and initialize it */
    hcryp->Lock = HAL_UNLOCKED;

    /* Init the low level hardware */
    HAL_CRYP_MspInit(hcryp);
  }
#endif /* (USE_HAL_CRYP_REGISTER_CALLBACKS) */

  /* Change the CRYP state */
  hcryp->State = HAL_CRYP_STATE_BUSY;

  /* Disable the Peripheral */
  __HAL_CRYP_DISABLE(hcryp);

  /*=============================================================*/
  /* AES initialization common to all operating modes            */
  /*=============================================================*/
  /* Set the Key size selection */
  MODIFY_REG(hcryp->Instance->CR, AES_CR_KEYSIZE, hcryp->Init.KeySize);

  /* Set the default CRYP phase when this parameter is not used.
     Phase is updated below in case of GCM/GMAC(/CMAC)(/CCM) setting. */
  hcryp->Phase = HAL_CRYP_PHASE_NOT_USED;



  /*=============================================================*/
  /* Carry on the initialization based on the AES operating mode */
  /*=============================================================*/
  /* Key derivation */
  if (hcryp->Init.OperatingMode == CRYP_ALGOMODE_KEYDERIVATION)
  {
    MODIFY_REG(hcryp->Instance->CR, AES_CR_MODE, CRYP_ALGOMODE_KEYDERIVATION);

    /* Configure the Key registers */
    if (CRYP_SetKey(hcryp) != HAL_OK)
    {
      return HAL_ERROR;
    }
  }
  else
  /* Encryption / Decryption (with or without key derivation) / authentication */
  {
#if !defined(AES_CR_NPBLB)
    /* Set data type, operating and chaining modes.
       In case of GCM or GMAC, data type is forced to 0b00 */
    if (hcryp->Init.ChainingMode == CRYP_CHAINMODE_AES_GCM_GMAC)
    {
      MODIFY_REG(hcryp->Instance->CR, AES_CR_DATATYPE|AES_CR_MODE|AES_CR_CHMOD, hcryp->Init.OperatingMode|hcryp->Init.ChainingMode);
    }
    else
#endif
    {
      MODIFY_REG(hcryp->Instance->CR, AES_CR_DATATYPE|AES_CR_MODE|AES_CR_CHMOD, hcryp->Init.DataType|hcryp->Init.OperatingMode|hcryp->Init.ChainingMode);
    }


   /* Specify the encryption/decryption phase in case of Galois counter mode (GCM),
      Galois message authentication code (GMAC), cipher message authentication code (CMAC) when applicable
      or Counter with Cipher Mode (CCM) when applicable */
#if defined(AES_CR_NPBLB)
   if ((hcryp->Init.ChainingMode == CRYP_CHAINMODE_AES_GCM_GMAC)
    || (hcryp->Init.ChainingMode == CRYP_CHAINMODE_AES_CCM))
#else
   if ((hcryp->Init.ChainingMode == CRYP_CHAINMODE_AES_GCM_GMAC)
    || (hcryp->Init.ChainingMode == CRYP_CHAINMODE_AES_CMAC))
#endif
    {
      MODIFY_REG(hcryp->Instance->CR, AES_CR_GCMPH, hcryp->Init.GCMCMACPhase);
      hcryp->Phase = HAL_CRYP_PHASE_START;
    }


    /* Configure the Key registers if no need to bypass this step */
    if (hcryp->Init.KeyWriteFlag == CRYP_KEY_WRITE_ENABLE)
    {
      if (CRYP_SetKey(hcryp) != HAL_OK)
      {
        return HAL_ERROR;
      }
    }

    /* If applicable, configure the Initialization Vector */
    if (hcryp->Init.ChainingMode != CRYP_CHAINMODE_AES_ECB)
    {
      if (CRYP_SetInitVector(hcryp) != HAL_OK)
      {
        return HAL_ERROR;
      }
    }
  }

#if defined(AES_CR_NPBLB)
  /* Clear NPBLB field */
  CLEAR_BIT(hcryp->Instance->CR, AES_CR_NPBLB);
#endif

  /* Reset CrypInCount and CrypOutCount */
  hcryp->CrypInCount = 0;
  hcryp->CrypOutCount = 0;

  /* Reset ErrorCode field */
  hcryp->ErrorCode = HAL_CRYP_ERROR_NONE;

  /* Reset Mode suspension request */
  hcryp->SuspendRequest = HAL_CRYP_SUSPEND_NONE;

  /* Change the CRYP state */
  hcryp->State = HAL_CRYP_STATE_READY;

  /* Enable the Peripheral */
  __HAL_CRYP_ENABLE(hcryp);

  /* Return function status */
  return HAL_OK;
}

HAL_CRYP_MspDeInit()

__weak void HAL_CRYP_MspDeInit

(

CRYP_HandleTypeDef *

hcryp

)

DeInitialize CRYP MSP.

Parameters

hcryp

pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

Return values

None

Definition at line 508 of file stm32l4xx_hal_cryp.c.

{
  /* Prevent unused argument(s) compilation warning */
  UNUSED(hcryp);

  /* NOTE : This function should not be modified; when the callback is needed,
            the HAL_CRYP_MspDeInit can be implemented in the user file
   */
}

HAL_CRYP_MspInit()

__weak void HAL_CRYP_MspInit

(

CRYP_HandleTypeDef *

hcryp

)

Initialize the CRYP MSP.

Parameters

hcryp

pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

Return values

None

Definition at line 492 of file stm32l4xx_hal_cryp.c.

{
  /* Prevent unused argument(s) compilation warning */
  UNUSED(hcryp);

  /* NOTE : This function should not be modified; when the callback is needed,
            the HAL_CRYP_MspInit can be implemented in the user file
   */
}