From bcd0590f3a0b097602bda4ce76550cee77131aaf Mon Sep 17 00:00:00 2001
From: Guilhem Moulin <guilhem@guilhem.org>
Date: Sat, 10 Oct 2015 21:38:25 +0200
Subject: [PATCH] Update remote unlocking via SSH due following the dropbear
 2015.68-1 release.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Since 2015.68-1 the ‘dropbear’ package is now a transitional dummy package for

    dropbear-bin - command line tools
    dropbear-initramfs - initramfs integration
    dropbear-run - startup scripts
---
 cryptsetup/trunk/debian/README.Debian |  61 ++++------------
 cryptsetup/trunk/debian/README.remote | 128 ++++++++++++++++------------------
 2 files changed, 74 insertions(+), 115 deletions(-)

diff --git a/cryptsetup/trunk/debian/README.Debian b/cryptsetup/trunk/debian/README.Debian
index cf4927b..238212f 100644
--- a/cryptsetup/trunk/debian/README.Debian
+++ b/cryptsetup/trunk/debian/README.Debian
@@ -202,68 +202,35 @@ nor in askpass.
 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
+ 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 is required for this to work. Thankfully this version
-configures everything automatically, so all you have to do after installing
-dropbear on the remote system, is to copy the root ssh keyfile from
-/etc/initramfs/root/ssh/id_rsa to your local system:
+ 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/cryptsetup/README.remote for information how to install and
+configure the dropbear SSH server into the initramfs.
 
-$ scp remote.system.com:/etc/initramfs/root/ssh/id_rsa remote_rsa
+ You can then unlock the disk remotely via SSH with
 
- The remote system should start dropbear automatically during the boot
-process's initramfs execution making it possible to ssh to the remote
-system and supply the rootfs passphrase.  Because the initramfs is
-kept in an unencrypted partition the default dropbear configuration
-uses a different host key in the initramfs than the remote system's
-normal host key.  This means some care must be taken when connecting
-to the remote system so that host key checking does not interfere with
-ssh connection establishment.  When using the OpenSSH client either
-the "-o StrictHostKeyChecking=no" or the "-o
-UserKnownHostsFile=alternate_known_hosts" options are some available
-choices.
+$ ssh -tF ~/.luks/ssh.conf root@remote.system.com unlock
 
- You can login into the initramfs via ssh (modified per above)
+ Or, using a local gpg-encrypted key file:
 
-$ ssh -i remote_rsa -l root remote.system.com
-
- and echo the passphrase to a fifo file on the remote system:
-
-# echo -n "my_secret_passphrase" > /lib/cryptsetup/passfifo
+$ gpg --decrypt ~/.luks/remote.key.gpg | ssh -TF ~/.luks/ssh.conf root@remote.system.com unlock
 
  That's it. Now that the encrypted root device is unlocked, the remote system
 should continue with the boot process.
 
- If the remote system has a network configuration at boot (via ip= on the
-kernel command line) which differs from the network configuration normally
-used, the network interfaces will need to be brought down after the rootfs is
-mounted.  Without this step the normal boot process will be unable to properly
-reconfigure the network interfaces. To do this take the following steps.
-
-# mkdir -p /etc/initramfs-tools/conf.d
-# cp -a /usr/share/initramfs-tools/conf.d/dropbear \
-        /etc/initramfs-tools/conf.d/
-
-Then edit /etc/initramfs-tools/conf.d/dropbear to specify the network
-interfaces to be brought down.
-
- Should it be desirable to have the remote system use the same host key
-during the boot process as during regular system operation the
-following steps may be taken.
-
-# cp -a /etc/dropbear/dropbear_{dsa,rsa}_host_key \
-        /etc/initramfs-tools/etc/dropbear/
-# update-initramfs -u -k all
+ You can also use the following authorized_keys(5) options in
+/etc/initramfs-tools/root/.ssh/authorized_keys to restrict access and avoid
+users poking around:
 
- /usr/share/doc/cryptsetup/README.remote.gz is a documentation with more
-details on the setup of an initramfs with suppurt to remotely unlock the
-encrypted rootfs.
+no-port-forwarding,no-agent-forwarding,no-X11-forwarding,command="/bin/unlock" ssh-rsa ...
 
 
 9. Backup the LUKS header
diff --git a/cryptsetup/trunk/debian/README.remote b/cryptsetup/trunk/debian/README.remote
index 856bd97..f8e12e6 100644
--- a/cryptsetup/trunk/debian/README.remote
+++ b/cryptsetup/trunk/debian/README.remote
@@ -1,69 +1,55 @@
-unlocking rootfs via ssh login in initramfs
+unlocking rootfs via SSH login in initramfs
 -------------------------------------------
 
-You can unlock your rootfs on bootup from remote, using ssh to log in to the
+You can unlock your rootfs on bootup from remote, using SSH to log in to the
 booting system while it's running with the initramfs mounted.
 
 
 Setup
 -----
 
-For remote unlocking to work, the following packages have to be installed
-before building the initramfs: dropbear busybox
+For remote unlocking to work, dropbear-initramfs has to be installed before
+building the initrd.
 
 The file /etc/initramfs-tools/initramfs.conf holds the configuration options
