Skip to main content

Secure Boot in Clea OS on Qualcomm QCS615 Platforms

This document describes the Secure Boot chain and provisioning flow used by Clea OS on supported Qualcomm QCS615 platforms.

The implementation consists of two complementary security stages:

  1. Qualcomm Secure Boot, which authenticates the Qualcomm firmware chain from the hardware root of trust to the UEFI firmware;
  2. UEFI Secure Boot, which authenticates the operating-system boot artifacts managed by UEFI and GRUB.
info

The procedures and command examples in this document are specific to the supported Clea OS QCS615 integration. Other Qualcomm SoCs, firmware packages or board variants may use different boot components, partitions, tools or provisioning procedures.

Security Model​

The Clea OS security model establishes a chain of trust from the hardware root of trust up to the Clea OS kernel and initial RAM filesystem.

The main authenticated stages are:

  1. the Primary Boot Loader (PBL) in ROM validates the next Qualcomm boot stage using the root hash stored in QFPROM;
  2. the authenticated Qualcomm boot chain validates the subsequent firmware components;
  3. the supported QCS615 firmware stack authenticates the Secure Monitor, Hypervisor and UEFI firmware;
  4. UEFI Secure Boot validates the operating-system boot artifacts;
  5. GRUB chainloads the signed Unified Kernel Image (UKI);
  6. UEFI verifies the UKI signature before execution.
important

This chain protects the bootloader, kernel and initial RAM filesystem. It does not, by itself, guarantee the integrity of every user-space file or process. A verified root filesystem or an equivalent mechanism is required when the complete user-space image must also be protected.

Validation Chain​

The supported QCS615 Clea OS boot flow uses the following logical chain:

  1. Hardware reset and PBL
    The PBL executes from ROM and authenticates the eXtensible Boot Loader (XBL) using the root-certificate hash stored in QFPROM.

  2. Qualcomm firmware chain
    XBL and the subsequent authenticated firmware components establish the Qualcomm chain of trust.

  3. Secure Monitor and Hypervisor
    The supported firmware stack validates and transfers control through the Secure Monitor and Qualcomm Hypervisor stages.

  4. UEFI firmware
    The authenticated Qualcomm firmware chain validates the UEFI firmware. This marks the boundary between Qualcomm Secure Boot and UEFI Secure Boot.

  5. UEFI payloads
    UEFI validates the supported operating-system boot artifacts, including:

    • the board Device Tree;
    • the GRUB UEFI executable;
    • the Unified Kernel Image.

  6. Clea OS kernel
    GRUB chainloads the signed UKI as a UEFI executable. The UEFI Secure Boot implementation verifies its PE/COFF signature against the enrolled signature database before transferring control.

Trust architecture overview

info

For additional background, refer to the Qualcomm cold boot architecture documentation.

In Clea OS, GRUB is used as the UEFI boot manager.

Prerequisites​

Before starting the signing or provisioning process, verify that:

  • the target board and software release are supported;
  • the Clea OS signing scripts have been generated by the matching build;
  • the Qualcomm signing and provisioning tools are available;
  • the OEM and product identifiers have been assigned;
  • the anti-rollback policy has been defined;
  • production signing keys are available through an approved key-management process;
  • a recovery and manufacturing strategy has been documented.
danger

Programming QFPROM or RPMB keys is irreversible. Perform all signing and validation activities on dedicated development units before provisioning production devices.

Qualcomm Secure Boot

Qualcomm Secure Boot is anchored in the hardware root of trust. QFPROM stores the hash of the root certificate and the security configuration used by the Qualcomm boot chain.

Clea OS Provisioning Profiles​

The Clea OS sign.sh utility provides two provisioning profiles:

  • basic;
  • complete.

These are Clea OS signing-tool profiles, not generic Qualcomm command-line modes.

basic​

The basic profile:

  • enables image authentication;
  • configures the OEM ID;
  • configures the OEM Product ID;
  • uses the root certificate located in the selected key directory.

It is intended for controlled development and validation activities.

complete​

The complete profile includes the basic configuration and also supports the production security settings required by the Clea OS QCS615 implementation, including:

  • debug and JTAG restrictions;
  • anti-rollback configuration;
  • QFPROM protection;
  • RPMB key provisioning;
  • enforcement of the supported Qualcomm firmware-authentication policy.
