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 describedoin the How_to_start_with_STM32CubeMX_STiROT_Boot_path_on_STM32H57 hands-on.
- The activation or not of the data image is done during the STiROT configuration.
- The data can be for instances used to store keys or any other secret information needed by the user. But for this 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 how to define the STiROT and Debug Authentication configuration.
Two configuration files (.obk) are generated that are needed later for the provisioning.
A script (Provisioning.bat) provided in the STM32Cube_FW, is guiding the user during the configuration definition and device programming.
The configuration management is step1 of the script execution.
3.1. STiROT configuration
The possible configuration options are described in the STiROT configuration detailed table.
The STiROT configuration options used by default are listed below (used in the STM32CUbeFW examples).
- User application images:
- One image: user application code image.
- Two images: one user application code image & one user application data images
- One image: user application code image.
- 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.
- Encryption and authentication key location (only ECDSA256 supported)
- 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:
- All the configurations can be chosen by directly editing this STiROT_Config.xml file or graphically using STM32TrustedPackageCreator.
- Default configuration parameters are visible in TrustedPackageCreator.
- Hidden parameters can be made visible by edditing the "Hidden" value in the STiROT_Config.xml file.
- 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).
- All the configurations can be chosen by directly editing this STiROT_Config.xml file or graphically using STM32TrustedPackageCreator.
When the STiROT configuration file (STiROT_Config.xml) is ready, based on this file the STM32TrustedPackageCreator is used to generate the file needed for the device provisioning (STiROT_Config.obk) (see How to start with ST-iROT article)
3.2. Debug Authentication configuration
Explanations about the Debug Authentication (DA) are available in the Introduction to Debug Authentication for STM32H5 MCUs article.
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.
8. Appendix STiROT
8.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:
- Configuration of DA and STiROT (see How to start with ST-iROT article)
- Encrypted and signed image(s) generation
- Provisioning of the device (option bytes programming, image(s) flashing and final product state setting).
8.2. STiROT Configuration detailed description
| Parameter | Hidden | Description | Additional controls/constraints |
|---|---|---|---|
| Product state minimal allowed | No | STiROT is executed only if the device is in the chosen minimum life cycle state (Open, Provisioning, Provisioned, TZ-Closed, Closed, Locked). | This information is duplicated from option bytes in order to control that the option bytes is well configured. |
| Number of images managed by ST-iRoT | No | 1: Firmware image only. Configuration selected for any application which does not manage secret information. 2: Firmware and data images. As example, in STiROT_OEMuROT bootpath, the data image contains the cryptographic keys of OEMuROT boot. |
Data image slot definition (size and offset) will be available trough STM32TrustedPackageCreator as soon as 2 images configuration is selected. |
| High speed clock activation | Yes | 0 : 64 MHz, default configuration 1: 200 MHz, best speed supporting the full range of temperature 2: 250 MHz, max speed clock |
|
| Is the firmware full secure | No | Yes : the firmware booted is full secure. As example STiROT_Appli provided in STM32H5 Cube. No : the firmware booted is made of a secure part and non-secure part. As example STiROT_Appli_TrustZone provided in STM32H5 Cube. |
The size of the secure area inside the firmware execution area must be specified as soon as the firmware is not full secure. In this configuration the image generation triggered by the post build command of the non secure project is preceded by an assembly command of the secure and non-secure binaries. |
| Firmware execution area offset | No | Offset from begin of the user flash memory.
It must me aligned on a sector start address. |
No overlap allowed between execution areas and download areas.
Firmware execution area cannot be mapped between the 2 download areas. |
| Firmware download area offset | No | Offset from begin of the user flash memory.
It must me aligned on a sector start address. |
No overlap allowed between execution areas and download areas.
Firmware execution area cannot be mapped between the 2 download areas. Both firmware and data download areas can overlap. In this case, the installation of a data and firmware image in a single execution using the dependency feature is not possible. |
| Firmware area size | No | Size of the firmware.
It must be a multiple of the sector size. |
No overlap allowed between execution areas and download areas.
Firmware slots definition should not exceed the user flash capacity. |
| Data area offset in HDPL2 OBkeys | No | Offset from the beginning of HDPL2 Obkeys area (0xFFD0900). | Range allowed from 0xFFD0900 to 0xFFD0BF0 : no overlap with HDPL3 OBKeys.
Parameter disabled for 1 image configuration. |
| Data slot size in HDPL2 OBKeys | No | Size of the data area in HDPL2 OBkeys. Maximum is 0x2F0. | Range allowed from 0xFFD0900 to 0xFFD0BF0 : no overlap with HDPL3 OBKeys.
Parameter disabled for the “1 image” configuration. |
| Data download area offset | No | Offset from begin of the user flash memory.
It must me aligned on a sector start address. |
Both firmware and data download areas can overlap. In this case, the installation of a data and firmware image in a single execution using the dependency feature is not possible. |
| Data download slot size | Yes | Offset from begin of the user flash memory.
It must me aligned on a sector start address. |
Must be 0x2000 for STM32H5 product (parameter hidden). |
| Size of the secure area inside the firmware execution area | No | Size of the secure part of the firmware image.
It must be a multiple of the sector size. |
Parameter disabled for the “firmware full secure” configuration.
STiROT will configure the MPU to allow execution only for the secure part of the firmware. Then, it is up to the secure application to update (disable, re-configure) the MPU configuration depending on its needs. |
| SRAM2 erasing in case of reset | Yes | Yes (default value) : the SRAM2 is automatically erased by hardware in case of reset. Ensure that all secrets are erased in case of reset.
No : SRAM2 is not erased. Less secure configuration but it can be required when the application has no other possibility to manage persistent information in SRAM2. |
This information is duplicated from option bytes in order to control that the option bytes is well configured. |
| SRAM2 ECC management activation | Yes | Yes (default value) : a reset will be generated in case of ECC detection. ECC is a mechanism to prevent mechanisms prevent external attacks.No : ECC not managed. Less secure configuration but it can be selected if hardware attack is not possible. | This information is duplicated from option bytes in order to control that the option bytes is well configured. |
| Encryption key | No | Key used to encrypt the firmware and data images | When this key is regenerated, both firmware and data images must be processed with STM32TrustedPackageCreator “Image Gen” tab (STiROT_Code_Image.xml & STiROT_Data_Image.xml) |
| Authentication key | No | key used to authenticate the firmware and data images. | When this key is regenerated, both firmware and data images must be processed with STM32TrustedPackageCreator “Image Gen” tab (STiROT_Code_Image.xml & STiROT_Data_Image.xml) |
| Output File | No | Name of the output file |
8.3. STiROT Config.obk file format
- Important note: endianness: uint32_t 0x01234567 is represented in obk file as 0xx67452312
| Offset | Size | Type | Description |
|---|---|---|---|
| 0 | 4 | uint32_t | sdp command header : destination address |
| 4 | 4 | uint32_t | sdp command header : data size address |
| 8 | 4 | uint32_t | sdp command header : encryption enabled/disabled (1/0) |
| 12 | 32 | array | SHA256 of the following data content (from offset 44 to 268) |
| 44 | 1 | uint8_t | Number of images managed by ST-iRoT |
| 45 | 1 | uint8_t | 250 Mhz / 200 Mhz / 64 Mhz : 2 / 1 / 0 |
| 46 | 1 | uint8_t | Firmware full secure (1/0) |
| 47 | 1 | uint8_t | Jump into ST bootloader when no valid image(s) |
| 48 | 4 | uint32_t | Firmware execution area offset |
| 52 | 4 | uint32_t | Firmware download area offset |
| 56 | 4 | uint32_t | Firmware area size |
| 60 | 4 | uint32_t | Data area offset in HDPL2 OBkeys |
| 64 | 4 | uint32_t | Data slot size in HDPL2 OBKeys |
| 68 | 4 | uint32_t | Data download area offset |
| 72 | 4 | uint32_t | Data download slot size |
| 76 | 4 | uint32_t | Size of the secure area inside the firmware execution area (meaningful only when the firmware is not fully secure. |
| 80 | 4 | uint32_t | SRAM2 erasing in case of reset |
| 84 | 4 | uint32_t | SRAM2 ECC management activation |
| 88 | 4 | uint32_t | Product state minimal allowed (0x0000ED00,Open / 0x00001700,Provisioning / 0x00002E00,Provisioned / 0x0000C600,TZ-Closed / 0x00007200,Closed / 0x00005C00,Locked |
| 92 | 70 | array | Encryption private key (MCU Boot format) |
| 162 | 2 | array | Reserved |
| 164 | 91 | array | Authentication public key (MCU Boot format) |
| 255 | 13 | array | Reserved (Global alignment of OBKkeys data on 16 bytes) |
8.4. STiROT DA.obk file format
- Important note: endianness: uint32_t 0x01234567 is represented in obk file as 0xx67452312 L
| Offset | Size | Type | Description |
|---|---|---|---|
| 0 | 4 | uint32_t | sdp command header : destination address |
| 4 | 4 | uint32_t | sdp command header : data size address |
| 8 | 4 | uint32_t | sdp command header : encryption enabled/disabled (1/0) |
| 12 | 32 | array | SHA256 of the following data content (from offset 44 to 108) |
| 44 | 32 | array | SHA256 of the DA root authentication public key |
| 76 | 32 | array | Permissions (cf DA Getting_started for more details) |
8.5. STiROT Data.obk file format
- Important note: endianness: uint32_t 0x01234567 is represented in obk file as 0xx67452312
| Offset | Size | Type | Description |
|---|---|---|---|
| 0 | 4 | uint32_t | sdp command header : destination address |
| 4 | 4 | uint32_t | sdp command header : data size address |
| 8 | 4 | uint32_t | sdp command header : encryption enabled/disabled (1/0) |
| 12 | 32 | array | SHA256 of the following data content (from offset 44 to 108) |
| 44 | 4 | uint32_t | Version n of the firmware image |
| 48 | 4 | uint32_t | Version n-1 (previous) of the firmware image |
| 52 | 4 | uint32_t | Version n of the data image |
| 56 | 4 | uint32_t | Version n-1 (previous) of the data image |
| 60 | 32 | array | Reserved |
| 92 | 16 | array | Reserved |
8.6. STiROT execution status
The STiROT is executed as a black box, but there is a way to verify the steps that have been executed and in case of an issue where the STiROT execution has stopped.
For each HDPL Obkey there are four bytes reserved for status log.
See following table.
| Item # | Executed step | Status coding | Description |
|---|---|---|---|
| 1 | STIROT_INIT_DONE | 0x00000001UL | Device intialization done. STiROT bootpath selected. STiROT executed |
| 2 | STIROT_CONFIG_DONE | 0x00000002UL | STiROT configuration according STiRoT_Config.obk is verified to be correct in Obkeys HDPL1 |
| 3 | STIROT_SECURITY_DONE | 0x00000004UL | Security activated (MPU, SAU, GTZC, Tamper, Flash, RAM). Obkeys STiROT configuration verified to be correct |
| 4 | STIROT_SLOT_PRIMARY_1_VALID | 0x00000010UL | Authenticity and integrity verified for the user application FW image in the execution slot |
| 5 | STIROT_SLOT_PRIMARY_2_VALID | 0x00000020UL | Authenticity and integrity verified for the data image in the HDPL2 Obkey secure storage |
| 6 | STIROT_SLOT_SECONDARY_1_VALID | 0x00000040UL | Authenticity and integrity verified for the user application FW image in the download slot |
| 7 | STIROT_SLOT_SECONDARY_2_VALID | 0x00000080UL | Authenticity and integrity verified for the data image in the download slot |
| 8 | STIROT_PARSING_DONE | 0x00000100UL | Slots parsing done (process MCUBoot) |
| 9 | STIROT_INSTALLATION_DONE | 0x00000200UL | Image in the download slot (1 or 2 images depending on config) are installed |
| 10 | STIROT_VALIDATION_DONE | 0x00000400UL | Primary slots analysis completed to verify which image is valid (integrity and authenticity) |
| 11 | STIROT_JUMP_BL | 0x00001000UL | At least one image is not valid -> embedded bootloader execution |
| 12 | STIROT_JUMP_APPLI | 0x00002000UL | All images (1 or 2 depending on config) are valid, application execution |
| 13 | STIROT_NOJUMP | 0x00004000UL | At least one image is not valid, but embedded bootloader execution is not allowed(option defined in STiROT_Config.xml) |
Following figure shows an example of a discover done with STM32CubeProgrammer after an STiROT provisioning has been completed and the product state has been set in CLOSED.
(STM32CubeProgrammer => Debug Authentication => Discover => see log window)
The STiROT is executed in HDPL1, so the status given by the Discover command corresponds to this isolation level.
For this example the indicated code is 0x2737.
- The digit 0x0007, is obtained by the sum of item 1, 2 and 3 of the above table. It means that all these operation have been executed successfully (STIROT_INIT_DONE; STIROT_CONFIG_DONE ; STIROT_SECURITY_DONE).
- The digit 0x0030 is obtained by successful execution of item 4 and 5 of the above table.
- The digit 0x0700 is obtained by successful execution of item 8, 9, and 10 of the above table.
- The digit 0x2000 is obtained by successful execution of item 12 of the above table => so the jump to user application (STIROT_JUMP_APPLI )