L-1004e.A5 i.MX 6 / i.MX 8 Security Manual

Table of Contents

L-1004e.A5 i.MX 6 / i.MX 8 Security Manual
Document TitleL-1004e.A5 i.MX 6 / i.MX 8 Security Manual
Article NumberL-1004e.A5
Release Date09.11.2022
Is Branch ofL-1004e.Ax i.MX 6 / i.MX 8 Security Manual Head


With increasing digitization and networking, the protection of embedded systems against unauthorized access and targeted attacks is more important than ever. Guaranteeing this type of security, along with functional security, is a major challenge in electronics design. PHYTEC supports you in minimizing risks by considering security requirements during the development of our hardware and board support packages. On top of these deployment-ready solutions, we support you with individual project consulting on complex security principles.

Security is a process encompassing all parts of a device and all development phases of its lifetime.

Compatible Controllers and Features

The following table lists the compatible controller as well as any other necessary information to use this manual.


Please make sure your controller can be found on one of these tables before beginning.

NXP i.MX6 and i.MX6UL/ULL

Example Distro

yogurt-secure (warrior)
ampliphy-secure (hardknott+)

(based on Linux Mainline)

yogurt-secure (dunfell)
ampliphy-secure (hardknott+)

(based on Linux Mainline)


Secure Boot

  1. Signed Kernel, DTS with HAB
  2. Signed FIT-Image
  3. Signed Kernel Modules
  4. Signed TEE kernel
  5. Device-Tree Overlay support
  6. Creation of new Device Tree with included Overlays (fdtapply)

from PD20.1.0 (warrior)

  1. -
  2. from PD20.1.0 (warrior)
  3. from PD21.1.0 (hardknott)
  4. -
  5. -
  6. from PD22.1.0 (kirkstone)

from PD21.1.0 (dunfell)

  1. -
  2. from PD21.1.0 (dunfell)
  3. from PD21.2.0 (hardknott)
  4. -
  5. -
  6. from PD23.1.0

Secure Key Storage

  1. NXP CAAM's Secure Key (black blob)
  2. Trusted Key NXP CAAM Support
  3. Trusted Key TPM Support
  4. Trusted Key TEE Support
  5. physecurekeystorage-install tool

from PD20.1.0 (warrior)

  1. -
  2. from PD21.1.0 (hardknott)
  3. on request
  4. on request
  5. from PD22.1.0

from PD21.2.0 (hardknott)

  1. -
  2. from PD21.2.0 (hardknott)
  3. from PD21.2.0 (hardknott)
  4. on request
  5. from PD21.2.0 (hardknott)

Secure Storage

  1. encrypted Filesystem
  2. encrypted Filesystem with integrity support
  3. physecurestorage-install tool

from PD20.1.0 (warrior)

  1. from PD20.1.0 (warrior)
  2. from PD22.1.0 ?!
  3. from PD22.1.0 ?!

from PD21.2.0 (hardknott)

  1. from PD21.2.0 (hardknott)
  2. from PD21.2.0 (hardknott)
  3. from PD21.2.0 (hardknott)

Secure Update

  1. encrypted filesystem remains intact

from PD20.1.0 (warrior)

  1. from PD21.1.0 (hardknott)

from PD21.1.0 (dunfell)

  1. from PD21.2.0 (hardknott)

Access Control: Protection Shield Level

  1. Version 1: root Password
  2. Version 2: different roles with Password

from PD20.1.0 (warrior)

  1. PD20.1.0 (warrior)
  2. from PD21.1.0 (hardknott)

from PD21.1.0 (dunfell)

  1. PD21.1.0 (dunell)
  2. from PD21.2.0 (hardknott)
HardeningExample for selected machine features

from PD21.1.0 (hardknott)

from PD21.2.0 (hardknott)
Provisioning Image

from PD21.1.1 (hardknott)

from PD21.2.1 (hardknott)

HSM PKCS#11 supports image signing

  1. Image PKCS#11 signing
  2. Rauc bundle PKCS#11 signing

  1. on request
  2. from PD22.1.y (kirkstone)

  1. on request
  2. from PD22.1.0 (kirkstone)
NXP i.MX6 and i.MX6UL/ULL Information

NXP i.MX8 Series

NXP i.MX8M Mini / NanoNXP i.MX8M PlusNXP i.MX8M
Example Distro

yogurt-vendor secure (zeus)
ampliphy-vendor-secure (hardknott+)

(based on NXP Vendor BSP)

yogurt-vendor secure (zeus)
ampliphy-vendor-secure (hardknott+)

(based on NXP Vendor BSP)

yogurt-vendor secure (zeus)

(based on NXP Vendor BSP)


Secure Boot

  1. Signed Kernel, DTS with HAB
  2. Signed FIT-Image
  3. Signed Kernel Modules
  4. Signed TEE kernel
  5. Device-Tree Overlay support
  6. Creation of new Device Tree with included Overlays (fdtapply)

from PD21.1.0 (zeus)

  1. PD21.1.0 (zeus)
  2. from PD22.1.0 (hardknott)
  3. from PD21.1.0 (zeus)
  4. from PD22.1.0 (hardknott)
  5. from PD22.1.0 (hardknott)
  6. from PD22.1.1 (hardknott)

from PD21.1.0 (zeus)

  1. PD21.1.0 (zeus)
  2. from PD22.1.0 (hardknott)
  3. from PD21.1.0 (zeus)
  4. from PD22.1.0 (hardknott)
  5. from PD22.1.0 (hardknott)
  6. from PD22.2.0 (kirkstone)

from PD21.1.0 (zeus)

  1. PD21.1.0 (zeus)
  2. from hardknott
  3. from PD21.1.0 (zeus)
  4. from hardknott
  5. ?!
  6. ?!

Secure Key Storage

  1. NXP CAAM's Secure Key (black blob)
  2. Trusted Key NXP CAAM Support
  3. Trusted Key TPM Support
  4. Trusted Key TEE Support
  5. physecurekeystorage-install tool

from PD22.1.0 (hardknott)

  1. from PD22.1.0 (hardknott)
  2. -
  3. from PD22.1.0 (hardknott)
  4. from PD22.1.0 (hardknott)
  5. from PD22.1.0 (hardknott)

from PD22.1.0 (hardknott)

  1. from PD22.1.0 (hardknott)
  2. -
  3. from PD22.1.0 (hardknott)
  4. from PD22.1.0 (hardknott)
  5. from PD22.1.0 (hardknott)

from hardknott

Secure Storage

  1. encrypted Filesystem
  2. encrypted Filesystem with integrity support
  3. physecurestorage-install tool

from PD22.1.0 (hardknott)

  1. from PD22.1.0 (hardknott)
  2. from PD22.1.0 (hardknott)
  3. from PD22.1.0 (hardknott)

from PD22.1.0 (hardknott)

  1. from PD22.1.0 (hardknott)
  2. from PD22.1.0 (hardknott)
  3. from PD22.1.0 (hardknott)

from hardknott

Secure Update

  1. encrypted filesystem remains intact

from PD21.1.0 (zeus)

  1. from PD21.2.0 (hardknott)

from PD21.1.0 (zeus)

  1. from PD22.1.0 (hardknott)
from PD21.1.0 (zeus)

Access Control: Protection Shield Level

  1. Version 1: root Password
  2. Version 2: different roles with Password

from PD21.1.0 (zeus)

  1.  PD21.1.0 (zeus)
  2. from PD22.1.0 (hardknott)

from PD21.1.0 (zeus)

  1.  PD21.1.0 (zeus)
  2. from PD21.1.0 (zeus)

from PD21.1.0 (zeus)

  1. -
  2. from PD21.1.0 (zeus)
Hardening Example for selected machine features

in progress

in progress
Provisioning Image

from PD22.1.0 (hardknott)

from PD22.1.0 (hardknott)

HSM PKCS#11 supports image signing

  1. Image PKCS#11 signing
  2. Rauc bundle PKCS#11 signing

  1. from PD22.1.1 (hardknott)
  2. from PD22.1.1 (hardknott)

  1. from PD22.1.0 (hardknott)
  2. from PD22.1.0 (hardknott)
on request
NXP i.MX8 Series Information

Short Crypto Refresher

Symmetric cryptographyThe same key for encryption or decryption
Public key cryptographyTwo mathematically dependent keys for encryption or decryption. The public key is used for encryption while the private key is used for decryption.
HashOne-way function, fixed output size (SHA*)
HMACData authentication using hash and shared secret
SignatureData authentication using public-key cryptography (keys & certificates, RSA & ECDSA)
Unauthenticated encryptionAttackers can‘t read private data but could modify it (AES-CBC, AES-XTS, ...)
Authenticated encryptionAttacker can‘t read private data and modification is detected (AEAD: AES GCM, AEGIS)
Trusted KeysSymmetric key with variable length is a key type of the existing kernel keyring service.
Require the availability of a Trust Source for greater security like a TPM or TEE (from Kernel 5.13 and backported in Mainline Kernel 5.10)
Encrypted KeysSymmetric key with variable length is a key type of the existing kernel keyring service.
Crypto Functions and Descriptions

Recommended Security Requirements

As of the writing of this manual, recommendations apply to key lengths, certificates, and hash values. These recommendations come from BSI (Bundesamt für Sicherheit in der Informationstechnik) and NIST (National Institute of Standards and Technology).

Security Features in PHYTEC Standard BSP

In the technical and connected world, it is important to build a "security by design” approach that thwarts intrusion into your product, data, and intellectual property at multiple levels.
Here are the Security features from the Standard BSP.

Basic Security

Basic Security is the fundament of the security measures implementations and includes support for basic modules such as:

  • True Number Generator and Cryptographic support
  • Secure Boot
  • Secure Key Storage and Usage
  • Secure Storage
  • Secure Updates

Parts from Access Control as an Example

Access Control regulates the access of users and services to the device and components in the device according to the least privilege access principle.

  • Secure Console
  • Secure Shell
  • User and Role Management

More Additional Security Features (not part of this BSP)

Network Security

Network Security enables secure connections to connected devices or servers via Ethernet, WLAN, and LTE, but also secures access to the device from outside.

  • Remote Access
  • Server, Cloud Integration Tools
  • Intrusion Protection
  • Firewall
  • Container

Interface Security

Interface Security secures the interfaces

  • USB
  • Field Bus

against third-party access and enables the secure connection of intended devices.


Hardening refers to the reduction of software components and kernel configuration to a necessary minimum.

Physical Security

