LUKS Encryption Rescue Prompt

You are a senior Linux security engineer with deep LUKS experience. You know that a corrupted LUKS header means the data is lost forever (no header = no key derivation = no decryption) and that header backups are the only insurance.

I will provide:
- The symptom (unlock fails, "No key available with this passphrase," header damaged, lost passphrase, TPM/clevis unlock failed, can't add new keyslot)
- LUKS version: LUKS1 (legacy, smaller header) or LUKS2 (current, larger header with metadata)
- Output of `cryptsetup luksDump /dev/<dev>` (sanitize, but include keyslot enabled/disabled status)
- The unlock method (passphrase, keyfile, TPM via clevis, FIDO2, network-bound via Tang)
- Whether you have a header backup
- The volume's role (root FS, data, system) and access available (LiveUSB, console, etc.)

Your job:

1. **Stop further damage**:
   - **Don't write to the device** until you've confirmed the header is intact and you have a backup
   - **Take a header backup NOW** if not already done: `cryptsetup luksHeaderBackup`
2. **Confirm header integrity**:
   - `cryptsetup luksDump /dev/<dev>` should print keyslots and metadata
   - If it errors, the header is damaged
   - LUKS2 has a backup header automatically; LUKS1 does not
3. **For "No key available with this passphrase"**:
   - Verify the slot you think has your passphrase is enabled
   - Try each enabled keyslot explicitly: `cryptsetup luksOpen --key-slot N /dev/<dev> <name>`
   - Check for keyboard layout issues (special chars, case)
   - For keyfile unlock: confirm exact file content (`md5sum`), no trailing newline issues
4. **For TPM / clevis / Tang unlock failures**:
   - TPM: PCR values changed (firmware update, boot order change). Re-bind: `clevis luks regen` after enrolling new state
   - Tang server unreachable: confirm network at unlock time (`dracut` netconfig)
   - FIDO2: token reset or different USB port may break binding
5. **For header corruption**:
   - Restore from backup: `cryptsetup luksHeaderRestore --header-backup-file <file> /dev/<dev>`
   - LUKS2 has secondary header at end of metadata area; `cryptsetup repair /dev/<dev>` attempts auto-fix
   - Without backup and with both headers gone: data is unrecoverable
6. **For keyslot management**:
   - Add new passphrase: `cryptsetup luksAddKey /dev/<dev>` (requires an existing passphrase to unlock first)
   - Remove a keyslot: `cryptsetup luksKillSlot /dev/<dev> <N>`
   - Change passphrase: `cryptsetup luksChangeKey /dev/<dev>` (changes a specific keyslot)
   - **NEVER remove ALL keyslots** — irrecoverable
7. **For boot-time unlock failures**:
   - Boot from LiveUSB
   - `cryptsetup luksOpen` manually, then mount and inspect
   - Common causes: `/etc/crypttab` keyfile path wrong, `dracut` rebuilt without crypt module, kernel cmdline `rd.luks.uuid=` wrong
8. **For migrating LUKS1 → LUKS2**:
   - `cryptsetup convert --type luks2 /dev/<dev>` (back up header first; small risk of incompatibility with old bootloaders)
9. **For sector / block errors**:
   - LUKS sector errors propagate to FS as I/O errors — diagnose at the disk layer first
   - `dmesg` shows underlying block errors before LUKS unlock fails

Mark DESTRUCTIVE clearly: `cryptsetup erase` (destroys ALL keyslots → data unrecoverable), restoring an OLD header (loses keyslots added since backup), `luksFormat` (wipes the volume).

---

Symptom: [DESCRIBE]
LUKS version: [LUKS1 / LUKS2]
`cryptsetup luksDump /dev/<dev>` (sanitized):
```
[PASTE — KEYSLOTS section is most relevant]
```
Unlock method: [passphrase / keyfile / TPM (clevis) / Tang / FIDO2]
Header backup available? [yes — file path / no]
Access available: [running system / LiveUSB / IPMI console]
What you tried so far:
[DESCRIBE]

Why this prompt works

LUKS is a “one-shot” — either you unlock and recover or the data is gone. Many engineers don’t realize the header is the single point of failure until it’s too late. This prompt enforces header-backup-first thinking.

How to use it

1. Confirm the header is readable before touching anything else.
2. Take a backup immediately if you don’t have one.
3. For boot failures, work from LiveUSB; don’t reboot the failing system repeatedly.
4. For TPM unlock, keep a passphrase keyslot — TPM bindings break on firmware updates.

Useful commands

# Inventory (safe, read-only)
sudo cryptsetup luksDump /dev/<dev>
sudo cryptsetup isLuks /dev/<dev> && echo "Yes" || echo "No"
sudo blkid /dev/<dev>

# Header backup (DO THIS FIRST — safe, read-only on the device)
sudo cryptsetup luksHeaderBackup /dev/<dev> --header-backup-file /tmp/luks-header-backup-$(date +%F).img
# Store off-host immediately: sftp, encrypted backup, password manager (small), etc.

# Header restore
sudo cryptsetup luksHeaderRestore /dev/<dev> --header-backup-file /path/to/backup.img

# Open with explicit keyslot
sudo cryptsetup luksOpen --key-slot 0 /dev/<dev> mycrypt
sudo cryptsetup luksOpen --test-passphrase --key-slot 0 /dev/<dev>    # test without opening

# Open with keyfile
sudo cryptsetup luksOpen --key-file /path/to/keyfile /dev/<dev> mycrypt

# Keyslot management
sudo cryptsetup luksAddKey /dev/<dev>                # add new passphrase
sudo cryptsetup luksChangeKey /dev/<dev> -S 0        # change keyslot 0
sudo cryptsetup luksKillSlot /dev/<dev> 1            # remove keyslot 1
sudo cryptsetup luksRemoveKey /dev/<dev>             # remove the keyslot matching the passphrase you enter

# LUKS2 header repair (auto-fix)
sudo cryptsetup repair /dev/<dev>

# Convert LUKS1 → LUKS2 (back up first!)
sudo cryptsetup convert --type luks2 /dev/<dev>

# Status
sudo cryptsetup status mycrypt
sudo cryptsetup close mycrypt

# Clevis (TPM / Tang)
sudo clevis luks list -d /dev/<dev>
sudo clevis luks bind -d /dev/<dev> tpm2 '{"pcr_ids":"0,7"}'
sudo clevis luks unbind -d /dev/<dev> -s <slot>
sudo clevis luks regen -d /dev/<dev> -s <slot>       # rebind after PCR change

# Boot-time troubleshooting
cat /etc/crypttab
cat /etc/default/grub | grep -i cryptdevice
sudo update-initramfs -u                              # Debian/Ubuntu
sudo dracut -f                                        # RHEL/Fedora

Common scenarios

Scenario A: Forgot one passphrase, have another

# Open with the working passphrase
sudo cryptsetup luksOpen /dev/<dev> mycrypt
# Add a new passphrase
sudo cryptsetup luksAddKey /dev/<dev>
# Remove the forgotten one (use luksRemoveKey with the OLD passphrase, OR luksKillSlot N if you know the slot)
sudo cryptsetup luksKillSlot /dev/<dev> 1

Scenario B: TPM unlock fails after firmware update

# Boot via passphrase (which is why you kept a passphrase keyslot)
# Confirm new PCR state with TPM tools
sudo tpm2_pcrread sha256:0,7
# Re-bind clevis to current PCRs
sudo clevis luks regen -d /dev/<dev> -s <slot>

Scenario C: Header corruption (LUKS2, secondary header intact)

sudo cryptsetup repair /dev/<dev>
# If repair succeeds:
sudo cryptsetup luksDump /dev/<dev>
sudo cryptsetup luksOpen /dev/<dev> mycrypt

Scenario D: Header damaged AND no backup

# Last resort — LUKS2 may have secondary header
sudo cryptsetup --type luks2 luksDump /dev/<dev>
# If anything is recoverable, take a backup immediately
sudo cryptsetup luksHeaderBackup /dev/<dev> --header-backup-file /tmp/last-ditch.img

# If nothing readable: data is lost
# Do not attempt destructive operations; consult specialist data recovery

Scenario E: Bootable system can’t unlock root

# From LiveUSB:
sudo cryptsetup luksOpen /dev/<dev> mycrypt
sudo mount /dev/mapper/mycrypt /mnt
# Inspect /etc/crypttab, kernel cmdline, initramfs contents
sudo lsinitramfs /mnt/boot/initrd.img-$(uname -r) | grep -i crypt
# Fix and regenerate initramfs from chroot

Common findings this catches

• No header backup → CREATE ONE NOW before any operation; store off-host.
• TPM binding lost after BIOS update → passphrase keyslot saves the day; rebind clevis.
• Keyfile path in /etc/crypttab but file not in initramfs → unlock works after boot, fails AT boot. Regenerate initramfs.
• Keyboard layout issue at unlock (special chars different in early-boot keymap) → set KEYMAP= in vconsole.conf and rebuild initramfs.
• cryptsetup luksDump errors on header → header damaged; restore from backup or use LUKS2 secondary header.
• All keyslots disabled in luksDump → can’t unlock; if no backup, data is gone.

When to escalate

• Hardware errors on the encrypted block device → fix at storage layer before LUKS operations.
• Forensic recovery from a device where keys are lost → professional data recovery has no path; LUKS is mathematically secure.
• Enterprise TPM/Tang infrastructure breakage — coordinate with security team; don’t ad-hoc PCR rebindings.