HALF ECHO LEARN / REFERENCE COLLECTION

v262.2

man/crypttab.xml

60,734 bytesGit mode 100644Download original fileLGPL-2.1-or-later

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>