Target description
The purpose of this article is to provide the background needed to understand and execute the related How_to_start_with_ST-iROT_on_STM32H573 hands-on
This step by step is based on the ST provided STM32CubeFW example (STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\Applications\ROT\STiROT_Appli).
Another STiROT how to start using STM32CubeMx with a secure and non-secure user applications is available in the article How_to_start_with_STM32CubeMX_STiROT_Boot_path_on_STM32H57.
This introduction article reviews some technical notions needed to understand the STM32CubeFW example.
More detailed explanations about STiROT are available in the two following articles:
- STiROT overview article: STiROT
- STiROT for STM32H5: STiROT_for_STM32H5.
Reminder
- STiROT states for ST Immutable Root of Trust and is an implementation of Secure Boot and Secure Firmware Update security features.
- The STiROT is embedded in all STM32H57x devices.
- Since the STiROT is requiring hardware cryptographic accelerator, it is not supported on STM32H6x and STM32H503 products.
1. STiROT services
The two provided STiROT services will be used in the How_to_start_with_ST-iROT_on_STM32H573.
- 1) The Secure Boot:
- Verification of the Integrity and Authenticity of the application code before every execution.
- Verification of the Integrity and Authenticity of the application code before every execution.
- 2) The Secure Firmware Update:
- Detection 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 case for the how to example
There are two possible use cases explained in the STiROT_for_STM32H5 (one or two boot stages)
The how to example is using the case 1: the full secure user application is executed after the STiROT (1 boot stage)
The figure below shows the related boot path.
As shown in the figure, two option bytes need to be programmed to define the wanted bootpath.
- The Trust Zone needs to be enabled
- The UBE (Unique Boot Entry) needs to be set to select the STiROT.
The programming of these Option Bytes is done automatically using the provided provisioning script.
The next sections will explain what is required and the steps to configure the bootpath before launching the script.
As shown in the figure below, with this chosen boot path the STiROT is the first application executed after any reset.
STiROT application is executed in temporal isolation 1 (HDPL1) (refer to Introduction to Silicon device life cycle article)
- This figure shows also the download areas for the encrypted and signed user application firmware and/or data image(s) to be installed.
- When installed the user application firmware is located in the execution area .
- When installed (if applicable) the data are stored (reencrypted) in a secure storage area dedicated to the related isolation level (HDPL2 OB Keys for the how to example).
- The user application needs to have secure part (at least the vector table and the reset handler) or can be full secure as for the "how to" hands-on.
The Firmware/Data image installations and update is adressed in the next sections.
When the installation is done, at each power-on or reset of the device, the STiROT is executed first.
- When the STiROT is executed, the debugger is deactivated and there is no possibility of access from user.
- After a successful verification of the user application (integrity and authenticity), the STiROT executes the user application in temporal isolation level 2 (HDPL2 for this example) and in secure mode.
- In case there is a verification failure of the user application code, the STiROT will execute the embedded Bootloader (refer to AN2606) to download a new user app code and/or data.
- As mentioned, the How_to_start_with_ST-iROT_on_STM32H573 hands-on uses a full secure user application. An example with secure and non-secure user application is described in the How_to_start_with_STM32CubeMX_STiROT_Boot_path_on_STM32H57 hands-on.
- The definition that the user application is full secure is done during the STiROT configuration.
- The activation or not of the data image is also done during the STiROT configuration.
- The data can for instances be used to store keys or any other secret information needed by the user. But for this "how to" example, it is just data without meaning to show the principle and to be read back through the user application.
3. STiROT and Debug Authentication configuration
This chapter describes the STiROT and Debug Authentication configuration used for the "how to"
(read STiROT_for_STM32H5 article for more details.
- Two configuration xml files are provided in the STM32CubeFW with default value.
- The STM32TrustedPackageCreator (TPC) is used to graphically update to the chosen configuration.
- TPC will save the modification in the configuration xml file.
- Two OB Key files are generated with TPC. These two encrypted files are used during the provisioning of the device.
A script (Provisioning.bat) provided in the STM32Cube_FW, is guiding the user during the configuration definition and device programming.
STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\STiROT\provisioning.bat <br.
The configuration management is the step1 of the script execution.
3.1. STiROT configuration
All possible configuration options are described in the appendix table of the STiROT_for_STM32H5 article.
For the STiROT configuration the following xml file is open and edited with STM32TrustedPackageCreator:
STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\STiROT\Config\STiRoT_Config.xml
The STiROT configuration listed below is used for the proposed "how to":
- User application images:
- Two images: one user application code image & one user application data images
- Two images: one user application code image & one user application data images
- User application secure and non-secure:
- User application full 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.
- Encryption and authentication key location (only ECDSA256 supported)
- Minimal product state: OPEN, this means that the STiROT will allow the user firmware execution for all the possible product states.
- 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. (see How to start with ST-iROT article).
- Two keys are provisioned: a key for the authentication and a key for the file encryption.
- User application images:
When the STiROT configuration is completed in TPC, the "Generate OBkey" button in TPC generates the related encrypted file:
STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\STiROT\Binary\STiRoT_Config.obk
This file is used by the provisioning script to set the STiROT configuration into the device.
3.2. Debug Authentication configuration
Detail explanations about the Debug Authentication (DA) are available in the Introduction to Debug Authentication for STM32H5 MCUs article.
If the product is set to a different state than OPEN, a debug authentication is needed to insure that only the authorized person can access or modify the content of the device.
As shown in figure1, for this example TrustZone is activated. So the Debug Authentication is done through a root key and a root certificate (for TZ=0 it's done through a password).
A default configuration file is provided in the STM32CubeFW:
STM32Cube_FW_H5_V1.x.x\Projects\STM32H573I-DK\ROT_Provisioning\DA\Config\DA_Config.xml
The DA configuration is an important step defining the location of the root key, the regression and debug opening permissions for the owner of the root key and root certificate.
These permissions are stored in what is called the SOC_MASK and is programmed into de device during the provisioning step explained in next section.
More explanations and how to practically define the DA configuration is explained in the How to start with ST-iROT article.
- In summary
- The Debug Authentication is configured using the DA_Config.xml file. (STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\DA\Config)
- This xml file can be directly edited or graphically using STM32TrustedPackageCreator.
- A default root key is provided in the STM32Cube_FW. A new key can be generated using STM32TrustedPackageCreator.
- The permission mask for the debug opening is set using STM32TrustedPackageCreator.
- The DA_Config.obk file is generated using STM32TrustedPackageCreator. This file is used during the device provisioning.
- The Debug Authentication is configured using the DA_Config.xml file. (STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\DA\Config)
- Note: for a commercial product, it is important to regenerate the debug authentication root key (key_1_root.pem), since the key provided in the STM32CubeFW is public.
When the DA configuration file (DA_Config.xml) is ready, based on this file the STM32TrustedPackageCreator is used to generate the file needed for the device provisioning (DA_Config.obk) (see How to start with ST-iROT article)
4. Firmware code and data images generation
The step 2 of the script (Provisioning.bat in STM32CubeFW) is the user application firmware image generation and the optional user data image
The required format for the user application firmware and user data to be compatible with STiROT are described in this chapter.
These images needs to be encrypted and signed.
The user data image management can be activated or not during the STiROT configuration.
The STM32CubeFW provides two examples:
- STiROT_Appli: full secure application code example with data
- STiROT_Appli_Trustzone: secure and non-secure application code example with data
4.1. User application code image
The following figure gives an overview of the user application code image generation.
To be installed successfully by the STiROT (see next chapter) this image needs to be encrypted, signed and aligned with the flash memory map config.
The user application can be full secure or split in a secure and a non-secure application. But a single image will be generated (see CubeFW examples mentioned above)
4.1.1. Memory mapping constraints for the user application code
The following figure gives some details about the mapping configuration and image format requirements for the user application to be compatible with STiROT.
- The header is a fixed size of 0x400.
- The "Magic" is a reserved 16 bytes memory region used to manage the installation
- TLV is a reserved 296 bytes memory region placed at the end of the image. It states for Type Length Value and contains metadata used to manage the images.
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.
For a practical example how to set the firmware code download and execution area offsets, refer to How to start with ST-iROT article.
4.1.2. User application code image generation
The user application code binary file can be generated by any IDE.
The mandatory generation of the encrypted and signed image is done with STM32TrustedPackageCreator.
- With an IDE supporting the postbuild command, the STM32TrustedPackageCreator is launched automatically at the end of the compilation (see How to start with ST-iROT article). In this case the encrypted and signed image creation is done automatically during the user application compilation.
- STM32TrustedPackageCreator can be launched separately to generate from a binary file, an encrypted and signed image file using the same encryption and authenticity keys provisioned during the STiROT configuration (see previous figure).
Reminder: the provisioning script of the STM32CubeFW, mentioned above, is guiding the user through all the steps
As sown in the figure below, STM32TrustedPackageCreator is using a configuration file (STiRoT_Code_Image.xml).
A file example is available in the STM32Cube_FW repository (\STM32Cube_FW_H5\Projects\STM32H573I-DK\ROT_Provisioning\STiROT\Image).
It can be edited directly in the xml file or graphically by using STM32TrustedPackageCreator (see How to start with ST-iROT article).
A dependency with a user data image version can be added in order to have simultaneous installation of firmware code and data images.
The related version of the data image is defined in the STiRoT_Code_Image.xml and can be updated accordingly.
The STM32TrustedPackageCreator generates the stm32h573xx_flash.if file defining a vector table located at: 0x0C000000 + code execution slot offset + 0x400 (header size).
For IAR Embedded Workbench IDE, this file is located in the STiROT_Appli\EWARM directory.
In case of configuration modification, it is mandatory to recompile the user application project to generate the correct binary file.
4.2. User Data Image
As mentioned previously, the data are optional and defined during the STiROT configuration.
To be installed successfully by the STiROT (see next chapter) this image needs to be encrypted, signed and aligned with the flash memory map config.
4.2.1. Memory mapping constraints for the user data
The following figure gives some details about the mapping configuration and image format for the user data to be compatible with the STiROT.
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.
4.2.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 are 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 (STM32Cube_FW_H5\Projects\STM32H573I-DK\ROT_Provisioning\STiROT\Image).
It can be edited directly in the xml file or graphically by using STM32TrustedPackageCreator (see How to start with ST-iROT article)
The user data download offset is defined in the xml file.
A dependency with a user application firmware image version can be added in order to have simultaneous installation of firmware code and data images.
The related version of the user application firmware image is defined in the STiRoT_Data_Image.xml and can be updated accordingly.
5. Provisioning
The step 3 of the script (Provisioning.bat in STM32CubeFW) is the provisioning of the device
The provisioning includes the option bytes programming, the image(s) flashing and the final product state setting.
How to practically perform the provisioning is explained in the How to start with ST-iROT article.
The provisioning is straighforward if the provisioning script is used. It will guide you step by step.
5.1. STiROT and DA provisioning
The STiROT and DA configurations are programmed on the device based on the two obk generated files.
The figure below gives an overview of the provisioning and the needed input files.
- Above figure points 1 and 2 shows the generation of the configuration OBK (STiROT_Config.obk and DA_Config.obk) as explained in chapter 3.
- The STiROT_Config.obk configuration file is used during the provisioning to store the STiROT configuration in the OB key level1 secure storage of the device.
- The DA_Config.obk configuration file is used during the provisioning to store the Debug Authentication configuration in the OB key secure storage of the device.
- The STiROT_Data.obk file contains some working data, for instance the installed firmware version. For the provisioning it should be initialized with "zero" values. This file is provided in the STM32CubeFW.
- Above figure point 3 shows the provisioning script that also launches four different scripts. (see How to start with ST-iROT article).
- update_appli_setup.bat: setting of the StiROT configuration (different settings, download and execution area, postbuild path for IDE) and update of specific files used for tests.
- obkey_provisioning.bat: configure Obkeys and set the option to boot in STiROT (UBE option byte).
- update_ob_setup.bat: updating of option byte.
- ob_flash_programming.bat : removal of the protection and erase the use flash, configure the option bytes according STiROT configuration and images download
- All these scripts are located in STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\STiROT with related log files giving a trace of the executed operations.
- As mentioned previously the provisioning.bat script is guiding you during the complete procedure and is launching automatically the scripts mentioned above.
- The provisioning script as shown in the figure above, includes also the two topics explained in next sections (code and data flashing in the dowload area and the final product state setting)
- Note: option bytes configuration such as SECWM, SRAM2_RST, SRAM2_ECC are extracted from STiROT configuration. Others option bytes such as TZ_EN, SECBOOT_LOCK are configured with a fixed value.
- Note: In order to mitigate the risk of attack, some major information are duplicated between option bytes and Obkeys configuration such as sram2_ecc, sram2_rst, secure watermark, product_state. (see also appendix STiROT Configuration detailed description table).
- Note: option bytes configuration such as SECWM, SRAM2_RST, SRAM2_ECC are extracted from STiROT configuration. Others option bytes such as TZ_EN, SECBOOT_LOCK are configured with a fixed value.
5.2. User application firmware and data installation
The following figure summarizes the steps for the user application firmware and data installation.
The download area locations and sizes are defined during the STiROT configuration (See STiROT configuration section).
The execution slot location and size are also defined during the STiROT configuration.
For the CubeFW STiROT example, the user application code and data are in isolation level 2 (HDPL2).
With STM32Cube_FW the provisioning.bat script used during the device provisioning will continue to guide the user during images generation and installation.
- The encrypted user application code is written in the download area
- After authenticity and integrity verifications, the user application code is decrypted and written in the user flash execution area
- The encrypted data are written in the download area
- The data authenticity and integrity are verified. Then the data are decrypted and re-encrypted with the DHUK (Derived Hardware Unique Key) and stored in the secure storage (HDPL2 OB Keys area) (For explanation about the DHUK, please refer to the "Secure storage" wiki article).
A firmware or data update is possible in any product state (except Locked state, see next chapter) through launch of the embedded bootloader.
A practical example is shown in the How to start with ST-iROT article
- The embedded bootloader is used to copy the encrypted new user application firmware and/or new user data in the user flash download area
- At next hardware reset, the STiROT installs the update(s) after authenticity and integrity verifications
5.3. Product State setting
Once the user application code and data are flashed into the device, the script is used to set the final state.
This is the last step done through the script.
The following figure shows the possible product state.
(for more details refer to product lifecycle and Debug Authentication wiki 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).
- Embedded 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).
- Embedded Bootloader can be used.
- Secure Firmware install can be launched in this state (not anymore possible in following states).
- Partial or full regression are possible.
- 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 embedded bootloader if the verification of the code located in the next isolation level is failing (authentication, integrity or missing code)
- Partial or full regression are possible.
- 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 embedded bootloader if the verification of the code located in the next isolation level is failing (authentication, integrity or missing code).
- uROT can launch the embedded 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).
- Partial or full regression are possible.
- 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) .
- Partial or full regression are possible.
- This state is used when the product is fully provisioned.
- Locked
- Locked is final product state that can’t be changed anymore.
- The debug is definitively closed and can’t be reopen through debug authentication.
- No regression is possible anymore.
- Locked is final product state that can’t be changed anymore.
- Open:
6. Provisioning without uploading a user application image or user data image
The previous chapters indicate the different steps according to the STM32CubeFW provisioning script and the related examples.
But it is also possible to make the provisioning of the device without uploading a user application firmware or user data.
- If after a reset the STiROT detects that no valid code is present in the download user flash area, it will start the embedded bootloader. (with the correct setting of the STiROT_Config.xml, see below)
- The encrypted and signed user application firmware image and the optional user data image is/are copied in the download using one of the supported bootloader interface (USART, SPI, I2C, I3C, USB, FDCAN).
- At next reset the STiROT:
- If a user application firmware image is present in the download area: after authenticity and integrity verifications, the firmware image is decrypted and installed in the execution area.
- If a data image is present in the download area: after authenticity and integrity verifications, the data image is decrypted and copied in the secure storage (Obkey HDPL2) after encryption using the DHUK.
The figure below gives an overview (click on the picture to see it full screen)
- The embedded bootloader will start only if the correct option is selected in the STiROT_Config.xml file
- This file can be directly updated using a text editor
- Or the "Hidden" can be set to "0" in order to see this option setting in the STM32TrustedPackageCreator
- It is stronly advised to reuse the scripts provided in the STM32CubeFW (see How to start with ST-iROT article) and to only comment out the "Download images" part of the ob_flash_programming.bat (one of the scripts launched by the provisioning.bat script)
7. User application firmware update and user data update
When the user application code and user data are installed into the device and that the final product state is set, it is possible to update the firmware or the data (unless the device is in "Locked" product state).
For that, the code executed after the STiROT needs to include the possibility to launch the embedded bootloader in order to upload the new image in the download area.
At next reset the STiROT will install it after authenticity and integrity verifications. (same principle as explained in previous chapters).
An example is shown in the How to start with ST-iROT, section 6.5.