1. Introduction
1.1. OEMiROT
OEMiROT is the bootloader developed by STMicroelectronics.
This bootloader is embedded in several products, including the STM32WBA6, and is based on the MCUboot open-source library. MCUboot is a reference implementation of a secure bootloader infrastructure on MCUs, already used in various implementations, such as Zephyr, TF-M, and Mynewt.
One of the main features of a secure bootloader is the secure firmware upgrade. A basic example, included with every STM32Cube package, demonstrates how to download new firmware or data using the YModem protocol over UART transport.
Since the STM32WBA6 includes Bluetoothc Low Energy (BLE) protocol, an example has been created to show how to perform a secure update of new firmware or data over the air (SFOTA) on this device using BLE.
This example can be found here: https://github.com/stm32-hotspot/STM32WBA-OEMiROT-FOTA.
This Wiki page is dedicated to explaining how the example works.
1.2. Prerequisite
This page introduces the Secure Firmware Update Over The Air (SFOTA):
- SFOTA relies on the OEMiROT secure bootloader, a common secure bootloader used across various STMicroelectronics parts. It is then important to understand its functionality. The following article details how to utilize the OEMiROT on the STM32WBA, and it must be reviewed before proceeding with the SFOTA project: Security:OEMiRoT OEMuRoT for STM32WBA - stm32mcu
- OEMiROT uses the TrustZone® framework. Even if the secure part of the TrustZone is not of interest for your matter (no code/data in the secure part), TrustZone must be activated to support the OEMiROT. Here you will find resources on how to create a simple BLE project on STM32WBA5 with the TrustZone activated: STM32WBA Bluetooth® LE & TrustZone - stm32mcu
2. Using OEMiROT for Secure FOTA
2.1. Images and slots
As for every MCUBoot based bootloader, the OEMiROT uses the notion of slot and image for its internal processing.
- Image: An “image” in MCUboot, refers to a complete binary that can be loaded or executed by the microcontroller. This image can include application code or application data.
- Slot: A “slot” in MCUboot is a unit that can contain an image (download slot or install slot)
In our example, two slots per image are used:
- A download slot where a new image is downloaded and where mcuboot checks for updates
- An install slot where images are installed and executed.
The full explanation of the update strategy can be found here : Security:OEMiRoT OEMuRoT for STM32WBA#OEMiRoT-2FOEMuRoT activation
2.2. SMP and MCUMGR
2.2.1. Introduction
As most of the security-related firmware manipulation (decryption, signature verification, rollback mechanism) is handled by the Secure bootloader (OEMiROT), the goal of the BLE application to make a secure firmware update is to manipulate and put the firmware to the correct download slot.
As OEMiROT, several projects are based on MCUboot. Unifying the transport layer for all ecosystems is the main goal of this project.
Zephyr ecosystem already proposes a standardized exchange layer for firmware upgrade, called MCUmgr.
As STMicroeletrconics is also present in the Zephyr ecosystem, the goal of this STM32Cube project is to unify the MCUmgr protocol between Zephyr and STM32Cube Ecosystem.
2.2.1.1. Protocol description
An open-source protocol called MCUmgr allowing to remotely manage MCU is currently embedded into the Zephyr environment.
A part of this protocol allows to manipulate the different images and slots of a remote device, to perform firmware update.
MCUmgr protocol is used on top of the SMP (Simple Managment Protocol). This protocol (which is not the same as the Bluetooth SMP layer) allows to encapsulate MCUmgr protocol to be exchanged on BLE or UART transport.
The full description of the two protocols can be found here
2.3. STM32WBA-OEMiROT-FOTA example project
The OEMiROT FOTA project replaces the default OEMiROT project. It is located in the folder: Firmware\Projects\STM32WBA65I-DK1\Applications\ROT
The SFOTA project only supports the OEMiROT bootloader configuration and the TrustZone isolated project (Secure and NonSecure projects).
It is composed of two different subprojects:
- OEMiROT_Boot
OEMiROT bootloader project, responsible of handling the secure boot and secure update mechanism.
- OEMiROT_Appli_TrustZone
This is the user application, which will be booted. This application contains the BLE application and the SMP and MCUmgr layer to update the different images using the BLE protocol.
- Data images
Data images are located in the folderFirmware\Projects\STM32WBA65I-DK1\ROT_Provisioning\OEMiROT\Binary:
- ns_data.bin: nonsecure data
- s_data.bin: secure data
The encrypted and signed versions are created when the provisioning script is launched.
By default, in our example, there are three updatable applicative images:
- A secure code image for the secure code project. This image configures the global security attribution and boots the nonsecure image. This is the Secure project of the OEMiROT_Appli_TrustZone
- A nonsecure image for the nonsecure code. This image runs the main application with the BLE and firmware upgrade facilities. This is the NonSecure project of the OEMiROT_Appli_TrustZone
- A NonSecure data image, displayed at the beginning of the boot of the NonSecure image. The only purpose of this image is to demonstrate the update of a data image. The first byte of the image is its revision version. This is the ns_data.bin binary
All these images use a dual slot configuration with overwriting mechanisms (the new images to download are pushed to secondary slot).
Upon reboot, mcuboot installs the secondary slot to the primary slot by overwriting it.
2.3.1. Setup and compilation
The full information on how to setup your environment is described in Security:OEMiRoT OEMuRoT for STM32WBA#Provisioning process.
2.3.1.1. Environment setup
The scripts allowing to customize the projects to your environment are env.sh and env.bat in the folder Projects/STM32WBA65I-DK1/ROT_Provisioning/.
If your environment is not the default one (that is, you use several versions of STtools, or you have not installed it to the standard path), you must edit these files to match your desired environment.
2.3.1.2. Bootloader configuration setup
The bootloader overall behavior is done in the OEMiROT_Boot project:
- Security behavior: RDP level, MPU, HDP, WRP configuration, ...
- Memory layout behavior: use of external flash memory, number of slots, number of images, ...
At the end of the compilation of the OEMiROT_Boot project, post-build scripts are executed to reflect this behavior to the OEMiROT_Appli_TrustZone project.
To keep a consistent environment, every modification of the OEMiROT_Boot project must be followed by a full recompilation of the different projects.
2.3.1.2.1. Security setup
The bootloader uses of STM32WBA6 security features. It can be enable/disabled in the following file:
Projects/STM32WBA65I-DK1/Applications/ROT/OEMiROT_Boot/Inc/boot_hal_cfg.h.
The following options can be modified:
- Icache
- WRP protection
- HDP protection
- SRAM2 erase at reset
- Tampering
- Option byte locking
- MPU
- RDP
2.3.1.2.2. Memory layout setup
The overall bootloader and application configuration can be made with the file
Projects/STM32WBA65I-DK1/Applications/ROT/OEMiROT_Boot/Inc/flash_layout.h
In this file several options can be chosen:
- Overwrite-only configuration
- Use of an external flash memory
- Number of applicative images
- Number of secure and nonsecure data slots
- Size of the different slots
2.3.1.3. Compilation
Once the previously mentioned options have been chosen, the compilation of the different project can be done
1. Compile the OEMiROT_Boot project.
This step must be done first, because post-build script of the OEMiROT_Boot project populates the rest of the script and project with the right values corresponding to the chosen configuration
2. Compile the OEMiROT_Appli_TrustZone project
2.3.1.4. Image signature and encryption
The encryption and signature is done automatically by post-build script. This script is launched after the OEMiROT_Appli_TrustZone compilation is done.
The resulting files are present in the OEMiROT_Appli_TrustZone/Binary folder with _enc and/or _sign suffixes, depending upon the OEMiROT security options
2.3.2. Flash
The flashing is done with several scripts in the folder Projects/STM32WBA65I-DK1/ROT_Provisioning/OEMiROT. If you have compiled with STM32CubeIDE, use the .sh file extension, if the projects have been compiled with IAR or Keil, use the .bat extension.
- img_config.{bat, sh}: holds the current project configuration, not to be executed
- ob_flash_programming.{bat, sh} : allows to flash boot, applicative project, along the right option bytes.
- provisioning.{bat, sh}: allows to set-up the board to be ready for an OEMiROT project
- regression.{bat, sh} : allows to set-up the board to be programmed with new files
During the development process, to flash new firmware, the script regression.{bat, sh} must be launched to configure the board to accept a new firmware.
When flashing the project, the provisioning.{bat, sh} must be launched.
2.3.3. Step by step illustration
The following steps are illustrated with STM32CubeIDE compiler and .sh scripts, but they can be performed with IAR or Keil compiler and using .bat scripts.
2.3.3.1. Step 1 - Customize your environment
If your STM32CubeProgrammer path is the default one, this step is not needed.
Customize your environment, open the env.bat and/or the env.sh files, and modify, if needed, the path to your tools binary.
2.3.3.2. Step 2 - Import projects on STM32CubeIDE
Open STM32CubeIDE and import the three projects
2.3.3.3. Step 4 - Build the projects
As explained previously, in the different project, OEMiROT_Boot must be built first, as it configurates the other projects.
In each TrustZone project (OEMiROT_Appli_TrustZone), the secure project must be built first. By default, there is a dependency between nonsecure and secure projects. Building a nonsecure project launches a secure project build first.
2.3.4. Step 5 - Modify the data slot
If the data slots are activated in your project, you can modify them in the following folder: Projects/STM32WBA65I-DK1/ROT_Provisioning/OEMiROT/Binary.
2.3.5. Step 6 - Flash the board
This is the final step, it allows you to:
- Encrypt and sign the data slot
- Flash the mcuboot "root key"
- Flash the different projets
As explained previously, the first step is to execute the regression script to prepare the board to be flashed. The second step is to execute the provisioning script.
- Launch the ./regression.sh script (.bat if using IAR or Keil), and follow the instructions
- Launch the ./provisionning.sh script (.bat if using IAR or Keil), and follow the instructions
2.4. Client
There are several clients implementing the SMP and MCUmgr protocol over the Bluetooth LE:
- STM32WebBluetooth Application : Web bluetooth App WBA
- AuTerm
- mcumgr-cli
These tools can be used to update the Cube and Zephyr applications.
2.4.1. Secure FOTA
This section describes how to perform a Secure FOTA using the STM32WebBluetooth Application. These steps are similar for every client.
Connect using BLE to the target
| Target connection |
|---|
Once connected, you can open the SMP protocol panel.
| SMP protocol panel |
|---|
Once connected, you can retrieve the list of all images and the corresponding slot on the target
All the slots are selectable by clicking on them before performing an operation (erase, test, confirm, upload)
| Image list |
|---|
The number of images and slots depends upon your overall configuration.
On a Zephyr application, empty secondaries slots are not displayed. On a STM32Cube application, empty secondaries slots are displayed with default values (hexadecimal 0xFF).
A prerequisite to download to the secondary slot is to have it erased. If the secondary slot is not erased, you can do so by clicking the "erase" button.
You can then select the targeted image to download to and the file to upload.
| Upload new image |
|---|
Once the image has been uploaded, you can see that the secondary slot is no longer empty.
| Secondary slot |
|---|
To install this image at the next boot, it must be flagged as a "test" image. To perform this action, select the corresponding hash to flag, and click the "test" button.
| Test slot |
|---|
You can now reset the board, by physically pushing the reset button or using the "Reset" button on the graphical interface. Once rebooted, you can reconnect, and see that the two slots have been swapped.
If you are not in MCUBOOT_OVERRIDE mode
For safety reason, if the new image is not confirmed, the old image is swapped back at the next boot. To confirm the installation, you must select the right hash and confirm it by pressing the "Confirm" button
| Confirm slot |
|---|
