Disk Encryption (LUKS)

An encrypted host (LUKS2 volume declared in its disko configuration) protects its data in case of theft or disposal, but asks for a passphrase at every boot. DNF industrializes this point of friction with two guarantees:

• several unlocking methods coexist at all times, so losing one method (forgotten passphrase, misplaced YubiKey) never locks you out;
• the boot prompt is answered remotely, from the administration workstation, with no screen or keyboard attached to the host, and that from the very first boot that follows the installation.

Unlock methods

Each method occupies its own keyslot in the LUKS2 header. All of them are valid at the same time, on every encrypted volume of the host.

Method	Where it lives	Role
Shared passphrase	sops → luks-passphrase	A single one for the whole fleet, it authorizes keyslot management. It is also what formats the disk
Per-host passphrase	sops → luks/<hôte>/passphrase	To hand over to the machine’s user without exposing the fleet
FIDO2 YubiKeys	Derived from the physical key	Touch the key at boot, nothing to type

Why two passphrases and not one

They are not meant for the same people : the shared one is the key of the fleet administrator, the per-host one is handed to the user of a single machine. And because there are two of them, rotating one remains authorized by the other : the synchronization service never finds itself without a way to act on the keyslots, it adds the new slot before killing the old one.

There is no installation passphrase anymore

just install formats the volume with the shared passphrase (nixos-anywhere --disk-encryption-keys) : the formatting keyslot is the shared keyslot. Nothing to remember from the installation, nothing to retype afterwards. The first machine, installed via darkone new, is formatted with the passphrase typed in the wizard : it becomes the shared passphrase of the fleet. A host installed before that switch is detected by just luks <hôte>, which then asks for its installation passphrase one last time to bootstrap the shared slot.

Nothing to declare in the Nix configuration

The darkone.system.luks module is active by default but completely inert as long as the host does not appear in the usr/secrets/luks.json manifest and declares no LUKS volume in its disko. Existing encrypted hosts do not change until just luks <hôte> has been run.

Provisioning a host

just luks <hôte>            # provisionne (ou converge) le chiffrement
just luks <hôte> pre        # moitié hors ligne, sans toucher à la machine
just luks <hôte> passwd     # fait tourner la passphrase par hôte
just luks <hôte> show       # audit : table des keyslots + conformité
just luks <hôte> '' <ip>    # cible une IP explicite (hôte pas encore résolu)

The recipe is idempotent : each run converges and only asks for what is missing. It is called automatically at two moments, and it is rare to have to run it yourself :

Called by	Action	What it does
just install <host>	pre	Before the build, therefore before the installation
just install-here <host>	pre, without a nix account (bootstrap-keys)	First machine, from the ISO
just configure <host>	(default)	After the first boot

Without a LUKS volume in the disko, it is a logged no-op.

The pre phase never touches the machine. It prepares what must exist before the system is built :

1. the shared passphrase in sops if absent (asked only once for the whole fleet) ;
2. the per-host passphrase in sops if absent, generated randomly and without asking anything (see the box below) ;
3. the initrd SSH host key, generated locally and stored in sops (luks/<host>/initrd-key, base64-encoded) ;
4. the registration of the host in the public manifest usr/secrets/luks.json (versioned in the clear, it contains no secret) : it is this entry that activates the module.

Why the per-host passphrase is never asked at installation

It serves to entrust the unlocking of a station to its user without giving them the key to the whole fleet. But at formatting time we still do not know who will use the machine : the answer was always ” empty ”. And an interactive question in the middle of an installation is exactly what breaks a remote installation.

It is therefore drawn randomly and kept in sops alone. The slot keeps its usefulness — it is a second means of opening the volume, and the fallback of just unlock. The day someone really must type a passphrase on this machine, just luks <host> passwd gives them a chosen one, and luks-passphrase-sync swaps the slot at the next apply.

The default phase adds what requires the machine :

5. re-places the initrd key from sops if it is missing on the target (it never regenerates a new one, that would invalidate the one placed by the installation) ;
6. on a gateway, reads the current WAN IP in the manifest (fallback of just unlock, see below), to be re-run if the access provider renumbers ;
7. if no managed passphrase unlocks the volume (host installed before the switch to shared formatting), asks for its installation passphrase one last time and enrolls the shared one with it.

Then commit and deploy :

git add usr/secrets/luks.json
just commit "system(luks): <hôte>"
just apply <hôte>

