]>
Commit | Line | Data |
---|---|---|
b32f9594 JR |
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> |