This article gives an overview of the OEMiRoT and the OEMuRoT solutions integrated in STM32H5.
The steps for using them are explained in the wiki pages. Getting started with STM32H5 security
List of applicable products:
| Type | Products |
|---|---|
| Microcontroller | STM32H573xx, STM32H563xx, STM32H562xx, STM32H533xx, STM32H523xx, STM32H503xx |
1 OEMiRoT/OEMuRoT presentation
1.1 Overview
OEMiRoT stands for OEM immutable (unchangeable) Root of Trust and acts as a first boot stage. OEMiRoT is an example based on the MCUboot open-source software (refer to mcuboot) provided with STM32CubeH5. OEMiRoT offers two services:
- The Secure Boot (root of trust service) is an immutable code, which is always executed after a system reset. It checks static protections (Options Bytes), activates runtime protections and then verifies the authenticity and integrity of the user application code before every execution.
- The Secure Firmware Update application is an immutable code that detects a new firmware image candidate. It checks its version (version downgrade prevention), authenticity, and integrity before installing it after decryption.
An OEM updatable RoT (OEMuRoT) can be generated by compiling OEMiRoT_Boot project with OEMUROT_ENABLE switch activated. OEMuRoT acts as a second boot stage after STiRoT and provides the same two services: Secure boot and secure firmware update. Both OEMiRoT and OEMuRoT examples are generated based on the OEMiRoT_Boot project with the switch OEMUROT_ENABLE activated or not.
1.2 Protection measures and security strategy
Cryptography ensures integrity, authentication, and confidentiality. However, the use of cryptography alone is not enough: a set of measures and system-level strategies are needed for protecting critical operations and sensitive data (such as a secret key), and the execution flow, to improve security robustness. On STM32H5, the security strategy is based on:
- Product life cycle: product state CLOSED or LOCKED must be selected to ensure that the JTAG debugger cannot access the device, except to execute the DA process (more details in Debug Authentication for STM32H5 wiki article).
- Boot configuration: BOOT_UBE, SECBOOT_LOCK , SECBOOTADD, NSBOOT_LOCK and NSBOOTADD option bytes are configured to establish a chain of trust, by forcing the system to boot on system flash memory (STiRoT) or user flash memory (OEMiRoT).
- Antitamper protection: the antitamper protection is used to protect sensitive data from physical attacks. The antitamper protection is activated at the start of the OEMiRoT_Boot project and remains active during OEMiRoT_Appli execution. In case of tamper detection, sensitive data in SRAM2, caches, and cryptographic peripherals are immediately erased, and a reboot is forced. Both external active tamper pins and internal tamper events are used.
- MPU: The MPU is a memory protection mechanism that allows specific access rights to be defined for any memory-mapped resources of the device: flash memory, SRAM, and peripheral registers. The MPU is configured to limit the execution surface to the code section of the OEMiRoT_Boot project during its execution then extended to the application code section after verifying its integrity and its authenticity. This protection is dynamically managed at runtime.
- HDP: HDP area is configured to cover the whole OEMiRoT_Boot project code area to prevent any execution out of the OEMiRoT_Boot execution. When jumping in the application, the temporal isolation (HDP level) is increased from HDPL1 to HDPL2 making the OEMiRoT_Boot project code no longer accessible.
- OBkeys: HDPL1 OBkeys (HDPL2 OBkeys for OEMuRoT) are a protected and isolated area used to store secrets such as encryption and authentication cryptographic keys. This area is no longer accessible when switching from HDPL1 to HDPL2 or to HDPL3. Data stored in this area is encrypted with a key derived from HUK.
- WRP: write protection is used to ensure OEMiRoT_Boot code immutability as requested by the state-of-the-art standards in secure boot implementation. In the OEMiRoT_Boot project, the system has been configured to make the OEMiRoT_Boot code as immutable.
- RAM ECC: RAM ECC is a mechanism to prevent memory corruption. A reset is generated in the case of RAM ECC detection.
- RAM Erase on reset: Data in SRAM2 is automatically erased when a system reset occurs.
See also STM32H503 Reference manual and STM32H573/STM32H56x Reference manual for more descriptions on each feature.
Notes:
- WRP and HDP protections cannot be activated when the OEMUROT_ENABLE switch is activated.
- There is no OBkeys on STM32H503. Secrets such as encryption and authentication cryptographic keys are stored in the user flash under HDP protection. See also Memories layout
1.3 OEMiRoT/OEMuRoT activation
On STM32H5, OEMiRoT/OEMuRoT activation is done by:
- Configuring the option bytes to boot on OEMiRoT or STiRoT.
- Configuring secrets: authentication and encryption keys used by OEMiRoT or OEMuRoT.
- Building OEMiRoT_Boot binary in the selected configuration (OEMiRoT or OEMuRoT).
All these operations are part of the provisioning process.
There are two different use cases:
- One boot stage, OEMiRoT: OEMiRoT_Boot project binary is built in OEMiRoT configuration. OEMiRoT directly manages the user application binary.
- Two boot stages, STiRoT + OEMuRoT: OEMiRoT_Boot project binary is built in the OEMuRoT configuration. STiRoT integrated inside the STM32H5 manages an updatable boot stage (OEMuRoT), which manages the user application binary.
See also secure boot for STM32H5 article.
The following table identifies the configuration available on STM32H5:
| RoT type | STM32H573/H533 | STM32H56x/H523 | STM32H503 | ||||||
|---|---|---|---|---|---|---|---|---|---|
| Swap (2 slots) |
Overwrite (2 slots) | Overwrite (1 slot) | Swap (2 slots) |
Overwrite (2 slots) | Overwrite (1 slot) | Swap (2 slots) |
Overwrite (2 slots) | Overwrite (1slot) | |
| OEMiRoT | X | X | X | X | X | ||||
| OEMuRoT | X | X | |||||||
1.3.1 One boot stage: OEMiRoT on STM32H503
OEMiRoT is generated by compiling the OEMiRoT_Boot project with OEMUROT_ENABLE switch deactivated.
This figure depicts the secure boot and update processes, demonstrating all necessary steps to boot the user application code image from user flash memory:
- In CLOSED or LOCKED product state with NSBOOT_LOCK and NSBOOTADD configured to boot on OEMiRoT located in the user flash memory, OEMiRoT is the first application executed in temporal isolation 1 (HDPL1).
- OEMiRoT checks if a new candidate image is stored in the application code and/or application data slots. A magic to trigger the installation must be detected (see also Images generation).
- If any, OEMiRoT decrypts it/them in place. See Features list for more details on PRIMARY_ONLY configuration slot mode.
- OEMiRoT controls the integrity, the authenticity, and the antirollback counter of the application data and/or code images.
- If successful, OEMiRoT saves the new images counter in the NV counters region for the antirollback verification then executes the user application in HDPL3. The jump to the user application code is done using a service from RSS located in the system flash memory. This service increases the temporal isolation (HDP level) HDPL1 to HDPL3 making the OEMiRoT_Boot project code and the secrets no longer accessible.
- In case of failure, the bootloader is started in HDPL3 to provide the capability to download a new image
Note: For security robustness, when OEMiRoT jumps into the user application, the MPU is configured to ensure that only the user application code area is allowed to be executed (execution surface controlled via MPU configuration). It is the user application responsibility to reconfigure the MPU to fit with its security needs.
1.3.2 One boot stage: OEMiRoT on STM32H573 / STM32H56x / STM32H533 / STM32H523 with overwrite strategy
OEMiRoT is generated by compiling OEMiRoT_Boot project with OEMUROT_ENABLE switch deactivated.
This figure demonstrates secure boot and update processes, displaying all steps required to boot user application code from flash memory. In this example, to simplify the presentation, the optional data image management is not activated (but data images are managed as code images) and the upgrade strategy is overwrite:
- In CLOSED or LOCKED product state with BOOT_UBE option byte configured to boot on OEMiRoT, OEMiRoT located in the user flash memory is the first application executed in temporal isolation 1 (HDPL1).
- OEMiRoT checks if a new candidate secure and/or nonsecure applications are stored in the download application code slots. A magic to trigger the installation must be detected (see also Images generation). If any, OEMiRoT decrypts it/them then controls its/their integrity, its/their authenticity, the antirollback versions, and its/their dependency version.
- If successful, one or more images is/are decrypted and copied in the application installation slots.
- OEMiRoT controls the integrity and the authenticity of the secure and nonsecure application images from the installation slots.
- If successful, OEMiRoT saves the new image version in HDPL1 OBkeys for the antirollback verification then executes the secure application in HDPL3. The jump to the secure application code is done using a service from RSS located in the system flash memory. This service increases the temporal isolation (HDP level) HDPL1 to HDPL3 making the OEMiRoT_Boot project code and the data in HDPL1 OBkeys no longer accessible.
- In case of failure, the bootloader is started in HDPL3 to provide the capability to download a new image
Note: For security robustness, when OEMiRoT jumps into the user application, the MPU is configured to ensure that only the secure application code area is allowed to be executed (execution surface controlled via MPU configuration). It is the secure application responsibility to reconfigure the MPU to fit with its security needs.
1.3.3 One boot stage: OEMiRoT on STM32H573 / STM32H56x / STM32H533 / STM32H523 with swap strategy
OEMiRoT is generated by compiling the OEMiRoT_Boot project with OEMUROT_ENABLE switch deactivated.
The following figure illustrates the secure boot and the secure update process by showing the steps (the first 2 steps are not represented but are the same as the ones with the overwrite method) required to boot the user application code image located in the user flash memory. In this example to simplify the presentation the optional data image management is not activated (but data images are managed as code images) and the upgrade strategy is swap:
- In CLOSED or LOCKED product state with BOOT_UBE option byte configured to boot on OEMiRoT, OEMiRoT located in the user flash memory is the first application executed in temporal isolation 1 (HDPL1).
- OEMiRoT checks if a new candidate secure and/or nonsecure applications is/are stored in the download application code slots. A magic to trigger the installation must be detected (see also Images generation). If any, OEMiRoT decrypts it/them then controls its/their integrity, its/their authenticity, its/their antirollback version, and its/their dependency version.
- If successful, the new images are decrypted and swapped with the installed images. The scratch area is used during the swap process.
- OEMiRoT controls the integrity and the authenticity of the secure and nonsecure application images from the installation slots.
- If successful, OEMiRoT executes the secure application in HDPL3. The jump to the secure application code is done using a service from RSS located in the system flash memory. This service increases the temporal isolation (HDP level) HDPL1 to HDPL3 making the OEMiRoT_Boot project code and the data in HDPL1 OBkeys no longer accessible.
- In case of failure, the bootloader is started in HDPL3 to provide the capability to download a new image.
- If the new images is/are validated during the user application execution, OEMiRoT saves the new image version in HDLP1 OBkeys for the antirollback verification at the next reset.
- If the new images is/are not validated during the user application execution, the images is/are swapped back (revert) at the next reset.
Note: For security robustness, when OEMiRoT jumps into the user application, the MPU is configured to ensure that only the secure application code area is allowed to be executed (execution surface controlled via MPU configuration). It is the secure application responsibility to reconfigure the MPU to fit with its security needs.
1.3.4 Two boot stages: STiRoT + OEMuRoT on STM32H573 / STM32H533
OEMuRoT is generated by compiling OEMiRoT_Boot project with OEMUROT_ENABLE switch activated. OEMuRoT (updatable Root of Trust) acts as a second boot stage.
The following figure illustrates the secure boot and the secure update process by showing all the steps required to boot the user application code image located in the user flash memory. In this example the optional data image management is not activated and the upgrade strategy is overwrite:
- In CLOSED or LOCKED product state with BOOT_UBE option byte configured to boot on STiRoT, STiRoT is the first software executed in temporal isolation 1 (HDPL1).
- After executing the secure firmware update process (refer to STiRoT_for_STM32H5 article for more details on STiRoT), STiRoT controls OEMuRoT integrity and authenticity. If successful, STiRoT executes OEMuRoT in HDPL2.
- OEMuRoT checks if a new candidate secure and/or nonsecure applications is/are stored in the download application code slots. A magic to trigger the installation must be detected (see also Images generation). If any, OEMuRoT decrypts it/them then controls its/their integrity, its/their authenticity, the antirollback version, and the dependency version.
- If successful, the images is/are decrypted and copied in the secure and/or nonsecure application code installation slots.
- OEMuRoT controls the integrity and the authenticity of the secure and nonsecure application images from the installation slots.
- If successful, OEMuRoT saves the new image version in HDPL2 OBkeys for the antirollback verification then executes the user application in HDPL3. The jump to the user application code is done using a service from RSS located in the system flash memory. This service increases the temporal isolation (HDP level) from HDPL2 to HDPL3 making the OEMiRoT_Boot project code and the data stored in HDPL2 OBkeys no longer accessible.
- In case of failure, the bootloader is started in HDPL3 to provide the capability to download a new image
Note: For security robustness, when OEMuRoT jumps into the user application, the MPU is configured to ensure that only the secure application code area is allowed to be executed (execution surface controlled via MPU configuration). It is the secure application responsibility to reconfigure the MPU to fit with its security needs.
1.3.5 Swap upgrade strategy
When OEMiRoT/OEMuRoT are generated with the swap upgrade strategy activated, the scratch buffer is used two times during the secure firmware update process:
- during installation, to swap download and installation slots.
- at reset the images are swapped back if the new user application is not confirmed.
The following figure illustrates the scratch buffer usage with OEMuRoT. The same exists for OEMiRoT :
The scratch area size can be tuned according to the expected number of upgrades in the product life:
- number_of_upgrades = number_of_erase_cycles / (image_size / scratch_size)
- Example: 64 Kbytes for 10 k programming cycles, 640 Kbytes firmware image size, and 1000 firmware image updates
Note : When the swap upgrade strategy is activated, the image version for antirollback control is stored in OBkeys only after reset.
2 Features list
The main features of the OEMiRoT/OEMuRoT are:
- ECDSA-P256 asymmetric cryptography for image authentication.
- SHA256 cryptography for image integrity check.
- AES-CTR-128 cryptography for image encryption with symmetric key encrypted in ECIES-P256 provided in the image itself. Refer to Image generation for more details.
- Accelerated boot thanks to image SHA256 reference management. Image verification mainly consists of verifying the SHA256 of the image (integrity check) and then verifying the signature of this SHA256 (authentication check). If successful, the SHA256 is stored as a reference for the next boot. At the next boot, the signature verification is skipped if the SHA256 of the image matches the reference stored in OBkeys (STM32H523, STM32H533, STM32H56x, STM32H573) or in Hash Ref region (STM32H503). This feature brings performance optimization (under the MCUBOOT_USE_HASH_REF compilation switch).
- Antirollback version checks based on image version stored in OBkeys (STM32H523, STM32H533, STM32H56x, STM32H573) or in NV counters region (STM32H503).
- Configurable slot mode:
- Single primary slot mode on STM32H503, which enables maximizing image size. The downloaded image is in the same memory slot as the installed image. The new downloaded image overwrites the previous installed image.
- Primary and secondary slots mode on STM32H573 / STM32H56x / STM32H533 / STM32H523, which enables safe image programming. The downloaded image and installed image are in different memory slots.
- Image installation is resistant to asynchronous power down and reset, in primary and secondary slot mode configuration.
- Flexible number of application images on STM32H573 / STM32H56x / STM32H533 / STM32H523 (TrustZone® is not activated on STM32H503):
- Either one application image (secure and nonsecure binaries combined in a single image) with:
- - Unique key pair
- - Antirollback version check
- Or two application images (a secure image and a nonsecure image) with:
- - Dedicated key pairs per firmware image
- - Dedicated antirollback version check per firmware image
- - Images version dependency management
- Flexible number of data images on STM32H573 / STM32H56x / STM32H533 / STM32H523: no data image, one data image (secure or nonsecure) or two images (secure and nonsecure) with the policies defined on application images (authenticity and integrity verification, antirollback version check, decryption). On STM32H503, only one data image can be configured.
- Integration of the full entropy TRNG source (RNG hardware peripheral) for random delay generation.
- Configurable firmware image upgrade strategy, for primary and secondary slots mode:
- Overwrite strategy, for which the image in the secondary slot overwrites the image in the primary slot.
- Swap strategy, for which the image in primary and secondary slots are swapped. After the swap, the new image in the primary slot must be confirmed by the user application, else, at the next boot, the images are swapped back.
- Memory configuration: all slots are located inside internal user flash (primary and secondary slots for secure and nonsecure code and data images).
- Integration of hardware security peripherals and mechanisms to implement a root of trust. Product life cycle, BOOT_UBE, MPU, WRP, HDP, and TAMPER are combined to protect the product. When connected on the hardware board, the external tamper can be activated with OEMIROT_TAMPER_ENABLE define.
- Image generation with STM32TrustedPackageCreator tool delivered within STM32CubeProgrammer.
The following table identifies the cryptography operations hardware-accelerated on the STM32H5 devices:
| Hardware accelerator | Operation | STM32H573/H533 | STM32H56x/H523 | STM32H503 |
|---|---|---|---|---|
| PKA | ECDSA | X | ||
| SAES | AES | X | ||
| HASH | SHA256 | X | X | X |
| RNG | Random generator | X | X | X |
Features configurability:
| Feature | OEMiRoT | OEMuRoT (STM32H573/H533) | Configuration switch |
|---|---|---|---|
|
Boot project generation |
OEMiRoT generation |
OEMuRoT generation |
OEMUROT_ENABLE |
|
Image upgrade strategy |
|
|
MCUBOOT_OVERWRITE_ONLY* |
| Flash memory configuration |
|
|
MCUBOOT_OVERWRITE_ONLY* MCUBOOT_APP_IMAGE_NUMBER* MCUBOOT_S_DATA_IMAGE_NUMBER* MCUBOOT_NS_DATA_IMAGE_NUMBER* MCUBOOT_DATA_IMAGE_NUMBER** |
|
Antitamper |
|
|
TAMPER_ENABLE |
|
Project phase (refer to Application development phase ) |
|
|
OEMIROT_DEV_MODE |
* available on STM32H573
/ STM32H56x / STM32H533 / STM32H523
** available on STM32H503
OEMiRoT/OEMuRoT differences on STM32H573 / STM32H533:
| Feature | OEMiRoT | OEMuRoT |
|---|---|---|
|
WRP |
ON, immutable RoT |
OFF, updatable RoT |
| Execution context | HDPL1 | HDPL2 |
| HDP | activated on user flash to hide OEMiRoT code after execution | activated on user flash to hide OEMuRoT code after execution |
| Protected data location (cryptographic keys, antirollback version, SHA256 reference) | HDPL1 OBkeys | HDPL2 OBkeys |
3 Memories layout
3.1 STM32H503
For STM32H503, the OEMiRoT relies on flash memory layout defining several regions:
- HASF REF region: region where the SHA256 references are stored (one reference per image).
- NV counters region: region where OEMiRoT_Boot gets nonvolatile information about last installed images (code and data) versions for the antirollback feature.
- Integrator personalized data region: region to personalize OEMiRoT secrets (authentication and encryption keys).
- OEMiRoT_Boot code region: region to program the OEMiRoT_Boot code binary that manages the functions "secure boot" and "Secure firmware update”.
- Application code slot region: region to program the image code.
- Application data slot region: region to program the image data.
Flash memory layout is as follow:
3.2 STM32H573 / STM32H56x
For STM32H573 / STM32H56x, the OEMiRoT relies on flash memory layout defining several regions:
- Secure application code installation slot region: region to program the image of an “active” secure application code after installation.
- Nonsecure application code installation slot region: region to program the image of an “active” nonsecure application code after installation.
- Secure application code download slot region: region to program the image of a "new" candidate secure application code for installation.
- Nonsecure application code download slot region: region to program the image of a "new" candidate nonsecure application code for installation.
- Secure application data installation slot region: region to program the image of an “active” secure application data after installation.
- Nonsecure application data installation slot region: region to program the image of an “active” nonsecure application data after installation.
- Secure application data download slot region: region to program the image of a "new" candidate secure application data for installation.
- Nonsecure application data download slot region: region to program the image of a "new" candidate nonsecure application data for installation.
Flash memory layout is as follows:
Default configuration of the flash memory layout is:
| Symbol | Value |
|---|---|
| MCUBOOT_APP_IMAGE_NUMBER | 2 |
| MCUBOOT_S_DATA_IMAGE_NUMBER | 0 |
| MCUBOOT_NS_DATA_IMAGE_NUMBER | 0 |
| MCUBOOT_OVERWRITE_ONLY | Activated |
| FLASH_S_PARTITION_SIZE | 24 Kbytes |
| FLASH_NS_PARTITION_SIZE | 640 Kbytes |
| FLASH_S_DATA_PARTITION_SIZE | 8 Kbytes (when MCUBOOT_S_DATA_IMAGE_NUMBER != 0) |
| FLASH_NS_DATA_PARTITION_SIZE | 8 Kbytes (when MCUBOOT_NS_DATA_IMAGE_NUMBER != 0) |
3.3 STM32H533 / STM32H523
For STM32H533 / STM32H523, the OEMiRoT relies on flash memory layout defining several regions:
- Secure application code installation slot region: region to program the image of an “active” secure application code after installation.
- Nonsecure application code installation slot region: region to program the image of an “active” nonsecure application code after installation.
- Secure application code download slot region: region to program the image of a "new" candidate secure application code for installation.
- Nonsecure application code download slot region: region to program the image of a "new" candidate nonsecure application code for installation.
- Secure application data installation slot region: region to program the image of an “active” secure application data after installation.
- Nonsecure application data installation slot region: region to program the image of an “active” nonsecure application data after installation.
- Secure application data download slot region: region to program the image of a "new" candidate secure application data for installation.
- Nonsecure application data download slot region: region to program the image of a "new" candidate nonsecure application data for installation.
Flash memory layout is as follows:
Default configuration of the flash memory layout is:
| Symbol | Value |
|---|---|
| MCUBOOT_APP_IMAGE_NUMBER | 2 |
| MCUBOOT_S_DATA_IMAGE_NUMBER | 0 |
| MCUBOOT_NS_DATA_IMAGE_NUMBER | 0 |
| MCUBOOT_OVERWRITE_ONLY | Activated |
| FLASH_S_PARTITION_SIZE | 24 Kbytes |
| FLASH_NS_PARTITION_SIZE | 64 Kbytes |
| FLASH_S_DATA_PARTITION_SIZE | 8 Kbytes (when MCUBOOT_S_DATA_IMAGE_NUMBER != 0) |
| FLASH_NS_DATA_PARTITION_SIZE | 8 Kbytes (when MCUBOOT_NS_DATA_IMAGE_NUMBER != 0) |
4 Provisioning process
4.1 OEMiRoT provisioning process on STM32H503
The product provisioning to activate and configure OEMiRoT is done following the three steps below:
- 1. Cryptographic keys generation for firmware authentication and encryption.
- 2. Generation of OEMiRoT binary and the application images. Up to 2 images are generated:
- Application code
- Application data
- 3. Programming of the option bytes, the application images in the device.
Note: A set of scripts is provided in Firmware/Projects/NUCLEO-H503RB/ROT_Provisioning/OEMiRoT folders. It guides the user all along the provisioning process. Refer to Getting started with STM32H5 security article.
4.2 OEMiRoT provisioning process on STM32H573 / STM32H56x / STM32H533 / STM32H523
The product provisioning to activate and configure OEMiRoT is done following the three steps below:
- 1. Configuration of OEMiRoT. At this stage, the cryptographic keys for authentication and encryption are defined.
- 2. Generation of OEMiRoT binary and the application images. Up to 4 Images are generated:
- Secure application code
- Nonsecure application code
- Secure application data
- Nonsecure application data.
- 3. Programming of the OBkeys, the option bytes, the application images in the device
Note: A set of scripts is provided in Firmware/Projects/STM32H573I-DK/ROT_Provisioning/OEMiRoT, Firmware/Projects/NUCLEO-H563ZI/ROT_Provisioning/OEMiRoT and Firmware/Projects/NUCLEO-H533RE/ROT_Provisioning/OEMiROT folders. It guides the user all along the provisioning process. Refer to Getting started with STM32H5 security article.
4.3 STiRoT + OEMuRoT provisioning process on STM32H573 / STM32H533
The product provisioning to activate and configure OEMuRoT is done following the three steps below:
- 1. Configuration of:
- STiRoT. At this stage, the location of the image, and the STiRoT cryptographic keys are defined.
- OEMuRoT. At this stage, the OEMuRoT cryptographic keys for authentication and encryption are defined.
- 2. Generation of the OEMuRoT code image and the application images. Up to 4 Images are generated:
- Secure application code
- Nonsecure application code
- Secure application data
- Nonsecure application data.
- 3. Programming of the OBkeys, the option bytes, the OEMuRoT and the application images in the device.
Note: A set of scripts is provided in Firmware/Projects/STM32H573I-DK/ROT_Provisioning/STiROT_OEMuROT and Firmware/Projects/NUCLEO-H533RE/ROT_Provisioning/STiROT_OEMuROT folder. It guides the user all along the provisioning process. Refer to Getting started with STM32H5 security article.
4.4 OEMiRoT/OEMuRoT configuration file
OEMiRoT/OEMuRoT configuration file (OEMiRoT_Config.obk, OEMuRoT_Config .obk) is generated using STM32TrustedPackageCreator with a template file listing all the different parameters (OEMiRoT_Config.xml, OEMuRoT_Config.xml) as input. The obk file is encrypted and saved in HDPL1 OBkeys (OEMiRoT) or HDPL2 OBkeys (OEMuRoT).
The list of the configuration parameters is the following:
| Parameter | Description | Additional constraints |
|---|---|---|
| Authentication secure key | Key used to authenticate the secure code and data images | When this key is regenerated, both secure code and data images must be processed with TPC “Image Gen” tab (OEMiRoT_S_Code_Image.xml, OEMiRoT_S_Data_Image.xml) |
| Authentication nonsecure key | Key used to authenticate the nonsecure code and data images | When this key is regenerated, both nonsecure code and data images must be processed with TPC “Image Gen” tab (OEMiRoT_NS_Code_Image.xml, OEMiRoT_NS_Data_Image.xml) |
| Encryption key | Key used to encrypt the firmware image | When this key is regenerated, firmware image must be processed with TPC “Image Gen” tab (OEMiRoT_Code_Image.xml) |
A detailed presentation of the format of STiROT_Config.obk file is provided in OEMiRoT_Config.obk file format.
5 Images generation
OEMiRoT/OEMuRoT manages application code and data images based on MCUBoot format including:
- a header,
- the encrypted application code or data binary,
- some metadata information (TLV format: Tags Length Value) allowing the control of the image (SHA256, ECDSA signature …),
- a trailer is reserved at the end of the slot, for the swap process, so that the image size (header + binary + TLV) is limited to the slot area size minus the trailer size. The trailer size depends on the image and flash memory properties. In overwrite mode, the image size is limited to the slot area size minus the magic data size (16 bytes).
- a magic to trigger the installation at the end of the slot.
Further information about the MCUBoot open-source software is available at mcuboot.
A PC tool STM32TrustedPackageCreator is provided to generate the firmware code image. This image is encrypted and signed using the keys configured in OBkeys configuration file (OEMiRoT_Config.xml / OEMuRoT_Config.xml). OEMiRoT_xx_Code_Image.xml, OEMiRoT_xx_Data_Image.xml, OEMuRoT_xx_Code_Image.xml and OEMuRoT_xx_Data_Image.xml contains all the parameters driving the image generation such as:
- The authentication and encryption keys. Keys value inherited from OEMiRoT_Config.xml / OEMuRoT_Config.xml.
- The version.
- The dependency with another image if a synchronized installation is required
OEMiRoT_xx_Code_Image.xml, OEMiRoT_xx_Data_Image.xml, OEMuRoT_xx_Code_Image.xml and OEMuRoT_xx_Data_Image.xml can be edited with STM32TrustedPackageCreator in order to modify the version and/or the dependency information.
The following figure shows the application code image generation (same applied for data image):
6 Appendix
6.1 OEMiRoT/OEMuRoT start-up sequence
6.2 Application development phase
During development phase, it is recommended to compile OEMiRoT_Boot project with DEV_MODE defined and to select OPEN state during provisioning process :
- When DEV_MODE is defined:
- logs are displayed in tera term during OEMiRoT_Boot project execution.
- an infinite loop is executed instead of a reset in Error_Handler() function .
- tamper event is cleared at startup when required. No need to power off/on the board to clear this event.
- OPEN product state can be selected during provisioning process.
At the end of the development phase, DEV_MODE must be disabled and the product state CLOSED or LOCKED must be selected during provisioning process. In CLOSED or LOCKED product state, the DA process should be run to be able to connect the debugger trough JTAG (more details in Debug Authentication for STM32H5 wiki article).
6.3 OEMiRoT_Config.obk file format
| Offset | Size | Type | Description |
|---|---|---|---|
| 0 | 4 | uint32 | sdp command header : destination address |
| 4 | 4 | uint32 | sdp command header : data size address |
| 8 | 4 | uint32 | sdp command header : encryption disabled/enabled (0/1) |
| 12 | 32 | array | SHA256 of the following data content (from offset 44 to 315) |
| 44 | 91 | array | ECDSA-P256 authentication public key for secure code and data images |
| 135 | 91 | array | ECDSA-P256 authentication public key for nonsecure code and data images |
| 226 | 70 | array | ECDSA-P256 encryption private key |
| 296 | 20 | array | Reserved |
Same applied for OEMuRoT_Config.obk
6.4 OEMiRoT_S_Code_image xml file format
| Parameter | Updatable | Description |
|---|---|---|
| Authentication key | Automatic | Private key inherited from OEMiROT_Config.xml file. |
| Encryption key | Automatic | Public key inherited from OEMiROT_Config.xml file. |
| Endianness | No | Little endian. |
| Padding | No | Add an installation magic value at the end of the image to trigger image installation. Padding with 0xFF when required. |
| Firmware area size | Automatic | Firmware slot size information. This value is updated during the postbuild of OEMiRoT_Boot project compilation based on slot configuration from flash_layout.h |
| Header Size | No | 0x400 bytes |
| Padding Header | No | Padding the header with 0xFF to fulfil the 0x400 bytes. |
| Dependency with other image | No | Number and version of the image to be installed with: Number, x.y.z |
| Write Option | Automatic | Image upgrade strategy: Overwrite, Swap. This value is updated during the postbuild of OEMiRoT_Boot project compilation based on MCUBOOT_OVERWRITE_ONLY definition from flash_layout.h. |
| Version | Yes | x.y.z firmware image version. |
| Security Counter | No | Security counter value automatically generated based on version information. |
| Align | No | The size of the encrypted binary generated is multiple of 16 bytes. |
| Firmware download area offset | Automatic | Used to generate .hex binary file format including the destination address. This value is updated during the postbuild of OEMiRoT_Boot project compilation based on slot configuration from flash_layout.h. |
| Firmware binary input file | Automatic | Location of the firmware binary file. This parameter is updated during the provisioning process based on information from env.bat file. |
| Image output file | Yes | Location of the encrypted image generated. If changed, provisioning scripts must be updated accordingly. |
Same applied for OEMiRoT_NS_Code_Image.xml, OEMiRoT_S_Data_Image.xml, OEMiRoT_NS_Data_Image.xml, OEMuRoT_S_Code_Image.xml, OEMuRoT_NS_Code_Image.xml, OEMuRoT_S_Data_Image.xml, OEMuRoT_NS_Data_Image.xml.