There are 3 ways of working to develop an application compatible with a secure boot:
- Develop your application without taking into account the secure boot in a first step then adapt the application to the secure boot path. This is the objective of this article.
- Or add your code into the ROT template projects (OEMiROT_Appli or STiROT_Appli). These projects are already adapted to the secure bootpath.
- Or update existing ROT applications projects (OEMiROT_Appli or STiROT_Appli). These projects are already adapted to the secure bootpath.
With STM32H5, four kinds of secure bootpath can be selected:
- One boot stage: STiRoT
- One boot stage: OEMiRoT
- Two boot stages: STiRoT + OEMuRoT
This article is not applicable with the Secure Manager.
This article mention STM32H573-DK board as example but it can be extended to other STM32H5 boards.
1. One boot stage: STiRoT
At reset, STiRoT checks the authenticity and the integrity of the user application before executing it. A detailed description is provided in STiRoT_for_STM32H5 article.
STiRoT supports the installation of two application toppologies:
- Secure only (as example : Firmware/Projects/STM32H573-DK/Applications/ROT/STiROT_Appli)
- Secure and non-secure (as example : Firmware/Projects/STM32H573-DK/Applications/ROT/STiROT_Appli_TrustZone)When your application runs without secure boot and you want to use STiRoT to secure it, you need to do the following adaptations:
- The memory mapping of the user application must be adapted. The user application booted by STiRoT is always executed in Flash memory. The memory mapping depends on STiRoT configuration.
- The user application binary must be signed and encrypted. At each boot STiRoT control 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 STiRoT when jumping in your application. To ensure the security of the device, the MPU is configured to allow only the user application code area to be executed, minimizing the risk of unauthorized code execution. It is the user application responsibility to reconfigure the MPU to fit with its security needs.
A set of scripts is provided in Firmware/Projects/STM32H573-DK/ROT_Provisioning folder to activate and configure STiRoT bootpath. These scripts are designed to adapt automatically the configuration files such as STiROT_Code_Image.xml, the ob_flash_programming.bat (.sh) script but also the application linker files based on STiRoT configuration.
1.1. STiRoT_Appli
Before executing these scripts it is mandatory to update the stirot_boot_path_project variable in Firmware/Projects/STM32H573-DK/ROT_Provisioning/env.bat (.sh) which must point to the user application folder (relative path from Firmware/Projects/STM32H573-DK).
1.1.1. User application adaptation
In this chapter, we will highlight some parts of the linker file to explain the most important points to take care, but we recommend to use the complete mapping file template provided for STiRoT_Appli bootpath. If you don't change this file, you can skip the ROM and RAM regions adaptation described below.
ROM region adaptation:
When started by STiRoT, the user application is always executed in Flash memory. Moreover the user application binary must be included in an image including a header as described in Image generation chapter. Therefore, the vector table is shifted of 0x400 bytes.
As done in Firmware/Projects/STM32H573-DK/Templates/ROT/STiROT_Appli example, S_CODE_OFFSET, S_CODE_SIZE, IMAGE_HEADER_SIZE symbols must be added in the linker file. These 3 symbols are automatically updated during the provisioning process, taking into account the memory configuration of STiROT_Boot. The vector table address and the ROM code section should be defined using S_CODE_OFFSET, S_CODE_SIZE, IMAGE_HEADER_SIZE symbols:
RAM region adaptation:
No adaptation is required for STiRoT_Appli bootpath.
1.1.2. Image generation
The image generation is done by STM32TrustedPackageCreator with STiRoT_Code_Image.xml (Firmware/Projects/STM32H573-DK/ROT_Provisioning/STM32H573-DK/STiROT/Images folder) containing all the required parameters especially the location of the user application binary file (appli.bin). This parameter is automatically updated during the provisioning sequence based on stirot_boot_path_project variable.
Therefore, the IDE must be configured to generate a .bin file.
The image generation can be started manually using STM32TrustedPackageCreator but a more efficient way of working is to modify the user application project to generate the image automatically at the end of each compilation as a postbuild command.
An example of postbuild.bat/.sh is provided in Firmware/Projects/STM32H573-DK/Templates/ROT/STiROT_Appli example and Firmware/Projects/STM32H573-DK/Applications/ROT/STiROT_Appli. The image generation is performed based on STiRoT_Code_Image.xml stored in Firmware/Projects/STM32H573-DK/ROT_Provisioning/STM32H573-DK/STiROT/Images folder. Depending on the location of your application the postbuild script may be updated to access STiRoT_Code_Image.xml file.
1.1.3. Security management
For security robustness, when STiRoT jumps into the user application, the MPU is configured to ensure that only the user application code area is allowed to be executed (execution surface controlled via MPU configuration). It is the application responsibility to reconfigure the MPU to fit with its security needs.
1.1.4. Miscellaneous
STiRoT system clock is setted to 64, 200 or 250 Mhz by the user at STiRoT configuration step. The application inherits the STiRoT system clock value if there is no reconfiguration of the system clock by the application.
1.2. STiRoT_Appli_TrustZone
STiRoT_Appli_TrustZone bootpath can be chosen if the user wants to configure his application as both secure and non-secure. In this purpose, STiRoT configuration must be updated as follow:
- Disable the full secure image option.
- Update the offset and size of each image area depending your need.
You can reuse the same set of scripts provided in Firmware/Projects/STM32H573-DK/ROT_Provisioning folder to activate and configure STiRoT_Appli bootpath.
Before executing these scripts it is mandatory to update the stirot_boot_path_project variable in Firmware/Projects/STM32H573-DK/ROT_Provisioning/env.bat (.sh) which must point to the user application folder (relative path from Firmware/Projects/STM32H573-DK).
1.2.1. User application adaptation
In this chapter, we will highlight some parts of the linker file to explain the most important points to take care, but we recommend to use the complete mapping files template provided for STiRoT_Appli_TrustZone bootpath. If you don't change this file, you can skip the ROM and RAM regions adaptation described below.
Comparing STiRoT_Appli bootpath, there are two projects to build and therefore two images generated at the end. The first project to build is for the secure image and another for the non-secure image. Each project has his own vector table as STiRoT will jump on the secure application, then the secure application will jump on the non-secure application.
ROM region adaptation:
When started by STiRoT, the user application is always executed in Flash memory. Moreover the user application binary must be included in an image including a header as described in Image generation chapter. Therefore, the vector table is shifted of 0x400 bytes.
As done in Firmware/Projects/STM32H573-DK/Applications/ROT/STiROT_Appli_TrustZone example, S_CODE_OFFSET, S_CODE_SIZE, IMAGE_HEADER_SIZE and CMSE VENEER_REGION_SIZE symbols must be added in the secure linker file. The vector table address should be defined using S_CODE_OFFSET and IMAGE_HEADER_SIZE symbols while the ROM code section should be defined using S_CODE_OFFSET, S_CODE_SIZE and IMAGE_HEADER_SIZE symbols.
- IMAGE_HEADER_SIZE is configured by default, and his value must not be updated.
- CMSE VENEER_REGION_SIZE defines the region used to safely switch context between secure and non-secure application. It ensures that the transition is controlled and that sensitive data is protected. This value can be configured by the user even if it is recommended to keep the default value.
- S_CODE_OFFSET and S_CODE_SIZE symbols are automatically updated during the provisioning process, taking into account the memory configuration of STiRoT.
As done inFirmware/Projects/STM32H573-DK/Applications/ROT/STiROT_Appli_TrustZone example, S_CODE_OFFSET, S_CODE_SIZE, NS_CODE_OFFSET, NS_CODE_SIZE and IMAGE_HEADER_SIZE symbols must be added in the non-secure linker file. The vector table address should be defined using NS_CODE_OFFSET and IMAGE_HEADER_SIZE symbols while the ROM code section should be defined using NS_CODE_OFFSET, NS_CODE_SIZE and IMAGE_HEADER_SIZE symbols.
- IMAGE_HEADER_SIZE is configured by default, and his value must not be updated.
- NS_CODE_OFFSET is configured in the examples as the beginning of the area just after the secure area. This value can be updated by the user if he decided to change partitioning logic.
- S_CODE_OFFSET, S_CODE_SIZE and NS_CODE_SIZE symbols are automatically updated during the provisioning process, taking into account the memory configuration of STiRoT.
RAM region adaptation:
No adaptation is required for STiRoT_Appli_TrustZone bootpath. From a partitioning point of view, secure and non-secure firmware cannot access the same physical area of SRAM. Therefore, to simplify RAM partitioning, secure code uses SRAM1 (through secure aliases) while non-secure code uses SRAM3 (through non-secure aliases).
1.2.2. Image generation
The image generation is done by STM32TrustedPackageCreator with STiRoT_Code_Image.xml (Firmware/Projects/STM32H573-DK/ROT_Provisioning/STM32H573-DK/STiROT/Images folder) containing all the required parameters especially the location of the user application binary file (appli.bin). This parameter is automatically updated during the provisioning sequence based on stirot_boot_path_project variable.
Therefore, the IDE must be configured to generate a .bin file.
Secure project
Non-secure project
The assembly is performed at the postbuild step of the non-secure project.
The image generation can be started manually using STM32TrustedPackageCreator but a more efficient way of working is to modify the user application project to generate the image automatically at the end of each compilation as a postbuild command.
Secure project
Non-secure project
An example of postbuild.bat/.sh is provided in Firmware/Projects/STM32H573-DK/Templates/ROT/STiROT_Appli_TrustZone example and Firmware/Projects/STM32H573-DK/Applications/ROT/STiROT_Appli_TrustZone. The image generation is performed based on STiRoT_Code_Image.xml stored in Firmware/Projects/STM32H573-DK/ROT_Provisioning/STM32H573-DK/STiROT/Images folder. Depending on the location of your application the postbuild script may be updated to access STiRoT_Code_Image.xml file.
1.2.3. Security management
For security robustness, when STiRoT jumps into the user application, the MPU is configured to ensure that only the user application code area is allowed to be executed (execution surface controlled via MPU configuration). It is the application responsibility to reconfigure the MPU to fit with its security needs.
1.2.4. Miscellaneous
STiRoT system clock is setted to 64, 200 or 250 Mhz by the user at STiRoT configuration step. The application inherits the STiRoT system clock value if there is no reconfiguration of the system clock by the application.
2. One boot stage: OEMiRoT
When your application runs without secure boot and you want to use OEMiRoT to secure it, you need to do the following adaptations:
- The memory mapping of the user application must be adapted. The memory mapping depends on OEMiRoT configuration.
- The user application binary must be signed and encrypted. At each boot OEMiRoT control 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 in your application. To ensure the security of the device, the MPU is configured to allow only the user application code area to be executed, minimizing the risk of unauthorized code execution. It is the user application responsibility to reconfigure the MPU to fit with its security needs.
A set of scripts is provided in Firmware/Projects/STM32H573-DK/ROT_Provisioning folder to activate and configure OEMiRoT bootpath. These scripts are designed to adapt automatically the configuration files such as OEMiROT_Code_Image.xml, the ob_flash_programming.bat (.sh) script but also the application linker files based on OEMiRoT configuration.
2.1. OEMiRoT_Appli_TrustZone
Before executing these scripts it is mandatory to update the oemirot_boot_path_project variable in Firmware/Projects/STM32H573-DK/ROT_Provisioning/env.bat (.sh) which must point to the user application folder (relative path from Firmware/Projects/STM32H573-DK).
2.1.1. User application adaptation
In this chapter, we will highlight some parts of the linker file to explain the most important points to take care, but we recommend to use the complete mapping file template provided for OEMiRoT_Appli_TrustZone bootpath. If you don't change this file, you can skip the ROM and RAM regions adaptation described below.
ROM region adaptation:
When started by OEMiRoT, the user application binary must be included in an image including a header as described in Image generation chapter. Therefore, the vector table is shifted of 0x400 bytes.
As done in Firmware/Projects/STM32H573-DK/Templates/ROT/OEMiROT_Appli_TrustZone example, S_CODE_OFFSET, S_CODE_SIZE, NS_CODE_OFFSET, NS_CODE_SIZE, IMAGE_HEADER_SIZE and CMSE_VENEER_REGION_SIZE symbols must be added in the linker files of the secure and non-secure projects. These symbols will be automatically updated during the OEMiROT_Boot project compilation, taking into account the memory configuration of OEMiROT_Boot which depends on MCUBOOT_OVERWRITE_ONLY, MCUBOOT_APP_IMAGE_NUMBER, MCUBOOT_S_DATA_IMAGE_NUMBER and MCUBOOT_NS_DATA_IMAGE_NUMBER compilation switches. The vector table address and the ROM code section should be defined using S_CODE_OFFSET, S_CODE_SIZE, NS_CODE_OFFSET, NS_CODE_SIZE, IMAGE_HEADER_SIZE and CMSE_VENEER_REGION_SIZE symbols:
2.1.2. Image generation
The image generation is done by STM32TrustedPackageCreator with OEMiRoT_Code_Image.xml (Firmware/Projects/STM32H573-DK/ROT_Provisioning/STM32H573-DK/OEMiROT/Images folder) containing all the required parameters especially the location of the user application secure (rot_tz_s_app.bin) and non-secure (rot_tz_ns_app.bin) binary files. This parameter is automatically updated during the provisioning sequence based on oemirot_boot_path_project variable.
Therefore, the IDE must be configured to generate a .bin file.
The image generation can be started manually using STM32TrustedPackageCreator but a more efficient way of working is to modify the user application project to generate the image automatically at the end of each compilation as a postbuild command.
An example of postbuild.bat/.sh is provided in Firmware/Projects/STM32H573-DK/Templates/ROT/OEMiROT_Appli_TrustZone example and Firmware/Projects/STM32H573-DK/Applications/ROT/OEMiROT_Appli_TrustZone. The image generation is performed based on OEMiRoT_Code_Image.xml stored in Firmware/Projects/STM32H573-DK/ROT_Provisioning/STM32H573-DK/OEMiROT/Images folder. Depending on the location of your application the postbuild script may be updated to access OEMiRoT_Code_Image.xml file.
2.1.3. Security management
For security robustness, when OEMiRoT jumps into the user application, the MPU is configured to ensure that only the user application code area is allowed to be executed (execution surface controlled via MPU configuration). It is the application responsibility to reconfigure the MPU to fit with its security needs.
3. Two boot stages: STiRoT + OEMuRoT
User application adaptation for a two boot stages STiRoT + OEMuRoT bootpath is very similar to the one boot stage OEMiROT use case:
- The major difference is the location of the provisioning scripts: Firmware\Projects\STM32H573-DK\ROT_Provisioning\STiROT_OEMuROT.
- The second difference is that OEMuRoT is generated by compiling OEMiRoT_Boot project with OEMUROT_ENABLE switch activated. OEMuRoT (updatable Root of Trust) acts as a second boot stage.