Levandor

YubiKey LUKS — lockout / recovery

4 min read

Action-first recovery for the YubiKey-gated LUKS FDE on telep-mainframe. Full design + mechanics: 2026-08-15-yubikey-gated-luks-fde.

Recovery access when the LAN is down

  • Mainframe (telep-mainframe): ssh levander@100.115.209.87 (Tailscale, raw IP). But if the disk hasn’t unlocked, the box isn’t on the network at all — the unlock happens in the initramfs, before networking, and there is NO dropbear/remote-unlock. A stuck-at-unlock box needs the physical console.
  • Volumes by UUID (NVMe node names drift — never trust nvmeXn1): root = /dev/nvme1n1p3 UUID a3a8e37d-79fa-484b-bc3f-40c56df95337; cam-archive = /dev/sdb1 UUID 7af64460-….

Symptom → fix

The box powered itself off

Most likely the live-lock fired — the enrolled YubiKey was pulled or jostled out of USB (a udev remove on PRODUCT==1050/407/* runs sync + systemctl poweroff).

  1. Reseat the YubiKey firmly in USB.
  2. Power the box on. It auto-unlocks root via the key and boots unattended (dmesg | grep YK-KEYSCRIPT → root key from YubiKey ok).

If it powered off during a command you ran: you probably ran ykman config … (or something that re-enumerated the key) while the live-lock was armed — that reads as a removal. See Disarm below before retrying.

Stuck at a passphrase prompt on the console (won’t auto-unlock)

The keyscript printed nothing → the YubiKey wasn’t readable in early boot (absent, dead, wrong key, or not enumerated).

  1. Type the passphrase at the physical console (keyslot 0, break-glass — the user knows it). This unlocks and boots.
  2. Once up, check the key: sudo ykman info (needs sudo + pcscd), confirm USB id 1050:0407, slot 2 present (ykman otp info).
  3. Reseat / try another USB port; confirm dmesg sees it. Next boot should auto-unlock.

There is no remote way past this prompt

No dropbear-initramfs is installed. A box stuck at the unlock prompt is only reachable at the physical keyboard. Don’t burn time looking for an SSH path in.

Need to run ykman config / swap or add a key — DISARM first

Any op that re-enumerates the key triggers the live-lock (= poweroff). Disarm, do the work, re-arm:

# disarm
sudo mv /etc/udev/rules.d/99-yk-lock.rules /root/99-yk-lock.rules.disabled
sudo udevadm control --reload-rules
# ... do ykman config / enroll a backup key / swap keys ...
# re-arm
sudo mv /root/99-yk-lock.rules.disabled /etc/udev/rules.d/99-yk-lock.rules
sudo udevadm control --reload-rules

Enroll a backup YubiKey (recommended — currently only ONE key enrolled)

  1. Disarm the live-lock (above).
  2. On the backup key: ykman config usb --enable OTP --force, then ykman otp chalresp --generate --force 2 (no --touch).
  3. Store its challenge (e.g. /etc/ykluks/root.challenge is shared only if the secret is the same — a separately-generated key has a different secret, so it needs its own keyslot derived from the same challenge but producing a different response). Add its keyslot with the existing passphrase at a real terminal: 
    sudo sh -c 'CH=$(cat /etc/ykluks/root.challenge); \
  ykchalresp -2 -x "$CH" | tr -d "\n" > /dev/shm/yk2.key; \
  cryptsetup luksAddKey /dev/nvme1n1p3 /dev/shm/yk2.key; shred -u /dev/shm/yk2.key'
    (The single-challenge-per-volume model means the keyscript tries the same challenge against whichever key is present; each enrolled key contributes its own keyslot.)
  4. Re-arm the live-lock.

LUKS header corrupted / metadata damage

Restore the post-YK header backup from the Mac (mode 600):

# root
cryptsetup luksHeaderRestore /dev/nvme1n1p3 \
  --header-backup-file ~/telep/root-nvme1n1p3-20260815-postyk.img
# cam-archive
cryptsetup luksHeaderRestore /dev/sdb1 \
  --header-backup-file ~/telep/camarchive-sdb1-20260815-postyk.img

Never restore the pre-YK header backup

The earlier pre-YubiKey header backup contained the clevis TPM token — restoring it re-enables TPM auto-unlock and BYPASSES the YubiKey. It was deliberately shredded from both the Mac and the box. Only the *-postyk.img backups are safe.

Verify state

sudo cryptsetup luksDump /dev/nvme1n1p3   # slots 0 (passphrase) + 2 (YubiKey); Tokens empty
clevis luks list -d /dev/nvme1n1p3        # must be EMPTY (no TPM binding)
dmesg | grep YK-KEYSCRIPT                  # after boot: root key from YubiKey ok
ls -l /etc/udev/rules.d/99-yk-lock.rules   # present = live-lock ARMED

Graph View

Backlinks