Cryptsetup for Debian --------------------- Table of Contents 1. Introduction into Cryptsetup for Debian 2. Encrypted swap partition(s) 3. Insecure mode/owner for keys 4. Cryptsetup and udev 5. Useful keyscripts: askpass and passdev 6. The 'check' option 7. Cryptsetup and Splashy 8. Remotely unlock encrypted rootfs 9. Backup the LUKS header 10. Changing the boot order of cryptdisks init scripts 11. Credits 1. Introduction into Cryptsetup for Debian ------------------------------------------ Cryptsetup is a command-line interface for configuring encrypted block devices via dm-crypt, a kernel device-mapper target. For documentation about the cryptsetup tool, see manpage of cryptsetup(8) and the frequently asked questions at /usr/share/doc/cryptsetup/FAQ.gz. The Debian cryptsetup package provides the initscript /etc/init.d/cryptdisks and a configuration file /etc/crypttab for automatically configuring encrypted devices at boot time. The applications cryptdisks_start and cryptdisks_stop are provided to process crypttab configured devices manually. See the manpages of crypttab(5), cryptdisks_start(8) and cryptdisks_stop(8) for more information. The luksformat script provides a simple interface for creating an encrypted device that follows the LUKS standard and for putting a file system onto the encrypted device. See man luksformat(8) for more information. If you wish to perform a Debian installation to an encrypted root, you might be interested in using a version of Debian Installer with partman-crypto, which will install the system and setup cryptsetup and initramfs-tools. For instructions about how to encrypt your root filesystem and integrate cryptsetup into initramfs on a running system, see /usr/share/doc/cryptsetup/README.initramfs.gz. 2. Encrypted swap partition(s) ------------------------------ An encrypted swap partition prevents spying on plaintext secrets (passwords) that may be written to disk when memory is swapped to disk. To encrypt your swap partitions, you'll first have to deactivate your swap: swapoff -a You'll have to add an entry for every swap partition in /etc/crypttab. Be sure to place the source device (here /dev/sde9) with your swap devices: # cswap1 /dev/sde9 /dev/urandom swap,cipher=aes-xts-plain64,size=256,hash=sha1 Now you need to change the swap devices in /etc/fstab to the encrypted swap device names (/dev/mapper/cswap1 in this example). # /dev/sde9 none swap sw 0 0 becomes # /dev/mapper/cswap1 none swap sw 0 0 Finally, you need to start the cryptsetup swap devices and reactivate swap: /etc/init.d/cryptdisks start swapon -a That's it! You have a crypted swap device. Note that /dev/urandom provides only pseudo-random entropy. So if you're paranoid rather use /dev/random as source for random data. Be aware though that /dev/random might not provide enough random bytes for your key, causing your system to hang at boot, waiting for more entropy. Moving mouse and keyboard typing might help in this case. Read the crypttab(5) manpage for more information, for example options to use a different encryption algorithm than the default. 3. Insecure mode/owner for keys ------------------------------- Any key that is stored somewhere to be used with cryptsetup should have the mode 400 (-r--------) and root as owner/group. 'chown root.root keyfile' and 'chmod 400 keyfile' will do the trick for you. If a key is stored on a vfat filesystem (very common for removable media), chmod and chown will not work. The vfat filesytem (and several others too) does not support file permissions and ownership. Instead, you should use the uid, gid and umask options in /etc/fstab to ensure secure permissions for the key. As an example, assume that /dev/sdg8 is the removable media containing keyfiles on a vfat filesystem and that it is going to be mounted on /media/flash0. The configuration in /etc/fstab should then be something like this: # /dev/sdg8 /media/flash0 vfat uid=0,gid=0,umask=277 0 0 If you are using udev, it might be a good idea to use the /dev/disk/by-label links instead of /dev/sdg8 as the link will work no matter in which order the media is inserted and detected. 4. Cryptsetup and udev ---------------------- As a workaround for some yet-to-be-fixed race condition in kernel, device-mapper or udev, cryptsetup currently runs udevsettle. This leads to problems if you invoke cryptsetup as part of a udev rule. udevsettle waits until queued kernel/udev events are processed and the 'run programs' have finished. Due to cryptsetup itself being a 'run program' in this case, this ends in a deadlock. Therefore cryptsetup should be detached directly after invocation in this case, so that it runs asynchronously. 5. Useful keyscripts: askpass and passdev ----------------------------------------- The cryptsetup package ships with several keyscripts. Keyscripts may be configured in /etc/crypttab in order to provide the key required to unlock the device. The shipped keyscripts are located at /lib/cryptsetup/scripts. Some keyscripts have an own README file at /usr/share/doc/cryptsetup/. Two special keyscripts, worth being mentioned here, are askpass and passdev. Askpass is located at /lib/cryptsetup/askpass. It's a simple helper program that supports different methods (console, fifo, splashy, ...) to prompt for a passphrase, and prints the result to stdout. The syntax is: /lib/cryptsetup/askpass PROMPT Passdev will wait for a given device to appear, mount it read-only, read the key, and unmount the device. See /usr/share/doc/cryptsetup/README.initramfs.gz for more information about passdev. 6. The 'check' option --------------------- The 'check' option in crypttab allows one to configure checks to be run against the target device after cryptsetup has been invoked. The default check 'blkid' can check for any known filesystem type, as it uses blkid from util-linux. you can check for a particular filesystem by giving for example 'checkargs=ext4' or 'checkargs=swap' as an option in /etc/crypttab. The 'precheck' option is for configuring checks to be run against the source device before cryptsetup has been invoked. They are only available for plain cryptsetup devices. LUKS devices have a hardcoded precheck that uses the 'isLuks' command of cryptsetup. As there is no way to check a device for plain cryptsetup data, you can only check for data that should not be on the device. for example the check could search for common filesystems on the device, and abort if it finds any. As this will never really ensure that no data is lost, the package doesn't provide such a check. Another example for a precheck could be to check the partition table id. For a device that shall be used as swap partition, it could verify that only partitions with type 'swap' (82) are used for encrypted swap. Please send us your checks, if you write new ones. If they are generally useful, we will include them in the package. See man crypttab(5) for more information about the checksystem. 7. Cryptsetup and Splashy ------------------------- Splashy support in cryptsetup is currently somehow limited. Splashy is known to freeze at the password dialog for encrypted non-root filesystems. Only the password dialog for the encrypted root filesystem works. It seems like splashy freezes for any input dialog in initscripts while input dialogs at initramfs stage seem to work. This leads to the assumption that the bug is somewhere in splashy and neither in cryptsetups initscripts nor in askpass. 8. Remotely unlock encrypted rootfs ----------------------------------- Thanks to Chris 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: $ scp remote.system.com:/etc/initramfs/root/ssh/id_rsa remote_rsa 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. You can login into the initramfs via ssh (modified per above) $ 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 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 /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. 9. Backup the LUKS header ------------------------- WARNING: This information might be outdated. Please read the cryptsetup FAQ at /usr/share/doc/cryptsetup/FAQ.gz for up-to-date information on how to backup the LUKS header. The LUKS header is located at the beginning of every LUKS encrypted device. It stores information such as used cipher, hash, etc. But most importantly, the header contains eight keyslots, which do keep an encrypted version of the LUKS masterkey. the data on an encrypted LUKS partition is encrypted with this masterkey. thus, there's no way to restore the data once the masterkey is lost. For that reason, one might want to backup the LUKS header in order to prevent accidential data loss. On the other hand keeping a backup of the LUKS header isn't recommended for security reasons. The reason is, that LUKS was designed with key revocation in mind. Once the LUKS header is copied to a backup, revoking a (possibly compromised) passphrase or keyfile from the keyslot isn't enough anymore. the revoked passphrase/keyfile can easily be reactived by writing back the header backup to the device. Beginning with version 1.1.0, cryptsetup has support for the commands luksHeaderBackup and luksHeaderRestore. If you want to store a backup of your LUKS header with the mentioned drawbacks in mind, do the following: Prepare a ramdisk to store the backup temporarely. You should do that in order to prevent any hardware caching functions or filesystem jounals to copy the backup around to places you cannot control. If you want to store the backup permanently, write it to a read-only medium like CD immediately from ramdisk, without your burning program writing an intermediate image to some temp dir. To actually backup the header, use the following command: # cryptsetup luksHeaderBackup --header-backup-file That's it. But once again, keep in mind all the security implications when doing LUKS header backups. In general it's better to backup the data from encrypted LUKS devices to another encrypted LUKS device. That way you can manage the keyslots for both original and backup device independently. 10. Changing the boot order of cryptdisks init scripts ----------------------------------------------------- In order to support non-standard setups, it might be necessary to change the order of init scripts in the boot process. Cryptsetup already installs two init scripts, cryptdisks-early and cryptdisks, in order to support some complex setups. For example, both "lvm on luks" and "luks on lvm" are supported that way. If your system isn't supported by the default order of init scripts in the boot process, you need to change the boot process on your own. In some cases it might be enough to change the LSB dependency headers at initscripts, see /etc/init.d/README for more information about that. For more complex setups, more intrusive changes are required. For example, adding a third cryptdisks init script might help. See the log of bugreport #576646[1] and discussion on debian-devel[2] for further information. [1] http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=576646 [2] http://lists.debian.org/debian-devel/2010/06/msg00021.html 11. Credits ----------- People who contributed to the Debian cryptsetup package: Jonas Meurer David Härdeman Bastian Kleineidam Michael Gebetsroither -- Jonas Meurer , Thu, 17 Feb 2011 20:54:56 +0100