caution

The exact fuse configuration must be reviewed against the manufacturing, field-recovery and service strategy for the product. Disabling debug interfaces, enabling anti-rollback and locking QFPROM can prevent later diagnostic or recovery operations.

For production deployment, use the complete profile unless a different provisioning policy has been explicitly approved for the product.

Key Directory​

The Qualcomm Secure Boot key directory must contain:

  • qpsa_rootca.cer: self-signed Root CA certificate;
  • qpsa_attestca.cer: Attestation CA certificate signed by the Root CA;
  • qpsa_attestca.key: Attestation CA private key;
  • qpsa_rootca.key: Root CA private key, required when generating the fuseblower image.
warning

Private keys must not be stored in source-control repositories, public release packages, shared build directories or target devices.

Production keys should be generated, backed up and used according to the organization's key-management policy, preferably through an isolated signing service or Hardware Security Module.

To generate the keys, follow Qualcomm's official guide.

Generating the Fuseblower Image​

The fuseblower image is generated using sign.sh.

./sign.sh \
    --keydir <KEYDIR> \
    --soc qcs615 \
    --fuseblower complete \
    --oem-id <OEM_ID> \
    --oem-product-id <OEM_PRODUCT_ID> \
    --anti-rollback-version <VERSION>

The command generates a signed sec.elf containing the requested provisioning configuration.

note

Values such as OEM_ID, OEM_PRODUCT_ID and the anti-rollback version are product security parameters. Do not copy example values into a production configuration. The same values must be used consistently during provisioning, signing and authenticated programming.

On the supported QCS615 platform, the generated sec.elf is written to the designated security-data partition and consumed by the Qualcomm provisioning flow during the next boot.

danger

Consuming sec.elf permanently modifies the device security configuration. Before flashing it:

  1. verify the contents of the generated provisioning package;
  2. confirm the root-certificate hash;
  3. verify the OEM and product identifiers;
  4. validate the anti-rollback version;
  5. confirm the selected debug and QFPROM lock settings;
  6. ensure that the corresponding production signing keys are available and backed up.

Signing Boot Images​

After provisioning, all boot images covered by Qualcomm Secure Boot must be signed with the corresponding keys and identifiers.

Run:

./sign.sh \
    --keydir <KEYDIR> \
    --soc qcs615 \
    --sign \
    --oem-id <OEM_ID> \
    --oem-product-id <OEM_PRODUCT_ID> \
    --anti-rollback-version <VERSION>

The generated artifacts include the signed Qualcomm .elf and .mbn images required by the target build.

note

Always use the signing package generated by the same Clea OS build as the images being signed. Mixing signing metadata or configuration from different builds can generate an invalid image set.

Anti-Rollback​

When anti-rollback is enabled, the device verifies the version value carried by the authenticated image.

An image whose version is lower than the version accepted by the device is rejected.

warning

Anti-rollback counters and fuse values are monotonic. Increasing the accepted version can permanently prevent earlier software releases from booting. Define the versioning and recovery policy before enabling this mechanism in production.

Validated Image Programming​

Devices configured to require authenticated programming must be reflashed using Qualcomm Validated Image Programming (VIP).

Generate the VIP authentication artifacts using the Clea OS signing script:

./sign.sh \
    --keydir <KEYDIR> \
    --soc qcs615 \
    --sign \
    --vip \
    --oem-id <OEM_ID> \
    --oem-product-id <OEM_PRODUCT_ID> \
    --anti-rollback-version <VERSION>

Depending on the Qualcomm tool and MBN configuration, the flow generates:

  • a digest table;
  • a digest payload to be signed;
  • the signed digest package;
  • the chained digest file used during authenticated programming.

Use PCAT with VIP enabled and select the files generated by the matching signing run.

tip

PCAT and the associated Qualcomm tools must be obtained through the Qualcomm Software Center using an appropriately licensed account.

caution

VIP files are tied to the selected image set and signing configuration. Do not reuse digest files after rebuilding or modifying the images.

UEFI Secure Boot

After the Qualcomm-authenticated firmware chain transfers control to UEFI, UEFI Secure Boot authenticates the Clea OS boot artifacts.

