Remotely unlock encrypted rootfs

8. Remotely unlock encrypted rootfs
-----------------------------------

 Thanks to Chris <debian@x.ray.net> it's possible to install a dropbear SSH
server into the initramfs, connect to this SSH server during execution of
initramfs early in the boot process, and unlock encrypted devices - even the
root device - before the boot process continues.

 This way it is possible to use an encrypted root filesystem on headless
systems where no physical access is available during boot process.

 Dropbear 0.52-1 or later is required for this to work. (Since 2015.68-1 the
functionality has its own binary package 'dropbear-initramfs'.) Consult
/usr/share/doc/dropbear-initramfs/README.initramfs from the dropbear-initramfs
package for information how to install and configure the dropbear SSH server
into the initramfs.

 You can then unlock the disk remotely via SSH with

$ ssh -tF ~/.luks/ssh.conf root@remote.system.com cryptroot-unlock

 Or, using a local gpg-encrypted key file:

$ gpg --decrypt ~/.luks/remote.key.gpg | ssh -TF ~/.luks/ssh.conf root@remote.system.com cryptroot-unlock

 That's it. Now that the encrypted root device is unlocked, the remote system
should continue with the boot process.

 You can also use the following authorized_keys(5) options in
/etc/dropbear-initramfs/authorized_keys to restrict access and avoid
users poking around:

no-port-forwarding,no-agent-forwarding,no-X11-forwarding,command="/bin/cryptroot-unlock" ssh-rsa ...

(Be sure to rebuild the initrd afterwards: `update-initramfs -u -k all`.)

Installing dropbear SSH in the initramfs
----------------------------------------

Setup
-----

For remote unlocking to work, dropbear-initramfs has to be installed before
building the initrd.

The host keys used for the initramfs are dropbear_{dss,rsa,ecdsa}_host_key, all
three located in the /etc/dropbear-initramfs directory.  They are created
automatically if they do not exist when dropbear-initramfs is installed or
upgraded.  They can also be created manually with the following commands:

  # dropbearkey -t dss   -f /etc/dropbear-initramfs/dropbear_dss_host_key
  # dropbearkey -t rsa   -f /etc/dropbear-initramfs/dropbear_rsa_host_key
  # dropbearkey -t ecdsa -f /etc/dropbear-initramfs/dropbear_ecdsa_host_key

A warning is raised if none of these host key files exist.  (dropbear will then
fail to start.)  In case of an encrypted rootfs, you typically don't want the
initramfs SSHd to reuse the host keys of the main SSH server (those in /etc/ssh
or /etc/dropbear), since the initrd lies in /boot which, unlike /etc, is
usually not encrypted.

Set the "ip=" kernel boot parameter if you wish to use a non-default IP address
or device.  (See Documentation/filesystems/nfsroot.txt in the Linux
documentation for details.)  If "ip=none" or "ip=off", then dropbear is not
started at boot time.  On local (non NFS) boots, all network interfaces are
brought down by default once the rootfs has been mounted; however
$DROPBEAR_IFDOWN can be set to a shell pattern matching the interface(s) to
bring down, or to the special value "none" to keep all interfaces up.

Command line options are taken from the $DROPBEAR_OPTIONS variable.  For
instance add DROPBEAR_OPTIONS="-p 2222" to /etc/dropbear-initramfs/config
to change the listening port to 2222.

Password logins are disabled.  Public key(s) used for authentication are taken
from /etc/dropbear-initramfs/authorized_keys, or from
/etc/dropbear-initramfs/id_{dsa,rsa,ecdsa}.pub if the former does not exist.  A
warning is raised if no authorized keys could be found.


Unlocking procedure
-------------------

You can unlock your rootfs on bootup remotely, using SSH to log in to
the booting system while it's running with the initramfs mounted.
Consult cryptsetup's /usr/share/doc/cryptsetup/README.Debian section 8
for details.


Issues
------

You'll have to include the driver of (one of) your network card(s) to
/etc/initramfs-tools/modules.  To list all network drivers curently in use, run

  $ while read m _; do /sbin/modinfo -F filename "$m"; done </proc/modules |
    sed -nr "s@^/lib/modules/`uname -r`/kernel/drivers/net(/.*)?/([^/]+)\.ko\$@\2@p"

Don't forget to run update-initramfs when you changed the config to make it
effective!

  # update-initramfs -u -k all

Since by default the initramfs' host keys differ from those of the main SSH
server, SSH clients such as OpenSSH's might issue a "REMOTE HOST IDENTIFICATION
HAS CHANGED!" warning.  In that case you might want to use another port for the
initramfs SSHd, and/or the "UserKnownHostsFile" option to specify an
alternative known_hosts file:

  $ ssh -F ~/.luks/ssh.conf remote.system.com
  $ cat ~/.luks/ssh.conf
  Host *
    User root
    UserKnownHostsFile ~/.luks/known_hosts
    PasswordAuthentication no
    IdentityFile ~/.ssh/id_rsa

Collecting enough entropy for the SSH daemon sometimes seems to be an issue.
Startup of the SSH daemon might be delayed until enough entropy has been
retrieved. This is non-blocking for the startup process, so when you are at the
console you won't have to wait for the SSHd to complete its startup.