-used when building the initramfs. It should contain BUSYBOX=y (this is set as
+used when building the initramfs.  It should contain BUSYBOX=y (this is set as
 the default when the busybox package is installed) to have busybox installed
 into the initramfs, and should not contain DROPBEAR=n, which would disable
-installation of dropbear to initramfs. If set to DROPBEAR=y, dropbear will
-be installed in any case; if DROPBEAR isn't set at all, then dropbear will only
-be installed in case of an existing cryptroot setup.
-
-The host keys used for the initramfs are dropbear_dss_host_key and
-dropbear_rsa_host_key, both located in/etc/initramfs-tools/etc/dropbear/.
-If they do not exist when the initramfs is compiled, they will be created
-automatically. Following are the commands to create them manually:
-
-# dropbearkey -t dss -f /etc/initramfs-tools/etc/dropbear/dropbear_dss_host_key
-# dropbearkey -t rsa -f /etc/initramfs-tools/etc/dropbear/dropbear_rsa_host_key
-
-As the initramfs will not be encrypted, publickey authentication is assumed.
-The key(s) used for that will be taken from
-/etc/initramfs-tools/root/.ssh/authorized_keys.
-If this file doesn't exist when the initramfs is compiled, it will be created
-and /etc/initramfs-tools/root/.ssh/id_rsa.pub will be added to it.
-If the latter file doesn't exist either, it will be generated automatically -
-you will find the matching private key which you will later need to log in to
-the initramfs under /etc/initramfs-tools/root/.ssh/id_rsa (or id_rsa.dropbear
-in case you need it in dropbear format). Following are the commands to do the
-respective steps manually:
-
-To create a key (in dropbear format):
-
-# dropbearkey -t rsa -f /etc/initramfs-tools/root/.ssh/id_rsa.dropbear
-
-To convert the key from dropbear format to openssh format:
-
-# /usr/lib/dropbear/dropbearconvert dropbear openssh \
-	/etc/initramfs-tools/root/.ssh/id_rsa.dropbear \
-	/etc/initramfs-tools/root/.ssh/id_rsa
-
-To extract the public key:
-
-# dropbearkey -y -f /etc/initramfs-tools/root/.ssh/id_rsa.dropbear | \
-	grep "^ssh-rsa " > /etc/initramfs-tools/root/.ssh/id_rsa.pub
-
-To add the public key to the authorized_keys file:
-
-# cat /etc/initramfs-tools/root/.ssh/id_rsa.pub >> /etc/initramfs-tools/root/.ssh/authorized_keys
-
-In case you want some interface to get configured using dhcp, setting DEVICE= in
-/etc/initramfs-tools/initramfs.conf should be sufficient.  The initramfs should
-also honour the ip= kernel parameter.
-In case you use grub, you probably might want to set it in /boot/grub/menu.lst,
-either in the '# kopt=' line or appended to specific 'kernel' line(s).
-The ip= kernel parameter is documented in Documentation/nfsroot.txt in the
-kernel source tree.
+installation of dropbear to initramfs.  If set to DROPBEAR=y, dropbear will be
+installed in any case; if DROPBEAR isn't set at all, then dropbear will only be
+installed if /etc/crypttab is non-empty.
+
+The host keys used for the initramfs are dropbear_{dss,rsa,ecdsa}_host_key, all
+three located in the /etc/initramfs-tools/etc/dropbear directory.  They are
+created automatically if they do not exist when dropbear-initramfs is installed
+or upgraded.  They can also be created manually with
+
+  # dropbearkey -t dss   -f /etc/initramfs-tools/etc/dropbear/dropbear_dss_host_key
+  # dropbearkey -t rsa   -f /etc/initramfs-tools/etc/dropbear/dropbear_rsa_host_key
+  # dropbearkey -t ecdsa -f /etc/initramfs-tools/etc/dropbear/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 $PKGOPTION_dropbear_OPTION variable.
+For instance add PKGOPTION_dropbear_OPTION="-p 2222" to /etc/initramfs-tools/initramfs.conf
+to change the listening port to 2222.
+
+Password logins are disabled.  Public key(s) used for authentication are
+taken from /etc/initramfs-tools/root/.ssh/authorized_keys, or from
+/etc/initramfs-tools/root/.ssh/id_{dsa,rsa,ecdsa}.pub if it does not
+exist.  A warning is raised if no authorized keys could be found.
 
 
 Issues
@@ -72,25 +58,31 @@ Issues
 Don't forget to run update-initramfs when you changed the config to make it
 effective!
 
-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
+  # 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.
+console you won't have to wait for the SSHd to complete its startup.
 
 
 Unlocking procedure
 -------------------
 
-To unlock from remote, you could do something like this:
-
-# ssh -o "UserKnownHostsFile=~/.ssh/known_hosts.initramfs" \
-	-i "~/id_rsa.initramfs" root@initramfshost.example.com \
-	"echo -ne \"secret\" >/lib/cryptsetup/passfifo"
-
-This example assumes that you have an extra known_hosts file
-"~/.ssh/known_hosts.initramfs" which holds the cryptroot system's host-key,
-that you have a file "~/id_rsa.initramfs" which holds the authorized-key for
-the cryptroot system, that the cryptroot system's name is
-"initramfshost.example.com", and that the cryptroot passphrase is "secret"
+See /usr/share/doc/cryptsetup/README.Debian section 8.
 
 -- <debian@x.ray.net>, Wed, 30 Sep 2009
-- 
2.6.1

