diff options
Diffstat (limited to 'man/crypttab.xml')
| -rw-r--r-- | man/crypttab.xml | 300 |
1 files changed, 182 insertions, 118 deletions
diff --git a/man/crypttab.xml b/man/crypttab.xml index e52b7e6015..298f39e0e3 100644 --- a/man/crypttab.xml +++ b/man/crypttab.xml @@ -75,23 +75,29 @@ fields are mandatory, the remaining two are optional.</para> + <para>Setting up encrypted block devices using this file + supports three encryption modes: LUKS, TrueCrypt and plain. + See <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for more information about each mode. When no mode is specified + in the options field and the block device contains a LUKS + signature, it is opened as a LUKS device; otherwise, it is + assumed to be in raw dm-crypt (plain mode) format.</para> + <para>The first field contains the name of the resulting encrypted block device; the device is set up within <filename>/dev/mapper/</filename>.</para> <para>The second field contains a path to the - underlying block device, or a specification of a block + underlying block device or file, or a specification of a block device via <literal>UUID=</literal> followed by the - UUID. If the block device contains a LUKS signature, - it is opened as a LUKS encrypted partition; otherwise, - it is assumed to be a raw dm-crypt partition.</para> + UUID.</para> <para>The third field specifies the encryption password. If the field is not present or the password - is set to none, the password has to be manually - entered during system boot. Otherwise, the field is - interpreted as a path to a file containing the - encryption password. For swap encryption, + is set to <literal>none</literal> or <literal>-</literal>, + the password has to be manually entered during system boot. + Otherwise, the field is interpreted as a absolute path to + a file containing the encryption password. For swap encryption, <filename>/dev/urandom</filename> or the hardware device <filename>/dev/hw_random</filename> can be used as the password file; using @@ -104,181 +110,237 @@ options are recognized:</para> <variablelist class='crypttab-options'> + + <varlistentry> + <term><varname>allow-discards</varname></term> + + <listitem><para>Allow discard requests to be + passed through the encrypted block device. This + improves performance on SSD storage but has + security implications.</para></listitem> + </varlistentry> + <varlistentry> <term><varname>cipher=</varname></term> - <listitem><para>Specifies the cipher - to use; see + <listitem><para>Specifies the cipher to use. See <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values and the default - value of this option. A cipher with - unpredictable IV values, such as - <literal>aes-cbc-essiv:sha256</literal>, - is recommended. </para></listitem> + for possible values and the default value of + this option. A cipher with unpredictable IV + values, such as <literal>aes-cbc-essiv:sha256</literal>, + is recommended.</para></listitem> </varlistentry> - <varlistentry> - <term><varname>size=</varname></term> + <term><varname>hash=</varname></term> - <listitem><para>Specifies the key size - in bits; see + <listitem><para>Specifies the hash to use for + password hashing. See <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values and the default - value of this - option. </para></listitem> + for possible values and the default value of + this option.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>keyfile-offset=</varname></term> + + <listitem><para>Specifies the number of bytes to + skip at the start of the key file. See + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of + this option.</para></listitem> + </varlistentry> <varlistentry> <term><varname>keyfile-size=</varname></term> <listitem><para>Specifies the maximum number - of bytes to read from the keyfile; see + of bytes to read from the key file. See <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values and the default - value of this option. This option is ignored - in plain encryption mode, as the keyfile-size is then given by the key size.</para></listitem> + for possible values and the default value of + this option. This option is ignored in plain + encryption mode, as the key file size is then + given by the key size.</para></listitem> </varlistentry> - <varlistentry> - <term><varname>keyfile-offset=</varname></term> + <term><varname>luks</varname></term> - <listitem><para>Specifies the number - of bytes to skip at the start of - the keyfile; see - <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values and the default - value of this option.</para></listitem> + <listitem><para>Force LUKS mode. When this mode + is used the following options are ignored since + they are provided by the LUKS header on the + device: <varname>cipher=</varname>, + <varname>hash=</varname>, + <varname>size=</varname>.</para></listitem> </varlistentry> - <varlistentry> - <term><varname>hash=</varname></term> + <term><varname>noauto</varname></term> - <listitem><para>Specifies the hash to - use for password hashing; see - <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> for possible values and - the default value of this - option. </para></listitem> + <listitem><para>This device will not be + automatically unlocked on boot.</para></listitem> </varlistentry> <varlistentry> - <term><varname>tries=</varname></term> + <term><varname>nofail</varname></term> - <listitem><para>Specifies the maximum - number of times the user is queried - for a password.</para></listitem> + <listitem><para>The system will not wait for the + device to show up and be unlocked at boot, and + not fail the boot if it does not show up.</para></listitem> </varlistentry> <varlistentry> - <term><varname>verify</varname></term> + <term><varname>plain</varname></term> - <listitem><para> If the encryption - password is read from console, it has - to be entered twice (to prevent - typos). </para></listitem> + <listitem><para>Force plain encryption mode.</para></listitem> </varlistentry> <varlistentry> <term><varname>read-only</varname></term><term><varname>readonly</varname></term> - <listitem><para>Set up the encrypted - block device in read-only - mode.</para></listitem> + <listitem><para>Set up the encrypted block + device in read-only mode.</para></listitem> </varlistentry> <varlistentry> - <term><varname>allow-discards</varname></term> + <term><varname>size=</varname></term> - <listitem><para>Allow discard requests - to be passed through the encrypted - block device. This improves - performance on SSD storage but has - security - implications.</para></listitem> + <listitem><para>Specifies the key size + in bits. See + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of + this option.</para></listitem> </varlistentry> <varlistentry> - <term><varname>luks</varname></term> + <term><varname>swap</varname></term> - <listitem><para>Force LUKS mode.</para></listitem> + <listitem><para>The encrypted block device will + be used as a swap device, and will be formatted + accordingly after setting up the encrypted + block device, with + <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + This option implies <varname>plain</varname>.</para> + + <para>WARNING: Using the <varname>swap</varname> + option will destroy the contents of the named + partition during every boot, so make sure the + underlying block device is specified correctly.</para></listitem> </varlistentry> <varlistentry> - <term><varname>plain</varname></term> + <term><varname>tcrypt</varname></term> + + <listitem><para>Use TrueCrypt encryption mode. + When this mode is used the following options are + ignored since they are provided by the TrueCrypt + header on the device or do not apply: + <varname>cipher=</varname>, + <varname>hash=</varname>, + <varname>keyfile-offset=</varname>, + <varname>keyfile-size=</varname>, + <varname>size=</varname>.</para> + + <para>When this mode is used, the passphrase is + read from the key file given in the third field. + Only the first line of this file is read, + excluding the new line character.</para> + + <para>Note that the TrueCrypt format uses both + passphrase and key files to derive a password + for the volume. Therefore, the passphrase and + all key files need to be provided. Use + <varname>tcrypt-keyfile=</varname> to provide + the absolute path to all key files. When using + an empty passphrase in combination with one or + more key files, use <literal>/dev/null</literal> + as the password file in the third field.</para></listitem> + </varlistentry> - <listitem><para>Force plain encryption - mode.</para></listitem> + <varlistentry> + <term><varname>tcrypt-hidden</varname></term> + + <listitem><para>Use the hidden TrueCrypt volume. + This implies <varname>tcrypt</varname>.</para> + + <para>This will map the hidden volume that is + inside of the volume provided in the second + field. Please note that there is no protection + for the hidden volume if the outer volume is + mounted instead. See + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for more information on this limitation.</para></listitem> </varlistentry> <varlistentry> - <term><varname>timeout=</varname></term> + <term><varname>tcrypt-keyfile=</varname></term> + + <listitem><para>Specifies the absolute path to a + key file to use for a TrueCrypt volume. This + implies <varname>tcrypt</varname> and can be + used more than once to provide several key + files.</para> - <listitem><para>Specify the timeout - for querying for a password. If no - unit is specified seconds is used. - Supported units are s, ms, us, min, h, - d. A timeout of 0 waits indefinitely - (which is the - default).</para></listitem> + <para>See the entry for <varname>tcrypt</varname> + on the behavior of the passphrase and key files + when using TrueCrypt encryption mode.</para></listitem> </varlistentry> <varlistentry> - <term><varname>noauto</varname></term> + <term><varname>tcrypt-system</varname></term> + + <listitem><para>Use TrueCrypt in system + encryption mode. This implies + <varname>tcrypt</varname>.</para> + + <para>Please note that when using this mode, the + whole device needs to be given in the second + field instead of the partition. For example: if + <literal>/dev/sda2</literal> is the system + encrypted TrueCrypt patition, <literal>/dev/sda</literal> + has to be given.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>timeout=</varname></term> - <listitem><para> This device will not - be automatically unlocked on - boot. </para></listitem> + <listitem><para>Specifies the timeout for + querying for a password. If no unit is + specified, seconds is used. Supported units are + s, ms, us, min, h, d. A timeout of 0 waits + indefinitely (which is the default).</para></listitem> </varlistentry> <varlistentry> - <term><varname>nofail</varname></term> + <term><varname>tmp</varname></term> + + <listitem><para>The encrypted block device will + be prepared for using it as <filename>/tmp</filename>; + it will be formatted using + <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + This option implies <varname>plain</varname>.</para> - <listitem><para>The system will not - wait for the device to show up and be - unlocked at boot, and not fail the - boot if it does not show - up.</para></listitem> + <para>WARNING: Using the <varname>tmp</varname> + option will destroy the contents of the named + partition during every boot, so make sure the + underlying block device is specified correctly.</para></listitem> </varlistentry> <varlistentry> - <term><varname>swap</varname></term> + <term><varname>tries=</varname></term> - <listitem><para> The encrypted block - device will be used as a swap - partition, and will be formatted as a - swap partition after setting up the - encrypted block device, with - <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - - <para>WARNING: Using the - <varname>swap</varname> option will - destroy the contents of the named - partition during every boot, so make - sure the underlying block device is - specified - correctly. </para></listitem> + <listitem><para>Specifies the maximum number of + times the user is queried for a password.</para></listitem> </varlistentry> <varlistentry> - <term><varname>tmp</varname></term> + <term><varname>verify</varname></term> - <listitem><para>The encrypted block - device will be prepared for using it - as <filename>/tmp</filename> - partition: it will be formatted using - <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - - <para>WARNING: Using the - <varname>tmp</varname> option will - destroy the contents of the named - partition during every boot, so make - sure the underlying block device is - specified - correctly. </para></listitem> + <listitem><para> If the encryption password is + read from console, it has to be entered twice to + prevent typos.</para></listitem> </varlistentry> + </variablelist> <para>At early boot and when the system manager @@ -291,12 +353,14 @@ <title>Example</title> <example> <title>/etc/crypttab example</title> - <para>Set up two encrypted block devices with - LUKS: one normal one for storage, and another - one for usage as swap device.</para> - - <programlisting>luks-2505567a-9e27-4efe-a4d5-15ad146c258b UUID=2505567a-9e27-4efe-a4d5-15ad146c258b - timeout=0 -swap /dev/sda7 /dev/urandom swap</programlisting> + <para>Set up four encrypted block devices. One using + LUKS for normal storage, another one for usage as a swap + device and two TrueCrypt volumes.</para> + + <programlisting>luks UUID=2505567a-9e27-4efe-a4d5-15ad146c258b +swap /dev/sda7 /dev/urandom swap +truecrypt /dev/sda2 /etc/container_password tcrypt +hidden /mnt/tc_hidden /null tcrypt-hidden,tcrypt-keyfile=/etc/keyfile</programlisting> </example> </refsect1> |