Skip to main content
Version: BSP 7.x.y

Introduction to meta-toradex-security

Introduction​

meta-toradex-security is a Yocto Project/OpenEmbedded meta-layer that provides metadata to enable security features when building Linux images for Toradex System-on-Modules (SoMs).

The layer is available at the meta-toradex-security GitHub repository, which contains detailed documentation for each supported feature.

The meta-toradex-security layer provides the following main security features:

  • Secure Boot, including full chain-of-trust and support for HSM-backed keys.
  • Data-at-Rest Encryption, supporting key management via i.MX CAAM, TPM, and OP-TEE.
  • Trusted Execution Environment, with support for using the RPMB eMMC partition for secure storage and fTPM (firmware Trusted Platform Module) and PKCS#11 Trusted Applications (TAs).
  • Secure Debug, restricting access to the SoC debug interface.

Enabling the Layer​

Ensure the following dependent layers are available in your build environment before enabling meta-toradex-security:

  • openembedded-core (meta layer)
  • meta-openembedded (meta-oe layer)
  • meta-security
  • meta-toradex-nxp (optional)
  • meta-toradex-ti (optional)

Clone the meta-toradex-security repository into your layers directory:

$ git clone https://github.com/toradex/meta-toradex-security.git -b scarthgap-7.x.y

Then add the layer to your build:

$ bitbake-layers add-layer </path/to/meta-toradex-security>

The layer is now available in your build. To enable a specific security feature, inherit the corresponding class in your conf/local.conf or in a distro configuration file. Refer to the Features section and the repository documentation for the class name and configuration variables available for each feature.

Features​

Secure Boot​

Secure Boot ensures that only trusted, cryptographically signed software runs on the device, protecting against unauthorized code execution from the earliest stages of boot.

danger

Enabling Secure Boot on a device is an irreversible operation. Once the SoC fuses are blown with your keys, the device only boots software signed with those keys. A mistake in the key or signing configuration can permanently brick the device. Always validate the full boot chain on a test device before programming production hardware.

The meta-toradex-security layer supports the following Secure Boot capabilities:

  • Bootloader signature checking: bootloader images are signed at build time and their signature is verified by the SoC ROM code at boot.
  • U-Boot hardening: patches applied to U-Boot to limit the attack surface, including command whitelisting, CLI access prevention, and kernel command-line protection.
  • FIT image signature checking: a FIT image containing the kernel, device trees, and ramdisk is signed at build time and verified by the bootloader at boot.
  • Root filesystem integrity checking: the rootfs image is generated using dm-verity, and its root hash is embedded in the signed ramdisk image, ensuring the rootfs cannot be tampered with.
  • HSM-backed signing: signing operations can be delegated to a PKCS#11-compatible Hardware Security Module (HSM) or token, avoiding the need to store private keys on the build host filesystem.

On i.MX 9-based SoMs (for example, Aquila iMX95, SMARC iMX95, and Verdin iMX95), this Secure Boot chain is rooted in the on-chip EdgeLock Secure Enclave (ELE), NXP's dedicated security subsystem that enforces AHAB authentication and provides hardware-backed cryptographic services.

The layer provides two Yocto classes for enabling Secure Boot:

  • tdxref-signed implements the full chain of trust, including dm-verity rootfs integrity verification.
  • tdx-signed covers bootloader and kernel signing but omits rootfs verification—use it when dm-verity is not suitable for your setup.

For more details, refer to the repository documentation:

Data-at-Rest Encryption​

Data-at-rest encryption protects sensitive data stored on the device from unauthorized access if the storage medium is removed or the device is compromised.

The meta-toradex-security layer supports the following encryption capabilities:

  • Encryption key management: the Linux kernel Trusted Keys subsystem manages the symmetric key used to encrypt and decrypt data on disk. The trust source can be CAAM (available on most NXP i.MX-based SoMs), a TPM (Trusted Platform Module), or a TEE (Trusted Execution Environment). The TEE backend requires OP-TEE to be enabled (see Trusted Execution Environment).
  • Block device encryption: the Linux kernel dm-crypt subsystem provides transparent disk encryption.
  • Persistent data partition: a dedicated encrypted partition for user data, created and mounted at first boot using Toradex Easy Installer.

Refer to the encryption documentation and the persistent data partition documentation for more details.

Trusted Execution Environment​

The meta-toradex-security layer includes support for OP-TEE (Open Portable Trusted Execution Environment), a secure OS that runs alongside Linux in the ARM TrustZone. OP-TEE enables trusted applications to execute in an isolated, hardware-protected environment.

info

