Network Bound Disk Encryption with clevis and tang on OpenWrt

updated 5 min read #tutorial #security #linux

Contents

Introduction#

This guide shows how to unlock a LUKS-encrypted Fedora system automatically at boot with Clevis, using a Tang server on an OpenWrt router. It is for anyone who wants encrypted disks on home servers without typing a passphrase after every reboot.

I always fully encrypt my drives, so I needed a secure way to unlock them in my home network after a reboot. The main reason was automatic system updates that need a reboot, for example for a new kernel.

This guide was written in early 2023 on Fedora 37. Package names and paths may differ on current releases.

Network-bound disk encryption#

Clevis and Tang are the client and server components of network-bound disk encryption (NBDE). Both use the José library (jose) for encryption and decryption.

Clevis

Clevis is a pluggable framework for automated decryption. For NBDE, it unlocks LUKS volumes automatically. It is provided by the clevis package.

Tang

Tang binds data to the presence of a network: a system can only unlock its data while it can reach the Tang server. Tang is stateless and needs neither TLS nor authentication, which makes it easy to run. That also means anyone who can reach the server can use it, so only make it reachable from your trusted network.

Installation#

First, we set up tang on the OpenWrt router, then install clevis and its dracut module on the client, and finally bind a LUKS volume to the Tang server.

OpenWrt Setup#

The OpenWrt router is always reachable in my home network, which makes it a good Tang server. Log in to the router as root, update the package lists and install the tang package. OpenWrt has no systemd to manage the socket, so the package uses xinetd instead.

opkg update
opkg install tang

OpenWrt 25.12 and later use apk instead of opkg:

apk update
apk add tang

xinetd runs tang as root here. For a setup with an unprivileged user, see Installing Tang on OPNsense.

The package creates the following xinetd configuration automatically. To change the port or other parameters, edit this file.

bash /etc/xinetd.d/tangdx
service tangd
{
    port            = 8888
    socket_type     = stream
    wait            = no
    user            = root
    server          = /usr/libexec/tangdw
    server_args     = /usr/share/tang/db
    log_on_success  += USERID
    log_on_failure  += USERID
    disable         = no
}

By default, tang listens on port 8888, which is probably unused on most OpenWrt installations.

Restarting the xinetd service should be enough; otherwise, reboot the router.

/etc/init.d/xinetd restart

Finally, check that the port is open:

netstat -tulpn | grep xinetd
tcp        0      0 0.0.0.0:8888            0.0.0.0:*               LISTEN      6897/xinetd

The keys are generated automatically when the first client registers and are stored in /usr/share/tang/db/.

Client Setup#

On the client, install clevis, its dracut module clevis-dracut and, for LUKS volumes, clevis-luks:

dnf install clevis clevis-dracut clevis-luks

Next, enable networking in the early boot phase by adding two parameters to the kernel options in /etc/default/grub:

  1. rd.neednet=1 to make the network stack available
  2. ip=dhcp so that the first network interface gets an address via DHCP (warning: footgun)

If the system has several active network ports, the first one to get an address wins. In the worst case, the machine can’t reach the Tang server and doesn’t unlock. To prevent this, name the interface, or even the whole IP configuration, in the parameter.

For example, a static IP configuration:

ip=192.168.180.120::192.168.180.1:255.255.255.0::enp1s0:off

Or DHCP on a specific interface:

ip=enp1s0:dhcp

More about IP networking in early user space:

The modification in /etc/default/grub should look something like this:

GRUB_CMDLINE_LINUX="resume=/dev/mapper/server-swap rd.luks.uuid=luks-**** rd.lvm.lv=server/root rd.md.uuid=**** rd.lvm.lv=server/swap rhgb quiet rd.neednet=1 ip=dhcp"

/etc/default/grub only applies to kernels installed later. To add the parameters to the installed kernels as well, use grubby:

grubby --update-kernel=ALL --args="rd.neednet=1 ip=dhcp"

Then rebuild the initramfs with dracut:

dracut -fv --regenerate-all

The output should now include these modules:

dracut: *** Including module: network ***
dracut: *** Including module: clevis ***

The clevis-dracut module also works together with dracut-sshd.

Binding the LUKS volume to Tang#

First, find the LUKS-encrypted volume. In my case, it is the system partition.

blkid -t TYPE=crypto_LUKS -o device
/dev/nvme0n1p3

Now bind the volume to the Tang server at its address and port. Clevis asks you to trust the server’s signing key and then for the existing LUKS passphrase.

clevis luks bind -d /dev/nvme0n1p3 tang '{"url":"http://openwrt.example.com:8888"}'
The advertisement contains the following signing keys:

-NYm6-gTZ9dquHe6zy9ynGU8SAI

Do you wish to trust these keys? [ynYN] Y
Enter existing LUKS password:

You can verify the displayed key on the OpenWrt router with tang-show-keys and the Tang port, 8888:

tang-show-keys 8888
-NYm6-gTZ9dquHe6zy9ynGU8SAI

Clevis has now added a key slot and a token to the LUKS header:

cryptsetup luksDump /dev/nvme0n1p3
...
Tokens:
  0: clevis
	Keyslot:    1
...

Finally, reboot the machine to test the setup.

Result#

The client now unlocks its volume at boot without a passphrase, as long as it can reach the Tang server on the router. Away from the home network, or if Tang is down, it falls back to the normal passphrase prompt.

If you prefer to unlock remotely with a passphrase, see Fedora encrypted disk unlocking via SSH.

Sources#

cd ~/writing