RTEMS 6.1-rc5
Loading...
Searching...
No Matches
stm32h7xx_hal_cryp.c File Reference

CRYP HAL module driver. This file provides firmware functions to manage the following functionalities of the Cryptography (CRYP) peripheral: More...

#include "stm32h7xx_hal.h"

Detailed Description

CRYP HAL module driver. This file provides firmware functions to manage the following functionalities of the Cryptography (CRYP) peripheral:

Author
MCD Application Team
  • Initialization and de-initialization functions
  • AES processing functions
  • DES processing functions
  • TDES processing functions
  • DMA callback functions
  • CRYP IRQ handler management
  • Peripheral State functions
Attention

Copyright (c) 2017 STMicroelectronics. All rights reserved.

This software is licensed under terms that can be found in the LICENSE file in the root directory of this software component. If no LICENSE file comes with this software, it is provided AS-IS.

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

     (#)Initialize the CRYP low level resources by implementing the HAL_CRYP_MspInit():
        (##) Enable the CRYP interface clock using __HAL_RCC_CRYP_CLK_ENABLE()
        (##) In case of using interrupts (e.g. HAL_CRYP_Encrypt_IT())
            (+++) Configure the CRYP interrupt priority using HAL_NVIC_SetPriority()
            (+++) Enable the CRYP IRQ handler using HAL_NVIC_EnableIRQ()
            (+++) In CRYP IRQ handler, call HAL_CRYP_IRQHandler()
        (##) In case of using DMA to control data transfer (e.g. HAL_CRYP_Encrypt_DMA())
            (+++) Enable the DMAx interface clock using __RCC_DMAx_CLK_ENABLE()
            (+++) Configure and enable two DMA streams one for managing data transfer from
                memory to peripheral (input stream) and another stream for managing data
                transfer from peripheral to memory (output stream)
            (+++) Associate the initialized DMA handle to the CRYP DMA handle
                using  __HAL_LINKDMA()
            (+++) Configure the priority and enable the NVIC for the transfer complete
                interrupt on the two DMA Streams. The output stream should have higher
                priority than the input stream HAL_NVIC_SetPriority() and HAL_NVIC_EnableIRQ()

     (#)Initialize the CRYP according to the specified parameters :
        (##) The data type: bit swap(1-bit data), byte swap(8-bit data), half word swap(16-bit data)
           or no swap(32-bit data).
        (##) The key size: 128, 192 or 256.
        (##) The AlgoMode DES/ TDES Algorithm ECB/CBC or AES Algorithm ECB/CBC/CTR/GCM or CCM.
        (##) The initialization vector (counter). It is not used in ECB mode.
        (##) The key buffer used for encryption/decryption.
        (##) The Header used only in AES GCM and CCM Algorithm for authentication.
        (##) The HeaderSize The size of header buffer in word.
        (##) The B0 block is the first authentication block used only  in AES CCM mode.

     (#)Three processing (encryption/decryption) functions are available:
        (##) Polling mode: encryption and decryption APIs are blocking functions
             i.e. they process the data and wait till the processing is finished,
             e.g. HAL_CRYP_Encrypt & HAL_CRYP_Decrypt
        (##) Interrupt mode: encryption and decryption APIs are not blocking functions
             i.e. they process the data under interrupt,
             e.g. HAL_CRYP_Encrypt_IT & HAL_CRYP_Decrypt_IT
        (##) DMA mode: encryption and decryption APIs are not blocking functions
             i.e. the data transfer is ensured by DMA,
             e.g. HAL_CRYP_Encrypt_DMA & HAL_CRYP_Decrypt_DMA

     (#)When the processing function is called at first time after HAL_CRYP_Init()
        the CRYP peripheral is configured and processes the buffer in input.
        At second call, no need to Initialize the CRYP, user have to get current configuration via
        HAL_CRYP_GetConfig() API, then only  HAL_CRYP_SetConfig() is requested to set
        new parametres, finally user can  start encryption/decryption.

      (#)Call HAL_CRYP_DeInit() to deinitialize the CRYP peripheral.

      (#)To process a single message with consecutive calls to HAL_CRYP_Encrypt() or HAL_CRYP_Decrypt()
         without having to configure again the Key or the Initialization Vector between each API call,
         the field KeyIVConfigSkip of the initialization structure must be set to CRYP_KEYIVCONFIG_ONCE.
         Same is true for consecutive calls of HAL_CRYP_Encrypt_IT(), HAL_CRYP_Decrypt_IT(), HAL_CRYP_Encrypt_DMA()
         or HAL_CRYP_Decrypt_DMA().

   [..]
     The cryptographic processor supports following standards:
     (#) The data encryption standard (DES) and Triple-DES (TDES) supported only by CRYP1 IP:
        (##)64-bit data block processing
        (##) chaining modes supported :
            (+++)  Electronic Code Book(ECB)
            (+++)  Cipher Block Chaining (CBC)
        (##) keys length supported :64-bit, 128-bit and 192-bit.
     (#) The advanced encryption standard (AES) supported  by CRYP1:
        (##)128-bit data block processing
        (##) chaining modes supported :
            (+++)  Electronic Code Book(ECB)
            (+++)  Cipher Block Chaining (CBC)
            (+++)  Counter mode (CTR)
            (+++)  Galois/counter mode (GCM/GMAC)
            (+++)  Counter with Cipher Block Chaining-Message(CCM)
        (##) keys length Supported :
            (+++) for CRYP1 IP: 128-bit, 192-bit and 256-bit.

   [..]  This section describes the AES Galois/counter mode (GCM) supported by both CRYP1 IP:
     (#)  Algorithm supported :
        (##) Galois/counter mode (GCM)
        (##) Galois message authentication code (GMAC) :is exactly the same as
             GCM algorithm composed only by an header.
     (#)  Four phases are performed in GCM :
        (##) Init phase: IP prepares the GCM hash subkey (H) and do the IV processing
        (##) Header phase: IP processes the Additional Authenticated Data (AAD), with hash
         computation only.
        (##) Payload phase: IP processes the plaintext (P) with hash computation + keystream
         encryption + data XORing. It works in a similar way for ciphertext (C).
        (##) Final phase: IP generates the authenticated tag (T) using the last block of data.
         HAL_CRYPEx_AESGCM_GenerateAuthTAG API used in this phase to generate 4 words which correspond
         to the Tag. user should consider only part of this 4 words, if Tag length is less than 128 bits.
     (#)  structure of message construction in GCM is defined as below  :
        (##) 16 bytes Initial Counter Block (ICB)composed of IV and counter
        (##) The authenticated header A (also knows as Additional Authentication Data AAD)
         this part of the message is only authenticated, not encrypted.
        (##) The plaintext message P is both authenticated and encrypted as ciphertext.
         GCM standard specifies that ciphertext has same bit length as the plaintext.
        (##) The last block is composed of the length of A (on 64 bits) and the length of ciphertext
         (on 64 bits)

   [..]  This section describe The AES Counter with Cipher Block Chaining-Message
         Authentication Code (CCM) supported by both CRYP1 IP:
     (#)  Specific parameters for CCM  :

        (##) B0 block  : According to NIST Special Publication 800-38C,
           The first block B0 is formatted as follows, where l(m) is encoded in
           most-significant-byte first order(see below table 3)

             (+++)  Q: a bit string representation of the octet length of P (plaintext)
             (+++)  q The octet length of the binary representation of the octet length of the payload
             (+++)  A nonce (N), n The octet length of the where n+q=15.
             (+++)  Flags: most significant octet containing four flags for control information,
             (+++)  t The octet length of the MAC.
        (##) B1 block (header) : associated data length(a) concatenated with Associated Data (A)
             the associated data length expressed in bytes (a) defined as below:
           (+++)  If 0 < a < 216-28, then it is encoded as [a]16, i.e. two octets
           (+++)  If 216-28 < a < 232, then it is encoded as 0xff || 0xfe || [a]32, i.e. six octets
           (+++)  If 232 < a < 264, then it is encoded as 0xff || 0xff || [a]64, i.e. ten octets
        (##) CTRx block  : control blocks
           (+++) Generation of CTR1 from first block B0 information :
             equal to B0 with first 5 bits zeroed and most significant bits storing octet
             length of P also zeroed, then incremented by one ( see below Table 4)
           (+++) Generation of CTR0: same as CTR1 with bit[0] set to zero.

     (#)  Four phases are performed in CCM for CRYP1 IP:
        (##) Init phase: IP prepares the GCM hash subkey (H) and do the IV processing
        (##) Header phase: IP processes the Additional Authenticated Data (AAD), with hash
         computation only.
        (##) Payload phase: IP processes the plaintext (P) with hash computation + keystream
         encryption + data XORing. It works in a similar way for ciphertext (C).
        (##) Final phase: IP generates the authenticated tag (T) using the last block of data.
        HAL_CRYPEx_AESCCM_GenerateAuthTAG API used in this phase to generate 4 words which correspond to the Tag.
        user should consider only part of this 4 words, if Tag length is less than 128 bits

 *** Callback registration ***
 =============================

 [..]
 The compilation define  USE_HAL_CRYP_REGISTER_CALLBACKS when set to 1
 allows the user to configure dynamically the driver callbacks.
 Use Functions @ref HAL_CRYP_RegisterCallback() or HAL_CRYP_RegisterXXXCallback()
 to register an interrupt callback.

 [..]
 Function @ref HAL_CRYP_RegisterCallback() allows to register following callbacks:
   (+) InCpltCallback     :  Input FIFO transfer completed callback.
   (+) OutCpltCallback    : Output FIFO transfer completed callback.
   (+) ErrorCallback      : callback for error detection.
   (+) MspInitCallback    : CRYP MspInit.
   (+) MspDeInitCallback  : CRYP 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_CRYP_UnRegisterCallback() to reset a callback to the default
 weak function.
 @ref HAL_CRYP_UnRegisterCallback() takes as parameters the HAL peripheral handle,
 and the Callback ID.
 This function allows to reset following callbacks:
   (+) InCpltCallback     :  Input FIFO transfer completed callback.
   (+) OutCpltCallback    : Output FIFO transfer completed callback.
   (+) ErrorCallback      : callback for error detection.
   (+) MspInitCallback    : CRYP MspInit.
   (+) MspDeInitCallback  : CRYP MspDeInit.

 [..]
 By default, after the @ref HAL_CRYP_Init() and when the state is HAL_CRYP_STATE_RESET
 all callbacks are set to the corresponding weak functions :
 examples @ref HAL_CRYP_InCpltCallback() , @ref HAL_CRYP_OutCpltCallback().
 Exception done for MspInit and MspDeInit functions that are
 reset to the legacy weak function in the @ref HAL_CRYP_Init()/ @ref HAL_CRYP_DeInit() only when
 these callbacks are null (not registered beforehand).
 if not, MspInit or MspDeInit are not null, the @ref HAL_CRYP_Init() / @ref HAL_CRYP_DeInit()
 keep and use the user MspInit/MspDeInit functions (registered beforehand)

 [..]
 Callbacks can be registered/unregistered in HAL_CRYP_STATE_READY state only.
 Exception done MspInit/MspDeInit callbacks that can be registered/unregistered
 in HAL_CRYP_STATE_READY or HAL_CRYP_STATE_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_CRYP_RegisterCallback() before calling @ref HAL_CRYP_DeInit()
 or @ref HAL_CRYP_Init() function.

 [..]
 When The compilation define USE_HAL_CRYP_REGISTER_CALLBACKS is set to 0 or
 not defined, the callback registration feature is not available and all callbacks
 are set to the corresponding weak functions.

Table 1. Initial Counter Block (ICB) +----------------------------------------------------—+ | Initialization vector (IV) | Counter | |-------------—|-------------—|--------—|------—| 127 95 63 31 0

         Bit Number    Register           Contents
         ----------   ---------------       -----------
         127 ...96    CRYP_IV1R[31:0]     ICB[127:96]
         95  ...64    CRYP_IV1L[31:0]     B0[95:64]
         63 ... 32    CRYP_IV0R[31:0]     ICB[63:32]
         31 ... 0     CRYP_IV0L[31:0]     ICB[31:0], where 32-bit counter= 0x2

Table 2. GCM last block definition

    +-------------------------------------------------------------------+
    |  Bit[0]   |  Bit[32]           |  Bit[64]  | Bit[96]              |
    |-----------|--------------------|-----------|----------------------|
    |   0x0     | Header length[31:0]|     0x0   | Payload length[31:0] |
    |-----------|--------------------|-----------|----------------------|

Table 3. B0 block Octet Number Contents


0 Flags 1 ... 15-q Nonce N 16-q ... 15 Q

the Flags field is formatted as follows:

Bit Number   Contents
----------   ----------------------
7            Reserved (always zero)
6            Adata
5 ... 3      (t-2)/2
2 ... 0      [q-1]3

Table 4. CTRx block Bit Number Register Contents


127 ...96 CRYP_IV1R[31:0] B0[127:96], where Q length bits are set to 0, except for bit 0 that is set to 1 95 ...64 CRYP_IV1L[31:0] B0[95:64] 63 ... 32 CRYP_IV0R[31:0] B0[63:32] 31 ... 0 CRYP_IV0L[31:0] B0[31:0], where flag bits set to 0