OEMiRoT for STM32H7P

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.

  1. At reset, boot is forced on OEMiRoT using the BOOT_LOCK option bytes.
  2. OEMiRoT then checks whether a new user application code image is present in the download slot.
  3. If present, the image is decrypted and its integrity, authenticity, security version number, and, when applicable, version dependencies with other images are verified.
  4. If verification succeeds, the image is copied to the user application installation slot.
  5. OEMiRoT then verifies the integrity and authenticity of the user application code image in the installation slot.
  6. If the verification is successful, OEMiRoT updates the anti-rollback counters and reference hashes, then executes the user application and hides OEMiRoT.
Information
OEMiRoT is using a service library located in system flash to jump to application and increment HDP level to HDPL2, thus disabling access to OEMiRoT code and assets.

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.

  1. At reset, boot is forced on OEMiRoT using the BOOT_LOCK option bytes.
  2. OEMiRoT checks whether the application code image in the installation slot is confirmed. If it is confirmed, OEMiRoT updates the anti-rollback counters.
  3. OEMiRoT checks whether new user application code is present in the download slot.
  4. 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.
  5. 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.
  6. OEMiRoT verifies the integrity and authenticity of the user application code image in the installation slot.
  7. OEMiRoT updates the hash reference.
  8. 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.

Information
OEMiRoT is using a service library located in system flash to jump to application and increment HDP level to HDPL2, thus disabling access to OEMiRoT code and assets.

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.
Information
The entire provisioning process is managed through a provisioning script that guides the user step-by-step. For more information, refer to the How to start with OEMiRoT on STM32H7P wiki page.

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_MODE is 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).
Warning
At the end of development, OEMIROT_DEV_MODE must be undefined, and Product state and minimum Product state must be configured to CLOSED or LOCKED to achieve the highest security level.

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 defined (Development mode)
  • OEMIROT_DEV_MODE undefined (Production mode)
OEMIROT_DEV_MODE boot_pre_include_global.h
Information
Disabling OEMIROT_DEV_MODE can reduce the OEMiRoT binary size by approximately 10 KB. This may allow the OEMiRoT code area in flash memory to be reduced, thereby maximizing the areas available for application images (refer to Flash memory layout).

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
  • OPEN
  • IROT-PROVISIONED
  • TZ-CLOSED
  • CLOSED
  • LOCKED
final_product_state provisioning.ini
Product state min

(controlled by OEMiRoT)

  • OPEN
  • IROT-PROVISIONED
  • TZ-CLOSED
  • CLOSED
  • LOCKED
min_product_state provisioning.ini
Information
The provisioning script generates a list of STM32CubeProgrammer commands (option bytes and binaries programming) in the cubeprogrammer_cmd.txt file, which can assist in preparing production scripts.

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.
Warning
When OEMIROT_FAST_WAKE_UP is enabled, the RoT relies on the hardware SBF (standby flag) to skip firmware image verification. The SBF flag remains set when the application is entered after a wake-up from standby mode. This allows the application to handle its own software context restoration. To maintain a secure execution environment, the user application must clear the SBF flag after it is processed.

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

Warning
Default OEMiRoT keys provided in the example must not be used in final product! They must be personalized with your own values.

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)
Warning
Default DA password and keys/certificate provided in the example must not be used in final product! They must be personalized with our own values.

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':

  • Index: '0' for application code image, '2' for application data image
  • Version: x.y.z (x ≤ 255, y ≤ 255, z ≤ 65535).

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