This article provides an overview of the OEMiRoT solution integrated into the STM32H7P devices.
For a step-by-step user guide, refer to the wiki page How to start with OEMiRoT on STM32H7P.
Applicable products:
| Type | Products |
|---|---|
| Microcontroller | STM32H7P5xx |
1. OEMiRoT presentation
1.1. Overview
OEMiRoT stands for OEM immutable root of trust. It acts as the first boot stage. It is based on the MCUboot open-source software[1].
OEMiRoT provides two services:
- Secure boot (root of trust service): immutable code that always runs after a system reset. It checks static protections (option bytes), enables runtime protections, and verifies the authenticity and integrity of the user application code before each execution.
- Secure firmware update: immutable code that detects new firmware image candidates. It checks the version to prevent version downgrade, authenticity, and integrity before it installs the firmware after decryption. Information about STMicroelectronics modifications in MCUboot is available in the MCUboot User Guide[2].
1.2. Protection measures and security strategy
Cryptography ensures integrity, authentication, and confidentiality. However, cryptography alone is insufficient. A combination of measures and system-level strategies is necessary to protect critical operations, sensitive data such as secret keys, and the execution flow. This combination enhances security robustness.
On STM32H7P devices, the security strategy is based on the following hardware mechanisms:
- Product state: The product state shall be set to CLOSED or LOCKED to prevent JTAG debugger access to the device, except for execution of the Debug Authentication (DA) process (more details in Debug Authentication for STM32H7P wiki article).
- Boot configuration: The BOOT_LOCK option byte shall be configured to establish a chain of trust by forcing the system to boot from a unique user flash memory address.
- WRP (Write Protection): Write protection shall be enabled to ensure OEMiRoT immutability, as required by secure boot standards. The OEMiRoT code is configured as immutable.
- HDP (Hide Protection): When activated, access to the protected flash memory area is denied for all operations, including fetch, read, programming, and erase. In OEMiRoT examples, HDP is used to protect the OEMiRoT code. The OEMiRoT executes in HDPL1 and the HDP level is increased to HDPL2 when launching the application, making the OEMiRoT code no longer accessible.
- OBkeys (Option Bytes keys): The HDPL1 OBkeys area is a protected and isolated memory region used to store secrets such as OEMiRoT encryption and authentication keys, as well as anti-rollback counters. This area is no longer accessible after switching from HDPL1 to HDPL2.
- MPU (Memory Protection Unit): The MPU shall define access rights for memory-mapped resources, including flash, SRAM, and peripherals. During OEMiRoT execution, the MPU limits execution to the OEMiRoT code region and then extends access to the user application only after integrity and authenticity verification. This protection is managed dynamically at runtime.
- Anti-tamper protection: Anti-tamper protection shall be enabled to protect sensitive data from physical tampering. It is activated at OEMiRoT start and remains active during execution. Upon tamper detection, sensitive data stored in SRAM and cryptographic peripherals is erased immediately, and the system is forced to reboot. Refer to the STM32H7Pxx Reference Manual for detailed descriptions. In addition, secure software coding techniques such as redundant critical tests, random delays, parameter validation, and flow-control mechanisms are implemented to improve security robustness.
.
1.3. OEMiRoT activation
On STM32H7P, activating OEMiRoT involves:
- configuring the flash layout and personalizing secrets, such as authentication and encryption keys;
- building the OEMiRoT and user application image binaries;
- programming the binaries and option bytes according to the flash layout and security strategy.
All these operations are part of the Provisioning process.
1.3.1. OEMiRoT in dual slot overwrite mode
In overwrite mode, OEMiRoT installs the new firmware image by overwriting the previous one.
This figure illustrates the secure boot and secure firmware update process in overwrite mode and shows all steps required to boot the application code from flash memory. For simplicity, optional application data image management is not enabled in this example; however, application data images are managed in the same way as application code images.
- At reset, boot is forced on OEMiRoT using the BOOT_LOCK option bytes.
- OEMiRoT then checks whether a new user application code image is present in the download slot.
- If present, the image is decrypted and its integrity, authenticity, security version number, and, when applicable, version dependencies with other images are verified.
- If verification succeeds, the image is copied to the user application installation slot.
- OEMiRoT then verifies the integrity and authenticity of the user application code image in the installation slot.
- If the verification is successful, OEMiRoT updates the anti-rollback counters and reference hashes, then executes the user application and hides OEMiRoT.
1.3.2. OEMiRoT in dual slot swap mode
In swap mode, OEMiRoT installs the new firmware image and backs up the previous one. The new image in the installation slot must be confirmed by the user application; otherwise, the images are swapped back at the next boot.
This figure illustrates the secure boot and secure firmware update process in swap mode and shows all steps required to boot the application code from flash memory. For simplicity, optional application data image management is not enabled in this example; however, application data images are managed similarly to application code images.
- At reset, boot is forced on OEMiRoT using the BOOT_LOCK option bytes.
- OEMiRoT checks whether the application code image in the installation slot is confirmed. If it is confirmed, OEMiRoT updates the anti-rollback counters.
- OEMiRoT checks whether new user application code is present in the download slot.
- If present, OEMiRoT decrypts the image and verifies its integrity, authenticity, security version against the anti-rollback counters, and, when applicable, version dependencies with other images.
- If verification succeeds, the new image is decrypted and copied to the user application installation slot, while the previously installed image is re-encrypted and copied to the user application download slot.
- OEMiRoT verifies the integrity and authenticity of the user application code image in the installation slot.
- OEMiRoT updates the hash reference.
- OEMiRoT executes the user application and hides OEMiRoT.
At the next boot, if the image in the installation slot is not confirmed, the image is reverted.
2. Feature list
OEMiRoT provides the following main features:
- Integration of hardware security peripherals and mechanisms to implement a root of trust: Product State, BOOT_LOCK, MPU, WRP, HDP, OBKeys, and anti-tamper protection are combined to achieve the highest security level.
- Dual-slot mode: The downloaded image and the installed image reside in different memory slots, enabling:
- safe image programming in the download slot without impacting the installation slot;
- image installation resistant to asynchronous power-down and reset.
- Firmware image upgrade strategies:
- Overwrite mode: The image in the download slot overwrites the image in the installation slot; no rollback is possible.
- Swap mode: The images in the primary and secondary slots are swapped. After the swap, the new image in the primary slot must be confirmed by the user application; otherwise, the images are swapped back at the next boot.
- Cryptography algorithms:
- ECDSA-P384 asymmetric cryptography for image authentication;
- SHA-384 for image integrity verification;
- AES-CTR-256 symmetric encryption with keys encrypted via ECIES-P256 and included in the image.
- Hardware cryptographic peripheral integration:
- HASH peripheral for SHA computation acceleration;
- RNG peripheral for true random number generation;
- software cryptography fallback using STCryptoLib when hardware peripherals are unavailable.
- Version anti-rollback: Images with security versions lower than the anti-rollback monotonic counters stored in OBKeys are rejected.
- Accelerated boot: Image verification uses stored SHA references to skip signature verification if the image is unchanged, improving performance.
- Fast wake-up from standby: Firmware image control is bypassed on wake-up to accelerate resume time, with software countermeasures maintaining security.
- Firmware image number: Support for one application code image and optionally one application data image, each with dedicated anti-rollback counters, while sharing the same authentication and encryption keys.
- Firmware image dependencies: New images can depend on other images’ versions; installation is pending until dependencies are met.
- Image slot location: Download and installation slots are located in internal user flash memory.
The different OEMiRoT use cases are demonstrated by dedicated OEMiRoT examples.
The following table lists the OEMiRoT examples on the STM32H7P boards:
| Example | NUCLEO-H7P5II | STM32H7P5I-DK | Description |
|---|---|---|---|
| oemirot_dualslot | OEMiRoT in dual slot mode, with cryptography relying on STCryptoLib software and the HASH/RNG peripherals. | ||
| oemirot_dualslot_hwcrypto | OEMiRoT in dual slot mode, with cryptography relying on HASH/RNG/SAES/PKA peripherals. |
3. Memory layout
3.1. Flash memory layout
OEMiRoT relies on a specific flash memory layout that defines several regions:
- OEMiRoT code region: Stores the OEMiRoT code binary that manages Secure Boot and Secure Firmware Update functions.
- Keys region: Stores personalized OEMiRoT secret keys, including authentication and encryption keys.
- Anti-rollback counters region: Holds nonvolatile information about the last installed image versions, for both code and data, used by the anti-rollback feature.
- Hash references region: Stores SHA references, one per image.
- Application code installation slot: Stores the verified application code that is executed.
- Application code download slot: Stores candidate application code images, encrypted, before installation.
- Application data installation slot: Stores verified application data images.
- Application data download slot: Stores candidate application data images, encrypted, before installation.
The flash memory layout is as follows:
Flash memory layout configuration:
| Flash region | Size | Configuration constraint | Configuration variable | Configuration file |
|---|---|---|---|---|
| OEMiRoT code region size | Configurable | Multiple of WRP group size | oemirot_size | mx_memory_config.ini |
| Application code slots size
(download and installation slots) |
Configurable | Multiple of FLASH page size | app_size | mx_memory_config.ini |
| Application data image enable | Configurable | 0 (disabled) or 1 (enabled) | data_image | mx_memory_config.ini |
| Application data slots size
(download and installation slots) |
Configurable | Multiple of FLASH page size | data_size | mx_memory_config.ini |
| OEMiRoT keys region size | 160 Bytes | No | NA | NA |
| OEMiRoT anti-rollback counters + OEMiRoT hash references
region size |
256 Bytes | No | NA | NA |
3.2. SRAM memory layout
AXISRAM1 is selected for OEMiRoT execution.
- The entire AXISRAM1 is available to the application; however, the OEMiRoT area is not persistent across reset or standby modes.
- Other SRAM regions are fully dedicated to application use and may be configured to remain persistent across reset and standby modes, depending on user configuration.
SRAM memory layout usage:
| SRAM region | Size | Configurability |
|---|---|---|
| OEMiRoT SRAM size | 20 KB | No |
4. Provisioning process
4.1. OEMiRoT provisioning process
The product provisioning process includes the following steps:
- Configure the flash memory layout and the installation mode, if applicable.
- Configure debug authentication.
- Configure OEMiRoT keys.
- Build the OEMiRoT binary.
- Build the application code image.
- Build the application data image, if applicable.
- Program the DA password and OEMiRoT keys.
- Program option bytes, such as WRP, HDP, boot, and product state.
- Program the binaries.
The image below shows a visual representation of all these steps.
Prebuild and postbuild commands are integrated into the projects.
- The prebuild command propagates the flash memory layout and the example configuration into the projects before the build.
- The postbuild command generates firmware images from the build output of the application code..
5. Images generation
OEMiRoT manages application code and data images that use the MCUboot format, which includes the following:
- A header
- The firmware binary (encrypted or unencrypted, depending on the image type)
- Metadata in tag-length-value (TLV) format, which enables decryption and verification, such as hash and signature checks
A 16-byte magic value is written at the end of the download slot. It is not part of the image. This value triggers the installation request to OEMiRoT at the next boot.
More information about the MCUboot image format is available in the MCUboot open-source software[1] documentation.
A PC tool, STM32TrustedPackageCreator[3] (provided through STM32CubeProgrammer), is provided to generate firmware images. This tool embeds imgtool python script, which manages the MCUboot image creation.
Images are encrypted and signed by using user-personalized keys.
Two types of images are generated:
- Provisioning image: Signed and in clear text, programmed in the installation slot during initial device programming
- Firmware update image: Signed and encrypted, programmed in the download slot and installed during the secure firmware update process
5.1. Initial images generation
The files appli_code_provisioning_image.xml and appli_data_provisioning_image.xml contain all parameters for generating initial images, including:
- Authentication keys (inherited from
oemirot_keys_config.xml) - Image version and security version
Refer to How to start with OEMiRoT on STM32H7P for location of these files.
These XML files can be edited using STM32TrustedPackageCreator[3] to modify user-selectable parameters (refer to Image xml format).
The following figure shows the initial image generation:
5.2. Update images generation
The files appli_code_fwu_image.xml and appli_data_fwu_image.xml contain parameters for generating update images, such as:
- Authentication and encryption keys (inherited from
oemirot_keys_config.xml) - Image version and security version
- Dependency on other images if synchronized installation is required
Refer to How to start with OEMiRoT on STM32H7P for location of these files.
These XML files can be edited using STM32TrustedPackageCreator[3] to modify user-selectable parameters (refer to Image xml format).
The following figure shows the update images generation:
6. Appendix
6.1. Startup sequence
The following diagram illustrates the OEMiRoT startup sequence.
The boot time to consider is in production mode, with OEMIROT_DEV_MODE undefined, that is, with no logs.
It mainly depends on the image size and the system clock frequency. However, it can also vary according to the toolchain version and the compile optimization level.
As an indication, here are the performance values obtained with the following configuration:
- 520 MHz system clock frequency
- IAR 9.60.3, high-level, size-oriented optimization
| Image size | 256 Kbytes | 512 Kbytes | 768 Kbytes |
|---|---|---|---|
| Boot time | 36 ms | 59 ms | 82 ms |
| Wake-up time | 5 ms | 5 ms | 5 ms |
6.2. From development to production phase
During development, it is recommended to compile the OEMiRoT project with the OEMIROT_DEV_MODE compile switch defined (default configuration) and to select Product state OPEN and minimum Product state OPEN during provisioning:
- When
OEMIROT_DEV_MODEis defined:- Logs are displayed in a terminal emulator (for example Tera Term, Minicom) during the OEMiRoT project execution.
- The
Error_Handler()function executes an infinite loop instead of resetting.
- When Product state OPEN is selected:
- The device is open and a debug interface is available.
- The minimum product state shall be configured to OPEN as well to authorize boot process (OEMiRoT does not authorize secure boot if the Product state is lower than the minimum Product state).
The OEMIROT_DEV_MODE switch definition can be managed by directly modifying the file below:
Development/production mode configuration:
| Configuration | Possible values | Configuration variable or SWITCH | Configuration file |
|---|---|---|---|
| Development / Production mode |
|
OEMIROT_DEV_MODE | boot_pre_include_global.h |
The Product state and minimum Product state can be configured during the provisioning script (user interaction) or by modifying the configuration variable/switch below.
Product state/Product state minimum configuration:
| Configuration | Possible values | Configuration variable or SWITCH | Configuration file |
|---|---|---|---|
| Product state |
|
final_product_state | provisioning.ini |
| Product state min
(controlled by OEMiRoT) |
|
min_product_state | provisioning.ini |
6.3. OEMiRoT constraints on application
When activating the OEMiRoT boot path, the following application constraints must be considered:
- For enhanced security, the MPU is configured to allow execution only in the application code when OEMiRoT transfers control. It is the user application’s responsibility to reconfigure the MPU according to its security requirements.
- Internal tamper 9 (fault generation for cryptographic peripherals such as SAES, PKA, AES, RNG) and internal tamper 15 (system fault detection) are activated in confirmed mode during OEMiRoT execution and remains active when jumping into the user application.
- AXISRAM1 is used by OEMiRoT. It is partly erased a each reset. Refer to SRAM memory layout.
- The system clock is configured to the maximum frequency using the PLL when the user application starts.
- The application starts in HDP level 2.
6.4. Keys and passwords personalization
6.4.1. OEMiRoT keys
Default OEMiRoT keys in .pem format are provided in the OEMiRoT examples:
| Keys filename | Description |
|---|---|
| oemirot_authentication.pem | SECP384R1 authentication private key |
| oemirot_encryption.pem
oemirot_encryption_pub.pem |
SECP256R1 encryption private key
SECP256R1 encryption public key |
OEMiRoT keys can be personalized using the STM32TrustedPackageCreator[3] tool with a template file (oemirot_keys_config.xml) listing all parameters.
The template generates a binary file (oemirot_keys_config.obk) programmed on the device during provisioning. Its format is:
| Offset (Bytes) | Size (Bytes) | Description |
|---|---|---|
| 0 | 4 | command header: destination information
Format 0xDADAHHII: – II specifies the OBKey starting index. – HH specifies the OBKey HDPL. – DADA specifies the debug authentication configuration, which is only relevant when the OBKey is writable only in HDPL0. |
| 4 | 4 | command header: data size |
| 8 | 4 | command header: encryption flag (enabled / disabled) |
| 12 | 32 | SHA256 of below data (from offset 44 to 172) |
| 44 | 48 | SHA384 of the SECP384R1 authentication public key |
| 92 | 48 | reserved |
| 140 | 32 | Raw SECP256R1 encryption private key |
After key personalization, firmware images must be regenerated.
6.4.2. DA password
Default DA password is provided in the OEMiRoT examples:
| Password filename | Description |
|---|---|
| da_config_password.xml | DA configuration, including DA password value (128 bits) |
DA password can be personalized using the STM32TrustedPackageCreator[3] tool with the xml file (da_config_password.xml).
The templates generate binary file (da_config_password.obk) programmed on the device during provisioning.
Refer to Security:Debug Authentication for STM32H7P for more information on DA for STM32H7P.
6.5. Image xml format
For each firmware image (code and data), there are two variants of the image XML file: the provisioning XML and the fwu (firmware update) XML. Most parameters are common to both variants.
Only few of them are manually updatable by user here, as indicated in below table.
| Parameter | Image xml variant | Updatable | Description |
|---|---|---|---|
| Authentication key | All | No | Private key used to sign image.
Corresponds to the provisioned public key referred in `oemirot_keys_config.xml`. |
| Encryption key | All | No | Public key used for image encryption,
Corresponds to the provisioned private key referred in `oemirot_keys_config.xml`. |
| Image magic | All | No | Magic value (32 bits) at start of image header |
| No encryption(clear) | provisioning | No | Image is clear in the installation slot but includes encryption metadata for re-encryption if swapped to download slot. |
| Symmetric key length | All | No | AES-CTR symmetric key (depends on crypto scheme) |
| Endianness | All | No | Little endian. |
| Public key format | All | No | Authentication public key fully provided in image metadata (must match SHA of provisioned key). |
| Application or Data image slot size | All | Automatic | Application or Data image slot size, updated during provisioning according to flash layout configuration. |
| Header size | All | No | Size of image header (0x400 bytes for application code image due to vector table alignment; 0x20 for application data image). |
| Padding header | All | No | Padding the header with 0xFF to fulfill the header size. |
| Version | All | Manual | Firmware image version in x.y.z format (x ≤ 255, y ≤ 255, z ≤ 65535). |
| Security version | All | Manual | Value used for anti-rollback. Can be 'auto' (aligned to image version) or manually set (32-bit).
Note that anti-rollback feature is inactive if security version remains unchanged at each update of image. |
| Dependency with other image | fwu | Manual | Index and version of other image required for synchronized installation.
Format is 'Index, version':
As long as dependency condition is not satisfied, the candidate image remains pending in download slot. |
| Installation mode | All | Automatic | Set according to installation mode (overwrite or swap mode): parameter present if overwrite mode selected, parameter removed if swap mode selected. It impacts the maximum image size inside the image area.
In overwrite mode: maximum allowed firmware image size is the Firmware area size. In Swap mode: maximum allowed firmware image size is 2 flash pages below the Firmware area size, as some space is reserved for the swap process. |
| Trailer info alignment | All | No | Used to align the swap info / copy done / image OK flags in trailer. |
| Swap status alignment | All | No | This parameter is effective in swap mode only.
Swap status (swap progress flags) alignment. Value depends on HW platform capabilities for programming. |
| Confirm | provisioning | No | This parameter is effective in swap mode only.
When this parameter is present, the image is pre-confirmed: It does not need to be confirmed at run time. This parameter is present in provisioning images by default. |
| Image type | All | No | Image index value: '0' for application code image, '2' for application data image. |
| Application or Data image download area offset | provisioning | Automatic | Used to generate .hex binary file format with destination address. |
| Firmware binary input file | All | Automatic | Location of the firmware binary file.
Automatically inherited from binary path configuration in project_appli.ini. |
| Image output file | All | Automatic | Location of the firmware image generated. |
6.6. Anti-rollback feature
Information on anti-rollback counter usage during the product life cycle:
The anti-rollback mechanism maintains two securely stored values for each counter in the OBKeys area: the previous value and the current value. Both values are updated securely whenever the counter changes. Because this implementation is entirely software based, it does not impose a limit on the number of counter updates. For more information on the security versions, refer to the security version.
6.7. imgtool script
The STM32TrustedPackageCreator PC tool generates firmware images using the MCUboot imgtool Python script, including STMicroelectronics modifications, to manage the MCUboot image format. Refer to the imgtool documentation in the MCUboot open-source software[1] for more information about the script.
The imgtool Python script is located in the /bin/Utilities directory of the STM32TrustedPackageCreator installation folder.
To check the imgtool command line used to generate an image, refer to the imgtool-command.log file, which STM32TrustedPackageCreator automatically creates at the following location: <User-Home>\STMicroelectronics\STM32CubeProgrammer\imgtool-command.log.
For detailed information, refer to Appendix B of the STM32TrustedPackageCreator tool user manual [3].
The imgtool script can be modified to meet customer-specific requirements, such as using an HSM for authentication-key management or changing the cryptographic scheme.
After modifying the script, the user can invoke it through STM32TrustedPackageCreator or directly, using the command recorded in the imgtool-command.log file.
7. References