Rambutan

Contents

1. Introduction

Rambutan is the program that runs between the firmware and the Linux kernel on a Fruit Basket appliance. At about eleven kilobytes it is small enough to read in full. It makes every byte that executes before userspace verifiable against keys the operator controls, and denies boot-time input any ability to change what boots or how.

An earlier design kept this policy in the kernel's build configuration, relying on EFI-stub behaviour and a set of CONFIG_* symbols: a fixed kernel command line, refusal of an attacker-supplied initramfs, and delivery of per-build parameters. This coupled the appliance's boot security to kernel symbol names and EFI-stub source, both of which change across kernel versions and architectures. Across seven rebuilds it produced five version-specific boot-critical bugs that the build's test suite did not detect, so boot policy moved into code the operator writes and freezes.

The kernel is therefore ordinary: a plain bzImage with no command-line-override or embedded-initramfs configuration, identical to the legacy-BIOS build's. The policy that used to live in Kconfig is now a few hundred lines of Rust that hand the kernel its command line and its initramfs, both verified first. The loader binds only to contracts frozen by specification: the UEFI protocol ABIs, the Linux boot ABI for passing a command line and an initramfs, and the stable Rust UEFI target. None of these move with a kernel bump, so the bug class that drove the rewrite is closed by construction.

Hand-rolling rather than adopting an existing UEFI Rust framework follows from the same constraint. A loader bound only to frozen ABIs needs no churning dependency in the un-appraised boot window, and a general-purpose framework would pull its release cadence and transitive crates into the one surface that must stay fixed. Rambutan's entire dependency tree is core plus the RustCrypto sha2 stack, the latter used for one operation: hashing the initramfs.

2. Threat model and scope

Secure Boot is the foundation of rambutan's boot design rather than a feature added to a generic boot path: with the operator's own keys enrolled on owned hardware, every pre-kernel byte is verified by a chain the operator roots — no shim, no Microsoft signature, no Machine Owner Key shimming, no GRUB. The loader makes that chain complete and gives boot-time input no point of entry.

2.1 Boot-input injection surface

A UEFI boot manager passes a launched program its LoadOptions — an attacker-influenceable field in a boot-menu entry's optional data. The Linux kernel's EFI stub will, by default, read a command line from there and will honour an initrd= token pointing at an attacker-chosen file. NVRAM boot entries, the ESP's filesystem metadata, and the firmware's variable store are all surfaces a physical or firmware-level adversary can perturb. The loader treats all of them as selection metadata, never as trusted content: it never reads its own LoadOptions, it sets the kernel's command line to a constant it carries internally, and it provides the initramfs itself rather than letting the kernel fetch one named on a command line.

2.2 Install-time trusted window

On a rented virtual machine the install step is a structural concession: code runs to write the disk before anything has verified it, under a provider hypervisor beneath the guest. Secure Boot on owned hardware shrinks that concession from "trust the provider's entire stack" to "trust a board vendor's firmware and the operator's own physical custody," a smaller and operator-inspectable floor. The loader is therefore tied to a sovereign substrate, though not because enrolment is impossible elsewhere: some rented platforms (AWS Nitro, Azure Trusted Launch) allow an operator to enrol their own PK/KEK/db, but the firmware that enforces those keys and the hypervisor beneath it stay the provider's, so the enforcement root is rented even when the signing keys are the operator's. Secure Boot there hardens the guest's boot against in-guest tampering without making the substrate sovereign.

2.3 Guarantees and limits

Against a remote attacker the verified chain is complete: there is no pre-kernel byte the attacker can substitute. Against an attacker with physical control of the firmware's variable store, Secure Boot yields cost and evidence rather than prevention: such an attacker can clear the keys, enrol their own, and re-sign a tampered chain that boots looking normal. The mitigation there is procedural (custody, tamper evidence), and the detector is the enrolled-key set itself (§7.3). The structural close for that adversary is measured boot bound to a TPM, documented here as a named future addition, not as a present capability.

3. Verified boot