Physical Security secures the device from direct physical access to protect the corresponding application and data from external access.

  • Secure Debug
  • Tamper Protection
  • Housing
  • Encapsulation of the circuit board


Provisioning includes the activation of hardware security features like Secure Boot and the generation of specific keys and X509 certificates on the device in secure manufacturing like the PHYTEC secure production area.

Introduction to Yocto and Board Support Packages

This document assumes that you are familiar with our Yocto BSPs. The basics of our BSPs are explained in our documents Yocto Reference Manual.

PHYTEC Documentation

PHYTEC will provide a variety of hardware and software documentation for all of our products. This includes any or all of the following:

  • QS Guide: A short guide on how to set up and boot a phyCORE board along with brief information on building a BSP, the device tree, and accessing peripherals.
  • Hardware Manual:  A detailed description of the System on Module and accompanying carrier board. 
  • Yocto Guide:  A comprehensive guide for the Yocto version the phyCORE uses. This guide contains an overview of Yocto; introducing, installing, and customizing the PHYTEC BSP; how to work with programs like Poky and Bitbake; and much more.
  • BSP Manual:  A manual specific to the BSP version of the phyCORE. Information such as how to build the BSP, booting, updating software, device tree, and accessing peripherals can be found here.
  • Development Environment Guide:  This guide shows how to work with the Virtual Machine (VM) Host PHYTEC has developed and prepared to run various Development Environments. There are detailed step-by-step instructions for Eclipse and Qt Creator, which are included in the VM. There are instructions for running demo projects for these programs on a phyCORE product as well. Information on how to build a Linux host PC yourself is also a part of this guide.
  • Pin Muxing Table:  phyCORE SOMs have an accompanying pin table (in Excel format). This table will show the complete default signal path, from the processor to the carrier board. The default device tree muxing option will also be included. This gives a developer all the information needed in one location to make muxing changes and design options when developing a specialized carrier board or adapting a PHYTEC phyCORE SOM to an application. 

On top of these standard manuals and guides, PHYTEC will also provide Product Change Notifications, Application Notes, and Technical Notes. These will be done on a case-by-case basis. Most of the documentation can be found on the applicable download page of our products.

These manuals and more can be found in the download section of

Controller with Link to the Download folder 
NXP i.MX8M Plus
NXP i.MX8M Mini
PHYTEC Product Pages

Distro ampliphy-(vendor)-secure and ampliphy-(vendor)-provisioning


Distro ampliphy-(vendor)-secure and ampliphy-(vendor)-provisioning are sampleYocto distros like ampliphy with additional security pre-configurations. Additional security measurements for production usage are necessary and depend on your threat model.

PHYTEC services can support your implementation.

  • The distro ampliphy-(vendor)-provisioning with the phytec-provisioning-image is for the production or the first initialization of your device in a secure area.
    The phytec-provisioning-image.rootfs.sdcard can boot directly from an SD card to a Kernel with a minimal ramdisk to
    • copy the phytec-security-image.rootfs.sdcard to the eMMC
    • initialize the secure key storage on the device
    • initialize the secure storage on the device
  • The distro ampliphy-(vendor)-secure with the phytec-security-image is an example of a production image with secure-update support.
    The phytec-security-image.rootfs.sdcard can boot only from an eMMC and not from an SD card!

 The following DISTRO_FEATURES are activated in the distro ampliphy-(vendor)-secure and ampliphy-(vendor)-provisioning:

  • for building a signed bootloader and FIT-Image or kernel
  • All necessary tools and configurations for file encryption and integrity initialization on the board


  • Three levels low, medium, and high
  • Four examples:  users root, phyadmin, phyuser, phyread
  • Password protection for bootloader and kernel serial and ssh
  • Example kernel reduction for machine features
  • Enabled Linux kernel module signing, so only modules signed with a specific key can be loaded.

Image phytec-security-image is configured for filesystem encryption with FIT-Image, which includes a ramdisk and a boot initialization script.


This example for filesystem encryption only works with eMMC, but not with NAND or NOR Flash.

Provisioning your Device with Security in 5 steps

In only 5 steps, you can have a device with a secure boot, secure key storage, and secure storage.
You can download the phytec-provisioning-image and phytec-security-image for your board from our server https://download.phytec.de/Software/Linux/
or check out the code with a script from our git server:

host$ mkdir ~/yocto
host$ cd ~/yocto
host$ wget https://download.phytec.de/Software/Linux/Yocto/Tools/phyLinux
host$ chmod +x phyLinux
host$ ./phyLinux init

Initialize your Provisioning SD-Card

  1. Copy the phytec-provisioning-image.rootfs.sdcard to an SD card
  2. Resize the second partition "root" with GParted to a minimum of 3 Gbyte
  3. Copy the necessary images to the partition "root"
    1. a device with eMMC: copy the phytec-security-image.rootfs.sdcard and phytec-security-image.tar.gz to the SD card partition "root"
    2. a device with NAND: copy the phytec-simple-fitimage, device tree, and phytec-security-image.ubifs the SD card partition "root"

Activate Secure Boot on your Device

Please follow the instructions in the chapter Activate Secure Boot

Flash the eMMC with the phytec-security-image 

  1. Set Bootjumper for booting from SD Card
  2. Plug-in power
  3. Boot to the Linux prompt and log in with the default password "root"
  4. Mount the root partition from the SD card to the folder/media:

    i.MX6 / i.MX6UL Mainline Kerneli.MX8M with NXP Kernel

    SD card Device: /dev/mmcblk0p2

    SD card Device: /dev/mmcblk1p2

    i.MX 6/i.MX 6UL/i.MX 8M SD Card Folders
    kernel$ mount <sd-card device> /media/ 
  5. Use the phyprovisioning-install-emmc tool to flash the security image on the eMMC of your device:

    kernel$ phyprovisioning-install-emmc -s /media/phytec-security-image.rootfs.sdcard -n

    Everything is ready for the next step.

Init the Secure Key Storage

Please follow the instructions in the chapter Secure Key Storage "Secure Key Storage initialization with phySecureKeyStorage Tool"

Init the Secure Storage

By default, integrity and encryption are set in the distro ampliphy-(vendor)-secure. Therefore, the option intenc must be selected.

Please follow the instructions in the chapter Secure Storage "Secure Storage initialization with phySecureStorage Tool"

Secure Boot 

Why Secure Boot?

Chain of Trust

Secure boot is used to ensure that only trustworthy, signed software can be executed on the controller. This is the first stage of the Chain-of-Trust. With the Chain-of-Trust, signed programs are always started by other previously verified programs. This ensures that even the end application is at the highest layer of trustworthiness.

Secure Boot Process Flow

Process flow i.MX6*:

  • A trusted ROM-bootloader verifies software images before they are executed
  • bootloader verifies Linux-kernel image and device tree (fit-image)
  • Linux-kernel verifies file system and customer application data

Process flow i.MX8*:

  • A Trusted ROM-bootloader verifies firmware blobs (DDR and HDMI on some variants) and uses HABv4 to verify u-boot SPL.
  • u-boot SPL loads u-boot proper from the FIT image and ATF (ARM Trusted Firmware) and optionally OP-TEE. It verifies those images using HABv4.
  • Then, u-boot loads and verifies the FIT-image containing a Linux kernel, DTB, and ramdisk. This FIT image is signed using HABv4 keys.
  • If built with signed kernel modules (standard), Linux will only load kernel modules signed with a proper private key.

i.MX6 / i.MX6UL / i.MX6ULLi.MX8MM / i.MX8MP
  • Super Root Keys for HABv4
  • FIT-Image Key
  • Super Root Keys for HABv4

Bootloader verified by HABv4

FIT-Image verified by Bootload with FIT-Image Public Key

Linux kernel modules verified by Linux

DDR/HDMI images (signed by NXP)

U-Boot SPL, U-Boot, ATF, TEE, and FIT-Image verified by HABv4

Linux kernel modules verified by Linux

Bootloader/Keys/Verification Information

Getting Started

NXP Controller 

Information about Secure Boot on NXP Controller: https://www.nxp.com/search?keyword=AN4581
HABv4 RVT guidelines and recommendations: https://www.nxp.com/search?keyword=AN12263

  • Code Signing Tools (CST) in version 3.3.1 or newer (install recipes are available in the BSP)
    • Download the cst-3.3.1.tar.gz file
    • Unpack the cst-3.3.1.tar.gz file to cst-3.3.1.tar file.
    • Place the cst-3.3.1.tar file in the Yocto download folder


On 12.3.2021 NXP changed the CST tool version 3.3.1 (published on 14.08.2020) without updating the version.
If you get a checksum/hash error for nxp-cst, then please update the recipe meta-phytec/recipes-devtools/nxp-cst/nxp-cst_3.3.1.bb or update your CST version 3.3.1.

Additionally, NXP removed older versions of the CST tool.

Enable Secure Boot Support in Yocto

Enable Secure Boot in your own distro

To enable secure boot, add the DISTRO_FEATURE "secureboot" to your distro configuration file conf/distro/xyz.conf:

DISTRO_FEATURES += "secureboot"                                                  
DISTRO_FEATURES_NATIVE += "secureboot"                                           

Active image signing during the build process. The class "secureboot" needs to be inherited in your distro configuration:

INHERIT += "secureboot"

Configuration Class-Path to the Certificates

The path to the keys and certificates used for code-signing during the build process can be changed in the secureboot.bbclass file:

CERT_PATH ??= "${OEROOT}/../../phytec-dev-ca"

For more information about keys and certificates, refer to Change PKI-Tree from phytec-dev-ca to the own PKI


i.MX6 and i.MX6UL/ULL with Barebox

Standard BootSecure Boot
  • barebox.bin for flash and serial download
  • Signed Barebox for flash: barebox-s.bin
  • USB signed Barebox for serial download: barebox-us.bin
Bootloader Environment
  • loads Environment from flash
  • uses only a built-in environment
    • Some variables required for RAUC are allowed to be read and written
Bootloader Image Boot
  • loads zImage
  • loads only signed fitImage
  • go command deactivated
eMMC image bootloader
  • barebox.bin
  • barebox-s.bin
i.MX6 and i.MX6UL/ULL with Barebox Information

i.MX8M Series with u-boot

Standard BootSecure Boot
  • u-boot.bin inside imx-boot container
  • u-boot.bin inside signed imx-boot container
Bootloader Environment
  • load Environment from Flash
  • uses only a built-in environment
    • Some variables required for RAUC are allowed to be read and written
Bootloader Image Boot
  • loads Image
  • loads signed FIT image.