At deployment, two idempotent services converge the LUKS header at each apply: luks-passphrase-sync (shared and per-host passphrases) and yubikey-luks-enroll (one FIDO2 entry per YubiKey enrolled on the fleet, see Strong authentication).

The initrd key must precede the boot loader

The initrd secrets are embedded at boot loader installation: a key created after the fact is simply not in the initrd that boots. A fresh installation is covered, just install places the key under /mnt before nixos-install. On a machine already in service, it is just luks <host> that places it over SSH : never add a host to luks.json by hand, and never deploy before the key is on the target. When in doubt, just luks <host> show checks it.

Passphrase rotation

• Per host: just luks <host> passwd, then commit and apply. The old keyslot is removed and replaced at the next deployment.
• Shared: modify luks-passphrase via just sops, then apply on the whole fleet — each encrypted host rotates its keyslot along the way.

The synchronization service detects changes thanks to a local registry (/var/lib/luks-passphrase/ledger): a modified sops value enrolls the new passphrase then kills the old slot. Slots absent from the registry (FIDO2, manual enrollments) are never touched.

Unlocking at boot

Every encrypted host follows the same sequence, with nothing to configure:

1. YubiKey — an enrolled, plugged-in key makes its LED blink: touching it opens the volume, nothing to type. With no key plugged in, the step takes ~6 s; with a key nobody touches, ~30 s (firmware limit).
2. Passphrase — a prompt is then displayed, with no time limit. It accepts the per-host passphrase, the shared one, or the installation one.

The prompt in step 2 is one and the same request, served in parallel on the physical console (/dev/tty1) and over ssh on port 2222. Nothing to choose, no window to miss: whoever answers first opens the volume.

How the key is tried

fido2-device= is not written in the crypttab entry but in a separate initrd unit, yubikey-luks-unlock-<volume>, ordered before systemd-cryptsetup@<volume> and only linked to it by a Wants=: it is allowed to fail, and its failure changes nothing at boot.

This separation avoids two flaws that contradict each other:

• the option in the crypttab kills the boot when a key is plugged in and nobody touches it: systemd-cryptsetup exits with an error instead of offering the passphrase, no prompt is displayed — neither on the console nor on port 2222 — and the initrd switches to emergency. A power cut on a host with nobody in front of it was enough to immobilise it;
• without the option, the token is only tried if it is already enumerated. Yet hidraw0 appears about one second after systemd-cryptsetup starts: never in time. The key then stops unlocking anything, silently, and with nothing in the log.

What the option actually brings is the wait for the device (token-timeout=, set to 5 s).

Remotely, the initrd starts a dedicated sshd on port 2222, with its own persistent host key, accessible only with the nix deployment key. just unlock answers it :

just unlock <hôte>     # passphrase read from sops, otherwise asked at the terminal

just unlock waits for port 2222 to appear (one dot per attempt), reads the shared passphrase from sops and pushes it into the initrd, then verifies that the machine really left its initrd before announcing success. If it is refused, it retries with the per-host passphrase. That is what just full-install calls by itself after the first reboot. On an unencrypted host, it is a logged no-op.

Why the shared one first

On the very first boot, the per-host keyslot does not exist yet: disko formats with the shared passphrase, and luks-passphrase-sync only adds the per-host keyslot from the booted system, hence after unlocking. The shared one is the only way in at that moment.

Moreover dnf-unlock only knows it has answered the request, never whether the passphrase was accepted: systemd simply asks again. The only reliable proof is therefore the machine leaving its initrd and answering on port 22, and that is what just unlock observes from the administration workstation.

If no stored passphrase is accepted, or there is no infrastructure key on the workstation : from a terminal, just unlock presents the LUKS prompt via systemd-tty-ask-password-agent. It probes2222 on the explicit IP (ifprovided), the hostname, then the WAN IP recorded in the manifest. In both cases, once the passphrase is accepted, the boot continues and port 22 comes back.

Why two paths

systemd-tty-ask-password-agent only talks to a terminal : no script can drive it. The initrd therefore embeds a small dnf-unlock utility that takes the passphrase on a pipe and answers all pending requests. That is what just unlock calls.

Why the WAN IP?

A zone’s VPN dies with its gateway: when the latter waits for its passphrase, only its WAN leg is reachable. Its initrd moreover replicates the production addressing (static IP on the lan0 bridge, DHCP on the WAN side), since it is itself the DHCP server its initrd would otherwise wait for. The other hosts do a simple DHCP on their wired interfaces.

