2012-06-27 14:19:35 +04:00
<?xml version="1.0"?>
<!-- * - nxml - * -->
2019-03-14 16:40:58 +03:00
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
2020-11-09 07:23:58 +03:00
<!-- SPDX - License - Identifier: LGPL - 2.1 - or - later -->
2013-02-03 07:47:47 +04:00
<refentry id= "systemd-cryptsetup@.service" conditional= 'HAVE_LIBCRYPTSETUP' >
2012-06-27 14:19:35 +04:00
2015-02-04 05:14:13 +03:00
<refentryinfo >
<title > systemd-cryptsetup@.service</title>
<productname > systemd</productname>
</refentryinfo>
2012-06-27 14:19:35 +04:00
2015-02-04 05:14:13 +03:00
<refmeta >
<refentrytitle > systemd-cryptsetup@.service</refentrytitle>
<manvolnum > 8</manvolnum>
</refmeta>
2012-06-27 14:19:35 +04:00
2015-02-04 05:14:13 +03:00
<refnamediv >
<refname > systemd-cryptsetup@.service</refname>
2021-04-09 10:27:42 +03:00
<!-- <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. -->
2015-02-04 05:14:13 +03:00
<refname > systemd-cryptsetup</refname>
<refpurpose > Full disk decryption logic</refpurpose>
</refnamediv>
2012-06-27 14:19:35 +04:00
2015-02-04 05:14:13 +03:00
<refsynopsisdiv >
<para > <filename > systemd-cryptsetup@.service</filename> </para>
2021-04-09 10:27:42 +03:00
<para > <filename > system-systemd\x2dcryptsetup.slice</filename> </para>
2023-09-22 19:47:05 +03:00
<para > <filename > systemd-cryptsetup</filename> </para>
2015-02-04 05:14:13 +03:00
</refsynopsisdiv>
2012-06-27 14:19:35 +04:00
2015-02-04 05:14:13 +03:00
<refsect1 >
<title > Description</title>
2012-06-27 14:19:35 +04:00
2021-04-09 10:27:42 +03:00
<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>
2012-06-27 14:19:35 +04:00
2015-02-04 05:14:13 +03:00
<para > <filename > systemd-cryptsetup@.service</filename> will ask
for hard disk passwords via the <ulink
2020-09-29 16:10:08 +03:00
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>
2012-06-27 16:51:47 +04:00
2016-12-16 15:01:03 +03:00
<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
2015-02-04 05:14:13 +03:00
<citerefentry > <refentrytitle > systemd-cryptsetup-generator</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> .</para>
2020-04-30 00:10:22 +03:00
<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
2020-12-07 19:18:52 +03:00
<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>
2020-04-30 00:10:22 +03:00
<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
2020-12-07 19:18:52 +03:00
too, if a PKCS#11/FIDO2/TPM2 token/device is configured, any key found this way is decrypted before
2020-04-30 00:10:22 +03:00
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>
2021-04-09 22:43:10 +03:00
<listitem > <para > Finally, the user is queried for a password, possibly multiple times, unless
the <varname > headless</varname> option is set.</para> </listitem>
2020-04-30 00:10:22 +03:00
</orderedlist>
<para > If no suitable key may be acquired via any of the mechanisms describes above, volume activation fails.</para>
2015-02-04 05:14:13 +03:00
</refsect1>
2012-06-27 14:19:35 +04:00
2015-02-04 05:14:13 +03:00
<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> ,
2020-12-07 19:18:52 +03:00
<citerefentry > <refentrytitle > systemd-cryptenroll</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> ,
2015-03-14 05:22:39 +03:00
<citerefentry project= 'die-net' > <refentrytitle > cryptsetup</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry>
2015-02-04 05:14:13 +03:00
</para>
</refsect1>
2012-06-27 14:19:35 +04:00
</refentry>