 |
RTEMS 6.1-rc2
|
Loading...
Searching...
No Matches
|
RTEMS 6.1-rc2
|
CRYP HAL module driver. This file provides firmware functions to manage the following functionalities of the Cryptography (CRYP) peripheral: More...
#include "stm32h7xx_hal.h"CRYP HAL module driver. This file provides firmware functions to manage the following functionalities of the Cryptography (CRYP) peripheral:
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
1.9.6