| <?xml version="1.0"?> |
| <!--*-nxml-*--> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
| <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
| <refentry id="systemd-cryptsetup@.service" conditional='HAVE_LIBCRYPTSETUP'> |
| |
| <refentryinfo> |
| <title>systemd-cryptsetup@.service</title> |
| <productname>systemd</productname> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>systemd-cryptsetup@.service</refentrytitle> |
| <manvolnum>8</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>systemd-cryptsetup@.service</refname> |
| <!-- <refname>system-systemd\x2dcryptsetup.slice</refname> — this causes meson to go haywire because it |
| thinks this is a (windows) path. Let's just not create the alias for this name, and only include it |
| in the synopsis. --> |
| <refname>systemd-cryptsetup</refname> |
| <refpurpose>Full disk decryption logic</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <para><filename>systemd-cryptsetup@.service</filename></para> |
| <para><filename>system-systemd\x2dcryptsetup.slice</filename></para> |
| <para><filename>/usr/lib/systemd/systemd-cryptsetup</filename></para> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para><filename>systemd-cryptsetup@.service</filename> is a service responsible for setting up encrypted |
| block devices. It is instantiated for each device that requires decryption for access.</para> |
| |
| <para><filename>systemd-cryptsetup@.service</filename> instances are part of the |
| <filename>system-systemd\x2dcryptsetup.slice</filename> slice, which is destroyed only very late in the |
| shutdown procedure. This allows the encrypted devices to remain up until filesystems have been unmounted. |
| </para> |
| |
| <para><filename>systemd-cryptsetup@.service</filename> will ask |
| for hard disk passwords via the <ulink |
| url="https://systemd.io/PASSWORD_AGENTS/">password agent logic</ulink>, in |
| order to query the user for the password using the right mechanism at boot |
| and during runtime.</para> |
| |
| <para>At early boot and when the system manager configuration is reloaded, <filename>/etc/crypttab</filename> is |
| translated into <filename>systemd-cryptsetup@.service</filename> units by |
| <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> |
| |
| <para>In order to unlock a volume a password or binary key is |
| required. <filename>systemd-cryptsetup@.service</filename> tries to acquire a suitable password or binary |
| key via the following mechanisms, tried in order:</para> |
| |
| <orderedlist> |
| <listitem><para>If a key file is explicitly configured (via the third column in |
| <filename>/etc/crypttab</filename>), a key read from it is used. If a PKCS#11 token, FIDO2 token or |
| TPM2 device is configured (using the <varname>pkcs11-uri=</varname>, <varname>fido2-device=</varname>, |
| <varname>tpm2-device=</varname> options) the key is decrypted before use.</para></listitem> |
| |
| <listitem><para>If no key file is configured explicitly this way, a key file is automatically loaded |
| from <filename>/etc/cryptsetup-keys.d/<replaceable>volume</replaceable>.key</filename> and |
| <filename>/run/cryptsetup-keys.d/<replaceable>volume</replaceable>.key</filename>, if present. Here |
| too, if a PKCS#11/FIDO2/TPM2 token/device is configured, any key found this way is decrypted before |
| use.</para></listitem> |
| |
| <listitem><para>If the <varname>try-empty-password</varname> option is specified it is then attempted |
| to unlock the volume with an empty password.</para></listitem> |
| |
| <listitem><para>The kernel keyring is then checked for a suitable cached password from previous |
| attempts.</para></listitem> |
| |
| <listitem><para>Finally, the user is queried for a password, possibly multiple times, unless |
| the <varname>headless</varname> option is set.</para></listitem> |
| </orderedlist> |
| |
| <para>If no suitable key may be acquired via any of the mechanisms describes above, volume activation fails.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| <para> |
| <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| </para> |
| </refsect1> |
| |
| </refentry> |