There are three ways to develop an application that is compatible with a secure boot:
- Develop the application without taking into account the secure boot in a first step then integrate it to the secure boot path. This article explains how to do this.
- Develop your code directly in the ROT template projects (OEMiROT_Appli_TrustZone or OEMiROT_Appli). These projects have already been adapted to the secure bootpath.
- Update existing ROT applications projects (OEMiROT_Appli_TrustZone or OEMiROT_Appli). These projects have already been adapted to the secure bootpath.
With STM32WBA, several kinds of secure bootpath can be selected. This article is applicable to:
- One boot stage: OEMiRoT
- Two boot stages: OEMiRoT + OEMuRoT
This article uses an STM32WBA65I-DK1 board, but it applies to other STM32WBA boards.
1. One boot stage: OEMiRoT
To use OEMiRoT to secure an application that runs without secure boot, follow these steps:
- Configure OEMiRoT according to your application requirements (such as the number of images or image size).
- The memory mapping of the user application must be adapted, depending on the OEMiRoT configuration.
- The user application binary must be signed and encrypted. At each boot, OEMiRoT controls the integrity and the authenticity of the user application binary based on TLV added during the image generation.
- Be aware that a default MPU configuration is already applied by OEMiRoT when jumping to the application. To ensure the security of the device, the MPU is configured to allow the execution of the user application code area only. This minimizes the risk of unauthorized code execution. It is the responsibility of the user application to reconfigure the MPU to meet the security requirements.
A set of scripts is provided in the Firmware/Projects/STM32WBA65I-DK1/ROT_Provisioning folder to activate and configure OEMiRoT Boot path. These scripts are designed to adapt the configuration files automatically, such as OEMiROT_Code_Image.xml and the ob_flash_programming.bat (.sh) script, but also the application linker files based on the OEMiRoT configuration.
Before executing these scripts it is mandatory to update the oemirot_appli_path_project variable in Firmware/Projects/STM32WBA65I-DK1/ROT_Provisioning/env.bat (.sh) which must point to the user application folder. As this path is relative from Firmware/Projects/STM32WBA65I-DK1, it may be necessary to add several "../" (parent directory) to navigate to the drive.
1.1. OEMiRoT configuration
1.1.1. OEMiRoT_Boot configuration
To tailor OEMiRoT to the application requirements, edit the file Firmware/Projects/STM32WBA65I-DK1/Applications/ROT/OEMiROT_Boot/Inc/flash_layout.h. The figure below lists the most important parameters from this file.
This example uses the default flash memory layout as defined:
- Two separate images for secure and nonsecure application binaries
- No secure data image
- No nonsecure data image
- FLASH_S_PARTITION_SIZE 0x08000
- FLASH_NS_PARTITION_SIZE 0x32000
- FLASH_S_DATA_PARTITION_SIZE 0x0 (as there is no secure data image)
- FLASH_NS_DATA_PARTITION_SIZE 0x0 (as there is no nonsecure data image)
The OEMiRoT_Boot postbuild command propagates the flash memory layout configuration to the provisioning scripts, the application header file (My_Appli\Secure_nsclib\appli_flash_layout.h) and the application postbuild script (My_Appli\<IDE>\postbuild). It is useful for the application to use it, especially to know where to program new firmware images in download slot areas.
1.1.2. Automatic configuration propagation
Due to the complex configurability of the OEMiROT_Boot (flash_layout.h) impacting xml images configuration files of the provisioning and scripts parameters, an automatic setup has been put in place.
Prerequisites:
- env file : this is a key element and it contains the
oemirot_appli_path_projectvariable that must be set to the user application folder.
Below, the setup for an application without isolation (OEMiROT_Appli) :
- appli_flash_layout.h : it is important and included by the linker scripts to automate changes. It is also included in the application code to specify where the download slots are (for scheduling encrypted candidate images) and where the execution slots are (to confirm images in swap mode).
Propagation scheme for application whitout isolation :
After setting oemirot_appli_path_project=Applications\ROT\OEMiROT_Appli in the env.bat, you can generate the OEMiROT_Boot. After building the binary, the postbuild script will be called and it will update all the files as described below:
Propagation scheme for application whit isolation :
After setting oemirot_appli_path_project=Applications\ROT\OEMiROT_Appli_TrustZone in the env.bat, you can generate the OEMiROT_Boot. After building the binary, the postbuild script will be called and it will update all the files as described below:
1.2. Application without isolation: My_Appli example
1.2.1. Project construction
The assumption described is that you have download and unzip the STM32Cube_FW_WBA_VX.Y.Z at the same level as your My_Path directory.
The different steps to integrate a project without TrustZone (My_Example) into a secure boot path is shown below :
STEP#1: Copy the OEMiROT_Appli template into our development path (My_Path/My_Appli).
STEP#2: Update the env script with the appropriate oemirot_appli_path_project value :
STEP#3: Update bin_path_xml_field variable according your PATH.
STEP#4:
- Copy your source and header files into the appropriate directory (except the main.h/main.c)
- Merge your main.h/main.c inside the corresponding one with care.
- Update your IDE project file with the new source files added.
STEP#5: Update the linker script if your example use dedicated memory region.
STEP#6: Adjust the RAM configuration to your needs in the appli_region_defs.h and appli_flash_layout.h
1.2.2. Security management
For security robustness, when OEMiRoT jumps to the user application, the MPU is configured to ensure that only the user application code area can be executed (execution surface controlled via MPU configuration). It is the responsibility of the application to reconfigure the MPU to meet the security requirements.
1.2.3. Ready to start
The application has now been adapted to OEMiRoT Boot path. To test it, run the provisioning.bat/sh script stored in the Firmware/Projects/STM32WBA65I-DK1/ROT_Provisioning/OEMiROT folder and follow the instructions.
1.3. Application with isolation: My_Appli_TrustZone example
1.3.1. Project construction
The assumption described is that you have download and unzip the STM32Cube_FW_WBA_VX.Y.Z at the same level as your My_Path directory.
The different steps to integrate a project with TrustZone (My_Example_TZ) into a secure boot path is shown below :
STEP#1: Copy the OEMiROT_Appli_TrustZone template into our development path (My_Path/My_Appli_TrustZone).
STEP#2: Update the env script with the appropriate oemirot_appli_path_project value :
STEP#3: Updatebin_path_xml_field variable according your PATH.
STEP#4:
- Copy your source and header files into the appropriate directory (except the main.h/main.c)
- Merge your main.h/main.c inside the corresponding one with care.
- Update your IDE project file with the new source files added.
STEP#5: Update the linker script if your example use dedicated memory region.
STEP#6: Adjust the RAM configuration to your needs in the appli_region_defs.h and appli_flash_layout.h
1.3.2. Security management
For security robustness, when OEMiRoT jumps to the user application, the MPU is configured to ensure that only the user application code area can be executed (execution surface controlled via MPU configuration). It is the responsibility of the application to reconfigure the MPU to meet the security requirements.
1.3.3. Ready to start
The application has now been adapted to OEMiRoT Boot path. To test it, run the provisioning.bat/sh script stored in the Firmware/Projects/STM32WBA65I-DK1/ROT_Provisioning/OEMiROT folder and follow the instructions.
2. Two boot stages: OEMiRoT + OEMuRoT
The adaptation of the user application for a OEMiRoT + OEMuRoT Boot path with two boot stages is very similar to the one-boot-stage OEMiROT use case, with two major differences:
- The location of the provisioning scripts: Firmware\Projects\STM32WBA65I-DK1\ROT_Provisioning\OEMiRoT_OEMuRoT.
- OEMuRoT is generated by compiling the OEMiRoT_Boot project with the OEMUROT_ENABLE switch activated. OEMuRoT acts as a second boot stage.
2.1. OEMxRoT configuration
2.1.1. OEMiRoT_Boot first boot stage configuration
It's a manual setup to generate a first boot stage. For that, you must uncomment OEMIROT_FISRT_BOOT_STAGE.
2.1.2. OEMiRoT_Boot second boot stage configuration
It's an automatic setup done by the script ROT_Provisioning\OEMiRoT_OEMuRoT\provisioning.bat .
The most important parameters in the fileFirmware/Projects/STM32WBA65I-DK1/Applications/ROT/OEMiROT_Boot/Inc/flash_layout.h are the same as One boot stage.
2.1.3. Automatic configuration propagation
Due to the complex configurability of the OEMiROT_Boot (flash_layout.h) impacting xml images configuration files of the provisioning and scripts parameters, an automatic setup has been put in place.
Prerequisites:
- env file : this is a key element and it contains the
oemirot_appli_path_projectvariable that must be set to the user application folder.
Below, the setup for an application without isolation (OEMiROT_Appli) :
- appli_flash_layout.h : It is important and included in the linker scripts to automate changes. It is also included in the application code to specify where the download slots are (for scheduling encrypted candidate images) and where the execution slots are (to confirm images in swap mode).
Propagation scheme for application whitout isolation :
After setting oemirot_appli_path_project=Applications\ROT\OEMiROT_Appli in the env.bat, you can generate the OEMiROT_Boot. After building the binary, the postbuild script will be called and it will update all the files as described below:
Propagation scheme for application whit isolation :
After setting oemirot_appli_path_project=Applications\ROT\OEMiROT_Appli_TrustZone in the env.bat, you can generate the OEMiROT_Boot. After building the binary, the postbuild script will be called and it will update all the files as described below:
2.2. Application without isolation: My_Appli example
Same as One boot stage.
2.3. Application with isolation: My_Appli_Trustzone example
Same as One boot stage.
3. Appendix
3.1. Constraints for OEMxRoT Appli without isolation
When an application is designed to run without isolation, it must be 'fully secure'. To meet this requirement, the project as been set to secure project:
Change nature of your project:
To change the nature of the project, open the .project file with a text editor and verify the line below :
Select the secure compilation option
Remove secure gateway generation
ROM region adaptation:
To avoid configuration mismatch or errors, the linker files are including appli_region_defs.h and are prebuild by the IDE's.
RAM region adaptation:
The RAM can be adjusted in the appli_region_defs.h :
Postbuild scripts adaptation:
Only bin_path_xml_field variable must be updated according your PATH and your IDE.
Image generation: STM32TrustedPackageCreator uses OEMiRoT_Code_Image.xml (in the Firmware/Projects/STM32WBA65I-DK1/ROT_Provisioning/OEMiROT/Images folder) to generate the image. It contains all required parameters, including the location of the secure (oemirot_tz_s_app.bin) binary file of the user application. This parameter is updated automatically during the postbuild call.
Therefore, the IDE must be configured to generate a .bin file and call the postbuild script.
$PROJ_DIR$/../Binary/oemirot_tz_s_app.bin
fromelf "#L" --bincombined --output="$L\..\..\Binary\oemirot_tz_s_app.bin"
3.2. Constraints for OEMxRoT Appli with isolation
When an application is designed to run with both a secure and a nonsecure part it must be compiled in a specific order (secure then nonsecure). To meet this requirement.
The secure and nonsecure partition of the project are define as follow:
Change nature of your project: To change the nature of the project, open the .project file with a text editor and verify the line below :
Select the secure compilation option and generate the secure gateway
Change nature of your project: To change the nature of the project, open the .project file with a text editor and verify the line below :
Check non secure compilation option and include secure gateway library
ROM region adaptation:
To simplify, the linker files are including appli_region_defs.h and are prebuild by the IDE's.
For the secure and nonsecure partition, see below :
RAM region adaptation:
The RAM can be adjusted manually in the appli_region_defs.h :
Postbuild scripts adaptation:
Only bin_path_xml_field variable must be updated according your PATH and your IDE.
Image generation:
The image is generated at the end of the nonsecure project compilation.
STM32TrustedPackageCreator usesOEMiRoT_Code_Image.xml (in the Firmware/Projects/STM32WBA65I-DK1/ROT_Provisioning/OEMiROT/Images folder) to generate the image. It contains all required parameters, including the location of the secure (oemirot_tz_s_app.bin, oemirot_tz_ns_app.bin) binary file of the user application. This parameter is updated automatically during the postbuild call.
Therefore, the IDE must be configured to generate a .bin file and call the postbuild script.
