cryptsetup: Add tcrypt support

Tcrypt uses a different approach to passphrases/key files. The
passphrase and all key files are incorporated into the "password"
to open the volume. So, the idea of slots that provide a way to
open the volume with different passphrases/key files that are
independent from each other like with LUKS does not apply.

Therefore, we use the key file from /etc/crypttab as the source
for the passphrase. The actual key files that are combined with
the passphrase into a password are provided as a new option in
/etc/crypttab and can be given multiple times if more than one
key file is used by a volume.

1 files changed, 182 insertions, 118 deletions

diff --git a/man/crypttab.xml b/man/crypttab.xml
index e52b7e601..298f39e0e 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>