|
Coming soon |
Please understand this is draft, thank you
1. SafeLink Module Presentation
The Safe link module allows for the secure communication between a Host and the STM32WW4, at the level of the SDIO interface. In particular, the Safe link module allows the Host to ensure it is communicating with a real STM32WW4 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 interface. Finally, the Safe link offers a mechanism that update the session key periodically.
To ensure the security of the communication channel between a Host and the STM32WW4, the following conditions must be respected:
- The SDIO/SPI link must allow authentication and confidentiality of messages
- Prevention against passive eavesdropping and/or active tampering (injection of fault) on the link
- Forward secrecy
- The Host must be connected to authentic Typhon from ST
- 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:
- Asymmetric Key agreement based on ECDH-key agreement P-384 ECC or P-256 ECC.
- Symmetric Key agreement base on challenge method and CMAC key agreement AES-256.
- AES-GCM packet encryption.
- Support of ephemeral keys pair, on STM32WW4 and on Host.
- The Host checks Typhon Certificate signature built by ST authority, based on ECDSA.
- The STM32WW4 private key is stored in its OTP Upper storage, tamper protected and decrypted by a ROM secret at EWS provisioning.
- The STM32WW4 Safe link code is protected against side channel attacks.
2. Safe Link Module implementation
The Safe link establishment, 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, on the fly is done by the CRYP module, integrated between the COM layer and the RPC layer.
The CRYP module handles RPC messages, encrypt them if necessary, and add 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.
To meet these conditions, the CRYP module adds padding
The Secure Header contains following information :
- cmdID (2 bytes) : RPC ID of the message
- Length (2 bytes) : length of the payload of the Secure Header
- NumID (4 bytes) : counter of transmitted messages (used by the COM layer) between the Host and the STM32WW4
- Tag (16 bytes) : the tag of the transmitted message
To maximize performances, the STM32WW4CRYP module uses DMA, to either copy or encrypt/decrypt data between an 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:
Upon receiving a message from the other device, the CRYP module takes care of removing the padding and retreive the original size of the message, before it is sent to the upper module (RPC layer).
The typical communication, for a blocking RPC command, between a Host and the STM32WW4 follows this scheme :
- On Host 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.
- Once the message is ready, the CRYP sends the message to the COM layer.
- On WW4 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).
- Once ready, the CRYP sends the message to the RPC layer.
- The WW4 sends its response following the same process.
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.
3. Safe Link establishment
[to do : explain the process (RPC commands involved)]
4. Safe Link user configuration
A couple of parameters, related to Safe link, 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 configuration of the STM32WW4 OTP word 25:
- Safe link establishment
- Symmetric or Asymmetric key exchange
It is important to note that if the Safe link is enabled in the STM32WW4 OTP word n°25, it is mandatory for the Host to start the Safe link establishment. After its initialization, the Typhon will not accept from the Host any other RPC command than eRPC_SL_CERT.
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 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:
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.
4.3. Choice of Hardware or Software cryptographic processing
Depending of its Host target, the user must choose between Hardware or Software processing layer for the Safelink 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.3.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.3.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.4. Bypassing the CRYP module (Host side)
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 CRYP module can't be remove from the WW4 FW.
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.4.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.4.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.
5. Safe Link performances analysis
[to do : show the impact of safelink of performances]