Securing NXP i.MX93 with spsdk and Keyfactor

1. Introduction

1.1. Scope of this document

This guide demonstrates how to implement AHAB secure boot with SignServer and spsdk. It prioritizes clarity and hands-on learning. While sections talk about production considerations, organizations deploying to production should conduct a thorough security review and adapt these procedures to meet their specific security requirements, compliance needs, and operational constraints. This document is not meant to replace these reviews as each companies risk assessment is different.

1.2. What You'll Learn

• Understanding AHAB boot architecture (~10 min read)
• Setting up PKI for secure boot (~20 min)
• Configuring SignServer (~45 min)
• Installing and using spsdk (~30 min)
• Signing images and programming fuses (~15 min)

Total time: ~2 hours
Prerequisites: Linux familiarity, basic PKI knowledge, access to i.MX93 board

1.3. Conventions used in this document

1.3.1. Code blocks

Code blocks designate commands to run (or output from commands). They look like this:

Code Block To Run

Inside of code blocks, you must replace anything in < and > brackets with your specific data. For example:

cat <filename_to_dump>

means that we replace <filename_to_dump> with the actual file we want to view the output of. If we want to see the contents of the file ~/.bashrc then the above command would become cat ~/.bashrc instead.

1.3.2. Bold text

Text in bold indicates a screen title, menu selection, or button text expected to be clicked on the screen during configuration. For example:

In the Workers tab we add a worker by clicking Workers > Add…

or

Navigate to Add… under the Workers tab

2. Understanding AHAB Boot Architecture

2.1. “Before/After” AHAB Boot Comparison

2.2. i.MX93 AHAB Boot Sequence

The diagram below shows the i.MX93 boot sequence. Before diving in, here are three key concepts:

1. Boot ROM verifies the bootloader chain

• Containers 1-3 are verified before any code runs

• Linux Kernel/DTB is verified separately (Container 4)

2. Why separate OS verification?

• ✅ Update Linux without touching bootloader

• ✅ Deploy different OS images to same bootloader

• ✅ Separate bootloader keys from OS keys (if desired)

3. ELE does the heavy lifting

• Dedicated security co-processor

• Performs all cryptographic operations

• Protects SRK hash from software access

For detailed component definitions, see the eMMC/SD Configuration section below.

2.3. i.MX93 eMMC/SD configuration

The following figure represents the storage configuration that the OEM provisions. This could be eMMC, an SD card, etc.

Note: These are ordinal container numbers. Some tools use 0-based indexing (Container 0 = first container).

This table describes the components used in AHAB boot in the diagram above.

2.4. Configuring Yocto NXP i.MX93 build for AHAB boot

• Establish standard Yocto build environment using NXP's manifest-based BSP distribution
  (imx-linux-scarthgap branch)
• Integrate the meta-imx-frdm layer into the build environment
• Build the base image to create a populated u-boot source code segment under the appropriate tmp/work directory. Example: For the imx91 the file is imx91_11x11_frdm_defconfig

• Create a custom meta layer to extend the default image recipe
• Create U-Boot bbappend file in custom layer (u-boot-imx_2024.04.bbappend)
• Generate patch file that modifies board-specific defconfig to add CONFIG_AHAB_BOOT=y
• Configure custom layer to inject the patch into U-Boot build process via FILESEXTRAPATHS and SRC_URI
• Set appropriate layer priority to ensure custom modifications take precedence (10 should work).
• Rebuild U-Boot and image with AHAB boot support enabled
• Verify CONFIG_AHAB_BOOT is active in compiled U-Boot (ahab_status command available in U-Boot console)
• Change directories to the deploy/images/<board_model> and use the mkimage_imx8 tool with proper offsets for the board to create the flash_os.bin file.
• Copy the flash_os.bin and imx-boot-imx93frdm-sd.bin-flash_singleboot file off the build machine. These are the files used below in the signing operations.

The approach outlined above follows standard Yocto Project practices for customizing BSP components without modifying upstream source repositories.

3. Setting up PKI for secure boot

3.1. PKI Configuration - Considerations