Three pieces of content are executed or consumed before userspace: the loader, the kernel, and the initramfs. Each is integrity-checked exactly once, and a failure at any link halts the boot rather than degrading it.

 PLATFORM FIRMWARE             RAMBUTAN LOADER              LINUX KERNEL
 PK / KEK / db enrolled        ~11 KB, db-signed PE         plain bzImage, db-signed
 ──────────────────────        ──────────────────────       ──────────────────────────
 1 verify the loader ─────────▶starts (db-trusted)
                            │
                            ├─ read \vmlinuz + \initrd
                            ├─ 2 digest-check \initrd
                            │
 3 re-verify the    <───────┤  LoadImage(\vmlinuz)
   kernel buffer vs db      │
   (EFI_SUCCESS only)       │
                            │
                            ├─ set the baked cmdline    ─▶  receives the fixed cmdline
                            ├─ serve \initrd (LoadFile2)─▶  pulls the verified initramfs
                            │
                            ▼
                               StartImage               ─▶  /init → dm-verity → IMA

A failed check (2, 3, or the loader's SB_REQUIRED gate) halts the boot — nothing downstream runs.

Figure 1. The verified boot chain — which party verifies each of the three executed-or-consumed artifacts, and where any failure halts.

Table 1. The three content checks — what verifies the loader, the kernel, and the initramfs, each exactly once, and the failure behaviour of each.

Selection metadata — the GPT, the ESP's FAT directory, NVRAM boot variables — is deliberately not in this table. A tamper there can only mis-select a target whose content is then caught by one of the three checks above (a redirected initramfs fails the digest; a swapped kernel fails LoadImage; a corrupt rootfs partition fails dm-verity downstream). Integrity is asserted over content; selection is covered by fail-closed rejection of whatever it selects.

4. Loader contract

The loader is a single straight-line program with no event loop and no runtime configuration. Its behaviour is fixed by three constants baked in at build time and by an exhaustively enumerated control flow.

4.1 Baked constants

Table 2. The loader's three build-time constants — the entirety of its configuration surface.

4.2 Control flow

1. Locate own image. Resolve the loader's own EFI_LOADED_IMAGE_PROTOCOL to obtain the device handle it was loaded from — its ESP. The loader's own incoming LoadOptions are never read; the runtime input surface is zero.
2. Secure Boot gate. If SB_REQUIRED, read the firmware's SecureBoot variable and proceed only on EFI_SUCCESS with a value of exactly 0x01. Absent, off, or an error halts — fail-closed.
3. Read inputs from its own ESP only. Open the loader's own filesystem and read \vmlinuz and \initrd. No other volume and no other path is consulted.
4. Initramfs digest gate. SHA-256 the initramfs buffer and compare it to INITRD_SHA256. A mismatch halts before the kernel is ever loaded.
5. Load the kernel, re-verified. Call LoadImage with boot-policy false, the real \vmlinuz media device path, and the in-memory buffer. The platform re-hashes the buffer against db (§5.1). The status must be EFI_SUCCESS; both EFI_SECURITY_VIOLATION and EFI_ACCESS_DENIED are fatal — the loader never calls StartImage on an image the platform flagged.
6. Set the command line. On the kernel's loaded-image protocol, set LoadOptions to KERNEL_CMDLINE as a null-terminated UCS-2 string, with the size field including the terminator.
7. Serve the initramfs. Install, on a fresh handle, a vendor-media device path bearing the LINUX_EFI_INITRD_MEDIA_GUID together with an EFI_LOAD_FILE2_PROTOCOL that serves exactly the verified initramfs buffer. The kernel's stub locates this handle and pulls the initramfs from it.
8. Start. StartImage on the verified kernel.

4.3 Protocol surface

The loader's bindings to the firmware are a deliberate whitelist: the boot- and runtime-services entries it calls (HandleProtocol, LoadImage, StartImage, InstallProtocolInterface, AllocatePool, GetVariable), the file and filesystem protocols, the device-path protocol, and the load-file-2 protocol. Each underlying structure is a hand-written layout matched field-by-field against the UEFI 2.10 specification, because a single wrong function-pointer offset would be a silent miscall the compiler cannot catch. The structures are frozen contracts; nothing outside the whitelist is reachable.

5. Cryptographic mechanics

5.1 Kernel re-verification via LoadImage

The loader does not verify the kernel itself, and must not try to. When it calls LoadImage with an in-memory source buffer, the platform's image-verification path hashes that buffer and checks it against db/dbx — for a memory load, not only for a load from a file. A kernel signed by a key absent from db, unsigned, or signed by a revoked key yields EFI_SECURITY_VIOLATION or EFI_ACCESS_DENIED, and the loader's EFI_SUCCESS-only check turns that into a halt. The loader therefore inherits the firmware's signature verification for the kernel instead of re-implementing it, which is smaller and harder to get subtly wrong. This behaviour was confirmed against the reference EDK2 implementation and is the subject of two negative boot tests: an unsigned kernel and a wrong-key-signed kernel, both halted.

5.2 Secure Boot key family

Secure Boot's trust is rooted in three operator-generated keys whose X.509 relationships mirror the firmware's own variable-update authority hierarchy:

RSA-3072 / SHA-256, generated by the operator off-box:

   PK   recipes-sb-pk      self-signed root        CA:TRUE
    │
    └─ signs ─▶  KEK   recipes-sb-kek      PK-signed     CA:TRUE
                  │
                  └─ signs ─▶  db   recipes-sb-db    image-signing leaf
                                    digitalSignature + code-signing EKU

Each certificate is enrolled into its matching firmware variable (PK / KEK / db).
The firmware verifies the loader against db; the loader's LoadImage re-verifies the
kernel against db.

Figure 2. The Secure Boot key family — the PK → KEK → db certificate chain, how each certificate is enrolled into a firmware variable, and which key verifies the loader and the kernel.

• Algorithm. RSA-3072 with SHA-256 is the primary choice, by firmware convention: real UEFI implementations universally exercise RSA Authenticode for db, whereas elliptic-curve support is uneven. RSA-2048 is a documented downgrade for firmware that rejects 3072, gated on a demonstrated test-boot failure rather than chosen silently. This family is deliberately separate from the appliance's ed25519 artifact-signing keys and its ECDSA integrity-measurement leaves.
• Chain shape. PK is self-signed with certificate-signing rights; KEK is signed by PK; db is a leaf signed by KEK carrying digitalSignature and the conventional code-signing extended-key-usage. The extended-key-usage is informational: EDK2 image verification matches the signing certificate or its hash in db and does not gate on the usage bits. But the shape documents intent and matches the variable-update hierarchy the specification expects.
• Validity is not a control. Certificate lifetimes are set far in the future and the design does not rely on expiry. EDK2 image verification does not enforce certificate time-validity (verified at source); revocation is the dbx mechanism, and rotation is by re-enrolment (both detailed as lifecycle procedures in §7.4). Treating expiry as a control would invite a surprise lockout with no security benefit.

5.3 Signing the boot PEs and reproducibility

The loader and the kernel are Authenticode-signed with the db key using sbsign inside the pinned build container, and the signed images are spliced into the ESP. Signing is not byte-deterministic, which matters for the reproducibility argument: sbsign embeds a wall-clock signingTime authenticated attribute, so signing the same input twice yields different bytes. The reproducibility property the appliance relies on is instead Authenticode-digest equivalence: the wall-clock timestamp, the certificate table, the PE checksum, and the certificate-table directory entry all live in regions the Authenticode hash excludes by construction. The signed PE's Authenticode-covered bytes therefore reproduce the unsigned, byte-reproducible build exactly, even though the raw bytes are not identical. The build's gate asserts that digest equivalence, not raw byte-identity, because raw byte-identity is unachievable with the standard tool and asserting it would be a false assurance.

5.4 Initramfs digest

The one cryptographic primitive the loader itself computes is SHA-256, via the audited RustCrypto sha2 crate, over the initramfs it has read. The expected value is the INITRD_SHA256 constant compiled into the loader, which is itself in db's signature scope, so the digest is as trustworthy as the loader. Because the initramfs travels as digest-gated content rather than as a PE in db, this is the loader's own gate rather than the firmware's: a one-byte change to the served initramfs produces a mismatch and a halt before the kernel is loaded. It also lets the command line carry no initrd= token: the kernel never names or fetches an initramfs, and the loader hands it one it has already verified.

6. Command line and initramfs delivery

Two long-standing properties of a hardened boot — "the command line is fixed" and "no attacker initramfs" — were previously expressed as kernel-configuration switches. The loader provides both as behaviour, and the kernel is plain.

Table 3. Two hardened-boot properties, compared as kernel configuration (the superseded expression) versus loader behaviour (the current one).

The command line is delivered the way the supported Linux UEFI boot ABI specifies: as the kernel's LoadOptions, a null-terminated UCS-2 string with the size field counting the terminator. The initramfs is delivered the way the same ABI specifies: a handle bearing the well-known LINUX_EFI_INITRD_MEDIA_GUID vendor-media device path and an EFI_LOAD_FILE2_PROTOCOL implementing the two-call contract (a NULL-buffer size query returning EFI_BUFFER_TOO_SMALL and the size, then a copy into the kernel's buffer). The kernel's stub locates that handle by GUID and pulls the initramfs from it; no file path is involved.

