FIDO2-first immutable OS - YubiKey is the root of trust
No TPM. No OEM. No trust anchors you don't control.
yubiOS is an immutable, bootc-delivered Linux OS that treats the owner's YubiKey as the user-facing root of trust. It combines:
| Layer | Inspiration | What it gives us |
|---|---|---|
| particleos ethos | systemd/particleos | Immutable /usr, UKIs, dm-verity, composefs, systemd-boot |
| bootc design | bootc-dev/bootc | OCI image as OS delivery unit, day-2 upgrades via registry pull |
| systemd image model | Fitting Everything Together | DPS partitions, systemd-repart first boot, A/B sysupdate, systemd-homed |
| YubiKey root of trust | FIDO2 / PIV / OATH | Owner-held trust for signing, unlock, SSH, PAM, and app 2FA |
ARM64 is the primary target platform because it is where yubiOS can own the firmware stack below the UKI through TF-A, OP-TEE, fTPM, and U-Boot. x86-64 remains fully supported above the UKI, but its firmware and optional TPM are platform/OEM trust anchors.
YubiKey 5
- PIV slot 9c via CCID: Secure Boot / UKI signing with systemd-sbsign + PKCS#11
- FIDO2 hmac-secret via hidraw: LUKS2 root and systemd-homed unlock
- FIDO2 ed25519-sk via hidraw: SSH resident keys
- FIDO2 U2F via hidraw: sudo/login with pam-u2f
- OATH via hidraw: application 2FA
Secure Boot signing uses PIV/CCID, not hidraw. Full rationale: ADR-002.
yubiOS ships as a multi-arch bootc OCI image on Docker Hub:
docker pull 0mniteck/yubios:latestFor reproducible installs, pin the image by the digest produced by the latest green yubiOS-ci.yml publish for the intended release. Do not treat a run-specific digest in an old PR or research note as evergreen.
Install or upgrade with bootc:
sudo bootc install to-disk --source-imgref docker://0mniteck/yubios:latest /dev/nvme0n1
sudo bootc switch 0mniteck/yubios:latest
sudo bootc upgrade| Registry | docker.io/0mniteck/yubios |
| Production tags | latest plus immutable commit tags |
| Test tags | dev, dev-<sha> for swu2f TEST-only images |
| Artifact tags | installer, firmware and per-commit variants |
| Platforms | linux/amd64, linux/arm64 |
| Supply chain | SLSA build provenance + SBOM attestations |
docker buildx build --policy reset=true,strict=true,filename=yubiOS.rego -t yubiOS .
docker run --rm --privileged --pid=host \
-v /dev:/dev -v /var/lib/containers:/var/lib/containers \
yubiOS bootc install to-disk /dev/nvme0n1Every approved base image and GitHub Action SHA lives in PINNED.md. That file is the single source of truth for pins.
On first boot yubiOS-enroll.service runs on tty1 and walks through:
- Secure Boot signing through PIV slot 9c.
- Disk encryption through FIDO2 hmac-secret.
- SSH resident key generation through
ed25519-sk. - sudo/login registration through pam-u2f.
Each step is skippable and independently re-runnable. See ONBOARDING.md.
yubiOS/
├── .github/workflows/ # CI, manifest refresh, publish, VM/e2e, integration lanes
├── assets/ # logo and CI assets
├── mkosi.conf # mkosi build path
├── mkosi.conf.d/ # desktop, minimal, surface, chipsec, and test profiles
├── Containerfile # production bootc image
├── Containerfile.dev # TEST-only swu2f dev image
├── yubiOS.rego # OPA/Rego Build Policy
├── renovate.json # digest-tracking automation
├── refs/ # research notes, planning cycles, per-issue implementation specs
├── tests/ # unit, VM, PKCS#11, and UKI verification tests
├── usr/lib/ # shipped OS overlay: bootc, dracut, PAM, repart, systemd, yubiOS scripts
├── ADR.md # architecture decision records
├── ARCHITECTURE.md # trust chain + build pipeline diagrams
├── SPEC.md # normative project specification
├── MISSION.md # project mission
├── MITIGATE.md # threat model and control mapping
├── FUTURE.md # post-launch ARM64-owned root-of-trust plan
├── ONBOARDING.md # operator enrollment guide
├── PINNED.md # approved refs and digests
├── BLOCKERS.md # dependency and blocker map
└── TODO.md # active planning surface
| Component | Minimum |
|---|---|
| YubiKey firmware | 5.2.3 for ed25519-sk |
| systemd | 261 for current measured-boot gates and v261 research targets |
| OpenSSH | 8.2 for FIDO2 key types |
| pam-u2f | 1.3.1 for CVE-2025-23013 fix |
| Platform | arm64/aarch64 primary; x86-64 secondary but fully supported |
graph TD
BASE["quay.io/fedora/fedora-bootc:45\n@sha256 (pinned base — ADR-015)\ndigest in PINNED.md"]
CF["Containerfile\nrootless docker buildx\n--policy yubiOS.rego\n(supply-chain gate)"]
MKOSI["mkosi --profile yubios\nUKI + dm-verity, signed via\nYubiKey PIV slot 9c (PKCS#11)"]
OCI["multi-arch OCI image\nlinux/amd64 + linux/arm64"]
CI["yubiOS-ci.yml . merge-manifest\nSLSA provenance + SBOM attested"]
REG["docker.io/0mniteck/yubios:latest\n+ immutable :<commit-sha> per build"]
INSTALL["bootc install to-disk\n(bare metal)"]
UPGRADE["bootc switch + upgrade\nday-2 atomic update"]
BCVK["bcvk\nephemeral VM / native-to-disk\n(test loop, USB YubiKey passthrough)"]
ENROLL["first boot\nyubiOS-enroll.service\nYubiKey tap"]
PIV["PIV slot 9c (CCID)\nSecure Boot signing\n(systemd-sbsign / PKCS#11)"]
FIDO["FIDO2 (hidraw)\nLUKS2 disk unlock\nSSH ed25519-sk, pam-u2f"]
HOMED["systemd-homed\nLUKS2 /home\nSLOT 0 FIDO2 unlock\nSLOT 1 recovery key"]
BASE --> CF
BASE --> MKOSI
CF --> OCI
MKOSI --> OCI
OCI --> CI
CI -->|docker push| REG
REG -->|pull| INSTALL
REG -->|pull| UPGRADE
REG -->|pull| BCVK
INSTALL --> ENROLL
ENROLL --> PIV
ENROLL --> FIDO
ENROLL --> HOMED
style REG fill:#ff1493,color:#fff
style ENROLL fill:#ff1493,color:#fff
style PIV fill:#0d6e0d,color:#fff
style FIDO fill:#0d6e0d,color:#fff
style HOMED fill:#0d6e0d,color:#fff
style CI fill:#8b4513,color:#fff
- Latest docs/research planning pass: refs/planning-cycle-2026-07-11.md
- ARM64 zstd EFI zboot / bcvk DirectBoot: refs/zstd-efi-zboot-bcvk.md
- LUKS2 FIDO2 e2e coverage: refs/luks-fido2-e2e-test.md
- ARM64 fTPM Phase F0: refs/arm64-ftpm-phase-f0.md
- systemd v261 base-image history: refs/v261-base-image.md
All decisions are recorded in ADR.md, with source-backed research in refs/.