The actual on-chip configuration does not require a PKI. However, SignServer does require one to verify that the worker is within its active/authorized time period. The ultimate configuration for the PKI behind SignServer must follow the Certificate Policy (CP) and Certificate Practice Statement (CPS) for the organization.

Items to consider:

• The worker keys are used to create the hash (SRKH) burnt onto the devices (efuses).

  • The PKI keys are only used by SignServer

  • The worker keys form the Root of Trust for secure boot; these keys are the only ones the device trusts in the boot process.

• SRKH is immutable on devices in the field.

  • The worker keys cannot change over time.

  • SRKH holds four (4) public keys

  • All four (4) keys must be of the same algorithm and size.

The implications here are:

• Device trust is based on SRKH (eFuse-burned hash), not certificates.

• Operational security is enforced via SignServer access controls.

• Compromised keys are addressed via worker deletion and hardware revocation fuses on devices, not certificate expiration.

• Keys cannot be rotated or changed once devices are fielded

Therefore, the use case is outside of standard PKI practices & organizations should treat this as such. Also, there is precedent in the industry via IEEE 802.1AR for hardware-bound device identity certificates lasting for the life of the device (IDevID).

3.2. Example PKI structure

Here is an example PKI structure for this signing use case. HSMs should be FIPS 140 certified and (preferably) Level 3.

3.3. Focus Security Where It Actually Matters

Real security controls:

• HSM protection of private keys and signing operations

• Offline Root CA with ceremony-based access (to create and sign workers)

• Multi-person authorization for production signing operations

  • One person can enable the worker

  • Another must sign

• Comprehensive audit logging and reviews

• Geographic separation of key backups

• Revocation happens in the revocation fuses on the i.MX93

Security exceptions:

• Certificate expiration

• Certificate renewal with same keys

• Intermediate Issuing CA

The best practices of certificate expiration assumes the keys are rotatable. The assumption does not hold here, so these PKI best practices don’t apply.

4. Configuring SignServer

4.1. Setup Overview

• Create key pairs (~10 minutes)
• Create signing workers (~15 minutes)
• Create CSRs (~5 minutes)
• Import signed certificates (~10 minutes)
• Extract public keys (~5 minutes)

4.2. Signing workflow diagram

4.3. Overview of SignServer

Refer to the above diagram elements:

4.4. Create key pairs

The first step in configuring Keyfactor’s SignServer is to create the cryptographic keys associated with the signing operation (worker).

1. Log into SignServer as an administrator.

2. Access the SignServer Administration Web.

3. On the Workers page, click the CryptoTokenXXX worker. Where XXX is the name of the interface type configured by Keyfactor and attached to your HSM or KeyVault.

4. Click the Crypto Token tab, select Generate Key…

5. Specify the following.

   • New Key Alias: <friendly name for the token>

   • Key Algorithm: <pulldown for the key type>

   • Key Specification: <key length or curve to use>

6. Click Generate.

7. Repeat steps 4 through 6 for the remaining keys.

4.5. Create signing workers

Workers are the unit that performs certain activities like signing files or hashes. Each worker has its own configuration (properties), a unique ID, and optionally a human-readable name.

For AHAB Secure Boot, we use a PlainSigner type of worker. This worker will take a HASH and then sign it with an appropriate private key. To do this:

1. Log into SignServer as an administrator.

2. Access the SignServer Administration Web.

3. On the Workers page, click the Add… button and select FROM FILE on the next page

4. Paste a configuration into the box [see below] and select APPLY

5. Repeat steps 3 and 4 for the remaining keys

Here is the configuration that created the worker

# Configure a PlainSigner Worker for AHAB Boot
# WORKERGENID1 tells SignServer to automatically assign the next worker number
WORKERGENID1.NAME=PlainSigner-SRK1
WORKERGENID1.DESCRIPTION=Plain Signer for NXP AHAB Boot using SRK1
WORKERGENID1.TYPE=PROCESSABLE
WORKERGENID1.IMPLEMENTATION_CLASS=org.signserver.module.cmssigner.PlainSigner

