RidgeRun Platform Security Manual - NXP i.MX95 Yocto Build Process: Over-the-Air (OTA)
🚧 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
Over-the-Air (OTA)
This section explains how an i.MX95 Yocto platform should be prepared for secure remote software updates. An OTA update must protect the complete update process: the connection to the server, the update package, the boot artifacts, the device recovery path, and the version policy.
The i.MX95 security hardware does not provide a complete OTA application by itself. The device requires an OTA framework and update agent, integrated with the signed Yocto image and the bootloader. The framework has not been selected for the current reference image, so the framework-specific commands must be added after that decision is made.
For systems using Torizon OS, Toradex recommends Torizon Remote Updates, which combines OSTree deployments with Aktualizr/Uptane update authentication. A Yocto product that does not use Torizon can select another framework, but its signing, rollback, and recovery behavior must be validated separately.
Prerequisites
Before integrating an OTA framework, the product should have:
- a signed image that boots successfully;
- a known bootloader and boot-media layout;
- a recovery method that can restore a known-good image;
- a persistent-data partition defined separately from the operating-system image;
- a versioning policy for images and update packages; and
- a signing-key management process for update releases.
Select the OTA Update Model
The framework and storage model should be selected before adding recipes to Yocto.
| Model | Description | Use in this guide |
|---|---|---|
| Complete image update | Installs a complete operating-system image, including the files required by the selected boot flow. | Recommended starting model for the base i.MX95 operating system. |
| A/B update | Keeps an active and an inactive system slot. The inactive slot is updated first and becomes active only after installation succeeds. | Recommended fallback model when the storage budget allows a second system image. |
| In-place or recovery update | Updates the device from a recovery or initramfs environment. | Requires a carefully tested recovery path and has less storage redundancy. |
| Application or container update | Updates applications independently from the base operating system. | Suitable for application-only changes; it does not replace a secure operating-system update design. |
The source notes identify Mender, RAUC, SWUpdate, and OSTree as possible frameworks. One framework must be selected before the Yocto integration is finalized because each one uses different image formats, bootloader variables, signing keys, and rollback behavior.
Combine the Security Layers
OTA security is composed of several controls. Each control protects a different part of the update process:
| Control | What it protects |
|---|---|
| HTTPS/TLS | Protects the connection while the device downloads an update. The device must validate the server certificate and trust chain. |
| OTA metadata signature | Proves that the update metadata and target information came from an authorized release process. |
| Artifact hash | Detects corruption or modification of the downloaded image or bundle. |
| Secure Boot/AHAB | Prevents unauthorized boot containers from executing on an OEM Closed device. |
| FIT verification or equivalent | Protects the kernel, device tree, initramfs, and boot configuration loaded after the AHAB container. |
| Rollback recovery | Restores the previous known-good image after a failed update or power interruption. |
| Antirollback | Rejects older versions when the product’s minimum-version policy is enabled and validated. |
The OTA server must not be the only place where trust is checked. The device must verify the update locally before installation and the boot chain must verify the installed artifacts during the next boot.
Define the Secure Update Flow
The expected update flow is:
- The build system creates a new signed Yocto image or update bundle.
- The release process assigns an image version and records its checksum.
- The update server authenticates the device, when device authentication is enabled.
- The device authenticates the server through TLS and downloads the update package.
- The update agent verifies the package signature and metadata before writing it.
- The agent writes the new image to the inactive slot or approved recovery target.
- The bootloader is configured to try the updated target.
- Secure Boot authenticates the updated boot chain during the next boot.
- The device runs health checks and marks the update successful only after the system is operational.
- If the boot or health check fails, the bootloader returns to the previous known-good target.
TLS protects the communication channel, but it is not a substitute for signing the update package. The device must verify the package even when it was downloaded over HTTPS.
Prepare the Yocto Integration
After selecting a framework, the developer should add its Yocto layer and update agent according to that framework’s documentation. The integration must provide the following functions:
- installation of the update agent in the target image;
- generation of the framework-specific update bundle;
- verification of the bundle before installation;
- configuration of the bootloader’s active and fallback targets;
- preservation of persistent data across updates; and
- reporting of installation, boot, and health-check results.
The exact layer name, image variable, partition layout, bootloader environment, and bundle-generation command depend on the selected framework. Those values should not be copied from another framework without validation.
Sign the OTA Update
The update release should contain at least two related security checks:
- Update-package authentication: the OTA agent verifies that the bundle was created by an authorized release process.
- Boot-chain authentication: after installation, the i.MX95 AHAB and the later verified-boot mechanism authenticate the boot artifacts before execution.
The OTA signing key should be managed separately from the device’s private Secure Boot keys unless the selected product policy explicitly combines them. The device must contain only the public verification material or a protected trust anchor required by the chosen framework. Private release keys must not be included in the Yocto image or OTA bundle.
An application-only update normally does not change the AHAB or FIT signing material. An update containing the kernel, device tree, initramfs, U-Boot, or AHAB boot container must be signed with keys trusted by the deployed device. A Tezi recovery image must follow the same trust policy when it is intended for an OEM Closed device.
Production designs should use separate keys for boot-image signing, OTA metadata signing, debug authorization, and data-encryption provisioning. Compromise of the OTA metadata key should not automatically allow creation of a bootable AHAB container. Key rotation and revocation must be tested on representative closed devices before production use.
Each release should record:
- the image and bundle version;
- the SHA-256 checksum;
- the signing-key identifier;
- the compatible hardware and BSP versions;
- the minimum supported version, if antirollback is enabled; and
- the recovery image or recovery procedure.
Configure the Device Update Behavior
The device should not report an update as successful immediately after writing the inactive target. A successful update requires all of the following:
- The bundle signature and metadata pass verification.
- The inactive target is written without an error.
- The bootloader selects the new target.
- Secure Boot accepts the updated boot artifacts.
- Linux starts and the update agent or health service runs.
- Product health checks pass.
- The bootloader marks the new target as known-good.
If any required check fails, the device should select the previous known-good target. The update agent should report the failure and preserve enough logs to identify whether the failure occurred during download, package verification, installation, Secure Boot, Linux startup, or the health check.
Validate the OTA Flow
Testing should begin with two signed images that are known to boot: a current image and a newer image.
Positive update test
- Install the current signed image and record its version and checksum.
- Confirm that the device reports the current slot or deployment as active.
- Publish the newer signed bundle to the test update server.
- Start the update from the device.
- Confirm that the bundle is downloaded over TLS and passes signature verification.
- Confirm that the inactive target is written.
- Reboot the device.
- Confirm that Secure Boot accepts the new boot chain.
- Confirm that Linux starts and the health checks pass.
- Confirm that the new target is marked active and that persistent data remains available.
To confirm that the device is running the new image, the developer should collect the image identity, boot command line, mounted root device, and boot log from the updated boot:
cat /etc/os-release cat /proc/cmdline findmnt / journalctl -b -n 100 --no-pager
The expected evidence is a release identifier matching the new image, a root mount or boot parameter pointing to the new target, and a boot log showing that the update agent completed its health check. The update agent should also report the new deployment or slot as active and known-good. The exact command for reading that state depends on the selected OTA framework, so its deployment-status command must be added to the product validation procedure. If the release identifier, mounted target, or update-agent result does not match, the update must not be reported as successful.
Invalid-signature test
Create a copy of the update bundle and modify one byte without resigning it. The device must reject the bundle before installation. The active image must remain bootable.
Interrupted-update test
Interrupt power or network connectivity during download and, where the selected framework permits it, during installation. The device must either resume safely or continue booting the previous known-good image. It must not mark a partially written target as successful.
Failed-boot test
Use a test bundle that passes package verification but fails a controlled post-boot health check. The bootloader or update agent must return to the previous known-good target and report the failed update.
Boot-firmware update test
Boot-firmware updates require additional caution because they can affect the AHAB container, U-Boot, TF-A, FIT verification keys, kernel, device trees, or initramfs. The developer should validate the complete signed package on an OEM Closed test device, retain a signed recovery image accepted by the same trust anchor, and test interrupted writes, wrong-key images, signature failures, boot failures, and downgrades before releasing the update.
Downgrade test
Attempt to install an older signed image. The device must reject it when the antirollback policy has committed a higher minimum version. Secure Boot signature validity alone is not sufficient to prove antirollback enforcement.
Evidence to Collect
For each OTA test, the developer should preserve:
- device identifier and hardware revision;
- current and target image versions;
- image and bundle checksums;
- update-server and device authentication result;
- bundle-signature verification result;
- installation and bootloader slot state;
- complete serial boot log;
- AHAB/ELE status when available;
- update-agent logs;
- health-check result; and
- recovery or rollback result.
The evidence must identify the last trusted boot stage reached. For a positive update, the developer should collect the following records:
| Record or command | What it shows | Expected result |
|---|---|---|
/etc/os-release |
The release identity running in Linux. | The version or release identifier matches the target OTA image. |
/proc/cmdline |
The boot parameters selected by the bootloader. | The parameters identify the new boot target, slot, or deployment when the framework exposes it there. |
findmnt / |
The device or partition currently mounted as the root filesystem. | The root filesystem belongs to the new target rather than the previous slot. |
journalctl -b |
Messages from the current boot, including update-agent and health-check activity. | Linux starts without update errors, and the health check completes successfully. |
| OTA framework deployment-status command | The framework's recorded deployment, slot, and target state. | The new deployment is active and marked known-good. The exact command depends on the selected OTA framework. |
These records should be reviewed together with the serial boot log and AHAB/ELE status to identify the last trusted boot stage. A successful download or package verification does not prove that the device booted the updated image successfully.