How to adapt a user application to ROT for STM32H7RS

There are 3 ways to develop an application that is 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 to the ROT template projects (OEMiROT_Appli or STiROT_Appli). These projects are already adapted to the secure bootpath.
Or update existing ROT application projects (OEMiROT_Appli or STiROT_Appli). These projects are already adapted to the secure bootpath.

Three kinds of secure bootpath can be selected:

One boot stage: STiRoT.
One boot stage: OEMiRoT.
Two boot stages: STiRoT + OEMuRoT.

This article uses the STM32H7S78-DK board as an example but the process can be extended to other STMH7RS boards.

1. Prerequisites

As you will see below, we provide different scripts to facilitate application configuration and firmware image generation.

The application folder structure should match the standard one available in the STM32CubeH7RS package. Underlined names of files and folders must be compliant.

To fulfill this folder structure, if you generate the application with STM32CubeMX, you must ensure that the option "Generate Under Root" is not selected.

2. One boot stage: STiRoT

At reset, STiRoT first requests the iLoader to load the user application from the external flash to the internal RAM. Then after a successful verification of the authenticity and the integrity of the user application, STiRoT executes it. A detailed description is provided in the STiRoT_for_STM32H7S article.

When your application runs without secure boot and you want to use STiRoT to secure it, the following adaptations must be done:

The memory mapping of the user application must be adapted. The user application booted by STiRoT is always executed in the internal RAM. All the AXI SRAMs can be allocated to the user application code execution area, except the last 8 Kbytes of AXI SRAM4 (max: 448 Kbytes). The memory mapping of the user application depends on the STiRoT configuration.
The user application binary must be signed and encrypted. At each boot, STiRoT controls the integrity and the authenticity of the user application binary based on TLV added during the image generation.
Note that a default memory protection unit (MPU) configuration is already applied by the STiRoT when jumping into your application. To ensure the security of the device, the MPU is configured to allow only the user application code area to be executed. This minimizes the risk of unauthorized code execution. It is the role of the user application to securely reconfigure the MPU.

A set of scripts is provided in the Firmware/Projects/STM32H7S78-DK/ROT_Provisioning folder to activate and configure STiRoT bootpath. These scripts are designed to automatically adapt the configuration files such as STiROT_Code_Image.xml, the ob_flash_programming.bat (.sh) script and the application linker files based on STiRoT configuration.

Before executing these scripts, the stirot_boot_path_project variable must be updated in Firmware/Projects/STM32H7S78-DK/ROT_Provisioning/env.bat (.sh) which must point to the user application folder (relative path from Firmware/Projects/STM32H7S78-DK).

2.1. User application adaptation

In this chapter, we highlight some parts of the linker file to explain the most important points to take care of, but if you don't modify this file we recommend to use the complete mapping file template provided for STiRoT bootpath and thus skip the ROM/RAM regions adaptation described below.

ROM region adaptation:

When started by the STiRoT, the user application is always executed in the internal RAM. Moreover, the user application binary must be included in an image which contains a header as described in the Image generation chapter. Therefore, the vector table is shifted by 0x400 bytes.

As done in the Firmware/Projects/STM32H7S78-DK/Templates/Template_ROT/STiROT_Appli example, CODE_OFFSET, 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 the STiROT_Boot. The vector table address and the ROM code section are defined using the CODE_OFFSET, CODE_SIZE, IMAGE_HEADER_SIZE symbols:

RAM region adaptation:

As the user application is always executed in internal RAM, the RAM must be split into two areas:

the execution area for the user application code is always mapped in the AXI SRAMs. All the AXI SRAMs can be allocated for the execution area except for the last 8 Kbytes of AXI SRAM4.
the data area for the stack, the heap and all the data of the user application. In the STiRoT_Appli template, use DTCM or AHB SRAMs for this area but this can be extended to non-allocated AXI SRAMs.

2.2. Image generation