# Crypto Token and Key used for signing operations - Replace with yours
WORKERGENID1.CRYPTOTOKEN=CryptoTokenP12
WORKERGENID1.DEFAULTKEY=AHAB_SRK1

# Signing configuration
# NOTE: AHAB Requires NONEwithRSAandMGF1 for RSA Signing
#       as PSS padding is a requirement for RSA
WORKERGENID1.ALLOW_CLIENTSIDEHASHING_OVERRIDE=true
WORKERGENID1.ACCEPTED_HASH_DIGEST_ALGORITHMS=SHA-256
WORKERGENID1.CLIENTSIDE_HASHDIGESTALGORITHM=SHA-256
WORKERGENID1.SIGNATUREALGORITHM=NONEwithECDSA

# Authorization of who can sign
WORKERGENID1.AUTHTYPE=NOAUTH

# Auditing and Logging
WORKERGENID1.AUDITLOGGING=ALL
WORKERGENID1.DO_LOGREQUEST_DIGEST=TRUE
WORKERGENID1.WORKERLOGGER=org.signserver.server.log.SecurityEventsWorkerLogger

4.6. Create CSRs

The next step is to have the workers create a CSR (certificate signing request) that your PKI can sign & eventually upload the signed certificate into the worker.

1. Back on the Workers page, click the name of the worker you just created.

2. Click the GENERATE CSR… button along the top of the Status Summary page.
   

   

   1. WORKER: is already populated

   2. KEY: is already populated

   3. SIGNATURE ALGORITHM: Choose an appropriate signature algorithm like SHA256withRSA or SHA256withECDSA that corresponds to your key.

   4. DN: is the Distinguished Name for the new certificate such as CN=Plain Signer Test,O=My Company, C=SE

   5. Click Generate.

   6. Click the DOWNLOAD button and save the CSR file.
      

      

3. Bring the CSR file to your Certification Authority to get the entire CHAIN of PEM certificates [leaf to root].

4. Repeat for the remaining workers.

4.7. Import signed certificates

1. Click the Workers tab at the top of the page.

2. Click the name of the worker you just created.

3. Click Install certificates and browse for the certificate chain file.

4. Click Add to have the certificates listed in the chain.

5. Click Install.

6. Once the certificates have been installed, the signer should be in state ACTIVE. If not, check the top of its Status Summary page for any errors.

7. Repeat for the remaining workers.

4.8. Extract public keys

1. You downloaded the certificate chains above, take these files and copy the PEM for the leaf certificate into a file. [The leaf should be the first certificate in the chain.]

2. Paste the leaf certificate into a file.

3. Run the following openssl command on the file to extract the key into a file:

   CODE

   openssl x509 -noout -pubkey -in <your_x509_cert_file> > <file_file_to_store_key>

4. Repeat for all keys

5. Installing and using spsdk

5.1. Create a virtual machine

In this example, we use Ubuntu 24.04 LTS as the server (headless) VM. After the VM is installed proceed to the next steps.

Install prerequisites

sudo apt update && sudo apt upgrade -y
sudo apt install -y python3-venv

Create a virtual environment

python3 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip

Install spsdk and the Keyfactor integration for spsdk:

pip install --upgrade setuptools
pip install spsdk
pip install spsdk-keyfactor

5.2. Create a directory structure & populate it with the right files

Make the directory

mkdir ~/imx93_demo

Move the binaries to sign into it

cp -v imx-boot-imx93frdm-sd.bin-flash_singleboot ~/imx93_demo
cp -v flash_os.bin ~/imx93_demo

Move the root of trust

You need to trust SignServer’s https interface, so download and install the https Root for signserver’s web interface:

cp -v <root_ca_cert_for_signserver_http.pem> ~/imx93_demo

Move your mTLS certificate and key

To authenticate to SignServer, we will use mTLS.

Create a p12 from a PKI that SignServer trusts, and copy that into the directory as well:

cp -v auth_creds.p12 ~/imx93_demo

Create a password file with the password of the P12 to pass to spsdk

echo "my_password" > ~/imx93_demo/auth_creds.pw

