|
Coming soon |
[WIP]
1. Safe link Module Presentation
The Safe link module allows for the secure communication between a Host and the STM32WW4, over the SDIO/SPI interface. In particular, the Safe link module allows the Host to ensure it is communicating with a STM32WW4 chip provisioned by ST, to compute a common session key between the two devices and to perform encryption, decryption and authentication of the data exchanged on the SDIO/SPI interface. Finally, the Safe link offers a mechanism that updates the session key periodically.
To ensure the security of the communication channel between a Host and the STM32WW, the following conditions must be respected:
- Authentication and confidentiality of messages transmitted on the SDIO/SPI interface.
- Prevention against passive eavesdropping and/or active tampering (injection of fault) on the link.
- Forward secrecy.
- Authentication of the connected STM32WW4 by the Host.
- Secure storage of key agreement private key.
- SCA and fault protection of key agreement private key.
- Safe link Security strength up to 192-bit for WPA3-Enterprise-192.
Following methods have been retained to meet these requirements:
- Key agreement based on:
- ECDH-KA over P384 or P256 ECC curves, with support of ephemeral keys.
- AES-CMAC-256 using challenges from both Host and STM32WW4.
- AES-256 packet encryption and authentication.
- The Host verifies STM32WW4's Certificate signature, built by ST authority, using ECDSA.
- The STM32WW4 Safe link code is protected against side channel attacks.
- Secure key storage API, using derived hardware unique key (DHUK 256-bit).
2. Safe link Establishment
From the STM32WW4 start-up procedure, upon initialization completion, it returns the event eRPC_EVT_DEVICE_INIT_DONE to the Host, along with its default configuration. This one specifies if the Safe link is enabled or disabled, and which method to use for the establishment (asymmetric or symmetric).
If the Safe link is enabled in the STM32WW4 OTP, then the Host must start the Safe link establishment just after it has received the eRPC_EVT_DEVICE_INIT_DONE command. The establishment method is selected statically by OTP:
2.1. Asymmetric Safe link establishment
The Host sends a eRPC_SL_CERT command, along with the ECC parameters to use (P-256 or P-384 ECC) for the key exchange. The STM32WW4 answers to this command by sending its certificate and associated signature. The certificate contains the STM32WW4 public key, derived from its private key. Both the STM32WW4 private key and certificate's signature are stored securely in its OTPs. The Host verifies the signature of the certificate using ECDSA, then retrieves the STM32WW4 public key.
The Host continues the Safe link establishment procedure by sending a eRPC_SL_EPUBK command, along with its public key and its ephemeral public key (if enabled). The STM32WW4 verifies the authenticity of these keys. Then, it uses the static keys (STM32WW4 private key / Host public key) and the ephemeral keys (STM32WW4 ephemeral private key / Host ephemeral public key) to compute the session key. It acknowledges back to the Host and send it its ephemeral public key. The Host computes the session key using the static keys (Host private key / STM32WW4 public key) and the ephemeral keys (Host private ephemeral key / STM32WW4 public ephemeral key). The 256-bit session key is now computed on both devices, and ready to be used by the CRYP module.
2.2. Symmetric Safe link establishment
The Host sends a eRPC_SL_CERT command, along with its randomly-generated 4-bytes challenge. Upon receiving this command, the STM32WW4 generates its 4-bytes challenge. Using the Host challenge, its own challenge, the symmetric 256-bit key stored securely in its OTP, it computes the session key using CMAC method. The STM32WW4 answers to the Host by sending back its own challenge. The Host can compute the session key using both challenges, and the symmetric key. The 256-bit session key is now computed on both devices, and ready to be used by the CRYP module.
2.3. Setting the new Secure Map table
Both the Host and the STM32WW4 now share a session key. The Host can send a eRPC_SL_SET_MAP command, along with the Secure Map table to use (defined in safelink_conf.h). This Secure Map table defines for every RPC command the security level to use (message transmitted in clear or encrypted). When the Safe link is disabled in the STM32WW4, its default Secure Map table is set to clear mode for every RPC command. When the Safe link is enabled, its default Secure Map table is set to encryption/decryption for every RPC command. With the eRPC_SL_SET_MAP command, the Host can update the default table to use the configuration defined by the user.
3. Safe link Module Implementation
The Safe link establishment, whose objective is to compute the session key, is done in a set of RPC commands that are specifically made for the Safe link. The encryption, decryption and authentication of data is done on-the-fly by the CRYP module, integrated between the COM layer and the RPC layer.
The CRYP module handles RPC messages, performs encryption or decryption (if required), and adds a secure header on top of the RPC header. This secure header is never encrypted, and allows the CRYP module of the other device to know the basic information about the message. In order to know what process to perform with a RPC message, the CRYP module checks the Secure Map table, using the ID of the message, to get the security mode associated with it.
The Secure Header, added on top of the RPC header, contains following information :
- cmdID (16 bits) : RPC ID of the message
- Length (16 bits) : length of the payload of the Secure Header
- NumID (32 bits) : counter of transmitted messages between the Host and the STM32WW4 (used by COM layer)
- Tag (128 bits) : the tag of the transmitted message
To maximize performances, the STM32WW4 CRYP module uses DMA, to either copy or encrypt/decrypt data between a SDIO buffer and a TX / CMD buffer. These DMA channels impose two requirements:
- The address of the Secure Header payload must be 32-bit aligned.
- The size of the Secure Header payload must be 32-bit aligned.
To meet these conditions, the CRYP module adds padding to respect the address alignment and the size alignment:
There are either two or 4 bytes of padding added between the Secure Header and the RPC Header. Upon receiving a message from the other device, the CRYP module takes care of removing the padding and retrieve the original size of the message, before it is sent to the upper module (RPC layer).
The typical communication between a transmitter and a receiver follows this scheme:
- On transmitter side, the RPC layer sends a message to the CRYP module.
- Using a secure table, the CRYP module checks if the message must be sent clear or authenticated/encrypted.
- If encryption is needed, the CRYP module writes inside the Secure Header the tag associated to the message.
- Once the message is ready, the CRYP sends the message to the COM layer.
- On receiver side, the COM layer receives the clear or encrypted message and send it to the CRYP.
- The CRYP check the secure table and performs copy (clear message) or decryption/authentication (encrypted message).
- In case of encrypted message, the CRYP verifies the tag sent by the transmitter matches the tag he has just calculated.
- Once ready, the CRYP sends the message to the RPC layer.
On the Host, a thread is dedicated to the CRYP module, to handle the encryption and decryption queues, to start the cryptographic processes, and send the messages to the COM or RPC layer. In the case where the user does not want to use the Safe link feature, the initialization and execution of this thread can be easily bypassed, to improve performances (see section 4.5. Turning OFF the CRYP module).
The encryption and decryption processes can be done by CRYP Hardware IP, if it is available on the Host target, or by using Software library (MbedTLS). User can implement its own implementation of the computations as long as they follow the specifications of the interface header files (see section 4.4 Choice of Hardware or Software cryptographic processing).
4. Safe link User Configuration
The list of parameters, related to Safe link, that are configurable using the Host project :
- For asymmetric key exchange, choice between P-256 ECC or P-384 ECC curve parameters.
- For asymmetric key exchange, enable (or disable) the use of ephemeral keys on Host side.
- The Secure Map table to send to the STM32WW4.
- Choice between Hardware or Software cryptographic processing.
- Enable (or disable) the CRYP module.
- Enable (or disable) the key rotation system.
Some parameters used in the context of the Safe link library are dependent of the configuration of the STM32WW4 connected to the Host. Following parameters are selected from the default configuration of the STM32WW4:
- Safe link enable
- Symmetric or Asymmetric key exchange
It is important to note that if the Safe link is enabled in the STM32WW4 default configuration, it is mandatory for the Host to start the Safe link establishment. If the Host does not send the eRPC_SL_CERT RPC command after the STM32WW4 has finished its initialization, while the Safe link is enabled, this one will go to blocking failure and reset.
4.1. Choice between P-256 ECC or P-384 ECC parameters
The choice between symmetric or asymmetric key exchange is dependent of the configuration of the STM32WW4. However, the user can decide to use P-256 ECC or P-384 ECC parameters, only relevant in the case of Safe link asymmetric establishment.
To do so, the user must use either "SL_P256" or "SL_P384" in the call to ww4_sl_establishment, in the safelink.c file (Middlewares/WLAN_Driver/rpc_if/safelink). Any other value will result in error.
Example with SL_P256 selected:
Updating this parameter will have no effect if the STM32WW4 is configured to use symmetric Safe link establishment.
4.2. Turning ON or OFF ephemeral keys
The choice between symmetric or asymmetric key exchange is dependent of the configuration of the STM32WW4. However, the user can decide to enable, or disable, the use of ephemeral keys on the Host (only relevant in the case of asymmetric establishment).
To do so, the user must use either "SL_EPHEM_ON" or "SL_EPHEM_OFF" in the call to ww4_sl_establishment, in the safelink.c file (Middlewares/WLAN_Driver/rpc_if/safelink). Any other value will result in error.
Example with SL_EPHEM_ON selected:
Updating this parameter will have no effect if the STM32WW4 is configured to use symmetric Safe link establishment.
4.3. Choice of the Secure Map table to use
The Secure Map table defines for every RPC command the associated security mode : clear or authenticated/encrypted. The user can decide to use one of the three pre-defined Secure Map tables, or implement its own. The three default Secure Map tables are :
- PLAIN_TEXT_TAB : every RPC command is sent, and received, in clear.
- FULL_AUTH_ENCRYPT_TAB : every RPC command is sent, and received, in authenticated/encrypted.
- FULL_AUTH_ENCRYPT_MINUS_TxRx_TAB : every RPC command is sent, and received, in authenticated/encrypted, but the command TX and RX (linked to the data path of wifi packets) that are sent, and received, in clear. This mode considers that the TX/RX content confidentiality decision is defined at application level (TLS), to avoid performances issue.
The PLAIN_TEXT_TAB Secure Map table will give the best performance, but the data on the SDIO/SPI interface are not encrypted. The FULL_AUTH_ENCRYPT_TAB Secure Map table will give the maximum security. The FULL_AUTH_ENCRYPT_MINUS_TxRx_TAB is a compromise between security and performances.
The user have to select the Secure Map table in the safelink_conf.h file, located in AppCommon\WLAN_DRIVER\Target folder.
Example of Secure Map table selection (PLAIN_TEXT_TAB ):
The user can choose to implement and use its own Secure Map table. To do so, he can take a look at the way the three default Secure Map tables are defined in safelink.h. It is important to note that following RPC commands must always be set to clear :
- eRPC_EVT_DEVICE_INIT_DONE
- eRPC_SL_CERT
- eRPC_SL_EPUBK
The reason is that to perform encryption and decryption of messages, the session key must have been established between the Host and the STM32WW4 : which is the case only after the eRPC_SL_EPUBK has been sent.
Example of the definition of FULL_AUTH_ENCRYPT_TAB in safelink.h :
For every RPC command, the user can select the security mode he wants to use, between:
- SL_CLEAR : command is sent, and received, in clear.
- SL_AUTH_ENC : command is sent, and received, in clear.
- SL_AUTH_ENC_TX_ONLY : command is sent encrypted, and received in clear.
- SL_AUTH_ENC_RX_ONLY : command is sent in clear, and received encrypted.
4.4. Choice of Hardware or Software cryptographic processing
Depending of its Host target, the user must choose between Hardware or Software processing layer for the Safe link establishment and the CRYP module. The Software cryptographic processing layer uses the MbedTLS library, which is compatible with every board. The Hardware cryptographic processing layer was designed based on the cryptographic peripherals available on the STM32U5A5, using the HAL library. The Hardware processing cryptographic layer will give the best performances, hence it is advised to use it on the STM32U5A5.
To port the Safe link on a new Host, the user can either choose to: - use the Software cryptographic processing layer, without worrying about compatibility. - adapt the Hardware cryptographic processing layer to take advantage of the peripherals available on its target.
The header files safelink_if.h and crypt_if.h provide the interface between the Safe link library and the target implementation. The APIs listed in "safelink_if.h" are used for the safelink establishment (symmetric / asymmetric key exchange), the secure storage of the keys and the computations for key rotation. The APIs listed in crypt_if.h are used by the CRYP module to perform GCM encryption and decryption.
To use the Software cryptographic processing layer, make sure the files crypt_mbedtls.c and safelink_mbedtls.c are included in the project. To use the Hardware cryptographic processing layer, make sure the files crypt_hal.c and safelink_hal.c are included in the project. It is not possible to include both xxx_hal.c and xxx_mbedtls.c files, as there would be duplicate function definition. The user can decide to create its own cryptographic processing layer, as long as its implementation provide every API listed in safelink_if.h and "crypt_if.h".
4.4.1. Using CubeIDE
The cryptographic layer files are located in Application/User/WLAN_Driver/Target folder. It's up to the user to decide which configuration to use, depending of its target. Default configuration is to use Software cryptographic processing layer.
4.4.2. Using IAR IDE
The cryptographic layer files are located in Application/User/WLAN_Driver/Target folder. It's up to the user to decide which configuration to use, depending of its target. Default configuration is to use Software cryptographic processing layer.
4.5. Turning OFF the CRYP module
It is up to the user to choose whether or not they want to include the CRYP module in the Host FW. This module is mandatory to perform encryption and decryption of data. However, if the user does not intend to use any of the security features, this module can be removed to have better performances. The STM32WW4 CRYP module can't be removed.
To enable the CRYP module, make sure the file rpc_safelink.c is included in the Host project. To bypass the CRYP, remove the rpc_safelink.c file from the project (or exclude it from the build).
4.5.1. Using CubeIDE
Make sure the "Project Explorer" panel is open, then right click on the file rpc_safelink.c (inside Middleswares/WLAN_Driver/source/rpc_if/safelink), select "properties", "C/C++ Build Settings", and enable (or disable) the box "Exclude ressource from build", to enable (or disable) the CRYP module. Then, rebuild the project.
4.5.2. Using IAR IDE
Make sure the "Workspace" panel is open, then right click on the file rpc_safelink.c (inside Middleswares/WLAN_Driver/source/rpc_if/safelink), select "Options...", and enable (or disable) the box "Exclude from build", to enable (or disable) the CRYP module. Then, rebuild the project.
4.6. Turning ON or OFF the key rotation mechanism
A key rotation mechanism of the session key is implemented, which will renew the session key after a certain amount of encrypted data has been exchanged between the Host and the STM32WW4. The default threshold is 240 Kbytes of data transmitted encrypted between both devices. Once this limit is exceeded, the Host will send a key rotation RPC command to the STM32WW4. This command will update the session key, and reset the counter of exchanged encrypted data. The key rotation RPC command is a blocking command, meaning that the WW4 will not be able to process any other command while the key rotation process is not finished.
The user can adjust the balance between security and performances in two ways:
- Decrease (for better security) the value of CRYPT_KEY_ROT_TRIGGER_BYTES, located in crypt.c, which defines the threshold before a key rotation command is sent by the Host.
- Turn off the key rotation system, by setting SL_SUPPORT_KEYROT_CONSTRAINT to 0 in the safelink_conf.h file.
5. Safe link Performances Analysis
The impact of the Safe link module has been analyzed on specific key points :
- Encryption and decryption processing latencies, for a single RPC message, on the STM32WW4.
- Encryption and decryption processing latencies, for a single RPC message, on a STM32U5A5 Host, using HW peripherals.
- Encryption and decryption processing latencies, for a single RPC message, on a STM32U575 Host, using SW peripherals.
- Latencies of a RPC echo command, sent encrypted to the STM32WW4, and received encrypted.
When the Safe link is enabled in the default configuration of the STM32WW4, it enables security features that increase the protection of the execution of the code against side-channel attacks. One of these features is the injection of temporal jittering in the CRYP module execution, which adds pseudo-random delays to prevent a temporal analysis of the processes running. The effect is this measure is that the performances of the CRYP module to process a message transmitted in clear will be better when the Safe link is disabled.
5.1. Encryption and decryption latencies on the STM32WW4
The performances, in number of CPU clock cycles, of the CRYP module have been reported for various processing, with a STM32WW4 running at 120MHz.
Processing latency for a clear message going through the CRYP module of the STM32WW4, without temporal jittering (Safe link disabled):
There are no Hardware processing involved when the CRYP module handles a clear message to send to the COM layer. Thus, the latency is the same for both payloads.
Processing latency for a clear message going through the CRYP module of the STM32WW4, with temporal jittering (Safe link enabled):
On average, the temporal jittering feature increases the CRYP processing by 50%. As this module can't be disabled on the STM32WW4, if the user does not intend to use the encryption / decryption of the SDIO/SPI interface provided by the Safe link, it is strongly advised to use a STM32WW4 with the Safe link disabled in its default configuration.
Processing latency for an encrypted message going through the CRYP module of the STM32WW4, with temporal jittering (Safe link enabled):
The STM32WW4 can perform encryption and decryption of data only when the Safe link is enabled in its default configuration. This means the temporal jittering is always enabled on the STM32WW4 when using the cryptographic features of the CRYP module.
5.2. Encryption and decryption latencies on the STM32U5A5
The Host Safe link library does not embed any security feature against side-channel attacks, thus there is no temporal jittering. The performances, in number of CPU clock cycles, of the CRYP module have been reported for various processing, with a STM32U5A5 running at 160MHz. The STM32U5A5 embeds an tiny AES IP module, which is slower than the STM32WW14's CRYP module.
Processing latency for a clear message going through the CRYP module of the STM32U5A5:
On Host side, the CRYP module does not perform any Hardware processing for a clear packet, whether transmitting or receiving. Thus, the CRYP processing latency is not dependent on the size of the payload.
Processing latency for an authenticated and crypted message going through the CRYP module of the STM32U5A5:
5.3. Throughput performances with Safe link
In this test, the Host sends a RPC echo command, and wait for the STM32WW4 response. The payloads vary from 100 bytes to 1600 bytes (maximum RPC payload size). The STM32U5A5 runs at 160 MHz (max frequency), uses an SDIO connection running at 50 MHz, and the STM32WW4 runs at 120 MHz (max frequency). In authenticated + encrypted mode, the Host encrypts the command, then the STM32WW4 decrypts it, process it at RPC level, encrypts it answers and the Host must decrypt the STM32WW4 response.
RPC Echo command throughputs, with clear mode and authenticated + encrypted mode (using HW AES IP):
RPC Echo command throughputs, with clear mode and authenticated + encrypted mode (using MbedTLS library):
It follows that the max throughput with RPC Echo commands, for a 1600 bytes payload, are :
* 22,7 Mbits/s in clear mode * 14,4 Mbits/s in authenticated and encrypted mode (using HW AES module) * 1,9 Mbits/s in authenticated and encrypted mode (using SW Mbedtls module)