The image generation is done by the STM32TrustedPackageCreator with STiRoT_Code_Image.xml (Firmware/Projects/STM32H7S78-DK/ROT_Provisioning/STM32H7S78-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 the oemirot_boot_path_project variable.

Therefore, the IDE must be configured to generate a .bin file into My_Appli/Appli/Binary folder (ensure the correct project tree has been selected).

The image generation can be started manually using the 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 the Firmware/Projects/STM32H7S78-DK/Templates/Template_ROT/STiROT_Appli example and Firmware/Projects/STM32H7S78-DK/Applications/ROT/STiROT_Appli. The image generation is performed based on the STiRoT_Code_Image.xml stored in Firmware/Projects/STM32H7S78-DK/ROT_Provisioning/STM32H7S78-DK/STiROT/Images folder. Depending on the location of your application, the postbuild script may be updated to access the STiRoT_Code_Image.xml file.

2.3. Security management

To ensure a robust security, when the STiRoT jumps into the user application, the MPU is configured to ensure that only the user application code area is allowed to be executed (the execution surface is controlled via MPU configuration). It is the responsibility of the application to reconfigure the MPU to fit with its security needs.

Warning

Even when there is no specific security requirement, a default MPU configuration is still required to access external memories.

2.4. Miscellaneous

The system clock is set to 380 MHz in order to be functional with all the possible hardware configurations (RAMECC enabled, no internal regulator) and with the full range of temperature (Tj up to 125°). In other circumstances, the system clock can be increased to 600 Mhz.

Depending on the external flash integrated in the board, the project Firmware/Projects/STM32H7S78-DK/Applications/ROT/STiROT_iLoader may be adapted and the correct flash loader must be selected with stm32ExtLoaderFlash and stm32ExtLoaderFlashOpen variables in Firmware/Projects/STM32H7S78-DK/ROT_Provisioning/env.bat (.sh).

As example, onNUCLEO-H7S3L8 the flash loader are:

A set of scripts is provided in the Firmware/Projects/STM32H7S78-DK/ROT_Provisioning folder to activate and configure the STiRoT bootpath. These scripts are designed to adapt automatically the linker files based on the STiRoT configuration. The linker file name may be replaced with the name used in your application.

3. One boot stage: OEMiRoT

At reset, the OEMiRoT located in the user flash memory (limited to 64 Kbytes) is executed. After a successful verification of the authenticity and the integrity of the user application, the OEMiRoT executes the user application from:

external flash memory.
or external RAM memory.
or internal RAM memory. In this configuration, the size of the application is limited to 128 Kbytes. During the load of the application in internal RAM, the OEMiRoT/OEMuRoT data, OEMuRoT code (depends on the bootpath selected) and the application code are mapped in RAM at the same time.

A detailed description is provided in the OEMiRoT for STM32H7S or OEMiRoT for STM32H7R articles.

When the application runs without secure boot, use the OEMiRoT to secure it.The following adaptations are needed:

The memory mapping of the user application must be adapted. The memory mapping depends on the OEMiRoT configuration.
The user application binary must be signed and encrypted. At each boot, the OEMiRoT controls the integrity and the authenticity of the user application binary based on TLV added during the image generation.
Note that a default MPU configuration is already applied by the OEMiRoT when jumping into your application. To ensure the security of the device, the MPU is configured to allow only the user application code area to be executed. This minimizes 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 the Firmware/Projects/STM32H7S78-DK/ROT_Provisioning folder to activate and configure the 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.

Before executing these scripts, it is mandatory to update the oemirot_boot_path_project variable in Firmware/Projects/STM32H7S78-DK/ROT_Provisioning/env.bat (.sh) which must point to the user application folder (relative path from Firmware/Projects/STM32H7S78-DK).

3.1. OEMiRoT configuration

To configure OEMiRoT according to your application requirements, you will have to edit the file Firmware/Projects/STM32H7S78-DK/Applications/ROT/OEMiROT_Boot/Inc/flash_layout.h.

Here are some of the key parameters you can find in the flash_layout.h file:

OEMiRoT_Boot postbuild command will propagate the flash layout configuration to the provisioning scripts and application linker files.

3.2. User application adaptation

In this chapter, we highlight some parts of the linker file to explain the most important points to take care of, but if you don't modify this file we recommend to use the complete mapping file template provided for the OEMiRoT bootpath and thus skip the ROM/RAM regions adaptation described below.

ROM region adaptation:

When started by the OEMiRoT, the user application binary must be included in an image containing a header as described in the Image generation chapter. Therefore, the vector table is shifted by 0x400 bytes.

As done in the Firmware/Projects/STM32H7S78-DK/Templates/Template_ROT/OEMiROT_Appli example, CODE_OFFSET, CODE_SIZE, IMAGE_HEADER_SIZE and PARTITION_START symbols must be added in the linker file. These four symbols are automatically updated during the OEMiROT_Boot project compilation, taking into account the memory configuration of the OEMiROT_Boot which depends on the MCUBOOT_OVERWRITE_ONLY and OEMIROT_LOAD_AND_RUN compilation switches. The vector table address and the ROM code section must be defined using CODE_OFFSET, CODE_SIZE, IMAGE_HEADER_SIZE and PARTITION_START symbols:

RAM region adaptation:

Two specific areas in the SRAM are reserved for communication between the OEMiROT_Boot and the OEMiROT_Appli projects:

0x30007FA0 / 0x30007FBF: area dedicated to confirmation flag processing between OEMiROT_Boot and OEMiROT_Appli projects. After secure firmware update with swap method, a new image must be confirmed by the user application. A reset must be generated by the user application after confirmation to update the confirmation flag in the installation slot. This procedure is required because the "read while write" feature is not managed for the external flash memory. Refer to Features list for more details.
0x30007FC0 / 0x30007FFF: area dedicated to the save the RAMECC handle (Refer to HAL RAMECC_HandleTypeDef structure in stm32h7rsxx_hal_ramecc.h). ECC is activated by OEMiRoT_Boot. In case of ECC, an error code is provided through RAMECC handle.

As NONCACHEABLEBUFFER area, these two areas must be excluded from the SRAM area available for the user application.

The RAMECC handle area must not be initialized by the user application as this area is already filled by the OEMiRoT.

In Firmware/Projects/STM32H7S78-DK/Templates/Template_ROT/OEMiROT_Appli and Firmware/Projects/STM32H7S78-DK/Applications/ROT/OEMiROT_Appli, we propose to use AHB SRAM2 for the stack, and the heap and the data of the user application in order to be compatible with the internal RAM memory execution mode. If this configuration is not used, all the RAMs can be allocated to the application data.

Note: Only accesses to AHB_SRAM2 (0x30004000 - 0x30007000) are allowed by the MPU at the user application start-up. To remove this constraint, the MPU configuration of the region 5 must be modified in Firmware/Projects/STM32H7S78-DK/Applications/ROT/OEMiROT_Boot to extend the configuration to other RAM memories.

3.3. Image generation

The image generation is done by the STM32TrustedPackageCreator with OEMiRoT_Code_Image.xml (Firmware/Projects/STM32H7S78-DK/ROT_Provisioning/STM32H7S78-DK/OEMiROT/Images folder) containing all the required parameters and especially the location of the user application binary file (rot_app.bin). This parameter is automatically updated during the provisioning sequence based on the oemirot_boot_path_project variable.

Therefore, the IDE must be configured to generate a .bin file into My_Appli/Appli/Binary folder (ensure the correct project tree has been selected).

The image generation can be started manually using STM32TrustedPackageCreator but a more efficient way 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 the Firmware/Projects/STM32H7S78-DK/Templates/Template_ROT/OEMiROT_Appli example and Firmware/Projects/STM32H7S78-DK/Applications/ROT/OEMiROT_Appli. The image generation is performed based on the OEMiRoT_Code_Image.xml stored in Firmware/Projects/STM32H7S78-DK/ROT_Provisioning/STM32H7S78-DK/OEMiROT/Images folder. Depending on the location of your application, the postbuild script may be updated to access the OEMiRoT_Code_Image.xml file.

3.4. Security management

To ensure a robust security, when the 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 the MPU configuration). It is the application responsibility to reconfigure the MPU to fit with its security needs.

