Hardening and Secure Boot¶

This flow covers generating the cryptographic keys required for a secured ToloMEO build, making them available to the build environment, and producing a production image with secure boot and system hardening enabled.

Involves: Edge Security, Edge, Embedded Manager

Chain of trust¶

Secure boot establishes a chain of trust from the moment power is applied to the device until the operating system is running. Each stage verifies the next using a cryptographic signature before handing over execution. If any signature check fails the device halts rather than running untrusted code.

flowchart LR
    ROM["BootROM\n(hardware, read-only)"]
    UB["U-Boot\nbootloader"]
    FIT["FIT image\n(kernel + DTB)"]
    OS["Linux kernel"]

    ROM -->|"verifies signature\n(NXP HAB / SRK fuses)"| UB
    UB -->|"verifies FIT signature\n(RSA key embedded in U-Boot)"| FIT
    FIT --> OS

On NXP i.MX hardware the BootROM uses the Hardware Authentication Block (HAB) and a Secure Root Key (SRK) hash burned into one-time-programmable fuses to authenticate the bootloader. U-Boot then verifies the FIT image containing the Linux kernel and device tree using an RSA public key embedded in the bootloader at build time. A device whose fuses have been programmed will refuse to boot any image not signed with the corresponding private key.

SWUpdate adds a parallel verification path for over-the-air updates: every .swu package is signed at build time and the on-device SWUpdate client rejects any package whose signature does not match the public key embedded in the running image.

Step 1 - Generate cryptographic keys¶

Two independent RSA key pairs are required before a secured build can be produced.

The first pair is used for FIT image signing: the private key signs the kernel and device tree at build time, and the corresponding public key is embedded into the U-Boot binary so the bootloader can authenticate the FIT image before passing control to the kernel.

The second pair is used for SWUpdate package signing: the private key signs every .swu update package produced by the build system, and the public key is embedded in the root filesystem so the on-device SWUpdate client can reject any package that was not signed with the matching key.

Both key pairs are generated with standard OpenSSL tooling. The exact commands, recommended file permissions, and the naming conventions expected by the build system are covered in the meta-tolomeo SWUpdate package generation guide.

A few practices are worth keeping in mind regardless of tooling:

• Never commit private keys or passphrase files to version control.
• Keep encrypted offline backups. Losing a private key means losing the ability to produce valid update packages or to build images that boot on fused production devices.
• Updating public keys on already-deployed devices requires a signed update that replaces the embedded key, so plan key rotation before devices are in the field.

Step 2 - Make keys available to the build¶

The build system locates signing keys through a pair of kas configuration variables that point to the directory containing the key files and define the base name used to derive each individual file path. For a local build this means placing the generated keys in the expected directory before invoking kas. The exact variable names and default paths are documented in the meta-tolomeo SWUpdate package generation guide.

Via Embedded Manager¶

When builds run inside Embedded Manager, private keys cannot be stored in the repository. Embedded Manager provides a secure mechanism for injecting signing material into the build environment without exposing keys in source control. Once keys are configured there, builds triggered from the platform produce fully signed images without any local key setup.

Step 3 - Build the production image¶

The tolomeo-prod distribution has the secure-boot DISTRO_FEATURE enabled by default. When a build runs with that feature active, the meta-tolomeo layer automatically:

• Configures U-Boot to verify the FIT image signature before booting the kernel
• Signs the FIT image with the keys found in UBOOT_SIGN_KEYDIR
• Embeds the FIT signing public key into the U-Boot binary
• Configures SWUpdate to require signature verification on every update package
• Embeds the SWUpdate public key into the root filesystem

Build the production image following the BSP and Application Development flow, selecting tolomeo-prod as the distribution target. No additional configuration is required beyond having the keys in place.

For NXP i.MX hardware the bootloader signing step additionally uses NXP CST to produce HAB-authenticated boot images. The SIG_TOOL_PATH kas variable must point to a directory containing the NXP CST binary and the SRK key material. That directory structure and the one-time fuse programming procedure are described in the meta-tolomeo architecture overview.

System hardening¶

Beyond secure boot, tolomeo-prod ships with a hardened system configuration. The following are enabled automatically when building with that distribution.

Filesystem and runtime¶

• Read-only root filesystem: the root partition is mounted read-only at runtime. Application state lives in declared overlayfs mounts so the base image is never modified in the field.
• A/B partitioning: SWUpdate writes updates to the inactive partition. The device only switches to the new partition after a successful boot, providing automatic rollback on failure. See OTA Release for how updates are delivered and monitored.

Kernel and network¶

• Kernel hardening sysctl: BPF JIT hardening, unprivileged BPF disabled, strict ptrace scope, protected symlinks and hardlinks, and reverse path filtering are applied at boot via sysctl-hardening.conf.
• IMA/EVM integrity checking: the integrity measurement architecture verifies file integrity at runtime against reference hashes stored in extended attributes.
• nftables firewall: the security package group includes nftables for network filtering.

Audit and access control¶

• Linux audit framework: system call auditing is enabled and the auditd daemon runs in production images.
• PAM with wheel group: pam-plugin-wheel restricts su to members of the wheel group.
• Optional root lockout: setting DISABLE_ROOT=1 in your image configuration locks the root account, leaving only the admin account as the privileged entry point.

Tooling¶

• Lynis: the Lynis security scanner is included in production test images and can be run manually to produce a hardening score and audit report for the running system.
• Kernel hardening checker: kconfig-hardened-check also included only in included in production test images verifies that kernel configuration options match expected hardening recommendations.