7. Key custody and enrolment

7.1 Generation

The PK/KEK/db family is minted by a pure-Rust ceremony (recipes-admin deploy generate-keys --secure-boot): three RSA keypairs from the OS CSPRNG, the X.509 chain assembled in-process, all six files written atomically (all or none) with private keys at mode 0600 and the directory at 0700. The same command writes a committed anchor recording the SHA-256 fingerprints of all three certificates — the operator's enrolment cross-check, in the same posture as the appliance's other pinned-fingerprint files.

7.2 Custody rungs

The buildable-now floor (software) keeps the family in the operator's keys directory; it weakens only the operator's own exposure, never the box's verified chain. The hardware rungs (one-signer, two-signers) route the db key to an air-gapped signer for a round-trip signing operation, so the signing key need never sit on the build host — these are named, fail-closed forward-debt that mirror the appliance's artifact-signer ceremony. Signing of the boot PEs is a container sbsign step regardless of rung; the db key is a bind-mounted input, and no signing tool ever resides on the box.

7.3 Detecting a physical re-key

Against an attacker with physical control of the firmware's variable store, the detector is the enrolled-key set. A naïve check of "is the operator's PK present?" is defeated trivially: setup-mode enrolment requires no proof of key possession, so a re-keying attacker can re-enrol the operator's public PK while substituting their own db (they cannot sign with the operator's db private key). The detector that works is therefore an exact-set comparison — enumerate every enrolled PK, KEK, and db entry and require the set to equal exactly the operator's committed fingerprints. An appended entry is the tamper signature: the attacker's own certificate, or a bare image-hash authorisation, both of which db permits. "My own fingerprints are present" proves nothing, because the attacker leaves them and adds to them. This check is an operator procedure, documented in an enrolment runbook, because the box cannot trust its own firmware variables to self-audit. Its structural replacement is TPM-measured boot, deferred.