eMMC image bootloader
  • u-boot.bin
  • u-boot.bin
i.MX8M Series with u-boot Information

Configuration Class - Signing Bootloader

All variables to adjust the bootloader signing process can be found in secureboot.bbclass:

BOOTLOADER_SIGN ??= "true"                                                       
BOOTLOADER_SIGN[type] = "boolean"

BOOTLOADER_SIGN_IMG_PATH ??= "${CERT_PATH}/nxp_habv4_pki/crts/IMG1_1_sha256_4096_65537_v3_usr_crt.pem"
BOOTLOADER_SIGN_CSF_PATH ??= "${CERT_PATH}/nxp_habv4_pki/crts/CSF1_1_sha256_4096_65537_v3_usr_crt.pem"
BOOTLOADER_SIGN_SRKFUSE_PATH ??= "${CERT_PATH}/nxp_habv4_pki/crts/SRK_1_2_3_4_table.bin"

BOOTLOADER_SIGN:  enable the bootloader signing
BOOTLOADER_SIGN_IMG_PATH, BOOTLOADER_SIGN_CSF_PATH, BOOTLOADER_SIGN_SRKFUSE_PATH:  paths to the certificates and SRKFUSE-table required to sign the bootloader

Linux Kernel in the FIT-Image 

FIT-Image Generation 

First, add a FIT-Image recipe to your BSP layer. A possible location for this recipe could be recipes-images/fitimage/

You can find three example recipes for Fit-Image generation in the meta-ampliphy layer at sources/meta-ampliphy/recipes-images/fitimage/.

  • phytec-simple-fitimage.bb:  Example for a FIT-image with kernel and device tree of a selected machine
  • phytec-secureboot-ramdisk-fitimage.bb:  example for a FIT-image with the kernel, device tree (fdt, fdto, fdtapply) of a selected machine, and a ramdisk with file encryption support enabled
  • phytec-provisioning-initramfs-fitimage.bb: example for a FIT-image with the kernel, device tree  (fdt, fdto, fdtapply) of a selected machine, and a ramdisk for device initialization

The FIT-Image recipes are based on the fitimage.bbclass, which creates the platform-specific image source file (.its). The mkimage tool creates and signs with its File the final FIT-Image.

To create a own FIT-Image, you need to specify some variables in the receipe:

  • FITIMAGE_SLOTS: Use this to list all slot classes for which the FIT-Image should contain images. A value of "kernel fdt fdtapply", for example, will create a manifest with images for two slot classes - kernel and devicetree.
  • FITIMAGE_SLOT_<slotclass>: For each slot class, set this to the image (recipe) name which builds the artifact you intend to place in the slot class.
  • FITIMAGE_SLOT_<slotclass>[type]: For each slot class, set this to the type of image you intend to place in this slot. Possible types are the kernel, fdt, fdto, fdtapply, or ramdisk.
  • FITIMAGE_SLOT_<slotclass>[file]: For slot type kernel, fdt, fdt0 and fdtapply set this to the file of the image you intend to place in this slot.
  • FITIMAGE_SLOT_<slotclass>[fstype]: For slot type ramdisk, set this to the filesystem type of image you intend to place in this slot.
  • FITIMAGE_SLOT_<slotclass>[name]: For slot type fdtapply, set this to the final device tree and configuration name.

The following table contains more information about the different FIT-Image slot types

slot type

  • default is the kernel from ${PREFERRED_PROVIDER_virtual/kernel}
  • only one Linux kernel per slot class

device tree
  • at least one type of fdt or fdtapply is necessary as it is used for the configuration name

  • default the first device tree from the variable KERNEL_DEVICETREE is used, which is defined in the machine configuration
  • several device trees at one slot name are possible
  • for every device tree in the slot is created one configuration with the existing kernel and ramdisk type

  • all device tree overlays (extension *.dtbo) from the variable KERNEL_DEVICETREE, which is defined in the machine configuration
  • one configuration is created for every device tree overlay in a slot 
  • this type is necessary for device tree overlay support with secure boot and the bootloader u-boot (i.MX8M series)

  • a final device tree is created with the first device tree from the variable KERNEL_DEVICETREE and the list of several devicetree overlays in the
  • The used device tree overlays must be set in the variable  KERNEL_DEVICETREE, too.
  • FITIMAGE_SLOT_<slotclass>[name] is the name of the created final device tree, which is used as a name for the configuration with the existing kernel and ramdisk type
  • This type is used for device tree overlay support with secure boot and the bootloader barebox (i.MX6, i.MX6UL)
    An example is in Yocto kirkstone with the ADIN1300 Ethernet PHY.

  • only one ramdisk per slot class

With different slot classes for the kernel, devicetree, and ramdisk you can build very complex FIT-Images, which have support for different hardware boards or configurations.

Configuration Class - Signing FIT-Image

In the configuration class, secureboot.bbclass, you can set all relevant variables for signing the FIT-Image.

FITIMAGE_SIGN ??= "true"                                                         
FITIMAGE_SIGN[type] = "boolean"

FITIMAGE_SIGNER ??= "customer"                                                   

FITIMAGE_SIGN_KEY_PATH ??= "${CERT_PATH}/fit/FIT-4096.key"                   
FITIMAGE_HASH ??= "sha256"                                                   
FITIMAGE_SIGNATURE_ENCRYPTION ??= "rsa4096"                                  
  • FITIMAGE_SIGN: Activation of the FIT-Image signing
  • FITIMAGE_SIGNER: Name of the FIT-Image signer, which is part of the FIT-Image certificate
  • FITIMAGE_PUBKEY_SIGNATURE_PATH: Automatically created manifest with a public key of the FITIMAGE_SIGN_KEY_PATH for storing in the bootloader device tree
  • FITIMAGE_SIGN_KEY_PATH: Path to the signing key
  • FITIMAGE_HASH: Hash function for the FIT-Image artifacts. SHA1 and SHA256 are supported
  • FITIMAGE_SIGNATURE_ENCRYPTION: Key type for FIT-Image certificate signing. RSA2048 and RSA4096 are supported
  • FITIMAGE_SIGNER_VERSION: Version of the signer, which is part of the FIT-Image certificate

Start the Build Process

Refer to Start the Build.

The phytec-security-image has support for FIT-Image creation with an example for file encryption eMMC only, not for NAND/NOR Flash. The phytec-security-image includes a FIT-Image with Kernel, devicetree, and ramdisk.

BSP Images

All images generated by Bitbake are deployed to yocto/build/deploy/images/<MACHINE>. The following list shows all additionally generated files for the i.MX 6 SoC, phyboard-mira-imx6-5 machine with activated Secure Boot:

  • Barebox:barebox-s.bin, barebox-us.bin
  • FIT-Image:fitImage.fitimg with the kernel, device tree, and ramdisk
  • FIT-Image manifest: phytec-secureboot-ramdisk-fitimage-phyboard-mira-imx6-5.its
  • RAM-disk: phytec-secureboot-ramdisk-image-phyboard-mira-imx6-5.cpio.gz
  • Root filesystem: phytec-security-image-phyboard-mira-imx6-5.tar.gz
  • eMMC image: phytec-security-image-phyboard-mira-imx6-5.sdcard with barebox-s.bin

Booting and Updating the System

Refer to BSP Reference Manual for booting from different flashes and updating the software. Please use the signed bootloader images and Kernel or FIT-Images to program to the flash. The eMMC image is ready to use with a signed bootloader.

Activate Secure Boot on the Device 

The final step to activate secure boot on your device is to burn the secure eFuse configuration.


The secure eFuse configuration can only be written once and is irreversible!

The SRK fuses contain the hash value of the SRK public keys. They are never used on open devices! In closed devices, they are used to validate the public key contained in signed firmware images. Before closing the device, you must store the hash of the public keys in the SRK OTP bits on the device. This will allow the ROM loader to validate the public key included in signed firmware images.

When building the yocto-secure distro for the first time, the bootloader image is signed with PHYTEC's development keys. Yocto stores these development keys to yocto/phytec-dev-ca. Please refer to Change PKI-Tree from phytec-dev-ca to the own PKI.

For NXP i.MX Controllers with HABv4 (i.MX6, i.MX7, i.MX8M, i.MX8M mini, i.MX8M Plus), you will need the SRK_1_2_3_4_fuse.bin file. An example file is located in yocto/phytec-dev-ca/nxp_habv4_pki/crts/SRK_1_2_3_4_fuse.bin.


Create and use your own keys and certificates for signing your images. Burn the right key into the Controller eFuse. Please refer to Create Your Own PKI Tree.

eMMC Boot Partition to Enable Boot

i.MX6* with Bareboxi.MX8M* with u-boot
Set eMMC as an active device
barebox$ detect mmc3
uboot$ mmc dev 2
Show active boot partition
barebox$ devinfo mmc3

You will receive:

  boot: boot0 (type: enum) (values: "disabled", "boot0", "boot1", "user")
  nt_signature: 9a54880c (type: uint32)
  probe: 0 (type: bool)

disabled is the default for user partition

uboot$ mmc partconf 2

You will receive:


0x0 Device not boot enabled(default)

0x1Boot partition1 enabled for boot

0x2Boot partition2 enabled for boot

0x7User area enabled for boot

Set user area for boot
barebox$  mmc3.boot=disabled
uboot$  mmc partconf 2 0 7 0  
eMMC Boot Partition to Enable Boot Information

Program the SRK eFuse

Taski.MX6* with Bareboxi.MX8M* with u-boot

Check the Current State of Your Device
barebox$ hab -i

You will receive:

Current SRK hash: 
devel mode
u-boot$ hab_status

You will receive:

Secure boot disabled

HAB Configuration: 0xf0, HAB State: 0x66
No HAB Events Found!

Get the eFuse from the right SRK_1_2_3_4_fuse.bin!
barebox$ cp /mnt/tftp/SRK_1_2_3_4_fuse.bin .
host$ hexdump -e '/4 "0x"' -e '/4 "%X""\n"' SRK_1_2_3_4_fuse.bin

You will receive:


Burn the eFuse with the right SRK_1_2_3_4_fuse.bin!
barebox$ hab -p -s SRK_1_2_3_4_fuse.bin

You will receive:

