Debian: Unlock LUKS root partition remotely by SSH using dropbear

Scenario

• You want to unlock a system remotely during boot process.
• Your root partition is a LVM volume.
• Your LVM setup is fully encrypted with LUKS.
• You’re running Debian 10 or above (buster, bullseye, bookworm) on the remote system.

How To

This tutorial describes an option to unlock your system remotely using SSH and dropbear.

apt-get install -yy dropbear-initramfs cryptsetup-initramfs lvm2

# Configuration directory and files for dropbear changes in Debian 12
DROPBEAR_DIR=/etc/dropbear/initramfs
DROPBEAR_CONFIG=DROPBEAR_DIR/dropbear.conf
if [ $(cut -d. -f1 /etc/debian_version) -lt 12 ]; then
  DROPBEAR_DIR=/etc/dropbear-initramfs
  DROPBEAR_CONFIG=DROPBEAR_DIR/config
fi

echo 'DROPBEAR_OPTIONS="-RFEsjk -c cryptroot-unlock"' > $DROPBEAR_CONFIG

# Add your local SSH public keys to dropbear's authorized_keys file to allow password-less logins
echo '<YOUR_PUBLIC_KEY>' > $DROPBEAR_DIR/authorized_keys

# Check if /etc/crypttab contains an entry like below;
# LUKS volume and device names vary depending on your configuration and hardware.
sda2_crypt /dev/sda2 none luks,initramfs

# Add network support to the initramfs; replace variables with your server's network configuration
# It's important to select the right network interface name.
echo 'IP="${ip_address}::${gateway_ip}:${netmask}:${optional_fqdn}:${interface_name}:none"' > /etc/initramfs-tools/conf.d/ip

update-initramfs -k all -u

Explanation

• Package dropbear-initramfs adds SSH support to initramfs during boot.
• Package cryptsetup-initramfs provides scripts required to unlock the LUKS device.
• Package lvm2 is required to identify and mount LVM volumes after unlocking LUKS-encrypted devices.
• Options configured in /etc/dropbear/initframfs/dropbear.conf (before Debian 12: /etc/dropbear-initramfs/config) let the dropbear server start in foreground during initramfs stage, so the boot process waits for LUKS devices to get unlocked before proceeding.
  • The SSH host keys required are generated by dropbear on the first SSH connection, see option -R. This requires you to accept new host keys on every reboot when connecting by SSH but prevents issues with missing host keys. Generating host keys on every boot does not mean a security issue as the boot partition isn’t encrypted and can’t be fully trusted at all.
  • SSH port forwarding is denied by dropbear options -j and -k
  • SSH password authentication is denied by option -s
  • The option -c cryptroot-unlock enforces the given binary to be executed after successful login, which directly prompts for the LUKS password to unlock the devices. This option also ensures a user isn’t able to run any other (interactive) command within the initramfs stage. The binary cryptroot-unlock is installed by package cryptsetup-initramfs.
• You have to add your local SSH public key to dropbear’s authorized_keys to be able to login during the boot process.
• The entry in /etc/crypttab informs cryptsetup how to handle LUKS devices within the initramfs stage.
  • You could also reference your device/partition using a UUID, to prevent boot problems after changes on the disks (see lsblk -o NAME,UUID).
• The kernel option ip will configure the given network device within the initramfs stage, so you’re able to connect to the SSH dropbear service on boot time.
  • If the kernel option ip is not specified, dropbear will not start at all.
  • The option ip was intended to mount the root filesystem from an NFS server over network but it can also be used to just assign an IP address during boot before the OS takes care about configuring network devices.
  • You can also enable DHCP for IP allocation:
    • ip=::::${optional_fqdn}:${device}:dhcp
• Don’t forget to run update-initramfs so dropbear and the IP settings are added to the initramfs files. Rerun update-initramfs after every change on the dropbear configuration files.
• Now you can reboot your system and try to unlock it via SSH.

Example

A successful initramfs configuration looks like this, when booting the server:

user@localhost:~$ ssh root@123.45.67.89
The authenticity of host '123.45.67.89 (123.45.67.89)' can't be established.
RSA key fingerprint is SHA256:W9CvWlZYo1I2A4Aed0tpkz2knOfUuIpcRTR74OJhLWKo.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '123.45.67.89' (RSA) to the list of known hosts.
[222] Dec 22 12:58:56 lastlog_perform_login: Couldn't stat /var/log/lastlog: No such file or directory
[222] Dec 22 12:58:56 lastlog_openseek: /var/log/lastlog is not a file or directory!
Please unlock disk sda2_crypt: 
cryptsetup: sda2_crypt set up successfully
Connection to 123.45.67.89 closed.

If you would like to prevent conflicts with known keys due to changing SSH host keys, just add the parameter -o UserKnownHostsFile=/dev/null to your SSH client command or your client configuration ~/.ssh/config.

Notes

• This setup also works for unlocking multiple devices with different keys.
• This solution works fine with Debian 10, 11 and 12.
• Warnings by dropbear about lastlog can be ignored as the dropbear binary from Debian does not support the option -m yet.
• Debian 11 reports following warning during update-initramfs, which can safely be ignored if DROPBEAR_OPTIONS contains -R:
  dropbear: WARNING: Missing host keys, SSH login to initramfs won't work!

References

• man 8 dropbear
• man 8 sshd -> AUTHORIZED_KEYS FILE FORMAT
• man 5 crypttab
• man 5 initramfs.conf
• https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt
• Other tutorials about this topic:
  • https://hamy.io/post/0009/how-to-install-luks-encrypted-ubuntu-18.04.x-server-and-enable-remote-unlocking/
  • https://thej6s.com/articles/2019-03-05__decrypting-boot-drives-remotely/
  • https://www.hagen-bauer.de/2018/09/verschl%C3%BCsseltes-debian-remote-starten.html