7.4 Rotation, revocation, and key recovery

Three lifecycle events follow generation, and each has a definite procedure rather than an assumed one. The appliance's scale — one operator, sovereign hardware, physical custody — makes the simple form of each correct rather than a shortcut, the same way §5.2 treats expiry as deliberately not a control.

Rotation has two paths; the operator chooses by what they still hold. With the operator's PK enrolled and the firmware in User Mode, a key is replaced in place by an authenticated variable update signed by its parent — a new db signed by KEK, a new KEK or PK signed by the current PK. That path is remote-capable and needs the current parent private key. If that key is lost the in-place path is closed, and rotation instead drops the firmware to Setup Mode by a physically-present operator and re-enrols the family. Re-enrolment is the default on purpose: a fleet of one needs no authenticated key distribution, and the ceremony that enrols a board's first PK is the ceremony that rotates it. A rotated db also means re-signing the loader and kernel and redeploying — the boot PEs are signed artifacts, not enrolled variables, so they follow the redeploy path, not the variable-update path.

Revocation is dbx, held for retiring a signature already in the wild. The forbidden-signatures database denies a specific signer certificate or image hash, and it is the right instrument when a signed image must stop verifying on firmware that will keep meeting it — a leaked db key whose past signatures must be retired in place. For one appliance whose every boot image the operator controls, the ordinary answer to a compromised signer is the rotation above: re-key, re-sign, redeploy, which retires the old signer by replacement. It is the exception here, not the routine path; maintaining a growing revocation list would be the wrong default on hardware the operator physically holds.

