TPM-based LUKS decryption with Clevis¶

Clevis is a pluggable framework for automated decryption. When combined with Trusted Platform Module (TPM) and Full Disk Encryption (FDE) via Linux Unified Key Setup (LUKS), Clevis can automatically unlock encrypted drives during boot without user intervention. The Clevis tooling is currently provided via the universe archive. While functional, it serves as a community-supported fallback for TPM-bound encryption until a fully integrated server FDE solution lands in a future LTS release.

This guide targets systems that use dracut(8) as the initramfs generator.

Warning

Keep at least one well-known LUKS passphrase for recovery. TPM measurements can change after firmware updates, Secure Boot state changes, or some bootloader changes, which can prevent automatic unlock until you rebind Clevis.

Prerequisites¶

An Ubuntu Server installation with LVM over LUKS, with Dracut as the initramfs generator
A system with a TPM 2.0 module
Root or sudo privileges

Install Clevis and Dracut integration¶

Install the necessary packages:

$

sudo apt update && sudo apt install clevis clevis-tpm2 clevis-dracut clevis-luks

Binding a LUKS volume¶

Before Dracut can auto-unlock a drive, the drive must be bound to the TPM. You can use Clevis to add a new key to the LUKS header, sealed against the TPM.

First, identify the encrypted partition before binding:

$

lsblk -f

Look for the partition with FSTYPE set to crypto_LUKS, then use that path in the following command as <encrypted_partition>.

Bind against Platform Configuration Register (PCR) 7, which tracks secure boot state. If your environment requires different trust guarantees, choose PCR values that match your threat model.

$

sudo clevis luks bind -d <encrypted_partition> tpm2 '{"pcr_ids": "7"}'

You will be prompted to enter the LUKS passphrase you created during installation. Clevis will generate a new cryptographic secret and store it in a new keyslot. It will also create a corresponding token linked to this new keyslot.

Updating the initial ramdisk¶

The clevis-dracut package provides the necessary Dracut modules to include Clevis decryption hooks in the early boot environment. After binding your root disk, you must regenerate the initial ramdisk.

To force a rebuild of the initial ramdisk for the current kernel, use:

$

sudo dracut -f

You can verify that the Clevis modules were successfully included with lsinitrd(1) by inspecting the generated image:

$

sudo lsinitrd | grep '^clevis'

clevis
clevis-pin-null
clevis-pin-sss
clevis-pin-tang
clevis-pin-tpm2

You can also verify that a Clevis token exists in the LUKS metadata – it should show a TPM pin bound to the device:

$

sudo clevis luks list -d <encrypted_partition>

2: tpm2 '{"hash":"sha256","key":"ecc"}'

For a lower-level check, inspect LUKS token metadata with cryptsetup(8), which should show the Clevis token and the keyslot it is bound to:

$

sudo cryptsetup luksDump <encrypted_partition> | grep -A2 -i Tokens

Tokens:
  0: clevis
        Keyslot:    2

After rebooting, confirm the root volume unlocks automatically and the system reaches the login prompt without asking for the LUKS passphrase.

Unlocking secondary disks¶

If your server has secondary encrypted data disks, you do not need to use dracut to unlock them, as they are unlocked later in the boot process by systemd(1).

To setup automatic unlocking, you must first bind the secondary disk to the TPM. Replace <secondary_encrypted_partition> with your secondary encrypted partition.

$

sudo clevis luks bind -d <secondary_encrypted_partition> tpm2 '{"pcr_ids": "7"}'

Then, get the UUID of the locked LUKS partition:

$

blkid -s UUID -o value <secondary_encrypted_partition>

Add the disk to crypttab(5), using none for the password file so systemd(1) automatically intercepts the prompt and recognizes the Clevis binding.

data_vol UUID=<UUID> none luks

The first field in the /etc/crypttab entry is the name used for the mapped device. In the example above the name is data_vol, so when the LUKS volume is unlocked the decrypted mapper device is exposed at /dev/mapper/data_vol. Add that device (/dev/mapper/data_vol) to fstab(5) as usual.

Removing a TPM binding¶

If you need to remove a Clevis binding (for example, if you are decommissioning a server or moving the drive), you can unbind it. First, list the active Clevis tokens to find the correct LUKS slot:

$

sudo clevis luks list -d <encrypted_partition>

Then, unbind the specific slot (replacing 1 with the slot number identified above).

$

sudo clevis luks unbind -d <encrypted_partition> -s 1