Warning

Even when there is no specific security requirement, a default MPU configuration is still required to access external memories.

3.5. Miscellaneous

In case the SWAP mode is selected for the OEMiRoT generation, the user application must implement the image validation feature. An example is provided in Firmware/Projects/STM32H7S78-DK/Applications/ROT/OEMiROT_Appli/src/main.c: FW_Valid_AppImage(void).

The OEMiRoT_Boot project configures MCE1/XSPI1 to encrypt the user application image in the external flash memory and MCE2/XSPI2 to encrypt the user application image in the external RAM.

The system clock is set to 380 MHz in order to function with all the hardware configurations (RAMECC enabled, no internal regulator) and with the full range of temperature (Tj up to 125°). In other circumstances, the system clock can be increased to 600 MHz using PLL1. PLL2 cannot be modified as it is used by XSPI to communicate with external memories.

Depending on the external flash integrated in the board the correct flash loader must be selected with stm32ExtLoaderFlash and stm32ExtLoaderFlashOpen variables in Firmware/Projects/STM32H7S78-DK/ROT_Provisioning/env.bat (.sh).

As example, on NUCLEO-H7S3L8 the flash loader are:

A set of scripts is provided in the Firmware/Projects/STM32H7S78-DK/ROT_Provisioning folder to activate and configure the OEMiRoT bootpath. These scripts are designed to adapt automatically the linker files based on the OEMiRoT_Boot configuration. The linker file name may be adapted (ensure the correct project tree has been selected).

4. Two boot stages: STiRoT + OEMuRoT

The user application adaptation for a two boot stages STiRoT and OEMuRoT bootpath is very similar to the one boot OEMiROT stage use case:

The major difference is the location of the provisioning scripts: Firmware\Projects\STM32H7S78-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.