How to install an encrypted Ubuntu 22.04 with automated unlocking via tang and clevis

Introduction

The installimage script in the Hetzner Rescue System provides an easy way to install various Linux distributions.

This tutorial shows how to use installimage to install an encrypted Ubuntu 22.04 system and add fully automated remote unlocking via clevis in initramfs stored in a separate /boot partition.

Prerequisites

• Hetzner account
• Two servers:
  • tang-server » Server with Ubuntu 22.04 installed
  • clevis-server/rescue » Server booted into the Rescue System
• No private networks attached on Hetzner Cloud

Step 1 - Configure the tang server

At first we will install Tang and José (which is the c implementation of the JavaScript Object Signing and Encryption standards used by Tang) on the Server where Ubuntu 22.04 is installed already.

user@tang-server:~$ apt update 
user@tang-server:~$ apt install tang jose
user@tang-server:~$ systemctl enable tangd.socket
user@tang-server:~$ systemctl start tangd.socket

Execute tang-show-keys to check if everything is installed correctly and to determine the signing key’s fingerprint.

user@tang-server:~$ tang-show-keys 
3ZWS6-cDrCG61UPJS2BMmPU4I54

Step 2 - Create or copy SSH public key to the clevis-server (Optional)

In order to log into the server remotely via an SSH key, we need to deposit the SSH key before the installation. If you do not have such a key, you need to generate one.

For example to generate an ed25519 SSH key run:

user@client:~$ ssh-keygen -t ed25519

Copy the public key to the rescue system of the clevis server, e.g. using scp:

user@client:~$ scp ~/.ssh/id_ed25519.pub root@<clevis-server>:/tmp/authorized_keys

If you have started the Rescue System with an existing SSH key, copy the public key for the installation:

root@rescue ~ # cp ~/.ssh/authorized_keys /tmp/authorized_keys

Step 3 - Create or copy installimage config file

When installimage is called without any options, it starts in interactive mode and will open an editor after a distribution image has been selected. After exiting the editor, the installation will proceed and the corresponding configuration is saved as /installimage.conf in the installed system. In this tutorial we will pass such a configuration file to install directly.

Create a file /tmp/setup.conf with the following content or copy it to the server in the Rescue System.

Note: Replace <secret> with a secure password and adjust drive names and partitioning as needed.

CRYPTPASSWORD <secret>
DRIVE1 /dev/sda
BOOTLOADER grub
HOSTNAME host.example.com
PART /boot/efi esp 256M
PART /boot ext4 1G
PART /     ext4 all crypt
IMAGE /root/images/Ubuntu-2204-jammy-amd64-base.tar.gz

If an SSH-Key has been configured in Step 2, please also add the following line to /tmp/setup.conf.

SSHKEYS_URL /tmp/authorized_keys

Step 4 - Create or copy post-install script

In order to automatically unlock the encrypted partition via the tang server, we need to install and add clevis to the initramfs which is stored on the unencrypted /boot partition. This will also trigger the inclusion of dhclient to configure networking, but without any extras. To enable support for Hetzner Cloud, we need to add a hook which includes support for RFC3442 routes.

In order to run these additional steps we need a post-install script for installimage.

Create a file /tmp/post-install.sh in the Rescue system with the following content.

Note: Replace <secret> with the password you set for the CRYPTPASSWORD value in the /tmp/setup.conf file, and replace <ip-tangserver> with the IP-address of your tang-server.

#!/bin/bash


add_rfc3442_hook() {
  cat << EOF > /etc/initramfs-tools/hooks/add-rfc3442-dhclient-hook
#!/bin/sh

PREREQ=""

prereqs()
{
        echo "\$PREREQ"
}

case \$1 in
prereqs)
        prereqs
        exit 0
        ;;
esac

if [ ! -x /sbin/dhclient ]; then
        exit 0
fi

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

mkdir -p \$DESTDIR/etc/dhcp/dhclient-exit-hooks.d/
cp -a /etc/dhcp/dhclient-exit-hooks.d/rfc3442-classless-routes \$DESTDIR/etc/dhcp/dhclient-exit-hooks.d/
EOF

  chmod +x /etc/initramfs-tools/hooks/add-rfc3442-dhclient-hook
}


# Install hook
add_rfc3442_hook

# Update system
apt-get update >/dev/null

# Install clevis on the system and add clevis to the initramfs
apt-get -y install clevis clevis-luks clevis-initramfs cryptsetup-initramfs

# Get the key from the tang server and then bind the device to the tang server
curl -sfg http://<ip-tangserver>/adv -o /tmp/adv.jws
echo '<secret>' | clevis luks bind -d /dev/sda3 tang '{"url": "http://<ip-tangserver>" , "adv": "/tmp/adv.jws" }'

# Update the existing initramfs
update-initramfs -u

Important note: make the post-install script executable:

root@rescue ~ # chmod +x /tmp/post-install.sh

Step 5 - Start installation

Before starting the installation check again the content of the following files:

• /tmp/setup.conf - installimage config
• /tmp/post-install.sh - is executable and contains the post-install script
• if configured in Step 2:
  • /tmp/authorized_keys - your public SSH key

Now you are ready to start the installation with the following command:

root@rescue ~ # installimage -a -c /tmp/setup.conf -x /tmp/post-install.sh

Wait until the installation completes and check debug.txt for any errors.

Step 6 - Boot installed system

After the installation has finished and any errors are resolved, you can run reboot to restart the server and boot the newly installed system. You can watch the boot process if you have a KVM attached or via remote console on a Cloud instance.

Conclusion

If you have followed all the steps in this tutorial, the clevis-server should automatically decrypt the root filesystem in initramfs and afterwards boot normally into the OS.

License: MIT