LUKS Keys, crypttab & Auto-Unlock

Multiple unlock methods and integrating with systemd

The Multi-Slot Unlock Model

LUKS's defining feature for operators is that a single master key can be unlocked by multiple independent credentials. Each key slot holds a copy of the master key encrypted under a different slot key (derived from a passphrase, a keyfile, a TPM-sealed secret, a FIDO2 response, etc.). Any slot's credential opens the device — they are not a chain, they are alternatives.

This is the foundation for realistic unlock policies:

Unlock Methods

Passphrase

The simplest credential: a string typed at a prompt. Goes through the KDF (Argon2id on LUKS2) to derive the slot key. Typically occupies slot 0.

$ cryptsetup luksAddKey /dev/sdX
Enter any existing passphrase: ****
Enter new passphrase for key slot: ****
Verify passphrase: ****
  

Keyfile

A keyfile is just bytes — any file. cryptsetup hashes the content (with the configured KDF) to derive the slot key. The file can be 4 KiB of random data or a sentence in a text file; cryptographic strength depends on the content's entropy.

# Generate a strong keyfile
$ dd if=/dev/urandom of=/root/keys/data.key bs=512 count=8
$ chmod 0400 /root/keys/data.key

# Enroll it to a LUKS slot
$ cryptsetup luksAddKey /dev/sdX /root/keys/data.key
Enter any existing passphrase: ****
  

TPM 2.0 (LUKS2 token)

The systemd-cryptenroll tool seals a random key to the TPM, bound to a set of PCR values (firmware, bootloader, kernel measurements). The sealed blob is stored as a LUKS2 token in the header, referencing a key slot. At boot, systemd asks the TPM to unseal — the TPM only releases the key if the PCRs still match.

# Bind to default PCRs (7 = Secure Boot state, usually)
$ systemd-cryptenroll --tpm2-device=auto /dev/sdX

# Bind to multiple PCRs — firmware (0), bootloader (2), kernel (4), Secure Boot (7)
$ systemd-cryptenroll \
      --tpm2-device=auto \
      --tpm2-pcrs=0+2+4+7 \
      /dev/sdX
  

Details of PCR selection, sealing, and Measured Boot live in Storage 07 — TPM & Secure Boot.

FIDO2 security key

A YubiKey or similar. The unlock requires user presence (touch the key). Useful for portable unlock that doesn't depend on a single TPM.

$ systemd-cryptenroll --fido2-device=auto /dev/sdX
Requested to enroll FIDO2 security token...
Please touch security token: ...
  

Tang / Clevis (Network-Bound Disk Encryption)

NBDE binds unlock to reachability of a trusted network service. Tang is a lightweight HTTP server that holds asymmetric keys; Clevis is the client that talks to Tang. The disk unlocks automatically only when the machine is on a network where Tang is reachable. Remove the network → no unlock → disk stays encrypted at rest.

# Simple single-Tang binding
$ clevis luks bind -d /dev/sdX tang '{"url":"http://tang.example.com"}'

# Shamir Secret Sharing: require 2 of 3 pins
$ clevis luks bind -d /dev/sdX sss '{
      "t": 2,
      "pins": {
        "tang": [
          {"url": "http://tang1.dc.example"},
          {"url": "http://tang2.dc.example"}
        ],
        "tpm2": {"pcr_ids": "7"}
      }
    }'
  

Use cases: servers in a trusted datacenter that should auto-recover from power cycles without operator intervention, but should not be trivially readable if someone steals the disk and takes it home.

systemd-cryptenroll — the unified tool

On modern systems, systemd-cryptenroll is the preferred single entry point for managing LUKS2 tokens. It speaks all the protocols above.

/etc/crypttab Format

One line per encrypted device. Fields separated by whitespace.

target-name  source-device  key-file  options

Common options

A realistic crypttab

# /etc/crypttab
# name          source                  key-file           options
cryptroot       UUID=3e2d6bc8-8d1c...   none               luks,discard,tpm2-device=auto,x-initrd.attach
cryptdata       UUID=def01234-5678...   /root/data.key     luks,discard,nofail
cryptbak        UUID=ghi56789-abcd...   none               luks,headless,nofail,noauto
  

