HALF ECHO LEARN / REFERENCE COLLECTION
v262.2man/crypttab.xml
Git blob: 2e93e11d26ec7301c8ebaa5f117aa43e5d59b717
Lines 1001–1158 of 1,158
<listitem><para>Setup this encrypted block device in the initrd, similarly to
<citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
units marked with <option>x-initrd.mount</option>.</para>
<para>Although it is not necessary to mark the mount entry for the root file system with
<option>x-initrd.mount</option>, <option>x-initrd.attach</option> is still recommended with
the encrypted block device containing the root file system as otherwise systemd will
attempt to detach the device during the regular system shutdown while it is still in
use. With this option the device will still be detached but later after the root file
system is unmounted.</para>
<para>All other encrypted block devices that contain file systems mounted in the initrd should use
this option.</para>
<xi:include href="version-info.xml" xpointer="v245"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>fixate-volume-key=</option></term>
<listitem><para>Pin the expected hash of the volume key.</para>
<para>In certain cases, e.g. for LUKS volumes where the key is sealed to the TPM2, this may be required
to provide a guarantee that the volume being attached is the volume which was previously created.
<option>fixate-volume-key=</option> can be used to set the expected volume key hash and refuse to attach the volume
if it has a different one. The expected hash matches the digest which is measured to the sha256 PCR bank of the
TPM2 when <option>tpm2-measure-pcr=</option> is used.</para>
<para>For newly created LUKS volumes, the expected hash can be generated by
<citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
For additional details, see the <option>EncryptedVolume=</option> description at
<citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v260"/>
</listitem>
</varlistentry>
</variablelist>
<para>At early boot and when the system manager configuration is
reloaded, this file is translated into native systemd units by
<citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
</refsect1>
<refsect1>
<title><constant>AF_UNIX</constant> Key Files</title>
<para>If the key file path (as specified in the third column of <filename>/etc/crypttab</filename>
entries, see above) refers to an <constant>AF_UNIX</constant> stream socket in the file system, the key
is acquired by connecting to the socket and reading the key from the connection. The connection is made
from an <constant>AF_UNIX</constant> socket name in the abstract namespace, see <citerefentry
project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
details. The source socket name is chosen according to the following format:</para>
<programlisting><constant>NUL</constant> <replaceable>RANDOM</replaceable> /cryptsetup/ <replaceable>VOLUME</replaceable></programlisting>
<para>In other words: a <constant>NUL</constant> byte (as required for abstract namespace sockets),
followed by a random string (consisting of alphanumeric characters only), followed by the literal
string <literal>/cryptsetup/</literal>, followed by the name of the volume to acquire they key
for. For example, for the volume <literal>myvol</literal>:</para>
<programlisting>\0d7067f78d9827418/cryptsetup/myvol</programlisting>
<para>Services listening on the <constant>AF_UNIX</constant> stream socket may query the source socket
name with <citerefentry
project='man-pages'><refentrytitle>getpeername</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
and use this to determine which key to send, allowing a single listening socket to serve keys for
multiple volumes. If the PKCS#11 logic is used (see above), the socket source name is picked in similar
fashion, except that the literal string <literal>/cryptsetup-pkcs11/</literal> is used. And similarly for
FIDO2 (<literal>/cryptsetup-fido2-salt/</literal>) and TPM2 (<literal>/cryptsetup-tpm2/</literal>).
A different path component is used so that services providing key material know that the secret key was
not requested directly, but instead an encrypted key that will be decrypted via the PKCS#11/FIDO2/TPM2
logic to acquire the final secret key.</para>
</refsect1>
<refsect1>
<title>Examples</title>
<example>
<title>/etc/crypttab example</title>
<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. For the fourth device, the option string is interpreted as two
options <literal>cipher=xchacha12,aes-adiantum-plain64</literal>,
<literal>keyfile-timeout=10s</literal>.</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 /dev/null tcrypt-hidden,tcrypt-keyfile=/etc/keyfile
external /dev/sda3 keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchacha12\,aes-adiantum-plain64
</programlisting>
</example>
<example>
<title>Yubikey-based PKCS#11 Volume Unlocking Example</title>
<para>The PKCS#11 logic allows hooking up any compatible security token that is capable of storing RSA
or EC cryptographic keys for unlocking an encrypted volume. Here's an example how to set up a Yubikey
security token for this purpose on a LUKS2 volume, using <citerefentry
project='debian'><refentrytitle>ykmap</refentrytitle><manvolnum>1</manvolnum></citerefentry> from the
yubikey-manager project to initialize the token and
<citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
to add it in the LUKS2 volume:</para>
<programlisting><xi:include href="yubikey-crypttab.sh" parse="text" /></programlisting>
<para>A few notes on the above:</para>
<itemizedlist>
<listitem><para>We use RSA2048, which is the longest key size current Yubikeys support</para></listitem>
<listitem><para>We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes,
see
<ulink url="https://developers.yubico.com/PIV/Introduction/Certificate_slots.html">Yubico PIV certificate slots</ulink>.
</para></listitem>
</itemizedlist>
</example>
<example>
<title>FIDO2 Volume Unlocking Example</title>
<para>The FIDO2 logic allows using any compatible FIDO2 security token that implements the
<literal>hmac-secret</literal> extension for unlocking an encrypted volume. Here's an example how to
set up a FIDO2 security token for this purpose for a LUKS2 volume, using
<citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>:</para>
<programlisting><xi:include href="fido2-crypttab.sh" parse="text" /></programlisting>
</example>
<example>
<title>TPM2 Volume Unlocking Example</title>
<para>The TPM2 logic allows using any TPM2 chip supported by the Linux kernel for unlocking an
encrypted volume. Here's an example how to set up a TPM2 chip for this purpose for a LUKS2 volume,
using
<citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>:</para>
<programlisting><xi:include href="tpm2-crypttab.sh" parse="text" /></programlisting>
</example>
</refsect1>
<refsect1>
<title>See Also</title>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
</refentry>