Move the public keys to the directory

cp -v keyfactor_srk_public_key?.pub ~/imx93_demo

Create an environment variable file

vi ~/imx91_demo/.keyfactor.env

paste the values for your signing instance into it:

KEYFACTOR_HOST="https://<your_signserver_instance> "
KEYFACTOR_HOST_VERIFY="~/imx93_demo/<root_ca_cert_for_signserver_http.pem>"
KEYFACTOR_AUTH_TYPE=client_certificate_pkcs12
KEYFACTOR_AUTH_VALUE="~/imx93_demo/auth_creds.p12,~/imx93_demo/auth_creds.pw"
KEYFACTOR_WORKER="<name_of_the_worker_to_sign_your_binary>"
KEYFACTOR_PREHASH="SHA-256"
KEYFACTOR_SIGNATURE_LENGTH=512

Create & modify a template file for the signing operation

Generate the template for the i.MX93

cd ~/imx93_demo
nxpimage ahab get-template -f mimx9352 -o keyfactor-signer.yaml -s

To see the other possible processor families possible to program with spsdk:

nxpimage ahab get-families -c get-template

Modify the template

Change the following:

1. Change the srk_set to OEM:
   srk_set: oem

2. Change the signature_provider line to point to the Keyfactor plugin and your Worker:
   signature_provider: type=keyfactor[;worker=<name_of_Worker_to_use>]

3. Change the hash_algorithm to sha256:
   hash_algorithm: sha256

4. Change the srk_array to point to the public keys you moved above:

   CODE

   srk_array:
     - <key_name_to_use_0>
     - <key_name_to_use_1>
     - <key_name_to_use_2>
     - <key_name_to_use_3>

6. Signing images and programming fuses

6.1. Recommended Testing Workflow

1. ✅ Generate keys

2. ✅ Sign bootloader binary (signed-imx-boot.bin)

3. ✅ Boot on dev board WITHOUT programming fuses
   - Expected: Boot fails with AHAB event 0x0087FA00 (wrong key)
   - This proves verification is working (NOTE: The board still boots, so you must look for this AHAB event)

4. ✅ Program fuses on dev board

5. ✅ Boot again - should succeed on FIRST AHAB check (may fail on second, since kernel not signed yet).

6. ✅ Only then proceed to production boards

Common Mistakes

6.2. Sign the bootloader containers and get the fuse programming

We can do this by both signing the singleboot image & writing the scripts out:

nxpimage -v ahab sign \
  -c keyfactor-signer.yaml \
  -b imx-boot-imx93frdm-sd.bin-flash_singleboot \
  -o signed-imx-boot.bin \
  -fs script \
  --force

This command outputs a signed binary file named signed-imx-boot.bin.

The output of this command also tells you how to program the fuses on the device (based on the srk_array defined in the yaml file). The output will contain something like this:

In addition, a scripts directory is created containing the actual script to run. The scripts directory will contain a file named ahab_oem0_srk0_hash_nxpele.bcf showing the commands to run to burn the e-fuses:

# nxpele AHAB SRK fuses programming script
# Generated by SPSDK 3.3.0
# Family: mimx9352, Revision: latest

# Value: 0xCEB3AE829F38DF5D3D8A4E7BF03D41F63E5F365D6B18E6B517200AADF9EB1AFF
# Description: SHA256 hash digest of OEM SRK public keys stored in Container
# Grouped register name: SRKH

# OTP ID: OEM_SRKH0, Value: 0x82AEB3CE
write-fuse --index 128 --data 0x82AEB3CE
# OTP ID: OEM_SRKH1, Value: 0x5DDF389F
write-fuse --index 129 --data 0x5DDF389F
# OTP ID: OEM_SRKH2, Value: 0x7B4E8A3D
write-fuse --index 130 --data 0x7B4E8A3D
# OTP ID: OEM_SRKH3, Value: 0xF6413DF0
write-fuse --index 131 --data 0xF6413DF0
# OTP ID: OEM_SRKH4, Value: 0x5D365F3E
write-fuse --index 132 --data 0x5D365F3E
# OTP ID: OEM_SRKH5, Value: 0xB5E6186B
write-fuse --index 133 --data 0xB5E6186B
# OTP ID: OEM_SRKH6, Value: 0xAD0A2017
write-fuse --index 134 --data 0xAD0A2017
# OTP ID: OEM_SRKH7, Value: 0xFF1AEBF9
write-fuse --index 135 --data 0xFF1AEBF9

