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).

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 will only boot 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.

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.

For more details, refer to the encryption documentation and the persistent data partition documentation.

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.

Feature Support Matrix​

  • ✅ feature is supported
  • ❌ feature is not supported
  • ⌛ feature is under development
  • – feature is not applicable
Device →
Feature ↓		Apalis iMX6Apalis iMX8Aquila AM69Colibri iMX6DLColibri iMX6ULL (eMMC)Colibri iMX7D (eMMC)Colibri iMX8XSMARC 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)✅✅⌛✅✅✅✅✅✅⌛⌛✅✅✅
Data partition✅✅✅✅✅✅✅✅✅✅✅✅✅✅
Data-at-rest encryption (CAAM backend)✅✅–1✅–1✅✅✅–1–1–1✅✅–1
Data-at-rest encryption (TPM backend)✅✅✅✅✅✅✅✅✅✅✅✅✅✅
Data-at-rest encryption (TEE backend)✅❌2✅✅⌛✅❌2✅✅✅✅✅✅✅
OP-TEE✅❌2✅✅⌛✅❌2✅✅✅✅✅✅✅
OP-TEE firmware TPM✅❌2✅✅⌛✅❌2✅✅✅✅✅✅✅
OP-TEE PKCS#11✅❌2✅✅⌛✅❌2✅✅✅✅✅✅✅

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. 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

  2. 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!