Secure Boot in Clea OS on NXP Platforms

This document describes the Secure Boot implementation used by Clea OS on supported NXP i.MX platforms.

Depending on the SoC family, Clea OS uses one of the following NXP Secure Boot technologies:

Platform family	Secure Boot technology	Boards supported
Supported i.MX8M platforms	High Assurance Boot version 4 (HABv4)	SOM-SMARC-MX8M-Plus (D18)
Supported i.MX9 platforms	Advanced High Assurance Boot (AHAB)	SOM-SMARC-MX93 (E39) - SOM-SMARC-MX95 (E88)

note

Not all devices in the i.MX8 family use HABv4. This document applies only to the Clea OS platforms explicitly supported by the relevant release and signing package.

Security Model

When the device is correctly provisioned and placed in the Closed lifecycle state, Secure Boot prevents unauthenticated boot artifacts from being executed as part of the verified boot chain.

The implementation covers the boot artifacts managed by the Clea OS boot flow, including:

• the NXP boot container or bootloader image;
• the U-Boot environment;
• the U-Boot boot script;
• the kernel FIT image.

important

Secure Boot protects the authenticated boot chain. It does not, by itself, guarantee the integrity of every user-space file or process. Additional mechanisms are required when the root filesystem or application payloads must also be verified.

Unified Boot Script and Environment

To reduce runtime complexity and the number of artifacts that must be signed, Clea OS packages the boot script and boot environment as two single files:

• boot.scr
• boot.env

At build time, the file-include.bbclass processes the include directives and merges the configuration fragments into the final files.

This approach provides a common boot-flow structure across HABv4 and AHAB platforms while keeping the platform-specific authentication logic inside U-Boot.

The auth_image Command

Clea OS adds the custom U-Boot command auth_image to provide a common authentication interface for HABv4 and AHAB platforms.

auth_image <address> <env_var> [<size_var>]

The command:

1. inspects the image located at <address>;
2. invokes the authentication mechanism supported by the SoC;
3. validates and, when required, extracts the authenticated payload;
4. stores the final payload address in <env_var>;
5. optionally stores the payload size in <size_var>.

For AHAB images, the command authenticates the AHAB container and identifies the payload contained in it. For HABv4 images, it validates the IVT and CSF information appended to the image.

This allows the boot script to use the same interface on both architectures.

Open and Closed Devices

On a Closed device, an authentication failure stops the affected boot path.

On an Open development device, the behavior depends on the Clea OS boot-flow configuration. Authentication errors may be reported without preventing execution, allowing development and signing validation before the device is permanently closed.

caution

An Open device must not be considered production-secure, even when signed images are used. Secure Boot enforcement is only guaranteed after the required OTP fuses have been programmed and the device has entered the Closed lifecycle state.

Prerequisites

Before signing or provisioning a device, verify that:

• the target board and SoC are supported by the Clea OS release;
• the matching Clea OS signing package is available in the build output;
• the required signing keys and certificates have been generated (see below);
• docker is installed in your host;
• recovery and manufacturing procedures have been defined.

The generated signing package normally includes:

• sign.sh;
• platform-specific YAML configuration files;
• the clea-os-signer container definition or image reference;
• the artifacts required for the selected target.

warning

Programming OTP fuses and closing a device are irreversible operations. Always validate the complete signed boot flow on a development unit before provisioning production hardware.

i.MX9 AHAB Secure Boot

Supported i.MX9 platforms use NXP Advanced High Assurance Boot (AHAB).

Clea OS uses the NXP Secure Provisioning SDK (SPSDK) through the clea-os-signer container for image signing and provisioning support.

Generating keys and certificates

Generating keys and certificates for AHAB is done with the nxpcrypto utility, part of NXP's SPSDK (Installation guide). You can either install it manually with PIP or use it via the secodocker/clea-os-signer Docker image.

To generate the four ECC key pairs needed for AHAB Secure Boot, run the following commands.

nxpcrypto key generate -k secp384r1 -o srk_ecc384_1.pem
nxpcrypto key generate -k secp384r1 -o srk_ecc384_2.pem
nxpcrypto key generate -k secp384r1 -o srk_ecc384_3.pem
nxpcrypto key generate -k secp384r1 -o srk_ecc384_4.pem

Signing Images

Run the sign.sh script from the Clea OS deployment directory:

./sign.sh --sign [--update-wic=<image.wic>]

The available options include:

• --sign: generates signed versions of the supported boot artifacts;
• --update-wic=<image.wic>: injects the generated signed artifacts into the specified WIC image.

The signed artifacts normally include:

• imx-boot;
• boot.scr;
• boot.env;
• the kernel FIT image.

When --update-wic is used, the script updates the partitions used by the target platform, such as the boot-system and kernel partitions.

note

The exact artifact names and partition layout may vary by platform. Use the files and instructions generated by the Clea OS build for the target board.

