]>
Commit | Line | Data |
---|---|---|
d0d6944c LP |
1 | <?xml version="1.0"?> |
2 | <!--*-nxml-*--> | |
3a54a157 ZJS |
3 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
4 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | |
db9ecf05 | 5 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
56ba3c78 | 6 | <refentry id="systemd-cryptsetup@.service" conditional='HAVE_LIBCRYPTSETUP'> |
d0d6944c | 7 | |
798d3a52 ZJS |
8 | <refentryinfo> |
9 | <title>systemd-cryptsetup@.service</title> | |
10 | <productname>systemd</productname> | |
798d3a52 | 11 | </refentryinfo> |
d0d6944c | 12 | |
798d3a52 ZJS |
13 | <refmeta> |
14 | <refentrytitle>systemd-cryptsetup@.service</refentrytitle> | |
15 | <manvolnum>8</manvolnum> | |
16 | </refmeta> | |
d0d6944c | 17 | |
798d3a52 ZJS |
18 | <refnamediv> |
19 | <refname>systemd-cryptsetup@.service</refname> | |
5c91fdf3 ZJS |
20 | <!-- <refname>system-systemd\x2dcryptsetup.slice</refname> — this causes meson to go haywire because it |
21 | thinks this is a (windows) path. Let's just not create the alias for this name, and only include it | |
22 | in the synopsis. --> | |
798d3a52 ZJS |
23 | <refname>systemd-cryptsetup</refname> |
24 | <refpurpose>Full disk decryption logic</refpurpose> | |
25 | </refnamediv> | |
d0d6944c | 26 | |
798d3a52 ZJS |
27 | <refsynopsisdiv> |
28 | <para><filename>systemd-cryptsetup@.service</filename></para> | |
5c91fdf3 | 29 | <para><filename>system-systemd\x2dcryptsetup.slice</filename></para> |
fb8d67cd | 30 | <para><filename>systemd-cryptsetup</filename></para> |
798d3a52 | 31 | </refsynopsisdiv> |
d0d6944c | 32 | |
798d3a52 ZJS |
33 | <refsect1> |
34 | <title>Description</title> | |
d0d6944c | 35 | |
5c91fdf3 ZJS |
36 | <para><filename>systemd-cryptsetup@.service</filename> is a service responsible for setting up encrypted |
37 | block devices. It is instantiated for each device that requires decryption for access.</para> | |
38 | ||
39 | <para><filename>systemd-cryptsetup@.service</filename> instances are part of the | |
40 | <filename>system-systemd\x2dcryptsetup.slice</filename> slice, which is destroyed only very late in the | |
41 | shutdown procedure. This allows the encrypted devices to remain up until filesystems have been unmounted. | |
42 | </para> | |
d0d6944c | 43 | |
798d3a52 ZJS |
44 | <para><filename>systemd-cryptsetup@.service</filename> will ask |
45 | for hard disk passwords via the <ulink | |
f856778b | 46 | url="https://systemd.io/PASSWORD_AGENTS/">password agent logic</ulink>, in |
47 | order to query the user for the password using the right mechanism at boot | |
48 | and during runtime.</para> | |
8e129f51 | 49 | |
c0cee5f1 LP |
50 | <para>At early boot and when the system manager configuration is reloaded, <filename>/etc/crypttab</filename> is |
51 | translated into <filename>systemd-cryptsetup@.service</filename> units by | |
798d3a52 | 52 | <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> |
6e41f4dd LP |
53 | |
54 | <para>In order to unlock a volume a password or binary key is | |
55 | required. <filename>systemd-cryptsetup@.service</filename> tries to acquire a suitable password or binary | |
56 | key via the following mechanisms, tried in order:</para> | |
57 | ||
58 | <orderedlist> | |
59 | <listitem><para>If a key file is explicitly configured (via the third column in | |
cf1e172d LP |
60 | <filename>/etc/crypttab</filename>), a key read from it is used. If a PKCS#11 token, FIDO2 token or |
61 | TPM2 device is configured (using the <varname>pkcs11-uri=</varname>, <varname>fido2-device=</varname>, | |
62 | <varname>tpm2-device=</varname> options) the key is decrypted before use.</para></listitem> | |
6e41f4dd LP |
63 | |
64 | <listitem><para>If no key file is configured explicitly this way, a key file is automatically loaded | |
65 | from <filename>/etc/cryptsetup-keys.d/<replaceable>volume</replaceable>.key</filename> and | |
66 | <filename>/run/cryptsetup-keys.d/<replaceable>volume</replaceable>.key</filename>, if present. Here | |
cf1e172d | 67 | too, if a PKCS#11/FIDO2/TPM2 token/device is configured, any key found this way is decrypted before |
6e41f4dd LP |
68 | use.</para></listitem> |
69 | ||
70 | <listitem><para>If the <varname>try-empty-password</varname> option is specified it is then attempted | |
71 | to unlock the volume with an empty password.</para></listitem> | |
72 | ||
73 | <listitem><para>The kernel keyring is then checked for a suitable cached password from previous | |
74 | attempts.</para></listitem> | |
75 | ||
cd5f57bd LB |
76 | <listitem><para>Finally, the user is queried for a password, possibly multiple times, unless |
77 | the <varname>headless</varname> option is set.</para></listitem> | |
6e41f4dd LP |
78 | </orderedlist> |
79 | ||
80 | <para>If no suitable key may be acquired via any of the mechanisms describes above, volume activation fails.</para> | |
798d3a52 | 81 | </refsect1> |
d0d6944c | 82 | |
798d3a52 ZJS |
83 | <refsect1> |
84 | <title>See Also</title> | |
85 | <para> | |
86 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
87 | <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
88 | <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
cf1e172d | 89 | <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
3ba3a79d | 90 | <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
798d3a52 ZJS |
91 | </para> |
92 | </refsect1> | |
d0d6944c LP |
93 | |
94 | </refentry> |