The Red Hat version has been written by Miloslav Trmac <mitr@redhat.com>.
-->
-<refentry id="crypttab" conditional='HAVE_LIBCRYPTSETUP'>
+<refentry id="crypttab" conditional='HAVE_LIBCRYPTSETUP' xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>crypttab</title>
character are ignored. Each of the remaining lines describes one
encrypted block device. Fields are delimited by white space.</para>
- <para>Each line is in the form<programlisting><replaceable>name</replaceable> <replaceable>encrypted-device</replaceable> <replaceable>password</replaceable> <replaceable>options</replaceable></programlisting>
+ <para>Each line is in the form<programlisting><replaceable>volume-name</replaceable> <replaceable>encrypted-device</replaceable> <replaceable>key-file</replaceable> <replaceable>options</replaceable></programlisting>
The first two fields are mandatory, the remaining two are
optional.</para>
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 first field contains the name of the resulting encrypted volume; its block device is set up
+ below <filename>/dev/mapper/</filename>.</para>
<para>The second field contains a path to the underlying block
device or file, or a specification of a block device via
<literal>UUID=</literal> followed by the UUID.</para>
- <para>The third field specifies the encryption password. If the
- field is not present or the password 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 an 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 <filename>/dev/random</filename>
- may prevent boot completion if the system does not have enough
- entropy to generate a truly random encryption key.</para>
+ <para>The third field specifies an absolute path to a file to read the encryption key from. Optionally,
+ the path may be followed by <literal>:</literal> and an fstab device specification (e.g. starting with
+ <literal>LABEL=</literal> or similar); in which case, the path is relative to the device file system
+ root. If the field is not present or set to <literal>none</literal> or <literal>-</literal>, a key file
+ named after the volume to unlock (i.e. the first column of the line), suffixed with
+ <filename>.key</filename> is automatically loaded from the <filename>/etc/cryptsetup-keys.d/</filename>
+ and <filename>/run/cryptsetup-keys.d/</filename> directories, if present. Otherwise, the password has to
+ be manually entered during system boot. For swap encryption, <filename>/dev/urandom</filename> may be
+ used as key file.</para>
<para>The fourth field, if present, is a comma-delimited list of
options. The following options are recognized:</para>
size is then given by the key size.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>keyfile-erase</option></term>
+
+ <listitem><para>If enabled, the specified key file is erased after the volume is activated or when
+ activation fails. This is in particular useful when the key file is only acquired transiently before
+ activation (e.g. via a file in <filename>/run/</filename>, generated by a service running before
+ activation), and shall be removed after use. Defaults to off.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>key-slot=</option></term>
<option>size=</option>.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>bitlk</option></term>
+
+ <listitem><para>Decrypt Bitlocker drive. Encryption parameters
+ are deduced by cryptsetup from Bitlocker header.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>_netdev</option></term>
<listitem><para>Perform encryption using the same cpu that IO was submitted on. The default is to use
an unbound workqueue so that encryption work is automatically balanced between available CPUs.</para>
+
<para>This requires kernel 4.0 or newer.</para>
</listitem>
</varlistentry>
<term><option>submit-from-crypt-cpus</option></term>
<listitem><para>Disable offloading writes to a separate thread after encryption. There are some
- situations where offloading write bios from the encryption threads to a single thread degrades
- performance significantly. The default is to offload write bios to the same thread because it benefits
- CFQ to have writes submitted using the same context.</para>
+ situations where offloading write requests from the encryption threads to a dedicated thread degrades
+ performance significantly. The default is to offload write requests to a dedicated thread because it
+ benefits the CFQ scheduler to have writes submitted using the same context.</para>
+
<para>This requires kernel 4.0 or newer.</para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
- <term><option>tmp</option></term>
+ <term><option>tmp=</option></term>
- <listitem><para>The encrypted block device will be prepared
- for using it as <filename>/tmp</filename>; it will be
- formatted using
- <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
- This option implies <option>plain</option>.</para>
+ <listitem><para>The encrypted block device will be prepared for using it as
+ <filename>/tmp/</filename>; it will be formatted using <citerefentry
+ project='man-pages'><refentrytitle>mkfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
+ a file system type as argument, such as <literal>ext4</literal>, <literal>xfs</literal> or
+ <literal>btrfs</literal>. If no argument is specified defaults to <literal>ext4</literal>. This
+ option implies <option>plain</option>.</para>
- <para>WARNING: Using the <option>tmp</option> option will
- destroy the contents of the named partition during every boot,
- so make sure the underlying block device is specified
- correctly.</para></listitem>
+ <para>WARNING: Using the <option>tmp</option> 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>
<varlistentry>
<term><option>verify</option></term>
- <listitem><para> If the encryption password is read from
- console, it has to be entered twice to prevent
- typos.</para></listitem>
+ <listitem><para>If the encryption password is read from console, it has to be entered twice to
+ prevent typos.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>pkcs11-uri=</option></term>
+
+ <listitem><para>Takes a <ulink url="https://tools.ietf.org/html/rfc7512">RFC7512 PKCS#11 URI</ulink>
+ pointing to a private RSA key which is used to decrypt the key specified in the third column of the
+ line. This is useful for unlocking encrypted volumes through security tokens or smartcards. See below
+ for an example how to set up this mechanism for unlocking a LUKS volume with a YubiKey security
+ token. The specified URI can refer directly to a private RSA key stored on a token or alternatively
+ just to a slot or token, in which case a search for a suitable private RSA key will be performed. In
+ this case if multiple suitable objects are found the token is refused. The key configured in the
+ third column is passed as is to RSA decryption. The resulting decrypted key is then base64 encoded
+ before it is used to unlock the LUKS volume.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>try-empty-password=</option></term>
+
+ <listitem><para>Takes a boolean argument. If enabled, right before asking the user for a password it
+ is first attempted to unlock the volume with an empty password. This is useful for systems that are
+ initialized with an encrypted volume with only an empty password set, which shall be replaced with a
+ suitable password during first boot, but after activation.</para></listitem>
</varlistentry>
<varlistentry>
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<example>
<title>/etc/crypttab example</title>
<para>Set up four encrypted block devices. One using LUKS for
hidden /mnt/tc_hidden /dev/null tcrypt-hidden,tcrypt-keyfile=/etc/keyfile
external /dev/sda3 keyfile:LABEL=keydev keyfile-timeout=10s</programlisting>
</example>
+
+ <example>
+ <title>Yubikey-based Volume Unlocking Example</title>
+
+ <para>The PKCS#11 logic allows hooking up any compatible security token that is capable of storing RSA
+ decryption keys. Here's an example how to set up a Yubikey security token for this purpose, using
+ <citerefentry project='debian'><refentrytitle>ykmap</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ from the yubikey-manager project:</para>
+
+<programlisting><xi:include href="yubikey-crypttab.sh" parse="text" /></programlisting>
+
+<para>A few notes on the above:</para>
+
+<itemizedlist>
+ <listitem><para>We use RSA (and not ECC), since Yubikeys support PKCS#11 Decrypt() only for RSA keys</para></listitem>
+ <listitem><para>We use RSA2048, which is the longest key size current Yubikeys support</para></listitem>
+ <listitem><para>LUKS key size must be shorter than 2048bit due to RSA padding, hence we use 128 bytes</para></listitem>
+ <listitem><para>We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes,
+ <ulink url="https://developers.yubico.com/PIV/Introduction/Certificate_slots.html">see
+ documentation</ulink>.</para></listitem>
+</itemizedlist>
+
+ </example>
</refsect1>
<refsect1>
projects / thirdparty / systemd.git / blobdiff