ocotp0: reloading shadow registers...
ocotp0: reloading shadow registers...
ocotp0: reloading shadow registers...
ocotp0: reloading shadow registers...
ocotp0: reloading shadow registers...
ocotp0: reloading shadow registers...
ocotp0: reloading shadow registers...
ocotp0: reloading shadow registers...
barebox@PHYTEC phyCORE-i.MX6 Quad with eMMC:/
uboot$ fuse prog 6 0 0x9A842534 
uboot$ fuse prog 6 1 0xB0491AB4 
uboot$ fuse prog 6 2 0xD5B6A07B 
uboot$ fuse prog 6 3 0xFD92DCE7    

uboot$ fuse prog 7 0 0xC10DC87C 
uboot$ fuse prog 7 1 0xD8BD04A9 
uboot$ fuse prog 7 2 0x704E9FE4 
uboot$ fuse prog 7 3 0x9B025359

Verify new SRK eFuse
barebox$ hab -i

You will receive:

Current SRK hash: 
devel mode
uboot$ fuse read 6 0 4

You will receive:

Reading bank 6:

Word 0x00000000: 9a842534 b0491ab4 d5b6a07b fd92dce7
uboot$ fuse read 7 0 4

You will receive:

Reading bank 7:

Word 0x00000000: c10dc87c d8bd04a9 704e9fe4 9b025359
Program the SRK eFuse Information

Lock the Device


This step is irreversible and could brick your device.

Before closing the device:

  • Verify you have built a signed bootloader image.
  • Reset your board and verify there are no HAB events.
  • Verify the SRK eFuses have been burned. The SRK OTP bits are not verified on open devices. For a closed device to boot, all the SRK OTP bits must be burned. An open device booting with no HAB events will stop booting after being closed if the SRK OTP bits are invalid, not burned, or only partially burned.
Taski.MX6* with Bareboxi.MX8M* with u-boot

Lockdown your device
barebox$ hab -p -l

You will receive:

ocotp0: reloading shadow registers...
ocotp0: reloading shadow registers...
Device successfully locked down
uboot$ fuse prog 1 3 0x2000000

You will receive:

Warning: Programming fuses is an irreversible operation!
         This may brick your system.
         Use this command only if you are sure of what you are doing!

Really perform this fuse programming? <y/N>
Device Locking Information


If you can successfully reboot after locking the device in the previous step, you should also burn the SRK_LOCK FUSE.


On i.MX6, this step was already performed by the "hab" command of the previous step.

Taski.MX8M* with u-boot

fuse prog 0 0 0x200

You will receive:

Warning: Programming fuses is an irreversible operation!
         This may brick your system.
         Use this command only if you are sure of what you are doing!

Really perform this fuse programming? <y/N>
Burn SRK_LOCK Information

Next Steps after Lockdown


After you have closed the device, consider the following points with regard to how firmware authentication can potentially be skipped:

Revoke NXP SRK Key

Although securing the device involves programming the hash of four public keys into the eFuses, only one key (number 1 by default) is used in the secure boot process. If the key gets compromised, it can be revoked and a different key used.

To use a different key for the signature of bootloader images, change the following variables in sources/meta-ampliphy/classes/secureboot.bbclass:

BOOTLOADER_SIGN_IMG_PATH ??= "${CERT_PATH}/nxp_habv4_pki/crts/IMG1_1_sha256_4096_65537_v3_usr_crt.pem"
BOOTLOADER_SIGN_CSF_PATH ??= "${CERT_PATH}/nxp_habv4_pki/crts/CSF1_1_sha256_4096_65537_v3_usr_crt.pem"

The following keys are available:

Key SlotIMG CertificateCSF CertificateSRK_REVOKE[2:0]
3IMG4_1_sha256_4096_65537_v3_usr_crt.pemCSF4_1_sha256_4096_65537_v3_usr_crt.pemnot revocable
Available NXP SRK Keys

Example: Revoke Key Slot 0 on i.MX6

i.MX6 and i.MX6ULi.MX8M series
barebox$ mw -l -d /dev/imx-ocotp 0xBC 0x0001
uboot$ fuse prog 9 3 0x1
i.MX 6 Revoke Key 0 Example


  • The SRK Revocation does not modify the SRK hash values, only the SRK_REVOKE fuse has to be programmed.
  • In a closed configuration, HAB, by default, sets the SRK_REVOKE_LOCK sticky bit in the OCOTP controller to write protect this eFuse field.
  • To instruct HAB not to lock the SRK_REVOKE field, the CSF commands in the bootloader need to be reconfigured.

For more information, refer to https://www.nxp.com/docs/en/application-note/AN4581.pdf or NXP CST User's Guide.

Secureboot on i.MX8M Series without FIT Images

In earlier releases, secureboot on the i.MX8M controller series signed the kernel and DTB. Support for authenticated ramdisks did not exist. We recommend using signed FIT images. Users who still wish to use that old mechanism should perform the following changes in their build configuration:

Disable FITIMAGE signing:


Set IMX_BOOT_FILES variable:

IMAGE_BOOT_FILES_secureboot = "Image-signed oftree"

Rebuild u-boot-imx, imx-boot-phytec and linux-imx.

Kernel Module Signing

When the kernel module signing facility is enabled, Linux can enforce that only modules that have been signed with a specific key can be loaded. Keys with invalid signatures won't be allowed to load. This makes it harder for attackers to load malicious or manipulated modules.

This is enforced by the kernel and does not require userland support.

Enable kernel module signing facility

To enable the kernel module signing facility, add the following DISTRO_FEATURE to your configuration file in conf/distro/xyz.conf

 DISTRO_FEATURES += "kernelmodsign"                                            


By default, the kernel modules will be signed with PHYTEC's public, for example, the development key. Unless you create your own key, this feature does not offer any protection.

Device Tree Overlay and Secure Boot

Device Tree overlays are device tree fragments that can be merged into a device tree during boot time. These are for example hardware descriptions of an expansion board. They are instead of being added to the device tree as an extra include, now applied as an overlay. They also may only contain setting a node's status depending on whether it is mounted or not. 

Device Tree Overlay for i.MX6UL and i.MX6

The Device Tree Overlay support is generally deactivated and not supported for i.MX6UL and i.MX6 with Secure Boot in the security distro and image

The new ADIN1300 Ethernet PHY is supported in the standard BSP as devicetree overlay for the phyBOARD-Mira and phyBOARD-Nunki.
In the security distro and image, a new device tree is created with the FIT-image recipes in the sources/meta-ampliphy/recipes-images/fitimages/ and the fdtapply mechanism from the source/meta-phytec/classes/fitimage.bbclass.
More information in the chapter Linux Kernel in the FIT-Image
In the barebox is an Ethernet PHY detection, which boots the correct configuration from the FIT-image.

Device Tree Overlay for i.MX8M Series

Standard BootSecure Boot
Build Time:
Overlays set in the $KERNEL_DEVICETREE Yocto machine variable will be
Automatically added to the boot partition of the final SD card image

Automatically added as a node to the signed FIT-Image.


Only Device Tree Overlays in the FIT-Image can be used on the device.

Run Time on the board:

The ${overlays} variable can be either set directly in the U-Boot environment. Or be a part of the external bootenv.txt  environment.




Manipulation Risk! The external bootenv.txt is not signed and protected against manipulation, so overlays can be changed and deleted in the bootenv.txt.

i.MX8M Series Device Tree Overlay

The ${overlays} variable loaded from the external environment will always overwrite the value from the environment saved directly in the flash. By default, the ${overlays} variable is not set directly in the U-Boot environment but comes from the external bootenv.txt environment file. It is also located in the boot partition of the SD card image.


Please use Device Tree Overlay only in the development stage of your product. Create a final Device Tree for your device for the production phase.

Deactivate Device Tree Overlay Support for i.MX8M Series

To disable the Device Tree Overlay support set the following variable in sources/meta-ampliphy/classes/secureboot.bbclass to true


All the machine-defined Device Tree Overlays will be added to the FIT-Image. If you do not want Device Tree Overlays in the FIT-Image, please remove fdto in the sources/meta-ampliphy/recipes-image /fitimage/phytec-secureboot-ramdisk-fitimage.bb or in your own FIT-Image recipe.

FITIMAGE_SLOTS ?= "kernel fdt fdto ramdisk"

Secure Key Storage 

A fundamental aspect of security is integrity and confidentiality. Many applications require an embedded device to keep sensitive data. The standard solution to this problem is to use encryption to protect the data and ensure that only authorized users have access to the encryption key. When a user interacts directly with a system, the encryption key can be protected with a password, pin code, or fingerprint that is provided by the user. However, many embedded devices work without user interaction, so this is not an option in those cases.

In the BSP, three different variants of Secure Key Storage can be implemented, depending on hardware support. The available hardware support is activated with MACHINE_FEATURE.

Type of Secure Key StorageHardware supportMACHINE_FEATURE
  • available on all NXP i.MX6, i.MX6UL and i.MX8 controllers
  • i.MX6ULL has no CAAM unit
Trusted Execution Environment TEE
  • available in all ARM Cortex-A controllers
  • When built with OP-TEE support, a trusted-key TA application is included.
    It will be called by the kernel module and OP-TEE will seal the trusted key.
Trusted Platform Module TPM
  • available on i.MX8M series phyBOARDs and phyGATE-Tauri-S/phyGATE-Tauri-L
Secure Key Storage Types

Machines built with the MACHINE_FEATURE have all necessary prerequisites enabled.

Supported Types of Secure Key Storage


The NXP i.MX6, i.MX6UL and i.MX8M series processors include hardware encryption through NXP's Cryptographic Accelerator and Assurance Module (CAAM, also known as SEC4). The CAAM combines functions to create a modular and scalable acceleration and assurance engine.

More information about the CAAM module can be found in the corresponding NXP reference Manual: https://www.nxp.com/docs/en/reference-manual/i.MX_Reference_Manual_Linux.pdf

CAAM Blob ImplementationNXP i.MX6NXP i.MX6 UL NXP i.MX8M Series
Mailinglist: Pengutronix trusted CAAM (red blob)

backported Patches trusted key framework and patches from a list of trusted CAAM 

from kernel 5.19 applied in the mainline kernel

from PD21.1.0 (hardknott)from PD21.2.0 (hardknott)

NXP CAAM's Secure Key based on CAAM's black key mechanism

More information about the mechanism can be found here: https://www.nxp.com/webapp/Download?colCode=AN12714

The implementation is part of the NXP Vendor BSP.

  • from PD21.2.0 (hardknott) for i.MX8MM/MN
  • from PD22.1.0 (hardknott) for i.MX8MP
CAAM Blob Information

Prerequisites and Caveats

