|
STM32H735xx HAL User Manual
|
CRYP HAL module driver. This file provides firmware functions to manage the following functionalities of the Cryptography (CRYP) peripheral: + Initialization and de-initialization functions + AES processing functions + DES processing functions + TDES processing functions + DMA callback functions + CRYP IRQ handler management + Peripheral State functions. More...
#include "stm32h7xx_hal.h"Go to the source code of this file.
Defines | |
| #define | CRYP_TIMEOUT_KEYPREPARATION 82U /*The latency of key preparation operation is 82 clock cycles.*/ |
| #define | CRYP_TIMEOUT_GCMCCMINITPHASE 299U /* The latency of GCM/CCM init phase to prepare hash subkey is 299 clock cycles.*/ |
| #define | CRYP_TIMEOUT_GCMCCMHEADERPHASE 290U /* The latency of GCM/CCM header phase is 290 clock cycles.*/ |
| #define | CRYP_PHASE_READY 0x00000001U |
| #define | CRYP_PHASE_PROCESS 0x00000002U |
| #define | CRYP_PHASE_INIT 0x00000000U |
| #define | CRYP_PHASE_HEADER CRYP_CR_GCM_CCMPH_0 |
| #define | CRYP_PHASE_PAYLOAD CRYP_CR_GCM_CCMPH_1 |
| #define | CRYP_PHASE_FINAL CRYP_CR_GCM_CCMPH |
| #define | CRYP_OPERATINGMODE_ENCRYPT 0x00000000U |
| #define | CRYP_OPERATINGMODE_DECRYPT CRYP_CR_ALGODIR |
| #define | CRYP_CCM_CTR1_0 0x07FFFFFFU |
| #define | CRYP_CCM_CTR1_1 0xFFFFFF00U |
| #define | CRYP_CCM_CTR1_2 0x00000001U |
| #define | CRYP_SET_PHASE(__HANDLE__, __PHASE__) |
| #define | HAL_CRYP_FIFO_FLUSH(__HANDLE__) ((__HANDLE__)->Instance->CR |= CRYP_CR_FFLUSH) |
Functions | |
| static void | CRYP_SetDMAConfig (CRYP_HandleTypeDef *hcryp, uint32_t inputaddr, uint16_t Size, uint32_t outputaddr) |
| Set the DMA configuration and start the DMA transfer. | |
| static void | CRYP_DMAInCplt (DMA_HandleTypeDef *hdma) |
| DMA CRYP input data process complete callback. | |
| static void | CRYP_DMAOutCplt (DMA_HandleTypeDef *hdma) |
| DMA CRYP output data process complete callback. | |
| static void | CRYP_DMAError (DMA_HandleTypeDef *hdma) |
| DMA CRYP communication error callback. | |
| static void | CRYP_SetKey (CRYP_HandleTypeDef *hcryp, uint32_t KeySize) |
| Writes Key in Key registers. | |
| static void | CRYP_AES_IT (CRYP_HandleTypeDef *hcryp) |
| Handle CRYP block input/output data handling under interruption. | |
| static HAL_StatusTypeDef | CRYP_GCMCCM_SetHeaderPhase (CRYP_HandleTypeDef *hcryp, uint32_t Timeout) |
| Sets the header phase in polling mode. | |
| static void | CRYP_GCMCCM_SetPayloadPhase_IT (CRYP_HandleTypeDef *hcryp) |
| Sets the payload phase in interrupt mode. | |
| static void | CRYP_GCMCCM_SetHeaderPhase_IT (CRYP_HandleTypeDef *hcryp) |
| Sets the header phase in interrupt mode. | |
| static HAL_StatusTypeDef | CRYP_GCMCCM_SetHeaderPhase_DMA (CRYP_HandleTypeDef *hcryp) |
| Sets the header phase when using DMA in process. | |
| static HAL_StatusTypeDef | CRYP_AESGCM_Process_DMA (CRYP_HandleTypeDef *hcryp) |
| Encryption/Decryption process in AES GCM mode and prepare the authentication TAG using DMA. | |
| static HAL_StatusTypeDef | CRYP_AESGCM_Process_IT (CRYP_HandleTypeDef *hcryp) |
| Encryption/Decryption process in AES GCM mode and prepare the authentication TAG in interrupt mode. | |
| static HAL_StatusTypeDef | CRYP_AESGCM_Process (CRYP_HandleTypeDef *hcryp, uint32_t Timeout) |
| Encryption/Decryption process in AES GCM mode and prepare the authentication TAG. | |
| static HAL_StatusTypeDef | CRYP_AESCCM_Process (CRYP_HandleTypeDef *hcryp, uint32_t Timeout) |
| AES CCM encryption/decryption processing in polling mode. | |
| static HAL_StatusTypeDef | CRYP_AESCCM_Process_IT (CRYP_HandleTypeDef *hcryp) |
| AES CCM encryption/decryption process in interrupt mode. | |
| static HAL_StatusTypeDef | CRYP_AESCCM_Process_DMA (CRYP_HandleTypeDef *hcryp) |
| AES CCM encryption/decryption process in DMA mode. | |
| static void | CRYP_AES_ProcessData (CRYP_HandleTypeDef *hcryp, uint32_t Timeout) |
| Process Data: Write Input data in polling mode and used in AES functions. | |
| static HAL_StatusTypeDef | CRYP_AES_Encrypt (CRYP_HandleTypeDef *hcryp, uint32_t Timeout) |
| Encryption in ECB/CBC & CTR Algorithm with AES Standard. | |
| static HAL_StatusTypeDef | CRYP_AES_Decrypt (CRYP_HandleTypeDef *hcryp, uint32_t Timeout) |
| Decryption in ECB/CBC & CTR mode with AES Standard. | |
| static HAL_StatusTypeDef | CRYP_AES_Decrypt_IT (CRYP_HandleTypeDef *hcryp) |
| Decryption in ECB/CBC & CTR mode with AES Standard using interrupt mode. | |
| static HAL_StatusTypeDef | CRYP_AES_Encrypt_IT (CRYP_HandleTypeDef *hcryp) |
| Encryption in ECB/CBC & CTR mode with AES Standard using interrupt mode. | |
| static HAL_StatusTypeDef | CRYP_AES_Decrypt_DMA (CRYP_HandleTypeDef *hcryp) |
| Decryption in ECB/CBC & CTR mode with AES Standard using DMA mode. | |
| static void | CRYP_TDES_IT (CRYP_HandleTypeDef *hcryp) |
| CRYP block input/output data handling under interruption with DES/TDES standard. | |
| static HAL_StatusTypeDef | CRYP_WaitOnIFEMFlag (const CRYP_HandleTypeDef *hcryp, uint32_t Timeout) |
| Handle CRYP hardware block Timeout when waiting for IFEM flag to be raised. | |
| static HAL_StatusTypeDef | CRYP_WaitOnBUSYFlag (const CRYP_HandleTypeDef *hcryp, uint32_t Timeout) |
| Handle CRYP hardware block Timeout when waiting for BUSY flag to be raised. | |
| static HAL_StatusTypeDef | CRYP_WaitOnOFNEFlag (const CRYP_HandleTypeDef *hcryp, uint32_t Timeout) |
| Handle CRYP hardware block Timeout when waiting for OFNE flag to be raised. | |
| static HAL_StatusTypeDef | CRYP_TDES_Process (CRYP_HandleTypeDef *hcryp, uint32_t Timeout) |
| Encryption in ECB/CBC Algorithm with DES/TDES standard. | |
| HAL_StatusTypeDef | HAL_CRYP_Init (CRYP_HandleTypeDef *hcryp) |
| Initializes the CRYP according to the specified parameters in the CRYP_ConfigTypeDef and creates the associated handle. | |
| HAL_StatusTypeDef | HAL_CRYP_DeInit (CRYP_HandleTypeDef *hcryp) |
| De-Initializes the CRYP peripheral. | |
| HAL_StatusTypeDef | HAL_CRYP_SetConfig (CRYP_HandleTypeDef *hcryp, CRYP_ConfigTypeDef *pConf) |
| Configure the CRYP according to the specified parameters in the CRYP_ConfigTypeDef. | |
| HAL_StatusTypeDef | HAL_CRYP_GetConfig (CRYP_HandleTypeDef *hcryp, CRYP_ConfigTypeDef *pConf) |
| Get CRYP Configuration parameters in associated handle. | |
| __weak void | HAL_CRYP_MspInit (CRYP_HandleTypeDef *hcryp) |
| Initializes the CRYP MSP. | |
| __weak void | HAL_CRYP_MspDeInit (CRYP_HandleTypeDef *hcryp) |
| DeInitializes CRYP MSP. | |
| HAL_StatusTypeDef | HAL_CRYP_RegisterCallback (CRYP_HandleTypeDef *hcryp, HAL_CRYP_CallbackIDTypeDef CallbackID, pCRYP_CallbackTypeDef pCallback) |
| Register a User CRYP Callback To be used instead of the weak predefined callback. | |
| HAL_StatusTypeDef | HAL_CRYP_UnRegisterCallback (CRYP_HandleTypeDef *hcryp, HAL_CRYP_CallbackIDTypeDef CallbackID) |
| Unregister an CRYP Callback CRYP callabck is redirected to the weak predefined callback. | |
| HAL_StatusTypeDef | HAL_CRYP_Encrypt (CRYP_HandleTypeDef *hcryp, uint32_t *Input, uint16_t Size, uint32_t *Output, uint32_t Timeout) |
| Encryption mode. | |
| HAL_StatusTypeDef | HAL_CRYP_Decrypt (CRYP_HandleTypeDef *hcryp, uint32_t *Input, uint16_t Size, uint32_t *Output, uint32_t Timeout) |
| Decryption mode. | |
| HAL_StatusTypeDef | HAL_CRYP_Encrypt_IT (CRYP_HandleTypeDef *hcryp, uint32_t *Input, uint16_t Size, uint32_t *Output) |
| Encryption in interrupt mode. | |
| HAL_StatusTypeDef | HAL_CRYP_Decrypt_IT (CRYP_HandleTypeDef *hcryp, uint32_t *Input, uint16_t Size, uint32_t *Output) |
| Decryption in itnterrupt mode. | |
| HAL_StatusTypeDef | HAL_CRYP_Encrypt_DMA (CRYP_HandleTypeDef *hcryp, uint32_t *Input, uint16_t Size, uint32_t *Output) |
| Encryption in DMA mode. | |
| HAL_StatusTypeDef | HAL_CRYP_Decrypt_DMA (CRYP_HandleTypeDef *hcryp, uint32_t *Input, uint16_t Size, uint32_t *Output) |
| Decryption in DMA mode. | |
| void | HAL_CRYP_IRQHandler (CRYP_HandleTypeDef *hcryp) |
| This function handles cryptographic interrupt request. | |
| uint32_t | HAL_CRYP_GetError (CRYP_HandleTypeDef *hcryp) |
| Return the CRYP error code. | |
| HAL_CRYP_STATETypeDef | HAL_CRYP_GetState (CRYP_HandleTypeDef *hcryp) |
| Returns the CRYP state. | |
| __weak void | HAL_CRYP_InCpltCallback (CRYP_HandleTypeDef *hcryp) |
| Input FIFO transfer completed callback. | |
| __weak void | HAL_CRYP_OutCpltCallback (CRYP_HandleTypeDef *hcryp) |
| Output FIFO transfer completed callback. | |
| __weak void | HAL_CRYP_ErrorCallback (CRYP_HandleTypeDef *hcryp) |
| CRYP error callback. | |
CRYP HAL module driver. This file provides firmware functions to manage the following functionalities of the Cryptography (CRYP) peripheral: + Initialization and de-initialization functions + AES processing functions + DES processing functions + TDES processing functions + DMA callback functions + CRYP IRQ handler management + Peripheral State functions.
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: 1-bit, 8-bit, 16-bit or 32-bit.
(##) 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
Definition in file stm32h7xx_hal_cryp.c.
1.7.6.1