Clevis and Tang are two tools that work together to provide policy-based unlocking for encrypted disks. One such usage is Network-Bound Disk Encryption.
Here's a more human guide as well: https://www.reddit.com/r/CentOS/comments/8my171/followup_luks_network_bound_disk_encryption/
NBDE addresses a specific threat model and use-case. It roughly assumes:
- You need to use full-disk encryption
- This means a password is required for boot to proceed
- You can't or don't want to type a password at the local machine when the server needs to boot, such as after routine patching
- Your primary concern is someone physically stealing the server or stealing the disks out of the server
- This is not concerned with data security in-transit on the wire, or with unauthorised access to the data via apps/network paths, etc.
Tang
Tang is a lightweight daemon that provides asymmetric crypto over the network. Tang has one or more keypairs, and publishes the public key component. Anyone can encrypt data to one of the public keys, then later request for it to be decrypted. If the client can reach the Tang daemon over the network, it's considered to be duly authorised.
The data that we encrypt with Tang is the decryption key to unlock an encrypted volume.
Clevis
Clevis is the client-side counterpart to Tang, it handles the policy for Tang-assisted volume decryption.
Technically what Clevis is unlocking is a key to unlock the volume's master key. in LUKS terms, we're using one of the key slots to hold a Clevis-managed key. Tang can unlock that slot, letting us retrieve the master encryption key, and mount the volume.
Installation
This stuff is fairly new, and also has backing from Redhat, so it's not quite as mature on Debian-type systems.
You can get Tang from the usual Debian packages, but the dependency libjansson4 is too old unless you're on Debian 10 Buster or later. On Debian 9 Stretch you can use the unstable channel to work around it.
tang
This uses systemd for management and it's actually pretty elegant. It's essentially run like an inetd service, starting a new instance for each incoming connection.
- Install tang and its dependencies
Override the listening port using systemctl edit tangd.socket if you want to, as it defaults to tcp/80
- Enable and start tangd.socket
clevis
Install the base package, along with clevis-luks. We would use the clevis-dracut package, but Debian doesn't use Dracut for building its initramfs, so that won't help us. For the record we'll do something similar to it though.
Messing around
These are unstructured notes.
# test encryption, works good:
echo hi | clevis encrypt tang '{"url": "http://tang.thighhighs.top:8264"}' > hi.jwe
# try binding tang to the luks partition
apt install clevis-luks
clevis luks bind -d /dev/sda3 tang '{"url": "http://tang.thighhighs.top:8264"}'root@illustrious:~# clevis luks bind -d /dev/sda3 tang '{"url": "http://tang.thighhighs.top:8264"}'
The advertisement contains the following signing keys:
1XVz7r6j7V5DwogkcAQdk927nig
Do you wish to trust these keys? [ynYN] y
You are about to initialize a LUKS device for metadata storage.
Attempting to initialize it may result in data loss if data was
already written into the LUKS header gap in a different format.
A backup is advised before initialization is performed.
Do you wish to initialize /dev/sda3? [yn] y
Enter existing LUKS password: <the password>root@illustrious:~# luksmeta show -d /dev/sda3 0 active empty 1 active cb6e8904-81ff-40da-a84a-07ab9ab5715e 2 inactive empty 3 inactive empty 4 inactive empty 5 inactive empty 6 inactive empty 7 inactive empty
man clevis-luks-unlockers apt install clevis-dracut update-initramfs -u # Steal the scripts from here and drop them in /etc/initramfs tools, one hook and two scripts. https://github.com/latchset/clevis/pull/101/files # Modify the scripts to have a wait before trying to hit the Tang server
In the end I had to add a sleep 5 to the local-top/clevis script, but it does work nicely. The machine boots, gets online with DHCP, then clevis kicks in and fetches the decryption key for slot 1.
Trying this in 2020 on a modern system
I'm using pop_OS! (Ubuntu 20.04 under the hood) to try this, it's a fairly standard out of the box install, which will keep things sane.
It looks like there's now packages for Debian-type systems, and there's initramfs integration too! And it works with LUKS2 metadata which is fantastic (but the docs don't know it yet).
- apt install clevis-luks
clevis luks bind -d /dev/nvme0n1p3 tang '{"url": "http://tang.thighhighs.top:8264"}'
The tang binding now gets stored as a Token, which is pinned to a Keyslot.
Then I followed this person's guide to get Wifi working in the initramfs environment: http://www.marcfargas.com/posts/enable-wireless-debian-initramfs/
However I can't check that it's working because my workstation doesn't like displaying video during boot time, which is... annoying.
I think I then need to add the unlock scripts manually from /usr/share/initramfs-tools or so.
Ubuntu in 2021
Packages for LUKS and initramfs! It only mentions LUKS v1 but I'm pretty sure it'll work on v2 as well. I've rebuilt illustrious so let's see if we can make it work again.
- apt install clevis-luks
clevis luks bind -d /dev/nvme0n1p3 tang '{"url": "http://tang.thighhighs.top:8264"}'
- clevis luks bind -d /dev/nvme0n1p3 tpm2 '{"pcr_ids":"7"}'
Seems to work great! I don't think my TPM is secure, but it does mean the encryption is still active, even if the unlocking isn't secure right now (until I get Tang working again).
On a DAP-1330 running Openwrt
I thought I might buy the DAP-1330 just to use its PSU and casing for mains power, but it seems the power supply puts out 3.3V and not 5V that I was hoping to serve as USB.
But even better, it turns out that openwrt has a package for tang, awesome!
This is for Tang v8 I think, or earlier. https://github.com/openwrt/packages/issues?q=is%3Aissue+tang
* Setup networking, disable router actions, make it a client
* Install tang package
* tang is on port 8888 now by default
* Generate keys
/usr/libexec/tangd-keygen /usr/share/tang/db
/usr/libexec/tangd-update /usr/share/tang/db /usr/share/tang/cacheNow you can try an encrypt, this will get the advert and do a transaction: echo "hello" | clevis encrypt tang '{"url":"http://tang.local:8888"}'
Go ahead and enrol a LUKS volume as normal.
The key generation stuff will change in future, but not yet: https://github.com/latchset/tang/pull/53
Take note of /lib/upgrade/keep.d/tang, looks like it'll keep the DB in future across upgrades, but will need the tangd-update run again to finish generation (unless v10 arrives sooner).