OP-TEE support in meta-toradex-security provides the runtime and integration plumbing. It is not a ready-to-deploy security solution on its own. Securing a device with TrustZone requires a correctly configured boot chain (including Secure Boot) and a threat model tailored to your application.

In addition to the core OP-TEE runtime, the layer supports:

  • RPMB (Replay Protected Memory Block): use the eMMC RPMB partition as a tamper-resistant secure storage backend for OP-TEE.
  • fTPM (firmware-based TPM): run a TPM implementation as a trusted application inside OP-TEE, without requiring a discrete TPM chip.
  • PKCS#11 trusted application: expose cryptographic operations from OP-TEE to userspace through the standard PKCS#11 API.

For more details, refer to the OP-TEE documentation.

Secure Debug​

SoCs usually expose a JTAG or other debug interface that is enabled by default. If left open in production, this interface may allow an attacker with physical access to halt the CPU, inspect memory, extract secrets, or inject code.

Protecting it is especially important for devices that use features such as Secure Boot and data-at-rest encryption. An open debug interface can become a practical way to bypass those protections.

To mitigate this risk, the meta-toradex-security layer provides a feature called Secure Debug. It exposes a small, policy-oriented interface that stays the same across SoC families, and delegates the hardware specifics to a per-family backend selected automatically from the machine. The layer supports two main modes:

  • Authenticated debug: debug access is blocked after reset and only reopens for a debug probe that successfully authenticates to the SoC.
  • No debug: security-sensitive debug features, such as CPU halt and memory access, are disabled.

Not every mode is available on every SoC (see the Feature Support Matrix), and some SoCs provide additional configuration options, described in the Secure Debug documentation.

caution

Secure Debug settings are programmed into the SoC fuses and cannot be changed afterward. If you lose the keys used for debug authentication, you lose authenticated debug access to the devices provisioned with them. Confirm that your debug probe supports the authentication flow on a test device before programming production hardware.

For more details, refer to the Secure Debug documentation.

Feature Support Matrix​

  • ✅ feature is supported
  • ❌ feature is not supported
  • ⌛ feature is under development
  • – feature is not applicable
Device →
Feature ↓		Apalis iMX6Apalis iMX8Aquila AM69Aquila iMX95Colibri iMX6DLColibri iMX6ULL (eMMC)Colibri iMX7D (eMMC)Colibri iMX8XLino iMX93SMARC iMX8MPSMARC iMX95Verdin AM62Verdin AM62PVerdin iMX8MMVerdin iMX8MPVerdin iMX95
Secure boot (bootloader authentication)✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅
Secure boot (bootloader hardening)✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅
Secure boot (kernel authentication)✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅
Secure boot (rootfs authentication)✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅
Secure boot (HSM-backed keys)✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅
Secure debug✅⌛⌛⌛✅✅✅⌛⌛✅1⌛⌛⌛✅✅1⌛
Data partition✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅
Data-at-rest encryption (CAAM backend)✅✅–2–2✅–2✅✅–2✅–2–2–2✅✅–2
Data-at-rest encryption (TPM backend)✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅
Data-at-rest encryption (TEE backend)✅❌3✅✅✅⌛✅❌3✅✅✅✅✅✅✅✅
OP-TEE✅❌3✅✅✅⌛✅❌3✅✅✅✅✅✅✅✅
OP-TEE firmware TPM✅❌3✅✅✅⌛✅❌3✅✅✅✅✅✅✅✅
OP-TEE PKCS#11✅❌3✅✅✅⌛✅❌3✅✅✅✅✅✅✅✅

Asking Questions​

For general questions about the layer or its features, contact Toradex support through the Toradex Developer Community.

Reporting Issues & Contributing​

Report issues or contribute to meta-toradex-security in the GitHub repository.

Footnotes​

  1. Authenticated Secure Debug is not available on the i.MX 8M Plus. Erratum ERR052318 states that in Secure JTAG mode the SJC "does not correctly control JTAG access and may not unlock the device for JTAG access," and AN4686 states that "the Secure Debug mode is not functional on the i.MX 8M Plus." NXP recommends "No Debug" mode or disabling the JTAG controller (SJC) instead, which is what the layer offers on this SoC. ↩ ↩2

  2. The CAAM (Cryptographic Acceleration and Assurance Module) backend for data-at-rest encryption is not applicable on TI K3-based SoMs, NXP i.MX 9-based SoMs, and Colibri iMX6ULL, as these SoCs do not include a CAAM hardware block. ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8

  3. OP-TEE requires SPL (Secondary Program Loader) to boot on i.MX 8-based SoMs. The Toradex BSP does not currently provide an SPL implementation for Apalis iMX8 and Colibri iMX8X, so OP-TEE is not supported on these SoMs. ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8

Send Feedback!