## page was renamed from furinkan/linux/Clevis_and_Tang
Clevis and Tang are two tools that work together to provide policy-based unlocking for encrypted disks. One such usage is [[https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/sec-Using_Network-Bound_Disk_Encryption.html| 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).

 1. apt install clevis-luks
 1. 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.