OEM-iROT Overview
STiRoT states for Immutable (unchangeable) Root Of Trust and acts as a first boot stage.
The STiROT is embedded in all STM32H57x devices.
Since the STiROT is requiring hardware cryptographic features, it is not supported on STM32H6x and STM32H503 products.
The services provided by the STiROT and the different user application use cases will be described in following sections.
1. STiROT services
The STiROT provides two services
- 1) The Secure Boot (Root of Trust Services):
- It is an immutable code, always executed after a system reset, that activates STM32 runtime protections and verifies the authenticity and integrity of the application code before every execution.
- Integrity: to ensure that a firmware that is going to be executed has not been corrupted or maliciously modified.
- Authenticity: to verify that a firmware is coming from a trusted and known source in order to prevent unauthorized entities to install and execute code.
- Integrity: to ensure that a firmware that is going to be executed has not been corrupted or maliciously modified.
- It is an immutable code, always executed after a system reset, that activates STM32 runtime protections and verifies the authenticity and integrity of the application code before every execution.
- 2) The Secure Firmware Update:
- It is an immutable code that detects if a new firmware image is available, checks its authenticity and verifies the integrity of the code before installing it after decryption.
2. STiROT use cases
There are two possible cases explained below.
- Case 1: The user application is executed after the STiROT
- The STiROT application is the first application executed after any reset (STiROT or OEMiROT application is executed in temporal isolation 1 (HDPL1) (see section temporal isolation)
- The following figure gives an overview and indicates the entry point after reset.
- It shows also the user application and data download areas for the different images and the user application location once installed.
- The STiROT application is the first application executed after any reset (STiROT or OEMiROT application is executed in temporal isolation 1 (HDPL1) (see section temporal isolation)
- After a successful verification of the user application (integrity and authenticity), the STiRoT executes the user application in temporal isolation level 2 (HDPL2) and in secure mode (i.e. at least, the first user flash sector has to be part of secure area).
- Only the user app execution area is allowed to be executed (execution surface controlled via MPU configuration)
- After a successful verification of the user application (integrity and authenticity), the STiRoT executes the user application in temporal isolation level 2 (HDPL2) and in secure mode (i.e. at least, the first user flash sector has to be part of secure area).
- If needed, the User app can reconfigure the secure MPU and move to temporal isolation level 3 (HDPL3) to switch in non-secure mode.
- If needed, the User app can reconfigure the secure MPU and move to temporal isolation level 3 (HDPL3) to switch in non-secure mode.
- When no secrets are required by the application, the data image management can be deactivated.
- This deactivation is done through the STiROT configuration.
- When no secrets are required by the application, the data image management can be deactivated.
- In case there is a verification failure of the user application code, the STiROT will execute the Bootloader to download a new user app code and/or data.
- In case there is a verification failure of the user application code, the STiROT will execute the Bootloader to download a new user app code and/or data.
- Case 2: The updatable Root of Trust (uROT) is executed after the STiROT
- The uROT is located in the user flash and will act as a second boot stage adapted to customer requirements.
- The following figure shows the entry point after reset and the STiROT controlling the step to uROT.
- The uROT is located in the user flash and will act as a second boot stage adapted to customer requirements.
- The STiROT application is the first application executed after any reset (STiROT or OEMiROT application is executed in temporal isolation level 1 (HDPL1) (see section temporal isolation).
- The STiROT application is the first application executed after any reset (STiROT or OEMiROT application is executed in temporal isolation level 1 (HDPL1) (see section temporal isolation).
- After a successful verification of the uRoT, the STiRoT executes the uRoT in temporal isolation level 2 (HDPL2) and in secure mode.
- After a successful verification of the uRoT, the STiRoT executes the uRoT in temporal isolation level 2 (HDPL2) and in secure mode.
- The uRoT will then execute the secure user application (S-User app) after a successful verification in temporal isolation level 3 (HDPL3) and in secure mode.
- The uRoT will then execute the secure user application (S-User app) after a successful verification in temporal isolation level 3 (HDPL3) and in secure mode.
- In case there is a verification failure of the uROT, the STiRoT will execute the Bootloader in order to download a new uRoT code and/or data.
- In case there is a verification failure of the uROT, the STiRoT will execute the Bootloader in order to download a new uRoT code and/or data.
3. STiROT configuration
The following STiROT configuration options are possible:
- Minimal product state:
- STiRoT will execute the firmware only if the product state is equal or greater than the "Product state minimal allowed".
- STiRoT will execute the firmware only if the product state is equal or greater than the "Product state minimal allowed".
- User application images:
- One image: user application code image.
- Two images: user application code image & user application data images
- One image: user application code image.
- Two slots per image (allow over the air update).
- User application secure and non-secure:
- User application full secure.
- User application secure & user application non-secure.
- User application full secure.
- User application image and execution:
- Flash location and size reserved for code image download.
- Flash location and size reserved for user application installation.
- Flash location and size reserved for code image download.
- User data image:
- Flash location and size reserved for data image download.
- Flash location and size reserved for decrypted user data.
- Flash location and size reserved for data image download.
- Crypto scheme with FW encryption:
- AES key encrypted with ECDSA256
- Authentication with ECDSA256
- AES key encrypted with ECDSA256
- HW crypto accelerator : PKA, SAES, HASH
- Dependencies verification enabled.
- Only internal flash managed.
- No loader integrated: over the air download managed by application or local download through standard bootloader if no image installed.
- Minimal product state:
The STiROT configuration is done through STM32TrustedPackageCreator tool and an xml configuration file.
The first step is to define the wanted configuration and to generate an option byte configuration file.
The configuration is handled by the STiROT_Config.xml file and TPC generated the STiROT_Config.obk file.
The second step is to program this configuration during the device provisioning described in next section.
The getting started with StiROT on STM32H573 wiki article describes how to practically define the configuration and how to perform the device provisioning.
A script (Provisioning.bat) provided in the STM32Cube_FW, is guiding the user during the configuration definition and device programming.
With STM32CubeMx the user will be guided by this tool to choose the bootpath, the configuration and the device programming.
4. STiROT configuration provisioning
When the STiROT configuration is defined it will be programmed on the device through the provisioning procedure.
The figure below gives an overview of the prerequisite input files and the provisioning step.
How to practically perform all the following steps is explained in the getting started with StiROT on STM32H573 wiki article.
- At step 1 the STiROT configuration is defined using the STiROT_Config.xml file.
- All the configurations can be chosen by directly editing this .xml file
- But most of the configurations can be chosen through the STM32TrustedPackageCreator interface.
- Two keys are provisioned: a key for the authentication and a key for the file encryption.
- Default keys are provided in the STM32Cube_FW but can be regenerated using STM32TrustedPackageCreator.
- The option byte file STiROT_Config.obk is generated using STM32TrustedPackageCreator.
- At step 1 the STiROT configuration is defined using the STiROT_Config.xml file.
- At step 2 the Debug Authentication is configured using the DA_Config.xml file.
- The .xml file can be edited to update the configuration.
- STM32TrustedPackageCreator is the interface to open this file and generate the option byte file (DA_Config.obk).
- A default root key is provided in the STM32Cube_FW. A new key can be generated using STM32TrustedPackageCreator.
- STM32TrustedPackageCreator is also used to set the permission mask for the debug opening.
- At step 2 the Debug Authentication is configured using the DA_Config.xml file.
- The STiROT data initialization.
- An STiROT_DA.obk file example is provided in the STM32Cube_FW
- The STiROT data initialization.
- Option bytes configuration.
- The option bytes defined during the STiROT configuration will be programmed during the provisioning.
- Option bytes configuration.
- The step 3 is the provisioning step done using the Provisioning.bat script.
- This script is performing the following:
- Program the option bytes on the device.
- Configure the STiROT and DA on the device.
- And the two steps explained in the next sections.
- Install the code and data images.
- Set the final chosen product state.
- The step 3 is the provisioning step done using the Provisioning.bat script.
5. Code and image generation
The signed and encrypted user application code image and user data image are generated with STM32TrustedPackageCreator.
The user data are optional and chosen during the STiROT configuration.
These images are downloaded in the user flash download area. Area location and size that are defined during the STiROT configuration (See STiROT configuration section)
After authenticity verification, the STiROT decrypts the firmware code and data and will copy it in the execution slot. Execution slot location and size defined during the STiROT configuration.
With STM32Cube_FW the provisioning.bat script used during the device provisioning will continue to guide the user during images generation and installation.
With STM32CubeMx the tool interface will guide the user and the provisioning script located in the STM32CubeMx repository (see STM32H5_BootPath_CubeMx_getting_started).
5.1. User application code image generation
The following figure gives an overview of the user application code image generation.
The user application code binary file can be generated by any IDE.
STM32TrustedPackageCreator can be launched separately to generate the encrypted and signed image file using the same encryption and authenticity keys provisioned during the STiROT configuration (see previous figure).
With IAR Embedded Workbench IDE the STM32TrustedPackageCreator can be launched automatically through the postbuild command (see getting started with STiROT on STM32H573 wiki article)
In this case the image creation is done automatically during the user application compilation.
As sown in the figure, STM32TrustedPackageCreator is using a configuration file (STiRoT_Code_Image.xml).
A file example is available in the STM32Cube_FW and in the STM32CubeMx repository.
It can be edited using STM32TrustedPackageCreator (see getting started with STiROT on STM32H573 wiki article)
A dependency with a user data image version can be defined.
The next paragraphs will give some details about the mapping configuration and image format requirements for the user application to be compatible with STiROT.
During the STiROT configuration done with STM32TrustedPackageCreator, the firmware code download and execution area offsets are chosen (see getting started with STiROT on STM32H573 wiki article).
The STM32TrustedPackageCreator generates the stm32h573xx_flash.if file defining a vector table located at: 0x0C000000 + code execution slot offset + 0x400 (header size)
The header is a fixed defined size.
For IAR Embedded Workbench IDE, this file is located in the STiROT_Appli\EWARM directory.
Performing a new configuration will generate a new stm32h573xx_flash.if , so it’s mandatory to recompile the code to generate the correct related user application code binary.
As explained previously and shown in the previous figure, this binary file is the input to generate the signed and encrypted image using STM32TrustedPackageCreator.
On the left of the above figure: the user application code image structure written in a download flash area by the STiROT.
On the right of the above figure: the user application code structure written in the execution flash area by the STiROT.
As described in previous sections, the STiROT decrypts the firmware code before the copy to this execution area.
5.2. User Data Image generation
The following figure gives an overview of the user data image generation.
STM32TrustedPackageCreator need to be launched separately to generate the encrypted and signed image file using the same encryption and authenticity keys provisioned during the STiROT configuration. The same keys also used for the user application code image generation.
As sown in the figure, STM32TrustedPackageCreator is using a configuration file (STiRoT_Data_Image.xml).
A file example is available in the STM32Cube_FW.
It can be edited using STM32TrustedPackageCreator (see getting started with STiROT on STM32H573 wiki article)
A dependency with a user application code image version can be defined.
The next paragraph will give some details about the mapping configuration and image format requirements to be compatible with STiROT.
During the STiROT configuration done with STM32TrustedPackageCreator, the user data download and installation area offsets are chosen (see STM32_STiROT_DA_getting_started)
On the left of the above figure: the user data image structure written in a download flash area by the STiROT.
On the right of the above figure: the user application data structure written in the Obkey store area.
Note that the user data are stored in the Obkey area and not in a user flash area.
For the STM32CubeFW STiROT example (see STM32_STiROT_DA_getting_started), a data.bn file is provided with 64 bytes. These data are just used to be written back during user application execution and have no other meaning.
6. Product State setting
The following figure shows the possible product state.
(for more details refer to product lifecycle and Debug Authentication articles).
The provided script mentioned previously (Provisioning.bat) is guiding the user also during this phase (see STM32_STiROT_DA_getting_started).
At the end of the provisioning script execution, the product state can be chosen, and the related option byte will be automatically set.
The product state is chosen depending on the user application development phase and the wanted security level.
- Open:
- This state is mainly used during development phase since the device is fully open.
- Debug is fully open.
- The Trust Zone can be disabled or enabled (TZEN option byte programming).
- Bootloader can be used.
- This state is mainly used during development phase since the device is fully open.
- Provisioning:
- This state is used during the provisioning.
- It is the device state during the provisioning script execution (Provisioning.bat).
- So this state will not be part of the proposed state that can be chosen at the end of the script execution.
- The debug is only available when non secure user application is executed.
- The Trust Zone can be disabled or enabled (TZEN option byte programming).
- Bootloader can be used.
- Secure Firmware install can be launched in this state (not anymore possible in following states).
- This state is used during the provisioning.
- Provisioned:
- In this state the STiROT setup is done.
- Debug is available only when non secure user application is executed.
- Debug access for secure application can be available by launching the Debug Authentication (see Debug Authentication setting).
- The STiROT can launch the bootloader if the verification of the code located in the next isolation level is failing (authentication, integrity or missing code)
- In this state the STiROT setup is done.
- TZ-Closed:
- The Trust Zone closed state is used when the STiROT is provisioned and the secure user application (case 1) or the uROT+Secure user application (case2) (see section 5.1.2).
- For case 2, the uROT is allowing the update of the next isolation level (Code and Data).
- uROT can launch the bootloader if the verification of the code located in the next isolation level is failing (authentication, integrity or missing code).
- uROT can launch the bootloader if the verification of the code located in the next isolation level is failing (authentication, integrity or missing code).
- The debug is only available when non secure user application is executed.
- Debug access for secure application can be available by launching the Debug Authentication (see Debug Authentication setting).
- The Trust Zone closed state is used when the STiROT is provisioned and the secure user application (case 1) or the uROT+Secure user application (case2) (see section 5.1.2).
- Closed:
- This state is used when the product is fully provisioned.
- The debug is fully closed but can be open by launching the Debug Authentication (see Debug Authentication setting) .
- This state is used when the product is fully provisioned.
- Locked:
- This state is used when the product is fully provisioned, and no changes are done anymore.
- Locked is definitive product state that can’t be changed anymore, the embedded FW and product configuration can’t be modified by any method.
- The debug is definitively closed and can’t be reopen through debug authentication.
- No regression is possible anymore
- This state is used when the product is fully provisioned, and no changes are done anymore.
- Open:
7. Appendix STiROT
to add, slide available
7.1. Application development phase
The most efficient way to develop and debug an application is first to boot directly on user flash in the Open product state by stetting with STM32CubeProgrammer the UBE to 0xB4 and the SECBOOTADD to 0x0C000400 (by default the firmware execution offset is 0x0)
As long as the device is in open state, the user flash can be erased without performing a regression and a debugger can be connected without performing a debug authentication.
Once validated, the secure boot path can be activated :
- DA configuration: important that the Debug Authentication configuration is done correctly (see article "How to start with STiROT")
- provisioning the STiRoT configuration
- generating the images
- downloading and installing the images
If after provisioning the device is set in another state than open, the Debug Authentication process must be used to open the debugger.