This article provides an overview of the OEMiRoT solution integrated into the STM32G5 devices.
For a step-by-step user guide, refer to the wiki page How to start with OEMiRoT on STM32G5.
Applicable products:
| Type | Products |
|---|---|
| Microcontroller | STM32G564xx |
1. OEMiRoT presentation
1.1. Overview
OEMiRoT stands for OEM immutable (unchangeable) Root of Trust and acts as a 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, which is always executed after a system reset. It checks static protections (option bytes), activates runtime protections, and verifies the authenticity and integrity of the user application code before every execution.
- Secure Firmware Update: immutable code that detects new firmware image candidates. It checks the version (to prevent version downgrade), authenticity, and integrity before installing the firmware after decryption.
Information on STMicroelectronics modifications in MCUboot are available in the MCUboot User Guide[2].
1.2. Protection measures and security strategy
Cryptography ensures integrity, authentication, and confidentiality. However, the use of 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, thereby enhancing security robustness.
On the STM32G5 devices, the security strategy is based on the following hardware mechanisms:
- 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 STM32G5 wiki article).
- Boot configuration: BOOT_UBE, SBOOT_LOCK, SBOOTADD and SWAP_LOCKOUT option bytes are configured to establish a chain of trust by forcing the system to boot from a unique user flash memory address.
- WRP (Write Protection): Ensures OEMiRoT immutability as required by secure boot standards. The OEMiRoT code is configured as immutable.
- HDP (Hide Protection): When activated, any access (fetch, read, programming, erase) to the protected flash memory area is denied. In OEMiRoT examples, the HDP is used to protect the OEMiRoT code. The OEMiRoT executes in HDPL1 (HDP level 1), and the HDP level is incremented to HDPL2 when launching the application, making the OEMiRoT code no longer accessible.
- OBkeys (Option Bytes keys): HDPL1 OBkeys are a protected and isolated area used to store secrets such as OEMiRoT encryption and authentication cryptographic keys, and anti-rollback counters. This area is no longer accessible when switching from HDPL1 to HDPL2. Additionally, when HUK is supported by the product (hw crypto devices), the data stored in this area can be encrypted with DHUK (Derived Hardware Unique Key).
- MPU (Memory Protection Unit): Defines specific access rights for memory-mapped resources (flash, SRAM, peripherals). The MPU limits execution to the OEMiRoT code section during its execution and extends to the user application after verifying integrity and authenticity. This is dynamically managed at runtime.
- Anti-tamper protection: Protects sensitive data from physical tampering. Activated at OEMiRoT start and remains active during execution. On tamper detection, sensitive data in SRAM and cryptographic peripherals are erased immediately, and a reboot is forced.
- SRAM Erase on reset: OEMiRoT SRAM is automatically erased on system reset.
- SRAM Error code correction: Data integrity is verified on OEMiRoT SRAM read access.
Refer to the STM32G5xx Reference manual[3] for detailed descriptions.
Secure software coding techniques such as redundant critical tests, random delays, parameter validation, and flow control mechanisms are also implemented to enhance security robustness.
1.3. OEMiRoT activation
On STM32G5, activating OEMiRoT involves:
- Configuring the flash layout and personalizing secrets (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 processes in overwrite mode, showing all steps required to boot the application code from flash memory. For simplicity, optional application data image management is not activated in this example (but application data image is managed similarly to application code image).
- At reset, boot is forced on OEMiRoT using BOOT_UBE, SBOOT_LOCK, SBOOTADD and SWAP_LOCKOUT option bytes.
- OEMiRoT checks if new user application code is stored in the download slot. If so, it decrypts it and verifies its integrity, authenticity, security version (against anti-rollback counters), and optionally version dependencies with other image.
- If verification succeeds, image is decrypted and copied to the user application installation slot.
- OEMiRoT verifies the integrity and authenticity of the user application code image in the installation slot.
- If successful, OEMiRoT updates 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 backups 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 processes in swap mode, showing all steps required to boot the application code from flash memory. For simplicity, optional application data image management is not activated in this example (but application data image is managed similarly to application code image).
- At reset, boot is forced on OEMiRoT using BOOT_UBE, SBOOT_LOCK, SBOOTADD and SWAP_LOCKOUT option bytes.
- OEMiRoT verifies if the application code image in the installation slot is confirmed. If yes OEMiRoT updates anti-rollback counters.
- OEMiRoT checks if new user application code is stored in the download slot. If so, it decrypts it and verifies its integrity, authenticity, security version (against anti-rollback counters), and optionally version dependencies with other image.
- If the verification succeeds, the new image is decrypted and copied to the user application installation slot while the previous 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.
- It updates the hash reference.
- Then executes the user application and hides OEMiRoT.
At next boot, in case the image in installation slot is not confirmed, the image is reverted.
2. Feature list
The main features of OEMiRoT include:
- Integration of hardware security peripherals and mechanisms to implement a root of trust: Product State, Boot lock, MPU, WRP, HDP, OBkeys, anti-tamper and SRAM protections are combined to achieve the highest security level.
- OEMiRoT secrets and NV data are stored in secure keys storage area (OBKeys). These data are additionally encrypted with DHUK (when supported by the device).
- Dual slots mode: The downloaded image and the installed image reside in different memory slots, enabling:
- Safe image programming in the download slot, without impacting 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.
- SHA384 for image integrity verification.
- AES-CTR-256 symmetric encryption with keys encrypted via ECIES-P256, included in the image.
- Hardware cryptographic peripherals integration:
- PKA peripheral for signature verification acceleration (when supported by the product).
- SAES peripheral for image decryption acceleration (when supported by the product).
- 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 rejected.
- Accelerated boot: Image verification uses stored SHA references to skip signature verification if the image is unchanged, improving performance (MCUBOOT_USE_HASH_REF compilation switch).
- Fast wake-up from standby: Firmware image control is bypassed on wake-up to accelerate resume time, with software countermeasures maintaining security (OEMIROT_FAST_WAKE_UP compilation switch). Software countermeasures ensures the same level of security of the secure boot.
- Support for one application code image and optionally one application data image, each with dedicated anti-rollback counters, and 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 slots location: Download and installation slots are located inside internal user flash memory.
The different OEMiRoT use cases are demonstrated by dedicated OEMiRoT examples.
The following table lists the OEMiRoT examples on the STM32G5 boards:
| Example | NUCLEO-G564RE | 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 managing Secure Boot and Secure Firmware Update functions.
- Keys region: Stores personalized OEMiRoT secret keys (authentication and encryption keys).
- Anti-rollback counters region: Holds nonvolatile information about the last installed image versions (code and data) for the anti-rollback feature.
- Hash References region: Stores SHA references (one per image).
- Application code installation slot: Where the verified application executes.
- Application code download slot: Where candidate application code images are downloaded (encrypted).
- Application data installation slot: Where verified application data images are installed.
- Application data download slot: Where candidate application data images are downloaded (encrypted).
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
SRAM1 is selected for OEMiRoT execution because it supports erase on reset and ECC features.
- The entire SRAM1 is available for the application but is not persistent through reset or standby modes due to the erase-on-reset feature.
- Other SRAM regions are fully dedicated to application use and can be persistent across reset and standby modes based 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:
- Configuration of:
- Flash memory layout and example configuration
- Debug Authentication
- OEMiRoT keys
- Building of:
- OEMiRoT binary
- Application code image
- Application data image (if applicable)
- Programming of:
- DA password or certificates and OEMiRoT keys
- Option bytes (WRP, HDP, Boot, Product State, etc.)
- Binaries
The image below shows a visual representation of all these steps.
Pre-build and post-build commands are integrated into the projects:
- The pre-build command propagates the flash memory layout and example configuration into the projects before building.
- The post-build command generates firmware images from the application code build output.
5. Images generation
OEMiRoT manages application code and data images based on the MCUboot format, which includes:
- A header.
- The firmware binary (encrypted or clear, depending on image type).
- Metadata in TLV (Tag-Length-Value) format, enabling decryption and verification (hash, signature, etc.).
A magic value (16 bytes) is written at the end of the download slot (not part of the image) to trigger 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[4] (provided through STM32CubeProgrammer), is provided to generate firmware images. This tool embeds imgtool python script, which manages the MCUboot image creation.
The images are encrypted and signed using user-personalized keys.
Two types of images are generated:
- Provisioning image: Signed and in cleartext, programmed in the installation area during initial device programming.
- Firmware update image: Signed and encrypted, programmed in the download area 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 STM32G5 for location of these files. These XML files can be edited using STM32TrustedPackageCreator[4] 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 STM32G5 for location of these files.
These XML files can be edited using STM32TrustedPackageCreator[4] 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 (withOEMIROT_DEV_MODE undefined, that is, no logs).
It mainly depends on image size and system clock frequency. However it can also vary according to toolchain version and compile optimization level.
As indication, here are performances obtained with:
- 280 MHz system clock frequency
- IAR 9.60.3 - optimization High level, size-oriented
| Image size | 64 Kbytes | 128 Kbytes | 190 Kbytes |
|---|---|---|---|
| Boot time | 17 ms | 25 ms | 32 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.
- The
- 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) |
*OPEN
|
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 area 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.
- SRAM1 is used by OEMiRoT and is erased on every reset.
- 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[4] 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 address |
| 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 or key/certificate
Default DA password is provided in the OEMiRoT examples:
| Password filename | Description |
|---|---|
| da_config_password.xml | DA configuration, including DA password value (128 bits) |
Default DA key/certificate/permissions are provided in the OEMiRoT examples:
| Key/certificate filename | Description |
|---|---|
| private-key.pem
private-key_pub.pem |
SECP256R1 DA private key
SECP256R1 DA public key |
| da_cert.b64 | DA certificate |
| da_config_certificate.xml | DA permissions are provided as parameter 'Permission' |
DA password and key/certificate can be personalized using the STM32TrustedPackageCreator[4] tool with the xml file (da_config_password.xml and da_config_certificate.xml).
The templates generate binary file (da_config_password.obk and da_config_certificate.obk) programmed on the device during provisioning.
Refer to Security:Debug Authentication for STM32G5 for more information on DA for STM32G5.
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 counters usage during the product lifecycle:
- 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. As this implementation is entirely software-based, it does not impose any limit on the number of counter updates.
- For more details 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 [4].
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