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 for the proposed "How to"
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.
- This default file contains already the configuration listed below.
The STiROT configuration listed below is used for the proposed "how to":
- Two images: one user application code image & one user application data images
- User application full secure.
- Flash location for user application (defined as offset from the beginning of the user flash, aligned with a sector start address; for this example: 0x00000000).
- Flash location for the user application download (defined as offset from the beginning of the user flash, aligned with a sector start address; for this example: 0x001E0000).
- Firmware area size (for download and execution), aligned on sector size (for this example: 0x00020000),
- Flash location for the data download (defined as offset from the beginning of the user flash, aligned with a sector start address; for this example: 0x001DE000).
- 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).
Note::
There is no execution area defined for the data. Once the data image is decrypted by the STiROT it is encrypted using a DHUK (Derived Hardware Unique Key, not accessible by a user) and stored encrypted in the secure storage area (for this example: HDPL2 secure storage and DHUK is used) (see STiROT_for_STM32H5 article).
When the STiROT configuration is ready in TPC, clicking "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 for the proposed "How to"
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 ensure that only the authorized person can access or modify the content of the device.
Without a correct DA provisioning it is not possible to reopen the debugger for these product states different than OPEN.
As shown in figure1, for this example TrustZone is activated. In this case the Debug Authentication is done through a root key and a root certificate (for TZ=0 it's done through a password but only a full regression is possible). (refer to Debug_Authentication_STM32H5_How_to_Introduction for more details)
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
This file can be edited using STM32TrustedPackageCreator.
The root key can be regenerated for a custom protection of the device (important for a commercial product).
But for this example or for trials it is advised to use the default provided key, because if the new generated key is lost you can't reopen the device or perform a regression.
The permission mask edited graphically in TPC, is used to define the authorization that the owner of the root key and certificate will have.
These permissions are stored in what is called the SOC_MASK and is programmed into de device during the provisioning step.
Details about the Debug Authentication are available in the Debug_Authentication_for_STM32H5_MCUs article.
When the DA configuration is ready in TPC, clicking "Generate OBkey" button in TPC generates the related encrypted file:
- STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\DA\Binary\DA_Config.obk
This file is used by the provisioning script to set the DA configuration into the device.
4. Firmware code and data images generation
The step 2 of the script (Provisioning.bat in STM32CubeFW) is the user application firmware image generation.
For the proposed "how to", there are two signed and encrypted images to be generated:
- User application firmware image
- The user data image
To be compatible with STiROT there are some specific format for these two files. For the STM32CubeFW examples you don't need to take care of these formats. But in case of own development, you will need to understand it, at least to define the correct size of your user application code and data. (refer to the STiROT_for_STM32H5 article)
4.1. User application code image generation
The described example is for a full secure user application.
So for the STiROT configuration with STM32TrustedPackageCreator (TPC) you need to tick the "Is the firmware full secure".
And in TPC the "Size of the secure area inside the firmware execution area" is grayed automatically and can't be filled-out.
But even in case of a secure and non-secure user applications, only one firmware image is generated containing both.
There are two ways to generate an encrypted and signed user application firmware image:
- Generate the binary and image using an IDE. The image is generated through a postbuild command, the TPC is launched automatically by the IDE at the end of the firmware compilation.
- If the user firmware binary is available, TPC can be used to generate the image.
How to proceed for both ways is explained in the How_to_start_with_ST-iROT_on_STM32H573 article
4.2. User data image generation
The described example is using a data file.
These data are just used to be written back during user application execution and have no other meaning.
So for the STiROT configuration with STM32TrustedPackageCreator (TPC), you need to select "firmware and data images".
For the data image generation you need to use TPC as described in the How_to_start_with_ST-iROT_on_STM32H573 article
4.2.1. 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.