|
Coming soon |
Please understand this is draft, thank you
1. Safe link Module Presentation
The Safe link module allows for the secure communication between a Host and the STM32WW4, at the level of 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 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:
- 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:
- Asymmetric Key agreement based on ECDH-key agreement P-384 ECC or P-256 ECC.
- Symmetric Key agreement based on challenge method and CMAC key agreement AES-256.
- AES-GCM packet encryption and authentication.
- Support of ephemeral keys pairs, both on STM32WW4 and on Host.
- The Host verifies Typhon's Certificate signature, built by ST authority, using 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.
- Secure key storage API, using derived hardware unique key (DHUK 256-bit).
2. 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 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. 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 (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 between the Host and the STM32WW4 (used by COM layer)
- Tag (16 bytes) : 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 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.
- 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 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).
- In case of encrypted message, the CRYP verifies the tag sent by the Host matches the tag he has just calculated.
- 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 (see section 4.5. Turning OFF the CRYP module).
The encryption and decryption processes can be done by Hardware peripherals, if they are 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).
3. Safe link Establishment
Once the STM32WW4 has finished its initialization, it sends the RPC command 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, then the Host must start the Safe link establishment just after it has received the eRPC_EVT_DEVICE_INIT_DONE command. The STM32WW4 decides the session key establishment method:
3.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 validity of the certificate using ECDSA, then retrieve the STM32WW4 public key.
The Host has verified the authenticity of the STM32WW4 with which he is communicating. He now sends 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.
3.2. Symmetric Safe link establishment
The Host sends a eRPC_SL_CERT command, along with its randomly-generated 16 bytes challenge. Upon receiving this command, the STM32WW4 generates its 16-bytes challenge. Using the Host challenge, its own challenge, the symmetric 256-bit key stored securely in its OTP, he 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.
3.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.
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 default configuration of the STM32WW4:
- Safe link establishment
- 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 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.
Example with SL_EPHEM_ON selected:
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.
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:
- Increase (for better performances) or decrease (for better security) the value of CRYPT_KEY_ROT_TRIGGER_BYTES, lcoated 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
[to do : show the impact of safelink of performances]