3 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
4 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
6 <refentry id=
"systemd-cryptsetup@.service" conditional='HAVE_LIBCRYPTSETUP'
>
9 <title>systemd-cryptsetup@.service
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>systemd-cryptsetup@.service
</refentrytitle>
15 <manvolnum>8</manvolnum>
19 <refname>systemd-cryptsetup@.service
</refname>
20 <refname>systemd-cryptsetup
</refname>
21 <refpurpose>Full disk decryption logic
</refpurpose>
25 <para><filename>systemd-cryptsetup@.service
</filename></para>
26 <para><filename>/usr/lib/systemd/systemd-cryptsetup
</filename></para>
30 <title>Description
</title>
32 <para><filename>systemd-cryptsetup@.service
</filename> is a
33 service responsible for setting up encrypted block devices. It is
34 instantiated for each device that requires decryption for
37 <para><filename>systemd-cryptsetup@.service
</filename> will ask
38 for hard disk passwords via the
<ulink
39 url=
"https://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">
40 password agent logic
</ulink>, in order to query the user for the
41 password using the right mechanism at boot and during
44 <para>At early boot and when the system manager configuration is reloaded,
<filename>/etc/crypttab
</filename> is
45 translated into
<filename>systemd-cryptsetup@.service
</filename> units by
46 <citerefentry><refentrytitle>systemd-cryptsetup-generator
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
48 <para>In order to unlock a volume a password or binary key is
49 required.
<filename>systemd-cryptsetup@.service
</filename> tries to acquire a suitable password or binary
50 key via the following mechanisms, tried in order:
</para>
53 <listitem><para>If a key file is explicitly configured (via the third column in
54 <filename>/etc/crypttab
</filename>), a key read from it is used. If a PKCS#
11 token is configured
55 (using the
<varname>pkcs11-uri=
</varname> option) the key is decrypted before use.
</para></listitem>
57 <listitem><para>If no key file is configured explicitly this way, a key file is automatically loaded
58 from
<filename>/etc/cryptsetup-keys.d/
<replaceable>volume
</replaceable>.key
</filename> and
59 <filename>/run/cryptsetup-keys.d/
<replaceable>volume
</replaceable>.key
</filename>, if present. Here
60 too, if a PKCS#
11 token is configured, any key found this way is decrypted before
61 use.
</para></listitem>
63 <listitem><para>If the
<varname>try-empty-password
</varname> option is specified it is then attempted
64 to unlock the volume with an empty password.
</para></listitem>
66 <listitem><para>The kernel keyring is then checked for a suitable cached password from previous
67 attempts.
</para></listitem>
69 <listitem><para>Finally, the user is queried for a password, possibly multiple times.
</para></listitem>
72 <para>If no suitable key may be acquired via any of the mechanisms describes above, volume activation fails.
</para>
76 <title>See Also
</title>
78 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
79 <citerefentry><refentrytitle>systemd-cryptsetup-generator
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
80 <citerefentry><refentrytitle>crypttab
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
81 <citerefentry project='die-net'
><refentrytitle>cryptsetup
</refentrytitle><manvolnum>8</manvolnum></citerefentry>