cryptsetup-luks-initramfs-README

   1 1. Introduction
   2 ---------------
   3 Kernels more recent than 2.6.12 have dropped support for devfs, which
   4 means that initrd-tools can no longer be used to boot into an encrypted
   5 root partition. Instead, a similar functionality has been developed for
   6 use with an initramfs-image.
   7
   8
   9 2. A fresh installation
  10 -----------------------
  11 If you plan to perform a completely new installation of Debian onto a
  12 machine and to do so using an encrypted root partition, you might want
  13 to consider using a version of Debian Installer with partman-crypto
  14 (see http://wiki.debian.org/DebianInstaller/PartmanCrypto).
  15
  16 The installation will then take care of all the details and perform the
  17 necessary configuration for you, meaning that you should not have to
  18 read the rest of this document to get a machine with an encrypted
  19 root fs up and running.
  20
  21 However, if you are not planning to perform a new installation from scratch,
  22 the following information might be useful to you.
  23
  24
  25 3. Requirements
  26 ---------------
  27 In order to boot from an encrypted root fs, you need an initramfs-image
  28 which includes the necessary kernel modules and scripts to setup
  29 the root device after the kernel has been initialized, but before the rest
  30 of the operating system is booted.
  31
  32 To do so, you need two partitions:
  33 - an unencrypted /boot partition
  34 - an encrypted / partition
  35
  36 In addition, you need to have initramfs-tools installed.
  37
  38 NOTE: You should make sure that your swap partition is either encrypted, or
  39 that you are using a swap file on an encrypted partition, as crypto keys and
  40 other sensitive information might otherwise be written out to the swap
  41 partition in unencrypted form.
  42
  43
  44 4. Setup (regular dm-crypt)
  45 ---------------------------
  46 First of all, you must edit /etc/crypttab and add a line describing your
  47 root device, for example:
  48
  49   cryptroot /dev/hda2 none cipher=aes-cbc-essiv:sha256,size=256,hash=sha256
  50
  51 This will allow cryptsetup to create /dev/mapper/cryptroot from the
  52 encrypted partition /dev/hda2 during boot.
  53
  54 In addition, you must also make sure that the root device is listed in
  55 /etc/fstab, for example:
  56
  57   /dev/mapper/cryptroot / ext3 defaults 0 1
  58
  59 This will allow the initramfs support scripts to know which of the devices
  60 in the crypttab that is the root device.
  61
  62 After doing these changes, you should regenerate the initramfs by running
  63 "initramfs-update -u", then make sure that your boot loader is configured
  64 to feed the initramfs to the kernel when booting. The kernel root argument
  65 should also be changed to /dev/mapper/cryptroot.
  66
  67 Now, reboot the machine, and if everything is correctly configured, you
  68 should be given a prompt to type in the passphrase for the encrypted
  69 root partition before the boot can continue.
  70
  71 NOTE: the initramfs scripts default to using the sha256 hash function while
  72 the plain cryptsetup binary defaults to using the ripemd160 hash function.
  73 In order to ensure that the crypto setup works in a consistant manner, you
  74 should make sure that the hash function is specified in the /etc/crypttab file
  75 if you are using regular dm-crypt (with LUKS the hash function to use is stored
  76 in the LUKS header).
  77
  78
  79 5. Setup (using LUKS)
  80 ---------------------
  81 If you are using the LUKS feature of cryptsetup, the above setup recipe should
  82 still apply, but since most options can be derived from the information stored
  83 in the LUKS header on-disk, the line to add to /etc/crypttab should look
  84 something like this:
  85
  86   cryptroot /dev/sda2 none luks
  87
  88
  89 6. Exotic key types
  90 -------------------
  91 The above examples assume that you use a regular passphrase as the key to the
  92 encrypted filesystem. However, if you wish to make use of more complex setups
  93 (such as root-key-on-usb-memory), you can create a script which does all the
  94 steps necessary to retrieve the key and then prints it to stdout.
  95
  96 Then add a keyscript=/path/to/your/script.sh to the options (fourth column) in
  97 the above mentioned /etc/crypttab line, so that it looks something like this:
  98
  99   cryptroot /dev/sda2 none luks,keyscript=/usr/local/sbin/cryptkey
 100
 101 Next, regenerate your initramfs image. This will copy the script into the
 102 initramfs image under the /keyscripts/ directory.
 103
 104 NOTE: there is a limited set of tools available when the script is executing
 105 as part of the initramfs bootup, you have to make sure that you do not use
 106 any tools which are not available or your script, and therefore boot, will
 107 fail.
 108
 109
 110 7. "cryptopts" boot argument
 111 ----------------------------
 112 In general, you should use the above approach with a line describing your
 113 root partition in /etc/crypttab and /etc/fstab. However, if for some reason
 114 you wish to override the settings that are derived from these files and
 115 stored in the initramfs image, you can use the "cryptopts" boot argument
 116 (this *only* works for the root partition).
 117
 118 The format of cryptopts is:
 119 cryptopts=<opt1>=<value1>,<opt2>=<value2>...
 120
 121 Beside the "hash", "size", "cipher" and "lvm" options that correspond to the
 122 same options in the fourth field of /etc/crypttab, the options "target",
 123 "source" and "key" are also supported. They correspond to the first, second
 124 and third field of /etc/crypttab, respectively. See the crypttab man page
 125 for further details.
 126
 127 Several "cryptopts" boot arguments can also be specified in case more than
 128 one mapping needs to be setup in the initramfs stage of the boot.
 129
 130 Example boot arguments:
 131 root=/dev/mapper/crypt0 cryptopts=target=crypt0,source=/dev/hda1,cipher=twofish
 132
 133 8. Resume device support
 134 ------------------------
 135 The initramfs scripts will also try to automatically determine the devices,
 136 if any, that are used for software suspend (swsusp, suspend2 or uswsusp) and
 137 to set them up during the initramfs stage in order to allow suspend and resume
 138 in combination with encryption to keep the resume image safe from potential
 139 attackers.
 140
 141 If your resume device and your root partition use two different cryptsetup
 142 mappings, you might want to use the "decrypt_derived" keyscript as described
 143 below.
 144
 145 9. The "decrypt_derived" keyscript
 146 ----------------------------------
 147 Assume that you have two entries in /etc/crypttab:
 148
 149 cryptroot /dev/hda1 none luks
 150 cryptswap /dev/hda2 none luks
 151
 152 If cryptswap is used as your suspend/resume device, you'd normally need to
 153 enter two different passphrases during the boot, but the "decrypt_derived"
 154 script can generate the key for the second mapping using a hash of the key
 155 for the first mapping.
 156
 157 In short, you'll need to do something like the following to take advantage
 158 of the decrypt_derived script:
 159
 160 1) swapoff -a
 161 2) cryptsetup luksClose cryptswap
 162 3) edit /etc/crypttab and change the cryptswap line to e.g.:
 163 cryptswap /dev/hda2 cryptroot cipher=aes-cbc-essiv:sha256,size=256,hash=sha256,keyscript=/lib/cryptsetup/scripts/decrypt_derived,swap
 164 4) /etc/init.d/cryptdisks start
 165 5) Make sure that /dev/mapper/cryptswap has been created
 166 6) swapon -a
 167 7) (optional) update-initramfs -u
 168
 169 After you've followed the above steps, your swap device should be setup
 170 automatically after the root device has been setup during the boot stage.
 171
 172 Note: If you don't use suspend device support, it's better to use completely
 173 random keys for your encrypted swap device. See the section '2. Encrypted
 174 swap partition(s)' in /usr/share/doc/cryptsetup/README.Debian for information
 175 on how to setup this.
 176
 177 10. The "passdev" keyscript
 178 ----------------------------
 179 If you have a keyfile on a removable device (e.g. a USB-key), you can use the
 180 passdev keyscript. It will wait for the device to appear, mount it read-only,
 181 read the key and then unmount the device.
 182
 183 The "key" part of /etc/crypttab will be interpreted as <device>:<path>, it is
 184 strongly recommended that you use one of the persistent device names from
 185 /dev/disk/*, e.g. /dev/disk/by-label/myusbkey.
 186
 187 This is an example of a suitable line in cryptsetup:
 188 cryptroot /dev/hda2 /dev/disk/by-label/myusbkey:/keys/root.key cipher=aes-cbc-essiv:sha256,size=256,hash=plain,keyscript=/lib/cryptsetup/scripts/passdev
 189
 190 The above line would cause the boot to pause until /dev/disk/by-label/myusbkey
 191 appears in the fs, then mount that device and use the file /keys/root.key
 192 on the device as the key (without any hashing) as the key for the fs.
 193
 194 -- David Härdeman <david@hardeman.nu>