Tang and Clevis can be used in order to unlock disks over network. This post will not cover all possible ways how to unlock LUKS devices. It will focus on unlocking devices over network if both TPM2 and Tang are available.

The disk can only be decrypted if it is still on the same mainboard (connected to the same TPM 2 device) and if the Tang server is reachable. A more complex setup with multiple Tang servers is also possible.

For more background about Tang/Clevis, several blog posts and documentations are available.

Special thanks to those sites, as they helped a lot to create this blog post.

Installation

Install a couple of required packages on Debian in order to get Clevis working.

$ sudo apt install clevis clevis-luks clevis-initramfs clevis-tpm2

The full disk encryption should already be in place and the used password will also remain in the LUKS device. Choose a good password for your LUKS device, it will remain as a backup. It is not recommended to remove it, as the TPM 2 can get overwritten.

In this example we are going to setup Clevis with sss which stands for Shamir Secret Sharing. One part will be Tang and the other part TPM2. t=2 defines the threshold of 2, which enforces both secrets to be available.

{
  "t": 2,
  "pins": {
    "tang": [
      {
        "url": "https://tang.example.net"
      }
    ],
    "tpm2": {
      "hash": "sha256"
    }
  }
}

Above is just the configuration, now let’s actually create a LUKS key with this configuration:

sudo clevis luks bind -d /dev/sda2 sss '{"t":2,"pins":{"tang":[{"url":"https://tang.example.net"}], "tpm2":{"hash":"sha256"}}}'

This will first ask for the current LUKS passphrase and will then ask if the Tang secret is the correct one. After this process the LUKS device can be decrypted automatically with TPM2 and Tang.

But this is not all.

initramfs

On Debian derivates often initramfs is used. This will not work if the system is booting with dracut. In order to unlock the disk during boot, the machine needs network during boot. There are several ways how to achieve this. On a Debian with WiFi checkout WiFi on Debian in initramfs.

In order Clevis can connect to Tang, a couple of things are required. DNS has to work and able to resolve the Tang server, TLS CA certificates are required, …

Create an initramfs hook which adds all those components to initramfs.

  • /etc/initramfs-tools/hooks/curl
#!/bin/sh -e

PREREQS=""

case $1 in
    prereqs)
        echo "$PREREQS"
        exit 0
        ;;
esac

. /usr/share/initramfs-tools/hook-functions

# copy curl binary
copy_exec /usr/bin/curl /bin

# fix DNS lib (needed for Debian 11)
cp -a /usr/lib/x86_64-linux-gnu/libnss_dns* "${DESTDIR}/usr/lib/x86_64-linux-gnu/"

# fix DNS resolver (needed for Debian 11 + 12)
echo "nameserver 1.1.1.1\n" > "${DESTDIR}/etc/resolv.conf"

# copy ca-certs for curl
mkdir -p "${DESTDIR}/usr/share"
cp -ar /usr/share/ca-certificates "${DESTDIR}/usr/share/"
cp -ar /etc/ssl "${DESTDIR}/etc/"

Update initramfs in order to add those components:

update-initramfs -u

Summary

During the boot process, initramfs will connect to the network (not documented in this post) and will then connect TPM 2 and Tang in order to get both parts of the key. This will then, with the knowledge of LUKS, unlock the disk and boot.