Boot Flow​

The supported flow is:

  1. UEFI validates the board Device Tree using the platform-specific detached signature;
  2. UEFI validates the signed GRUB executable, normally installed as bootaa64.efi;
  3. GRUB chainloads the signed UKI;
  4. UEFI verifies the PE/COFF signature of the UKI before execution.

The UKI contains the Clea OS kernel and initramfs, together with the metadata included by the build configuration.

UEFI secure boot flow

note

The exact UKI contents depend on the Clea OS build configuration. They may also include the kernel command line, OS release information or other measured boot metadata.

UEFI Variables and RPMB​

UEFI Secure Boot uses the standard authenticated variables:

  • PK: Platform Key;
  • KEK: Key Exchange Key database;
  • db: allowed signature database;
  • dbx: revoked signature database, when supported and provisioned.

On the supported Qualcomm implementation, these variables are protected through the platform secure-storage mechanism backed by the Replay Protected Memory Block (RPMB).

RPMB access is mediated by the secure firmware. The operating system cannot directly replace authenticated UEFI variables without satisfying the platform authorization policy.

Architecture of RPMB access

RPMB Provisioning​

Production Provisioning​

For production devices, the RPMB key is provisioned as part of the Clea OS complete Qualcomm Secure Boot flow.

The platform derives and programs the device-specific key through the supported secure provisioning mechanism.

Development Provisioning​

A development RPMB key can be programmed using the platform test utilities.

danger

RPMB key programming is irreversible. A device provisioned with a development or test key must be treated as a disposable development unit and must never enter the production manufacturing flow.

UEFI Key Generation​

Generate the UEFI Secure Boot certificates and authenticated variable-update files according to the supported Qualcomm and Clea OS key-generation procedure.

Follow this guide to generate the keys and certificates for UEFI Secure boot.

The key directory used by sign-uefi.sh must contain:

  • PK.auth;
  • KEK.auth;
  • db.auth;
  • db.key;
  • db.crt;
  • dbx.auth, when revocation support is used.

The private key db.key is used to sign the UEFI binaries.

Signing UEFI Artifacts​

Run the Clea OS UEFI signing utility from the deployment directory:

./sign-uefi.sh --keydir <KEYDIR>

The script:

  • signs the supported UEFI executables;
  • signs the board-specific Device Tree artifacts;
  • signs the UKI;
  • places the authenticated variable-update files in the boot partition.
warning

The signing and enrollment package contains security-sensitive material. Do not distribute private keys or intermediate signing files with the Clea OS image.

UEFI Key Enrollment​

On the next boot, the Clea OS GRUB integration detects the authenticated variable-update files and invokes the platform-specific enrollment flow.

The flow installs the UEFI Secure Boot variables into the RPMB-backed secure storage and then reboots the device with UEFI Secure Boot enforcement enabled.

important

Before enrollment, verify that:

  • GRUB and the UKI are signed by a key included in db;
  • the Platform Key and Key Exchange Keys belong to the intended product;
  • the update files are valid and have not expired;
  • the boot partition contains a complete and consistent signed image set;
  • a recovery path exists for key rotation or revocation.

After enrollment, verify that:

  • UEFI Secure Boot reports an enabled state;
  • the signed GRUB executable boots successfully;
  • the signed UKI is accepted;
  • an unsigned or incorrectly signed UEFI executable is rejected;
  • enrollment files are removed or otherwise prevented from being processed repeatedly.

Production Validation Checklist​

Before releasing a provisioned device, verify:

  • the Qualcomm root-certificate hash stored in QFPROM;
  • the OEM ID and OEM Product ID;
  • the configured anti-rollback version;
  • the selected debug and QFPROM lock state;
  • successful authentication of all Qualcomm firmware images;
  • successful enrollment of PK, KEK, db and, when used, dbx;
  • successful validation of the Device Tree, GRUB and UKI;
  • rejection of altered or incorrectly signed images;
  • the authenticated programming and recovery procedures;
  • archival of the signing configuration and key identifiers for the Clea OS release.
warning

Keep signing records, key identifiers, provisioning parameters and release-specific signing metadata under controlled access. They are required for secure updates, recovery and long-term product maintenance.