Secureboot is required for trusted CAAM Key blob functionality. If Secure Boot Keys are burned, the keys are locked. After a reset, the CAAM unit creates internal keys for the signing and encryption CAAM blobs. These keys are internal in the CAAM and can not be read out and overwritten.

Trusted Execution Environment: OP-TEE

OP-TEE is a Trusted Execution Environment (TEE) designed as a companion to a non-secure Linux kernel running on Arm; Cortex-A cores using the TrustZone technology.

Since the Yocto hardknott release, ampliphy-secure includes experimental OP-TEE support for the i.MX8MM and i.MX8MN. This allows users who are interested in utilizing OP-TEE to test it on their devices. However, OP-TEE is not yet suitable for production use.


Currently, OP-TEE cannot be used to properly protect secrets due to incomplete isolation between the normal and secure TrustZone world. For more information https://optee.readthedocs.io/en/latest/architecture/platforms/nxp.html

PHYTEC includes OP-TEE only as a preview in ampliphy-secure. As an example application, once ready OP-TEE can then be used to protect the trusted key, as described in Testing OP-TEE.

OP-TEE is divided into the following components:

  • OP-TEE kernel: The kernel acts as a secure world OS. This kernel is signed by HABv4.
  • tee-supplicant: Helper daemon allowing OP-TEE to read/write from/to secure storage. In practice, this means OP-TEE will save encrypted and authenticated data in the filesystem.
  • xtest: Utilities to test OP-TEE.

Prerequisites and Caveats

Secureboot and Hardware Unique Key

Secureboot is required for OP-TEE to prevent a malicious OP-TEE kernel from loading. It is furthermore required to allow the generation of a hardware unique key that OP-TEE can use to derive a key for secure storage encryption and other use cases.

Trusted Application Key-Pair

