Build1 publisher3 min readPublished
systemd-cryptenroll hands LUKS2 boot unlock on unattended Linux nodes to a TPM2 chip
systemd-cryptenroll binds LUKS2 volumes to TPM2, FIDO2 and PKCS#11 hardware so unattended Linux nodes can boot with no one typing a passphrase. A safe rollout keeps the old passphrase and an offline recovery key in place until hardware unlock is proven.
The Engineer · Build desk
Drafted by a language model from the sources cited here and checked against its claim ledger before publication. How we use AISend a correction
What happened
- Unlock metadata lives in the LUKS2 header's JSON token area, and systemd-cryptsetup reads it together with /etc/crypttab at boot.
- The tool handles LUKS2 only, so LUKS1 volumes need a cryptsetup convert to LUKS2, after backups, before any enrollment.
- The guide follows man pages covering features through systemd 262, and its device-listing command needs systemd 257 or later.
- With no device named, systemd-cryptenroll targets whatever block device backs /var, and the guide advises naming the device explicitly.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- exposure Under the no-PCR setup, anyone who leaves with the whole machine, TPM included, has a disk that unlocks itself at power-on.
- decision Adding a PCR policy narrows when the TPM will unseal, but it makes drifted TPM state a new way for boot to fail, and the recovery key is the planned way back in.
- constraint A FIDO2 key with the tap requirement on cannot unlock a node nobody visits, which leaves TPM2 as the factor that takes the person out of boot.
Enrollment seals a random unlock key to the TPM and writes the sealed blob, with its policy, into the LUKS2 token header [6]. The LUKS master key is never stored on the token in the clear [6]. At boot the TPM unseals only if it can reproduce that policy, which can include PCR values, a PIN, a signed PCR policy or pcrlock [6].
Each new factor gets its own slot. The recovery-key command prompts for the existing passphrase to authorize the new slot [10]. TPM enrollment with `--tpm2-device=auto` also authenticates with the existing passphrase unless you pass an `--unlock-*` option [17]. The passphrase slot stays where it was. I think this is the right design: a botched TPM enrollment still leaves the slot that booted the machine yesterday.
FIDO2 works differently. The token HMACs a random salt with a secret that never leaves the authenticator, and the HMAC output unlocks the volume [7]. Presence, client PIN and user verification can each be switched on or off [7]. With the tap left on, the node waits for a person at every boot. The guide calls that wait the outage on fleet boxes and on anything expected to come back after power loss [1].
The guide's simplest TPM path for a trusted physical host seals to no PCRs at all [11]. The man page default does exactly that when `--tpm2-pcrs=` is empty or omitted [12]. The volume then unlocks whenever that machine's TPM is present [11]. Someone holding only the stolen disk cannot unlock it. Someone holding the disk and the machine it came from can, and the guide says that is the risk you accept [11]. This setup stops a thief who takes the drive and leaves the computer behind, a thief with unusual priorities. I'd accept that for a rack behind a locked door and not for a box in shared space.
The rollout in the guide runs in this order:
1. Check for the hardware with `systemd-cryptenroll --tpm2-device=list` and `--fido2-device=list` [19]. 2. Enroll a recovery key with `systemd-cryptenroll --recovery-key "$DEV"` and store it offline, away from the machine [10]. 3. Enroll the TPM with `systemd-cryptenroll --tpm2-device=auto "$DEV"` [17]. 4. Confirm the tokens with `cryptsetup luksDump` [18]. 5. Point /etc/crypttab at the token: `rootfs UUID=YOUR-LUKS-UUID none tpm2-device=auto,x-initrd.attach`. Here `none` in the key-file field means the unlock metadata sits in the LUKS header [13]. The `x-initrd.attach` option is recommended for root so devices detach in the right order at shutdown [14]. 6. Only after that, consider wiping passphrase slots, with a second session or a live USB path kept open [15].
The guide gives one warning about step 6: "A bad wipe without recovery is a brick for the volume key." [15]
What to watch
- How PCR-bound TPM2 enrollments hold up across TPM state drift on real fleets, the case the recovery key is meant to cover.
- Which systemd versions fleet distributions actually ship, given the guide tracks features through 262 and device listing needs 257.
- Whether LUKS1-to-LUKS2 conversions on existing installs go cleanly enough to make enrollment practical on older nodes.