6.3. Sign the kernel/DTB container

nxpimage -v ahab sign -c keyfactor-signer.yaml -b flash_os.bin -o os_cntr_signed.bin

7. Summary and next steps

You’ve now completed the full secure boot workflow for the NXP i.MX93 AHAB boot.

7.1. What you’ve accomplished

• ✅ Understood AHAB boot architecture and container verification

• ✅ Configured a production-grade PKI for secure boot

• ✅ Set up SignServer with signing workers (HSM-backed if a production instance was purchased)

• ✅ Generated fuse programming scripts for device provisioning

7.2. Your final deliverables

1. ✅ signed-imx-boot.bin - Signed bootloader (ready to flash at 0x8000)

2. ✅ os_cntr_signed.bin - Signed kernel/DTB container

3. ✅ ahab_oem-_srk-_hash_nxpele.bcf - Fuse programming script

4. ✅ Four active SignServer workers [backed by HSM keys if in a production instance]

7.3. Critical production points to consider

• Test fuse programming on development boards first - it’s permanent!

• Create separate production and development workers with their own keys.

  • Separating production keys from development keys allows developers to sign and develop without a complex process.

  • This separation prevents rogue firmware from being executed on production devices & secures against insider attacks

• Backup HSM keys and store the backups in geographically separate secure locations

  • Keyfactor offers cloud HSMs with a BYoK (Bring Your own Key) option

  • This enables companies to create the keys on their own HSM, back them up, and then wrap & import them into cloud HSMs for signing

• Enable comprehensive audit logging for all signing operations

• Turn off production workers when signing is not required

• Separation of duties with RBAC:

  • Managers can turn off and on production workers

  • CI/CD pipeline is initiated by developers/QA

  • Document the process

  • Audit the process

7.4. Next steps

1. Conduct a review of cybersecurity standards to identify cybersecurity requirements.

2. Establish a set of cybersecurity policies for products in your portfolio

3. Integrate signing workflow into your CI/CD pipeline

4. Establish multi-person authorization for production signing

5. Document your certificate policy (CP/CPS) for secure boot keys

6. Consider implementing rootfs verification (dm-verity, IMA/EVM)

Appendix A: Quick Reference

A.1. Common Commands

A.2. Key Files

A.3. Troubleshooting

Appendix B: Glossary

AHAB - Advanced High Assurance Boot (NXP secure boot for i.MX8/9)
ATF - ARM Trusted Firmware (BL31)
Container - Signed structure containing one or more boot images
ELE - EdgeLock Enclave (security co-processor in i.MX93)
FSBL - First Stage Boot Loader (also called SPL)
OCRAM - On-Chip RAM (SRAM for early boot)
SPL - Secondary Program Loader (also called FSBL)
SRKH - Super Root Key Hash (SHA-256 of 4 SRK public keys)
SSBL - Second Stage Boot Loader (full U-Boot)

Appendix C: References

1. NXP - AN12312 - Secure Boot on AHAB Supported Devices
   https://www.nxp.com/docs/en/application-note/AN12312.pdf

2. NXP - i.MX93 Datasheet
   https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/i-mx-applications-processors/i-mx-9-processors/i-mx-93-applications-processor-family

3. NXP - i.MX93 Applications Processor Reference Manual https://www.nxp.com/docs/en/reference-manual/IMX93RM.pdf

4. Keyfactor - SignServer Documentation
   https://www.keyfactor.com/products/signserver-enterprise/

5. NXP SPSDK Documentation
   https://spsdk.readthedocs.io/

6. NXP UUU (Universal Update Utility)
   https://github.com/nxp-imx/mfgtools