OP-TEE signs trusted applications (see https://optee.readthedocs.io/en/latest/architecture/porting_guidelines.html#trusted-application-private-public-keypair ) in order to ensure their authenticity and integrity. By default, OP-TEE uses a pre-generated key, which you must replace with your own before using OP-TEE in production.

Removing OP-TEE from your Build

If you wish to remove OP-TEE from your build, add the following code to your local.conf:

MACHINE_FEATURES_remove = "optee"

Testing OP-TEE 


When OP-TEE is enabled during the build, the "xtest" utility will be shipped. Executing "xtest" will run a couple of tests supplied by the OP-TEE project to ensure it is working as intended.

Memory Isolation: devmem2

OP-TEE will load itself into a defined region in RAM. This region is reserved in Linux and does not attempt to allocate memory in this area. OP-TEE modifies the device tree of Linux during startup to ensure this.

During runtime, the following nodes will be visible in the device tree:

# dtc -I dtb -O dts /proc/device-tree
# ...
reserved-memory {
                #address-cells = <0x02>;
                #size-cells = <0x02>;

                linux,cma {
                        alloc-ranges = <0x00 0x40000000 0x00 0x40000000>;
                        compatible = "shared-dma-pool";
                        size = <0x00 0x28000000>;

                optee_shm@0x57c00000 {
                        reg = <0x00 0x57c00000 0x00 0x400000>;

                optee_core@0x56000000 {
                        reg = <0x00 0x56000000 0x00 0x1c00000>;

optee_core denotes the secure world memory region. It is not accessible, even to the Linux kernel. optee_shm is the shared region between the normal and secure world, allowing normal-world client applications to exchange data with OP-TEE-trusted applications.

Memory access policy enforcement can be tested using the "devmem2" utility.

root@phyboard-polis-imx8mn-1:firmware# devmem2 0x5600000 

Memory mapped at address 0xffff88e2c000.
Bus error
root@phyboard-polis-imx8mn-1:firmware# echo $?
root@phyboard-polis-imx8mn-1:firmware# devmem2 0x57c00000                                                                                                                                    
/dev/mem opened.
Memory mapped at address 0xffffb4f3c000.
Read at address  0x57C00000 (0xffffb4f3c000): 0xA0A28501
root@phyboard-polis-imx8mn-1:firmware# echo $?

The 0x5600000 address is the optee_core region. Access is currently being blocked by the TZASC policy set up by OP-TEE, which causes a "Bus error". The shared region, on the other hand, is accessible.

Trusted Platform Module (TPM) 2.0

The Trusted Platform Module (TPM) is an international standard for a secure cryptoprocessor, a dedicated microcontroller designed to secure hardware through integrated cryptographic keys.
The TPM 2.0 is:

  • specified from the Trusted Computing Group (TCG) https://trustedcomputinggroup.org/resource/pc-client-platform-tpm-profile-ptp-specification/
  • TCG and Common Criteria (CC) certified EAL4+
  • updateable for the Firmware
  • available from different manufacturers
  • used to create and store keys and certificates that can be used for filesystem encryption, device identification, and authentication
  • a safe on the device, because the persistent keys are in the TPM and the key blobs can only be encrypted with the specific TPM

The Linux kernel has driver support for the TPM. TPM is the standard trusted key in the kernel keyring service. The middleware for the TPM is Open Source (https://github.com/tpm2-software) and supports OpenSSL, PKCS#11, and more.
More information about the software stack for the TPM 2.0:  https://tpm2-software.github.io/
A practical guide for using the TPM 2.0: https://link.springer.com/content/pdf/10.1007%2F978-1-4302-6584-9.pdf

The following list is a selection of PHYTEC boards with soldered TPM. The TPM is not on a module, it is located on the carrier board.

Initialization of TPM for filesystem Encryption

All commands are in the ramdisk userspace. Refer to First Boot or Recover a Device to stop the boot in the ramdisk.

Please use the tool phySecureKeyStorage Tool for the initialization of filesystem encryption if a trusted TPM key is initialized.

More information about Disk Encryption with TPM: https://tpm2-software.github.io/2020/04/13/Disk-Encryption.html

Initialization of TPM for Device Identification

In this example, the TPM will initialize and a self-signed certificate will be stored:

kernel$ physecurekeystorage --newkeystorage trustedtpm
  • Then create a device identification key pair
kernel$ physecurekeystorage --pkcs11testkey
  • After that, you can create the device identification certificate and store it in the TPM
# Create self-signed certificate
kernel$ openssl req -config "${CA_DIR}/csrtpm.cnf" -new -x509 -engine pkcs11 -keyform engine -key "pkcs11:model=SLB9670;manufacturer=Infineon;token=test;object=test-keypair;type=private;pin-value=${TPM_PIN}" -out ecc.crt
# Write Device Cert to TPM
kernel$  pkcs11-tool --module /usr/lib/libtpm2_pkcs11.so.0 -w ecc.crt -y cert -a iotdm-cert --pin ${TPM_PIN} -d 2


For device identification on a server or cloud provider, you need a Certificate Authority to sign the device certificate.

The csrtpm.cnf:

openssl_conf = openssl_init

engines = engine_section

pkcs11 = pkcs11_section

engine_id = pkcs11
MODULE_PATH = /usr/lib/libtpm2_pkcs11.so.0
init = 0

Kernel Key Retention Service for filesystem Encryption

"The Linux key-management facility is primarily a way for various kernel components to retain or cache security data, authentication keys, encryption keys, and other data in the kernel."
Linux kernel is a kernel’s facility for “password caching”, which stores them in a computer’s memory (RAM) during an active user’s/system session.
The Linux keyring accessing is via syscalls from the user space into the kernel space. A
pplications to access are keyctl, systemd-ask-password and others.

The documentation about the Kernel Key Retention service can be found at https://www.kernel.org/doc/html/latest/security/keys/core.html
The following description and implementation are based on the https://www.kernel.org/doc/html/latest/security/keys/trusted-encrypted.html

The following implementation is in the different BSP available:

  • warrior (i.MX6 only): NXP CAAM secure key (red blob) secure_key.blob file name
  • hardknott: trusted with the blob file name key trusted_key.blob independent from the trusted source tpm|caam|tee
  • hardknott (NXP vendor-based BSP only): NXP CAAM secures key (black blob) with tksecure_key.bb as a blob file name.

depend on
i.MX6 / i.MX6ULi.MX8M Series
trusted key: tpm
trusted key: caam
trusted key: tee

on request

NXP CAAM secure key (black blob)
Trusted Key Information

Secure Key Storage Initialization with phySecureKeyStorage Tool

The tool physecurekeystorage-install is part of the ramdisk userspace and included in the BSP from Yocto hardknott. Refer to First Boot or Recover a Device to stop the boot in the ramdisk. If the tool is not part of your BSP, then you can find the tool at: https://git.phytec.de/meta-ampliphy/tree/recipes-physecurity/secure-key-storage

The physecurekeystorage-install tool can initialize all supported secure key storages of your machine, but always only one can be active. For example, the phyBOARD-Polis-imx8mm supports Trusted TEE, Trusted TPM, and Secure CAAM, but initialized is only Trusted TPM.

PHYTEC Install Script v1.5 for Secure Key Storage

Usage:  physecurekeystorage-install [PARAMETER] [ACTION]

    physecurekeystorage-install --newkeystorage trustedtpm
    physecurekeystorage-install --deletekeystorage
    physecurekeystorage-install --loadkeystorage
    physecurekeystorage-install --pkcs11testkey

One of the following action can be selected:
    -n | --newkeystorage <value>  Create new Secure Key Storage
                            trustedcaam or securecaam (black blob NXP BSP)
    -d | --deletekeystorage Erase the existing Secure Key Storage
    -l | --loadkeystorage   Load the existing Secure Key Storage
    -p | --pkcs11testkey    Create an ECC testkey with user pin 1234
    -h | --help             This Help
    -v | --version          The version of physecurekeystorage-install


OpenSSL is a robust, commercial-grade, full-featured software library for general-purpose cryptography and secure communication.

OpenSSL with TPM 2.0

The source/meta-ampliphy-/recipes-image/packagegroups/packagegroup-openssl-tpm2.bb makes the TPM 2.0 accessible via the standard OpenSSL API and command-line tools.
This package group uses the tpm2-tss-engine as a cryptographic engine for OpenSSL for Trusted Platform Module (TPM 2.0).

Example usage:

Cryptographic Token Interface PKCS#11

Also known as "Cryptoki". An API defining a generic interface to cryptographic tokens. Often used in single sign-on, public-key cryptography, and disk encryption systems. RSA Security has turned over further development of the PKCS #11 standard to the OASIS PKCS 11 Technical Committee.

The source/meta-ampliphy-/recipes-image/packagegroups/packagegroup-pkcs11-tpm2.bb makes the TPM 2.0 accessible via PKCS#11 interface with pkcs11-tool and OpenSSL (with engine pkcs11) with:

  •  /usr/lib/libtpm2_pkcs11.so.0 for TPM 2.0
  • /usr/lib/opensc-pkcs11.so for Smart Cards


Secure Storage

Secure storage is a combination of the authenticated and encrypted filesystem that adds another layer of security to your product. It uses the kernel's cryptographic support to encrypt all the data you store in the root filesystem. Attempting to access this data without the correct encryption key returns random, meaningless bytes.

The first implementation of secure storage in the PHYTEC BSP was the root filesystem encryption. Newer BSP from Yocto hardknott are with integrity support:

IntegrityEncryptedIntegrity and Encrypted
& MD
block device
block device



& MD

block device
supported from hardknott
with file integrity support
first example implementation version,
which is supported in newer BSP, too
supported from hardknott
with file integrity support
Secure Storage Information

This manual describes the integrity or/and encryption of the complete root filesystem. Note that on-the-fly encryption and decryption do introduce a small performance penalty in read and write speeds.

Alternatives for the complete root filesystem with integrity and encryption are:

  • Partition encryption: To protect some sensitive files but not pay the cost of encrypting the complete rootfs, you can keep the rootfs partition authenticated unencrypted and set up a specific authenticated encrypted partition where the sensitive files will be stored.

  • File-specific encryption: Only separate folders and files will be encrypted.


  • ampliphy-secure is an example of how integrity and encryption on embedded devices work. It uses encryption with integrity for a complete partition on eMMC. 
  • Encrypting the entire root partition should be considered. However, this can only be done on the device.
  • An integrity check with dm-integrity is a highly recommended addition to the filesystem encryption.

Filesystem with Integrity vs Authenticated filesystem

The actual standard BSP includes integrity support with hash sha-256,  which has protection against data error.
An authenticated file system should use HMAC with signed hashes, which have protection against device-turned-off data manipulation from attackers. For this variant, an additional symmetric key is necessary.

Requirements for Filesystem Encryption

  • File integrity and encryption support for block devices (SD card, eMMC) or MTD device (NAND, NOR)
  • Secure Key Storage to securely store the authentication and encryption key
  • Secure Boot must be activated and the device must be locked for proper secure key storage. 
  • Protection Shield Level should be activated for access control on runtime.

Boot Process Flow

  • bootloader verifies FIT-Image with linux-kernel image, device tree, and ramdisk before they are executed
  • Linux kernel executes the ramdisk (read-only filesystem)
  • The bootscript loads the authenticated encrypted filesystem encryption key with the CAAM|TEE|TPM unit in the RAM and encrypts the filesystem. After the encryption, the root filesystem will be switched and the boot process continues.

Starting the Build Process

Filesystem integrity and encryption are included in the DISTRO_FEATURE secureboot and securestorage.

You can choose in the sources/meta-ampliphy/conf/distro/common-secure.inc between

  • fileauthorenc: use integrity or encrypted filesystem
  • fileauthandenc: use integrity and encrypted filesystem

This configuration is important for the RAUC update system because the use of integrity and encrypted filesystem are stacked and the number of device-mappers is doubled to use integrity or encrypted filesystem.

DISTRO_FEATURES += "securestorage"
#possible types: fileauthorenc , fileauthandenc
SECURE_STORAGE_TYPE = "fileauthandenc"
OVERRIDES_append = ":securestorage:${SECURE_STORAGE_TYPE}"

You will find an example of how to enable filesystem with integrity and encryption in your distro in meta-ampliphy:

  • phytec-secureboot-ramdisk-fitimage
  • phytec-secureboot-ramdisk-image

Filesystem integrity and encryption have several dependencies:

DependencyFile ExampleDescriptionDepends OnExample
Trigger for eMMC image with file encryption support


with file integrity support:


  • trigger to build FIT-Image with ramdisk for eMMC image creation (wic)

Image for encrypted partitionrecipes-images/images/phytec-security-image.bb
  • image recipe, which should  encrypt on the target
  • can include a trigger for building the FIT-Image with ramdisk for  eMMC image (wic)
  • include security/fileencryption.inc

    with file integrity support:


FIT-Image with ramdisk for bootrecipes-images/fitimage/phytec-secureboot-ramdisk-fitimage.bb
  • configuration recipe for the FIT-Image with ramdisk

Ramdisk for encryption handlingrecipes-images/images/phytec-secureboot-ramdisk-image.bb
  • minimal ramdisk with busybox file authentication and encryption support
  • package for file authentication/encryption and init script for file authentication and encryption
  • recipe secureboot-fileencrypt

    with file integrity support:

    recipes secure-storage

Install boot init script and encryption packages


with file integrity support:

  • include different runtime packages for file authentication and encryption
  • ramdisk init script for authenticat and encrypt filesystem at boot
  • init script secureboot-fileencrypt.sh

    with file integrity support:


Boot init script for encryption handling on the target


with file integrity support:

  • boot init script to encrypt / decrypt and authenticated the filesystem on the target at boot
  • filesystem encryption key, which is stored in the Secure Key Storage
  • with i.MX CAAM unit, TEE or TPM encrypted trusted_key.blob, which is stored in the first boot partition
Filesystem Integrity and Encryption Dependencies

Build All Necessary Images and eMMC Image

host$ bitbake phytec-security-image

When you change something on the boot init script, then you should, at minimum, clean the recipes for ramdisk and FIT-Image too. If you need a new eMMC image, then clean the image for encryption partition, too

Setup Secure Storage on your Device

The filesystem encryption ensures the target has a unique key or an equal key per device.

The filesystem encryption process flow:

  • The filesystem encryption key is generated and stored encrypted with CAAM, TEE, or TPM.
  • Encryption is initialized.
  • The partition is formatted.
  • Data is copied to the encrypted partition.

1. First Boot 

From a high-level point of view, an eMMC device is like an SD card. Therefore, it is possible to flash the imagephytec-provisioning-image.sdcard from the Yocto build system directly to the SD card. The image contains the signed bootloader and signed FIT-Image with an initramfs.

If your filesystem is not initialized, is damaged, or the key blob is deleted, then you can reinstall the encrypted filesystem with the following instructions.

  • Boot the phytec-provisioning-image from the SD card
  • Stop booting in the bootloader. The Protection Shield Level low is in default with password: root
  • The device stops with the following message because there is no encrypted key stored in the folder/secrets:
Run /init as init process

(none) login:

The Protection Shield Level low is in default with user: root and password: root


If there is no login in 60s, then the system goes to power off

Login timed out after 60 second
[ERROR] Key and Filesystem Initialization
The system will poweroff in 10 seconds
reboot: Power down

2. Key Generation for Secure Storage

Please follow the instructions in the chapter Secure Key Storage initialization with phySecureKeyStorage Tool

3. Secure Storage Initialization with phySecureStorage Tool

The tool physecurestorage-install is part of the ramdisk userspace and included in the BSP from Yocto hardknott. Refer to First Boot or Recover a Device to stop the boot in the ramdisk. If the tool is not part of your BSP, then you can find the tool at: https://git.phytec.de/meta-ampliphy/tree/recipes-physecurity/secure-storage

The physecurestorage-install tool can initialize the filesystem with encryption, integrity, or both methods together.

i.MX6 / i.MX6UL Mainline Kerneli.MX8M with NXP Kernel

eMMC Device: /dev/mmcblk3

eMMC Device: /dev/mmcblk2

physecurestorage-install Filesystem
PHYTEC Install Script v1.2 for Secure Storage

Usage:  physecurestorage-install [PARAMETER] [ACTION]

    physecurestorage-install --flashpath /dev/mmcblk0
    --filesystem /media/phytec-security-image.tgz --rauc
    --flashlayout 5,6
    --newsecurestorage intenc

One of the following action can be selected:
    -n | --newsecurestorage <value>   Create new Secure Storage of type
                            int     Root File System with integrity
                            enc     Encrypted root file system
                            intenc  Encrypted root file system with integrity
    -h | --help             This Help
    -v | --version          The version of the physecurestorage-install

The following PARAMETER must be set for new Secure Storage:
    -p | --flashpath <flash device>
    -s | --filesystem <path to root as tgz>
    -l | --flashlayout <value>    partion number for the rootfs partitions
                       2,4        rootfs partitions are 2 and 4 (old)
                       5,6        rootfs partitions are 5 and 6 (new)

The following PARAMETER can be set for new Secure Storage:
    -r | --rauc   (A/B system on the flash)
  • The parameter <flashpath> is the eMMC partition for:
    •  i.MX6/UL (Mainline): /dev/mmcblk3
    • i.MX8M Series (NXP Vendor Kernel): /dev/mmcblk2
  • The parameter <filesystem> is the path to tar.gz archive of the filesystem, which should be installed on the flash device.
    Please copy the filesystem image, <IMAGENAME>-<MACHINE>.tar.gz, to a USB or MMC drive so that it can be installed on the target.
  • The parameter <flashlayout> contains the rootfs partition.
  • The parameter RAUC initializes both RAUC rootfs partitions.
  • After the installation, power off the system:
kernel$ poweroff -f
  • Restart the system. After a successful installation, the system will boot to the kernel login console.

Recover an Initialized Device

If your filesystem is damaged or the key blob is deleted, then you can reinstall the encrypted filesystem with the following options.

  1. Reinitialize your device with the phytec-provisioning-image from the SD card (Boot in ramdisk)
  2. Boot in rescue mode of the existing flash image with minimal tools support

The following commands are for starting the rescue mode with a booted device from eMMC:

  • Stop booting in the bootloader. The Protection Shield Level low is in default with password: root
  • Add Linux bootargs:
i.MX6 / i.MX6UL with bareboxi.MX8M with u-boot
barebox$ global linux.bootargs.rescue="rescue=1"
uboot$ run loadraucimage
uboot$ run raucargs
uboot$ setenv bootargs ${bootargs} rescue=1
  • Boot the FIT-Image:
i.MX6 / i.MX6UL with bareboxi.MX8M with u-boot
barebox$ boot
uboot$ bootm ${loadaddr}
  • The device stops with the following message
Run /init as init process
(none) login:

The Protection Shield Level low is in default with user: root and password: root


If there is no login in 60s, then the system goes to power off

Login timed out after 60 second
[ERROR] Key and Filesystem Initialization
The system will poweroff in 10 seconds
reboot: Power down

Secure Update

Due to the connected nature of devices, security vulnerabilities are more widespread than ever before, and new threats are discovered by the security community daily. Security requirements change often, and it is therefore important to make sure your system is ready to be securely updated so new vulnerabilities can be patched or functionality can be added to the product. A secure update process involves more than safely updating a device. It also verifies that the delivered image is coming from a known source and that the image was not modified to introduce malware.

The phytec-security-image includes the phytec-rauc-image with an A/B system and the RAUC update client.

For more information about the supported update client RAUC refer to RAUC Update & Device Management Manual and the ESEC/Connagtive IoT UDM Kit Guide.

The RAUC handler on the target backs up and restores the secrets for boot0 partition. 

From the BSP (with Yocto hardknott), the encryption for the filesystem remains intact because the device mapper will be updated.


Before the version Yocto hardknott:

After the RAUC update, the encrypted filesystem partition is NOT encrypted. The RAUC handler must be reworked to handle the updates for an encrypted filesystem. Additionally, the data in the RAUC bundles should be encrypted during the transition to the target with a different key.

Access Control: Protection Shield Level

The DISTRO_FEATURE protection shield offers an easy way to switch between different protection levels. You can use the low protection level during your development and easily switch to a higher level for your final build when entering series production.

Password Protection in Protection Shield V1

The following table shows the different protection shield levels for password protection.

FeatureLevel LowLevel  MediumLevel High
Debug Interface: Password Protection for Bootloader
  • random hash is set
Debug Interface: Password Protection for Kernel Image
  • the PROTECTION_SHIELD_ROOT_PASSWORD is set for the user root
  • the PROTECTION_SHIELD_ROOT_PASSWORD is set for the user root
  • login for root is disabled
Password Protection Shield Levels

Password protection depends on the quality of the password. The default password for user root is "root", which is an extremely low-quality password.


The variable PROTECTION_SHIELD_ROOT_PASSWORD is stored in your distro configuration file conf/distro/xyz.conf. Do not push this file to the git repository with your actual series password.

User Role and Password Protection in Protection Shield V2

The phytec-security-image includes the phytec-example-users with the following configuration depending on the shield level. Most interfaces are in the group phyapix for access control.

Descriptionthe superuser with rights to allis for administration and can get superuser rights with sudoa normal user with rights to only selected featuresonly read access and no access to the most interfaces
Grouprootroot, phyadmin, phyapix,  tty, tssphyuser, phyapix, tty, tssphyreaduser

Protection level Login
Password for Serial and ssh


  • all devices have the same password
  • password set in buildsystem





  • set individual passwords at the first boot


  • set individual passwords at the first boot
  • root users have no login access

serial and ssh no login access

phyapix Access Control

Enable Protection Shield Support in Yocto

Enable Protection Shield in Your Own Distro

To enable the protection shield, add the DISTRO_FEATUREprotectionshield to your distro configuration file conf/distro/xyz.conf. The variables PROTECTION_SHIELD_LEVEL and PROTECTION_SHIELD_ROOT_PASSWORD must be set:

 DISTRO_FEATURES += "protectionshield"                                            
 PROTECTION_SHIELD_LEVEL = "shieldlow"                                            
 #user root password for shield low and midle                                     
 #password quality decide about the protection level                              

Enable Protection Shield Level in Your Kernel Image

To enable a protection shield in your Linux kernel image, you need to include security/userauthentication.inc into your image recipe.  For an example, please take a look at recipes-images/images/phytec-security-example-image.bb included in ampliphy-secure.

If you use a ramdisk for your filesystem, you will need to include security/userauthentication.inc into your ramdisk recipe, too. For an example, please take a look at recipes-images/images/phytec-secureboot-ramdisk-image.bb included in ampliphy-secure.

Hardening of the System

The DISTRO_FEATURE hardening activates the kernel reduction with deselect fragments.  The name of the deselection variable is KERNEL_FEATURES_DESELECT.

The deselect fragment selection for bluetooth, can, optee, pci and wifi depend on MACHINE_FEATURES with the same name.
If these features are not set in MASCHINE_FEATURES, then the deselect fragment with the same name is active. but can be selected independently from the MASCHINE_FEATURE too.
The fragments debug, kvm, media and xen are selected by default and independent from the machine feature.

Overwriting the initial definition of the variable KERNEL_FEATURES_DESELECT is possible.

Kernel FragmentDescriptionSelection with

Activate Fragment


Activate some hardening features in the kernel.
This fragment is the default active with the distro feature hardening.

deselect-bluetooth.cfgDisable the Bluetooth support.(tick)(tick)
deselect-can.cfgDisable the CAN support.(tick)(tick)
deselect-optee.cfgDisable optee support.(tick)(tick)
deselect-pci.cfgDisable PCI interface support.(tick)(tick)
deselect-wifi.cfgDisable wireless and WLAN support(tick)(tick)
deselect-debug.cfgDisable kernel debug support.(tick) initial set(minus)
deselect-kvm.cfgDisable kernel-based virtual machine support.(tick) initial set(minus)
deselect-media.cfgDisable the ANALOG / DIGITAL TV, RADIO and SDR support(tick) initial set(minus)
deselect-xen.cfgDisable  xen paravirtualisation(tick) initial set(minus)

Physical Security

To further protect your device, it is important to reduce attack vectors. Start by securing development features like JTAG and serial downloader. For activation or deactivation of controller features, is necessary to write and read eFuses.


The secure eFuse configuration can only be written once and is irreversible.

Secure JTAG

Most embedded devices provide a JTAG interface for debugging purposes. However, if left unprotected, this interface can become an important attack vector on the systems in series production. The i.MX6 series System JTAG Controller (SJC) allows you to regulate JTAG access with three security modes using OTP (One Time Programmable) eFuses:

ModeSecurity LevelDescription
EnabledlowThis is the default mode of operation and you have full access to JTAG
Disabled debuggingmediumThis mode disables debugging but leaves the boundary scan functionality enabled.
SecurehighThis mode provides high security. JTAG use is regulated by a 56-bit secret key-based challenge/response authentication mechanism.
Disabled JTAGhighThis mode provides maximum security. All security-sensitive JTAG features are permanently blocked, preventing any debugging.
OTP Three Security Modes

Additional information about JTAG Security can be found here: https://www.nxp.com/docs/en/application-note/AN4686.pdf

Disabled Debugging Mode

Set JTAG to "Disabled debugging" mode:

i.MX6* with bareboxi.MX8M*

barebox$  mw -l -d /dev/imx-ocotp 0x18 0xC00000
uboot$ fuse prog 1 3 0xC00000  
JTAG Disabled Debugging Information

Secure JTAG Mode

Set JTAG to "Secure" mode as an example for i.MX6/i.MX6UL.

  1. Generate a secret response key

    You can choose between Identical Response Keys on each device or unique response keys for every device

    host$ cat /dev/random | tr -dc a-f0-9 | head -c${1:-14} | sed 's,^\([[:xdigit:]]\{6\}\)\([[:xdigit:]]\{8\}\),0x00\1 0x\2,g'

    You will receive, for example:

    0x00edcba9 0x87654321
  2. Write secret response key:

    i.MX6* with bareboxi.MX8MM

    barebox$  mw -l -d /dev/imx-ocotp 0x80 0x87654321
    barebox$  mw -l -d /dev/imx-ocotp 0x81 0x00edcba9
    uboot$ fuse prog 8 0 0x87654321
    uboot$ fuse prog 8 1 0x00edcba9    
    Secret Response Key
  3. Lock access to secret response key:

    i.MX6* with bareboxi.MX8MM

    barebox$ mw -l -d /dev/imx-ocotp 0x00 0x0040
    uboot$ fuse prog 0 0 0x400
    Secret Response Key
  4. Set Secure JTAG mode:

    i.MX6* with bareboxi.MX8MM
    barebox$  mw -l -d /dev/imx-ocotp 0x18 0x400000

    uboot$ fuse prog 0 0 0x400000
    Secure JTAG Mode

Disable JTAG Mode

Taski.MX6* with Bareboxi.MX8MM/i.MX8MP Bootloader

Set JTAG to "Disabled" (SJC_DISAB FUSE)
barebox$  mw -l -d /dev/imx-ocotp 0x18 0x00100000
uboot$ fuse prog 1 3 0x200000
Disabling JTAG Mode

Disable HAB JTAG Enabling

When JTAG is set in "Secure", an option to enable HAB JTAG DEBUG becomes available. By writing '1' to HAB_JDE (HAB JTAG DEBUG ENABLE) bit in the e-fuse controller module, the JTAG is opened, regardless of its security mode. If this feature is not required, it is highly recommended this be disabled. 

For this, we program the JTAG_HEO FUSE.

Taski.MX6 with Bareboxi.MX8MM/i.MX8MP Bootloader

Prevent HAB from Enabling JTAG

barebox$  mw -l -d /dev/imx-ocotp 0x18 0x08000000

information only available with NXP NDA

Disable HAB JTAG Information

Disable Serial Downloader

The i.MX6, i.MX6UL and i.MX8M series Controller supports the burning of different eFuse to disable the USB Serial Download Protocol (SDP) and Force Internal Boot Only to enhance device security.


 i.MX6 and i.MX6UL:  i.MX & Vybrid Security Vulnerability Errata - ERR010872, ERR010873

Below is a list of PHYTEC Products and variants that include the controller version with the feature for Disable Serial Downloader and Force Internal Boot:

PHYTEC Products with Disable Serial Downloader and Force Internal Boot

For phyFLEX-i.MX6 and phyCARD-i.MX6 support, ask your sales contact.

Disable SDP Mode Completely

Disabling the serial download support is recommended for security-enabled configurations:

i.MX6i.MX6ULi.MX8M series
barebox$ mw -l -d /dev/imx-ocotp 0x18 0x0001
barebox$ mw -l -d /dev/imx-ocotp 0x18 0x20000
uboot$ fuse prog 2 0 0x200000
Disabling Serial Download Support

Disable Read Access in SDP

Disabling only read access via SDP. Writing will still be possible.

barebox$ mw -l -d /dev/imx-ocotp 0x18 0x0004
barebox$ mw -l -d /dev/imx-ocotp 0x18 0x40000
Disable Read Access

Force Internal Boot

Ensure the device always boots in INTERNAL BOOT mode, ignoring BOOT_MODE pins. This setting is recommended for security-enabled configurations. This feature is supported in the listed PHYTEC products.



barebox$  mw -l -d /dev/imx-ocotp 0x18 0x80000000
barebox$  mw -l -d /dev/imx-ocotp 0x18 0x10000

For i.MX8M*

uboot$ fuse prog 2 0 0x100000
Forcing Internal Boot

Disable Boot from External Memory

By writing to the DIR_BT_DIS FUSE, we can disable boot from external memory.

i.MX6 / i.MX6ULi.MX8M
barebox$ mw -l -d /dev/imx-ocotp 0x18 0x0008
uboot$ fuse prog 1 3 0x8000000

Keys and Certificates Management

Public Key Infrastructure Tree (PKI tree)

To use a secure boot with a signed bootloader and a signed kernel image, several keys and certificates are required to sign the images. The key and certificate creation is a manual process and the public key infrastructure (PKI) tree must be in place before you start your build. This BSP includes the PHYTECD development pki-tree as an example. You are obligated to create your own pki-tree with your own keys and certificates.


It is highly recommended to use different keys for different parts of your system to avoid a single point of failure regarding your security concept.

PHYTEC Development Keys (phytec-dev-ca)

The included phytec-dev-ca example consists of a self-signed main-ca and three derived sub-ca's for bootloader, Fit-Image, and RAUC updates.

phytec-dev-ca Breakdown

The recipes for Bootloader, FIT-Image, and RAUC depend on the recipe phytec-dev-ca. If you build the BSP for the first time, the PHYTEC development keys are downloaded in yocto/phytec-dev-ca. They are used to sign the Bootloader, FIT-Image, Kernel modules, and the RAUC bundles.

NameDescriptionKey Type
main-caself-signed Certificate authorityRSA-4096
nxp_habv4_pkimain-ca signed NXP HABv4 Key AuthorityRSA-4096
fitmain-ca signed FIT-Image signing key and certificateRSA-4096, RSA-2048
raucown self-signed Certificate authority and development key for signing the bundlesRSA-2048
rauc-intermediatemain-ca signed RAUC ca (intermediate ca) and RAUC ca sign development key for signing the bundlesRSA-2048
kernel-modsignExample key for the Linux kernel module signing facility, independent of CARSA-4096
phytec-dev-ca Recipes

All keys and certificates are stored in an XCA database phytec-dev-ca.xdb, which can be configured with the open-source application XCA from https://hohnstaedt.de/xca/. The password for the phytec-dev-ca.xdb is: phytec-dev-ca

Only the necessary keys and certificates for the build process are exported to the directory.


The phytec-dev-ca is installed in the directory
|-------- build
|-------- phytec-dev-ca
|-------- source

All keys and certificates are in an XCA database and are not copied to different paths from the packages in the build folder. The directory contains only the necessary certificates and keys for the building process.


  • Use the PHYTEC development keys only for the first test.
  • The PHYTEC development keys are not secure!
  • Create and use your own keys and certificates!

NXP HABv4 Key Structure

The NXP HABv4 Key structure is for signing the bootloader and FIT-Image, which is verified from the ROM bootloader of the NXP controller with the HABv4 module. The i.MX6, i.MX6UL, i.MX7, i.MX8M, and i.MX8M Mini includes a HABv4 module for secure boot.

  • CA (Certification Authority): This certificate is used to sign the SRK keys and establish the authority of other keys. There is only one CA certificate per PKI tree. This certificate is never used on the target and has no requirements. An existing certificate can be used as CA during the generation of all these keys. The rest of the keys and certificates are always generated and have special requirements, as they are directly used on the target.
  • SRK (Super Root Keys): This certificate is used to sign the CSF and IMG certificates. There are up to four SRK certificates per PKI tree (each one is used to sign one CSF and one IMG certificate). See revoke a key for more information on having multiple SRK certificates.
  • CSF (Command Sequence File): This certificate is used to validate the CSF region.
  • IMG: This certificate is used to validate the bootloader or FIT-Image data.

Create Your Own PKI Tree

Please create your PKI offline with a separate system. For example, boot a read-only system from USB which you only use to create the PKI. The phytec-dev-ca is created with XCA from https://hohnstaedt.de/xca/, but you can use any other tool, too.

NXP has included a script cst-3.3.1/keys/hab4_pki_tree.sh for creating the keys and certificates for the nxp_habv4_pki. You can use this script or a PKI application like the XCA.

For creation, the SRK table and SRK Fuses from the SRK certificates are scripts in the NXP CST archive in the folder cst-3.3.1/code/hab_srktool_scripts,which used the cst-3.3.1/linux64/bin/srktool.

Change PKI-Tree from phytec-dev-ca to Your Own PKI

In the configuration class sources/meta-ampliphy/classes/secureboot.bbclass, the path to your PKI tree is initially defined:

CERT_PATH ??= "${OEROOT}/../../phytec-dev-ca"

If you want to change the path, then reinit the CERT_PATH ?= in your layer or overwrite the CERT_PATH in the conf/local.conf

The name of your PKI tree must have a name other than phytec-dev-ca. The recipe for phytec-dev-ca uses the name "phytec-dev-ca" as a parameter for the clean command.

After the CERT_PATH has been changed, you must clean and rebuild the bootloader, FIT-Image, RAUC bundles, and the rootfs!

host$ bitbake -c cleanall phytec-secureboot-ramdisk-fitimage
host$ bitbake -c cleanall phytec-security-bundle
host$ bitbake -c cleanall phytec-security-image

Encryption Keys


Secure other keys:

  • a symmetric file encryption key

Unique per device and unreadable.

  • You do not need to do anything about this key.
Filesystem encryption keyEncrypts file system dataEncrypted and stored in the first boot partition.
Secure JTAGProtects JTAG port

Stored in the OTPs of the device. Unreadable when the Secure JTAG configuration is locked.

  • You must securely back up this key.
Encryption Key Information

Using HSM (PKCS#11 tokens) to Sign Images


Support is experimental as, at this point, it relies on the PIN value being specified in the PKCS#11 URI.

Generally, storing private keys on the file system of the build server makes the key subject to attacks, allowing it to be compromised should third-party gain access to the server. A method to mitigate that risk is the use of hardware security modules (HSM). Examples of HSMs are SmartCard-HSM or NitroKey HSM 2.  When using an HSM, your key will be stored in special hardware in a manner that makes it very difficult for attackers to access it without special means. Keys stored on the HSM then will be used to sign images, never leaving the HSM in the process.

It is possible to sign PHYTEC's images using such hardware security modules, or tokens, by using the PKCS#11 API. If a PKCS#11 API is available for your token, then the build process can be directed to use the keys stored there to sign the images.

Currently, NXP's CST tool can be used to sign images. RAUC also has the ability to sign bundles using PKCS#11. In addition, the kernel can also handle PKCS#11-based keys. This means it is possible to have all components involved in the secureboot process signed by using HSMs.


A number of pitfalls are available in PKCS#11 which may allow a private key to leave the token. https://link.springer.com/chapter/10.1007/978-3-540-45238-6_32
You generally should make sure a key does not possess the C_DECRYPT and C_WRAP attributes.

Signing Secure Boot Images

A guideline on how to sign images using the CST tool and PKCS#11 has been made available by NXP: https://www.nxp.com/webapp/Download?colCode=AN12812

The steps to build a CST version that makes use of the OpenSSL PKCS#11 engine have been automated by PHYTEC. An example build/local.conf config can be found here:

CST_KEY_SOURCE = "token"


Setting the PIN value in the URI reveals it to the attacker. As long as your token is plugged into your system, an attacker may sign images if he compromises your system.

By setting the CST_KEY_SOURCE variable to "token", the recipe will automatically build a version that understands the pkcs11 URI syntax. The CST tool will search for the p11-kit-proxy library on the host. On Debian-based systems, it can be installed by executing "apt-get install p11-kit". Note that your token may require configuration before it becomes known to the p11-kit.


Systems without p11-kit-proxy

The path to the PKCS#11 module must be specified in the PKCS11_MODULE_PATH variable in your build/conf/local.conf file.

Signing Kernel Modules

Kernel modules can also be signed using HSMs. Keep in mind that signing the modules takes time; therefore, your build time for the kernel will likely vastly increase when employing PKCS#11 Hardware tokens. This largely depends on the processing power of your token, but generally smart card-like tokens will lead to a significant increase.

Signing RAUC Bundles

RAUC will use the libp11-proxy library. To override it, set the path to your library in the RAUC_PKCS11_MODULE var in the build/conf/local.conf. You must set the PKCS#11 URI for the key and cert:


More information about RAUC and PKCS#11 can be found here: https://rauc.readthedocs.io/en/latest/advanced.html?highlight=pkcs11#pkcs-11-support

PKCS#11 from Inside Docker

If you are using Docker to build images, tokens plugged into your machine can't be accessed right away. You must allow the Docker container access to your device, as described below.

As PKCS#11 does not specify the underlying device interface, it is not generally possible to provide guides for all devices. With a network HSM for example, the container only needs is network access. For interfaces such as USB, certain steps have to be taken.

USB-based Tokens

On your host, run lsusb

host$ lsusb
Bus 003 Device 008: ID 20a0:4230 Clay Logic Nitrokey HSM

Identify your device from the list. You have to pass the proper path to the Docker container.

host$ docker run -it --device=/dev/bus/usb/003/008

From the lsusb output, we can tell that it is on bus 003 and the device is at 008. Therefore, we pass /dev/bus/003/008 to the container.

container$ pcscd
container$ # start using your device

Your container must have all the libraries and drivers installed/configured that are necessary to use your token.

Security Vulnerabilities

The used software can be affected by security vulnerabilities. A security vulnerability generally is a bug in software code that could allow an attacker to gain control of a system. It is essential to check the software regularly against published security flaws (Common Vulnerabilities and Exposures).

Revision History

DateVersion NumberChanges to the Manual
11.05.2020L-1004e.A01st Release
03.8.2021L-1004e.A1Information added for:
  • phyCORE-i.MX 6UL
  • phyCORE-i.MX 8M Mini
  • phyCORE-i.MX 8M Plus
  • Update Security Feature for the Yocto hardknott releases
  • Support for the update of encrypted file system
  • Support for optee
  • Add Protection Shield Version 2
  • restructure the Manual
  • Add phyTools support
  • Add ampliphy-(vendor)-provisioning and phytec-provisioning-image
  • Add HSM pkcs#11 support for image and rauc bundle signing
  • Hardening with Kernel config reduction
  • FIT-Image: final kernel device tree generation with device tree overlays
  • PDF Version
  • Fix the FIT-Image description
  • Update the Link "Activate Secure Boot" in chapter "Provisioning your Device with Security in 5 steps"
  • No labels