Laptops over Wi-Fi

No network in the initrd without a cable: an encrypted laptop is unlocked at the console (passphrase or YubiKey), remote unlocking does not apply.

A NIC driver is not always enough

A virtio card does not plug into its PCI slot but into the virtio0 device that its transport creates (virtio_pci, virtio_mmio). Without that module in the initrd, virtio_net is never loaded: no link, no IP, and the sshd on port 2222 listens into the void — the host waits indefinitely for its passphrase, with nothing in the log to say so.

Both transports are now shipped by default, and just luks <hôte> show compares the drivers actually used by the machine’s wired cards with those carried by the built initrd.

Network drivers detected at installation time

nixos-generate-config never puts a network driver in the initrd. A card outside the list shipped by default (Broadcom tg3, for example) therefore leaves the host unreachable in the initrd.

just install and just copy-hw run just detect-hw : it records on the machine the modules of its wired cards and writes them into usr/machines/<hôte>/hardware/detected-hardware.nix, imported automatically. Those modules are only added to the initrd if it has a network (remote unlocking).

On an already installed host, if just luks <hôte> show reports a missing driver : just detect-hw <hôte>, then just apply <hôte>.

Checking a host

just luks <hôte> show writes nothing : it queries the machine and reports. It exits with an error as soon as a check fails, so it can also be used in a script.

just luks <hôte> show

A first block draws up the keyslot table of each volume. Nothing is assumed : every managed passphrase is actually tried against the header, so the “Check” column says what the volume accepts today, not what a registry has remembered.

/dev/disk/by-partlabel/disk-main-luks
  Slot  Content              Source                       Check
  ----  -------------------  ---------------------------  -----------------
  0     Shared passphrase    sops luks-passphrase         opens the volume
  1     Host passphrase      sops luks/poste/passphrase   opens the volume
  2     YubiKey alice/main   systemd-fido2 token          enrolled
  7     Unknown              -                            not managed by DNF
  Slots in use: 4/32

An “Unknown” slot

No managed passphrase opens it and no FIDO2 token claims it. Most often it is an interrupted YubiKey enrollment between the keyslot’s creation and its token being written — typically during an installation, where passphrase convergence restarts the enrollment service. The service now repairs this case on its own at the next just apply: it adopts the keyslot if it belongs to a declared key, deletes it if it is a duplicate. A slot that persists after an apply therefore comes from elsewhere : a manual systemd-cryptenroll, for example — DNF never touches it, since it cannot prove who owns it.

A second block audits the remote unlocking, point by point :

Check	What it catches
Host present in luks.json	The module would stay inert
Initrd key on the target (+ fingerprint)	Next apply without remote unlocking
sops backup with the same fingerprint	A reinstall would lose remote access
initrd sshd enabled in the configuration	nix.pub missing, or host outside the manifest
Boot loader more recent than the key	The trap : key missing from the initrd that boots
Wired-card drivers present in the initrd	No stage-1 networking : nothing answers on 2222
Booted system = audited configuration	A pending apply would make the audit misleading
WAN IP recorded (gateways)	Unreachable in initrd once the VPN is down

Under the hood

Location	Content	Status
usr/secrets/luks.json	Manifest of provisioned hosts + WAN IP of gateways	Public, versioned
secrets.yaml → luks-passphrase	Shared fleet passphrase	Encrypted sops
secrets.yaml → luks/<host>/passphrase	Per-host passphrase	Encrypted sops
secrets.yaml → luks/<host>/initrd-key	Initrd SSH host key (base64)	Encrypted sops
/var/lib/luks-initrd/ (target)	Working copy of the initrd key	Persistent, outside the repo
/var/lib/luks-passphrase/ledger (target)	Registry of managed keyslots (rotation detection)	Persistent, outside the repo

The module exposes two options: darkone.system.luks.enable (default true) and darkone.system.luks.sshPort (default 2222).

Keyslot budget

A LUKS2 header contains at most 32 keyslots. Each enrolled YubiKey consumes one on every encrypted host (fleet policy), on top of the shared and per-host passphrases. The module warns when the projected total approaches the limit.

See also

• Strong authentication (YubiKey): enrollment of physical keys, including the LUKS FIDO2 part
• Secrets management: sops, age keys and rotation
• The Justfile: reference for the luks, enter and configure recipes