Signing Configuration

The signing flow is driven by SoC-specific YAML files deployed with the signing package, for example:

• imx_boot_ahab.yaml;
• fit_ahab.yaml;
• configuration files for boot.scr and boot.env.

These files define information such as:

• the components included in the AHAB container;
• load addresses;
• entry points;
• signing parameters.

Do not modify these values unless required by a documented platform customization.

Device Provisioning

During the signing process, sign.sh generates the provisioning command files required to program the Super Root Key (SRK) hashes into the device OTP fuses.

The generated files are placed in the signing output directory. Depending on the platform, they may include files similar to:

ahab_oem0_srk0_hash_nxpele.bcf

The NXP nxpele utility can then execute the generated provisioning sequence.

Example for a supported i.MX95-based platform:

nxpele \
    -f mimx9596 \
    --uboot-prompt "MX SECO U-Boot > " \
    -d uboot_serial \
    -p /dev/ttyUSB0 \
    batch output/ahab_oem0_srk0_hash_nxpele.bcf

note

The device identifier, serial port, U-Boot prompt and generated file name in the example are platform-specific. Replace them with the values provided for the target board.

After the SRK hashes have been programmed, the device remains in the Open lifecycle state until the close operation is performed.

On supported Clea OS U-Boot builds, the device can be moved to the Closed state using the platform-specific AHAB close command, such as:

ahab_close

danger

Closing an AHAB device is irreversible. Before running the close command:

1. boot the complete signed image successfully;
2. verify the AHAB authentication events;
3. confirm that the programmed SRK hash matches the production signing keys;
4. verify that a modified or incorrectly signed image is rejected;
5. confirm that a documented recovery procedure is available.

i.MX8M HABv4 Secure Boot

Supported i.MX8M platforms use High Assurance Boot version 4 (HABv4).

Clea OS uses the NXP Code Signing Tool (CST) through the clea-os-signer container.

Generate keys and certificates

Generating keys and certificates for HABv4 is done with the NXP Code Signing Tool (CST) utility. You can either acquire it from the NXP website or use it via the secodocker/clea-os-signer Docker image.

The CST package contains documentation on how to use it to generate the keys.

Signing Images

Run:

./sign.sh --sign [--update-wic=<image.wic>]

The script automates the HABv4-specific processing.

Data Images

For artifacts such as boot.env, boot.scr and the kernel FIT image, the script:

1. pads the binary to the required alignment;
2. generates and appends an Image Vector Table (IVT);
3. generates the corresponding Command Sequence File (CSF) configuration;
4. invokes cst to create the signature block;
5. appends the generated signature information to the image.

imx-boot

For imx-boot, the script parses the build logs produced during the Yocto build, including the relevant .log and .fitlog files.

It uses the extracted HAB block offsets to:

1. generate the CST signing configuration;
2. sign the required boot components;
3. inject the generated signatures into the final imx-boot image.

Updating a WIC Image

When --update-wic=<image.wic> is specified, the script writes the signed artifacts into the corresponding partitions of the target WIC image.

note

Always use the build logs and signing configuration generated for the same Clea OS build as the image being signed. Reusing offsets or signing metadata from another build can produce an invalid boot image.

Device Provisioning

The HABv4 key-generation process produces the SRK hash data that must be programmed into the device OTP fuses.

On supported Clea OS U-Boot builds, the platform-specific fuse_prog command can be used to program the generated fuse data.

note

fuse_prog is part of the supported Clea OS U-Boot integration and may not be available in a generic U-Boot build. Use the command and input format provided with the target platform documentation.

After the SRK hash has been programmed and verified, the corresponding SEC_CONFIG fuse must be programmed to move the device to the Closed state and enforce HAB authentication.

danger

Programming SEC_CONFIG is irreversible. An incorrectly signed bootloader will no longer boot after the device is closed.

Before closing the device:

1. boot all signed artifacts successfully while the device is Open;
2. inspect the HAB event log and confirm that no authentication errors are reported;
3. verify the programmed SRK hash;
4. test rejection of an altered or incorrectly signed image;
5. retain a controlled backup of the production signing keys.

Recommended Production Validation

For both HABv4 and AHAB platforms, perform at least the following checks before production provisioning:

• verify the full signed boot sequence on an Open device;
• confirm that every artifact in the supported boot chain is authenticated;
• verify the reported HAB or AHAB authentication events;
• confirm that an unsigned, altered or incorrectly signed artifact is rejected;
• verify the recovery and update procedures;
• record the key identifiers and SRK hash used for the product;
• archive the signing configuration together with the corresponding Clea OS release.

warning

Private signing keys are production security assets. Do not store them in source-control repositories, release packages, shared build directories or target devices. Production keys should be managed through an approved key-management process, preferably using an isolated signing service or Hardware Security Module.