• cryptroot — root disk. Unlocks via TPM2 in initramfs; falls back to passphrase if the TPM refuses (PCR mismatch).
• cryptdata — data disk. Keyfile lives on the encrypted root, so it's only readable after root is unlocked. Chain of trust: passphrase / TPM → root → data keyfile. nofail ensures boot continues if the data disk is missing.
• cryptbak — backup disk. noauto + headless means it's not touched at boot; unlock manually when needed. headless prevents any prompt dialog if run in a non-interactive context.

systemd Integration

At boot, systemd-cryptsetup-generator reads /etc/crypttab and generates a systemd-cryptsetup@<target>.service unit for each entry. These units are wired into the boot ordering so that:

1. LUKS open

   cryptsetup@cryptroot

2. LVM activate

   LVs appear on cryptdevice

3. FS mount

   /etc/fstab entries

4. local-fs.target

   System continues

# See the generated units
$ systemctl list-units 'systemd-cryptsetup*'
UNIT                                 LOAD   ACTIVE SUB     DESCRIPTION
systemd-cryptsetup@cryptroot.service loaded active exited  Cryptography Setup for cryptroot
systemd-cryptsetup@cryptdata.service loaded active exited  Cryptography Setup for cryptdata

# Inspect one
$ systemctl cat systemd-cryptsetup@cryptdata.service
  

Initramfs Unlock (Root Disk)

The root filesystem is encrypted, but the kernel needs something to boot before it can unlock root. That something is the initramfs: a small userspace packed alongside the kernel in /boot, loaded into RAM, run before the real root is mounted.

Headless Remote Unlock

Servers in colocation / remote datacenters with no console need a way to supply the passphrase at boot. Three common approaches:

dropbear-initramfs (SSH in the initramfs)

Embeds a minimal SSH server in the initramfs. On boot, the system acquires an IP (via DHCP) and waits for an SSH connection. The operator SSHes in and types the passphrase (or runs cryptroot-unlock).

# Debian/Ubuntu
$ apt install dropbear-initramfs

# Place your ops key (different from the one on the booted system)
$ echo "ssh-ed25519 AAAAC3Nza... ops@laptop" \
      > /etc/dropbear/initramfs/authorized_keys
$ chmod 0600 /etc/dropbear/initramfs/authorized_keys

# Configure network in initramfs (DHCP by default, or static)
$ echo 'IP=dhcp' >> /etc/initramfs-tools/initramfs.conf

# Rebuild
$ update-initramfs -u -k all

# Later, from the ops laptop
$ ssh -i ~/.ssh/ops_initramfs root@server.example.com
To unlock root partition, and maybe others like swap, run `cryptroot-unlock`
# cryptroot-unlock
Please unlock disk cryptroot: ****
cryptsetup: cryptroot set up successfully

  

tinyssh-initramfs

Smaller alternative to dropbear, Ed25519-only. Same idea, lighter binary footprint.

Tang / Clevis NBDE (auto-unlock)

If the server only needs to auto-unlock when it's on the trusted datacenter network, NBDE removes the need for any human intervention on reboot. Power cycle → boots → reaches Tang → unlocks. If the disk is stolen and taken off-network, it stays encrypted.

Security boundary: you're trusting the network as the policy. An attacker with access to the Tang server, or the ability to connect the stolen disk to the datacenter network, can unlock. Useful in physical-theft threat models, not in insider ones.

Keyfile Best Practices

Recovery Planning Checklist

--allow-discards Details

See dm-crypt & LUKS for the full trade-off discussion. Quick reference:

See Also

• dm-crypt & LUKS — the layer beneath everything on this page.
• Storage 04 — Device Mapper — dm-crypt is a DM target; understanding the DM framework explains how the crypto device appears in /dev/mapper.
• Storage 07 — TPM & Secure Boot — PCR selection, sealing, Measured Boot, and the full story of TPM-based unlock.