Key recovery is the operator's: the box escrows no root keys. Their off-host backup is the operator's posture for a root secret, by the same logic that keeps the artifact-signer keys off the appliance. The blast radius of loss is bounded: a lost db key stops new images being signed but boots every deployed box unchanged, and is recovered by the rotation above; a lost PK closes the in-place authenticated update but does not brick the board.

8. Build, size and reproducibility

The loader is compiled for x86_64-unknown-uefi in the pinned build container. Its three constants are injected as a generated source module from build-script environment variables — there is no post-link byte-patching, because patching would break both the reproducibility argument and the signature. The build fails closed if the policy environment is absent: a loader without its policy must not come into existence, so a missing-constant build panics rather than baking a default.

Table 4. Loader size and dependency-closure measures, with a size comparison to common bootloaders.

The dependency closure is held by a build-time tree-lock test: any crate creeping into the boot window — anything pulling std, alloc, or a heavy framework — fails the build, not the boot. Two reproducibility gates run on produced bytes: the unsigned loader builds byte-identically twice over fixed inputs, and the signed PE's Authenticode digest equals the unsigned reproducible build's (§5.3). The one runtime branch in the digest path is RustCrypto's CPU-feature detection choosing a SHA-NI versus a portable code path — a bare CPUID instruction with no operating-system surface, and both paths are the same audited implementation.

9. Verification and assurance

The loader's pure logic is host-tested: the UCS-2 command-line encoding, the SHA-256 gate, the device-path construction, and the fail-closed Secure-Boot decision. Its firmware-facing behaviour is proven on produced bytes under OVMF, the open EDK2 firmware, in a battery of #[ignore]d gates that run the real signed image and assert against the boot console. A gate that is not given its environment panics rather than reporting a false pass.

Table 5. The OVMF produced-bytes gate battery — each boot gate and the property it asserts against the real signed image.

The implementation passed a three-surface, fresh-context code audit that iterated to a strict zero-finding convergence across four rounds: the boot chain and command-line seam, the key custody and signing, and the build and reproducibility. Two of its findings shaped the final design: it caught a reproducibility gate that asserted a false determinism invariant and was never run (now the Authenticode-digest gate of §5.3, running on produced bytes), and it caught that an earlier un-deferring of the firmware build had silently removed a downstream fail-closed assumption in the deployment path (now an explicit, tested guard).

10. Limitations and accepted residuals

The loader's claims are bounded, and the boundaries are stated rather than implied.

• Proven on OVMF, not yet on metal. Every gate above runs under emulated EDK2 firmware. The verified-boot chain is demonstrated; running it on a physical machine additionally requires the two items below.
• The signed-USB installer ceremony is not built. Closing the install-time trusted window on owned hardware needs an installer that boots through this same loader under Secure Boot — a second loader baked with an installer command line plus a signed bootable medium. That is named build-side forward-debt, not a present capability.
• Real-hardware key enrolment is a physical, substrate-gated ceremony, and enrolment alone does not confer sovereignty. Some rented platforms (AWS Nitro, Azure Trusted Launch) do let an operator enrol their own PK/KEK/db, but the firmware that enforces those keys and the hypervisor beneath stay the provider's, so the enforcement root is still rented. An operator-owned root of trust needs owned hardware, where enrolment is additionally a hands-on ceremony performed at the machine.
• Key backup and recovery are the operator's procedure, not the appliance's. The sovereign root keys are not escrowed by the box; their off-host backup is the operator's posture, and recovery from a lost PK is a physical-presence reset to Setup Mode — bounded by the chosen board exposing operator-controlled key clearing (§7.4). A lost db key blocks new signing but not running boxes.
• Vendor firmware and SPI flash sit below the platform key. A firmware implant — supply-chain or physical flash programming — can fake the entire chain, including the SecureBoot variable. Owned hardware shrinks this floor from "provider hypervisor, structurally unauditable" to "board-vendor firmware plus physical custody," smaller but not zero. The mitigations are procedural; vendor-keyed boot-guard anchors bring no operator sovereignty.
• The physical re-key attacker is detected, not prevented. The §7.3 exact-set check raises the cost and leaves a durable operator-checkable trace, but its structural close is deferred: TPM-measured boot, so that a re-keyed chain changes the measurements and seals become unavailable. At-rest confidentiality of the persistence layer is likewise out of this loader's scope.

Appendix — glossary

Table 6. Glossary of terms used in this paper.