RidgeRun Platform Security Manual - NXP i.MX95 Yocto Build Process: Disk Encryption
🚧 Documentation is under development
The RidgeRun Platform Security Manual guide is currently under active development. Some sections may be incomplete or change without notice.
Questions? Contact RidgeRun or email to support@ridgerun.com.
- Introduction
- General Security Concepts
- Getting Started
- Contact Us
- Sponsor your Favorite Feature
Disk Encryption
This section explains how to evaluate disk encryption on a Toradex Verdin i.MX95 system built with Yocto. The base Linux mechanism is dm-crypt with the LUKS format, managed from userspace with cryptsetup.
The current reference minimal image uses a normal unencrypted boot partition and an ext4 root filesystem. It does not include a complete encrypted-root implementation, an initramfs unlock flow, or an OP-TEE-backed key-release mechanism. The procedure therefore begins with a separate test data partition, which can be validated without making the board unbootable.
Prerequisites
The implementation uses the following components:
| Component | Purpose | Reference |
|---|---|---|
Linux device mapper and dm-crypt
|
Provides block-level encryption in the Linux kernel. | Linux dm-crypt documentation
|
cryptsetup
|
Creates LUKS metadata and opens or closes encrypted mappings. | cryptsetup project |
| initramfs | Required when the root filesystem itself is encrypted, because it must be unlocked before the real root filesystem is mounted. | Linux initramfs documentation |
| OP-TEE and trusted keys | Optional key-protection mechanisms for designs that should not expose raw disk keys to normal-world userspace. | NXP imx-optee-os and OP-TEE client |
The following checks must be run on the board, from its Linux shell or through SSH after the image has booted. They do not check the host or the Yocto build environment:
command -v cryptsetup command -v systemd-cryptsetup grep -E 'dm_crypt|dm-crypt' /proc/modules /proc/config.gz 2>/dev/null
Expected output includes paths such as /usr/sbin/cryptsetup and, when available, /usr/lib/systemd/systemd-cryptsetup. The kernel check should show dm_crypt when the module is loaded or a matching kernel configuration entry when /proc/config.gz is enabled. A missing command returns no path and a non-zero status.
If cryptsetup is not present, it must be added to the image on the host before rebuilding. Add the package to the image configuration or recipe, for example:
IMAGE_INSTALL:append = " cryptsetup"
The exact package name and any initramfs integration package depend on the selected BSP. After rebuilding, the image must be installed on the board and the checks above must be repeated. Adding a host package alone does not add cryptsetup to the target image.
Choose the Encryption Scope
The product should select one of these scopes before changing the image:
| Scope | Boot behavior | Recommended starting point |
|---|---|---|
| Encrypted data partition | Linux boots normally, then unlocks the data partition. | Recommended first validation because it does not change the rootfs boot path. |
| Encrypted root filesystem | The initramfs unlocks the rootfs before Linux switches to the real root. | Use only after the data-partition flow works and the recovery image is available. |
| File or application encryption | Only selected files are protected. | Use when full block-device encryption is not required. |
Disk encryption protects data at rest. It does not authenticate the kernel, device tree, initramfs, or unlock logic. The boot chain must remain protected by Secure Boot.
Validate an Encrypted Data Partition
This test demonstrates the basic LUKS and dm-crypt flow on a separate test partition. It is not a production key-management design.
Identify the test device
The board should be booted normally first. The developer should list storage devices and filesystems:
lsblk -o NAME,SIZE,TYPE,FSTYPE,PARTLABEL,MOUNTPOINTS,UUID findmnt
The test device should be an unused partition, for example /dev/mmcblk0p3. The correct path depends on the board storage layout and must be confirmed from the command output.
Create the LUKS container
Replace /dev/mmcblk0p3 only after confirming that it is the disposable test partition:
TEST_DEVICE=/dev/mmcblk0p3
sudo cryptsetup luksFormat "${TEST_DEVICE}"
sudo cryptsetup luksDump "${TEST_DEVICE}"
luksFormat initializes the partition and destroys its previous contents. The developer should record the LUKS version, cipher settings, and UUID printed by cryptsetup luksDump.
Open and format the encrypted mapping
sudo cryptsetup open "${TEST_DEVICE}" encrypted-data
ls -l /dev/mapper/encrypted-data
sudo mkfs.ext4 /dev/mapper/encrypted-data
sudo mkdir -p /mnt/encrypted-data
sudo mount /dev/mapper/encrypted-data /mnt/encrypted-data
echo "i.MX95 encrypted-data test" | sudo tee /mnt/encrypted-data/verification.txt
sync
cat /mnt/encrypted-data/verification.txt
The decrypted mapping should appear under /dev/mapper and the test file should be readable while the mapping is open.
Close and verify the mapping
sudo umount /mnt/encrypted-data
sudo cryptsetup close encrypted-data
test ! -e /dev/mapper/encrypted-data
sudo cryptsetup open "${TEST_DEVICE}" encrypted-data
sudo mount /dev/mapper/encrypted-data /mnt/encrypted-data
cat /mnt/encrypted-data/verification.txt
The data should be available again after entering the correct passphrase. The mapping should then be closed after the test:
sudo umount /mnt/encrypted-data sudo cryptsetup close encrypted-data
Test failure behavior
The developer should test a wrong passphrase and confirm that the mapping is not opened:
sudo cryptsetup open "${TEST_DEVICE}" encrypted-data
The command should fail with an invalid passphrase. The encrypted contents must not be mounted without the correct key.
Integrate the Data Partition into Yocto
After the manual test works, the image configuration can be updated to include the userspace tools needed by the product:
IMAGE_INSTALL:append = " cryptsetup"
The exact package name should be confirmed with BitBake for the selected BSP. The developer can inspect available recipes and packages with:
bitbake-layers show-recipes cryptsetup bitbake -e <image-target> | grep '^IMAGE_INSTALL='
The image should then be rebuilt and installed through the normal validated process. A systemd-based design may use a /etc/crypttab entry and a matching mount unit; another init system may use an equivalent service or script. In this context, the unlock secret is the passphrase or raw encryption key that allows cryptsetup to open the encrypted device. It must not be placed in the image, local.conf, or committed to the Yocto metadata. A development passphrase should be entered at test time; an unattended product requires a separately designed protected key-release mechanism.
Integrate Encrypted Rootfs
Root filesystem encryption changes the early boot path. The boot partition remains readable so that the bootloader can load the kernel, device tree, and initramfs, while the rootfs partition is stored as a LUKS container.
The required flow is:
- Yocto builds the kernel, device tree, and initramfs.
- Secure Boot protects the boot artifacts, including the initramfs.
- The kernel starts the initramfs.
- The initramfs loads device-mapper and cryptographic support.
- The initramfs obtains the unlock secret.
cryptsetupopens the encrypted rootfs mapping.- The initramfs mounts the mapping as the real root filesystem.
The image must include the kernel support, cryptsetup, initramfs hooks or an equivalent unlock program, and the required storage drivers. The kernel command line must identify the encrypted root device and mapping rather than pointing directly to the unencrypted partition.
The current image uses a direct root partition reference similar to:
root=PARTUUID=<root-partition-uuid> ro rootwait
An encrypted-root design must replace this with the command-line parameters required by the selected initramfs and cryptsetup integration. The exact parameters depend on the initramfs implementation and must be validated on the selected BSP.
Select the Key-Unlock Method
The procedure in this wiki uses a manual passphrase for development validation. The passphrase is entered when cryptsetup opens the test volume and is not stored in the Yocto image.
This method is suitable for an interactive development test, but it is not suitable for an unattended product. An unattended product requires a separately designed protected key-release mechanism, such as OP-TEE or another hardware-backed service. Those mechanisms are not implemented or validated by the current reference image and are therefore outside this procedure.
Validation
The data-partition validation is successful when:
- the encrypted partition cannot be mounted without the correct key;
cryptsetup luksDumpreports the expected LUKS metadata;- the mapping appears only after a successful
cryptsetup open; - data remains available after closing and reopening the mapping;
- a wrong passphrase does not open the mapping; and
- Secure Boot still authenticates the kernel, device tree, and any initramfs used by the image.
The encrypted-root validation additionally requires successful boot after unlock, successful recovery with the approved image, and failure testing for a missing key, wrong key, modified initramfs, and modified unlock configuration.