quantra-ramfs and zainium-fsverity: how Zainium OS boots and protects its files

Two projects do most of the work before Zainium OS starts its first service. Both are written in Rust, both are open source, and both ran in the tests of this release.

quantra-ramfs

quantra-ramfs is the initramfs of Zainium OS: one static Rust program, with no shell and no busybox, that runs as /init before systemd. In about 6,800 lines it:

• finds the system disk without outside tools (by UUID, label, device or loop image), assembles RAID and LVM, and supports dm-verity;
• unlocks LUKS disks with a TPM2, a key file or a passphrase, and records every boot step in the TPM2 when there is one;
• loads the display driver from the disk and starts the boot splash;
• applies a waiting base upgrade before anything uses the base;
• seals the system files with fs-verity;
• builds the system view and starts systemd.

Safe upgrades

An upgrade staged by zex syshub --u is applied by quantra-ramfs at the next boot, with a journal. Before a file is replaced, the old one is kept; the journal is written to disk before every step, and the whole filesystem is synced before the upgrade is marked done. If anything fails, quantra-ramfs undoes the upgrade. If even that fails, the boot stops — the system never starts on a half-applied base.

The update list is checked too: every file against its SHA-256 sum, no path may lead outside the base (no .., no symlinked directory on the way), and no entry may appear twice. Tests cover applying and rolling back, a power cut after every journal step (with the recovery run twice), a wrong checksum, a symlink that points outside, and broken update lists.

The system view

quantra-ramfs mounts:

• /overlayer/syshub — the base with your installed software on top — read-only and sealed: root cannot write to it or remount it writable, while software zex installs appears at once;
• /overlayer/syshub/etc and /overlayer/syshub/var as writable layers, so your changes are kept in zexlib/union;
• /overlayer/zaisys, the boot files, as a separate read-only mount that root cannot make writable.

If it cannot build this view, it stops in a rescue shell instead of starting an unprotected system. Afterwards it detaches the raw disk, so nothing in the running system can reach it.

zainium-fsverity

fs-verity is a Linux kernel feature: once it is turned on for a file, the kernel checks every block read from it against a hash tree, and refuses any change to its content — as root too, and even when the disk is mounted by another system.

zainium-fsverity (on crates.io) is our pure-Rust fs-verity library and command-line tool. It is a fork of fs-verity-rs by Ronald Volgers, with fixes that matter on Zainium OS:

• the ioctl numbers work on musl and on 32-bit systems;
• the argument passed to the kernel has the size the kernel expects (128 bytes, it was 136);
• salted digests are computed the way the kernel computes them;
• it passes the kernel's own test vectors.

It computes fs-verity digests, turns fs-verity on, and reads the state and digest back:

fs-verity status /overlayer/syshub/bin/zex
fs-verity digest /overlayer/syshub/bin/zex

How they work together

At every boot quantra-ramfs uses zainium-fsverity to make sure every file of the base and the boot files is sealed, sealing any that are not — on all CPUs at once. On the first boot this takes a moment ("Securing the system…"). After that, quantra-ramfs keeps a fingerprint of each tree's directories; if no file was added, removed or renamed since the last check, it skips the per-file check, so a normal boot does not wait for it. Your installed software can be sealed the same way when you choose: elevate zex verity --union on.

In the tests of this release, 36,876 of 36,876 files in the system view were sealed, and opening one of them for writing failed for root. See the security report.

What comes next

• Signed fs-verity: checking each file against a signed digest from the package build, not only that fs-verity is on.
• Signed update lists, checked in quantra-ramfs with the distribution key.
• Secure Boot with our own key, with the kernel and initramfs pinned by hash in the boot loader.