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 -->
2023-09-23 14:43:55 +03:00
<refentry id= "systemd-cryptsetup" conditional= 'HAVE_LIBCRYPTSETUP' >
2012-06-27 14:19:35 +04:00
2015-02-04 05:14:13 +03:00
<refentryinfo >
2023-09-23 14:43:55 +03:00
<title > systemd-cryptsetup</title>
2015-02-04 05:14:13 +03:00
<productname > systemd</productname>
</refentryinfo>
2012-06-27 14:19:35 +04:00
2015-02-04 05:14:13 +03:00
<refmeta >
2023-09-23 14:43:55 +03:00
<refentrytitle > systemd-cryptsetup</refentrytitle>
2015-02-04 05:14:13 +03:00
<manvolnum > 8</manvolnum>
</refmeta>
2012-06-27 14:19:35 +04:00
2015-02-04 05:14:13 +03:00
<refnamediv >
2023-09-23 14:43:55 +03:00
<refname > systemd-cryptsetup</refname>
2015-02-04 05:14:13 +03:00
<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
<refpurpose > Full disk decryption logic</refpurpose>
</refnamediv>
2012-06-27 14:19:35 +04:00
2015-02-04 05:14:13 +03:00
<refsynopsisdiv >
2023-09-23 14:43:55 +03:00
<cmdsynopsis >
<command > systemd-cryptsetup</command>
<arg choice= "opt" rep= "repeat" > OPTIONS</arg>
<arg choice= "plain" > attach</arg>
<arg choice= "plain" > VOLUME</arg>
<arg choice= "plain" > SOURCE-DEVICE</arg>
<arg choice= "opt" > KEY-FILE</arg>
<arg choice= "opt" > CONFIG</arg>
</cmdsynopsis>
<cmdsynopsis >
<command > systemd-cryptsetup</command>
<arg choice= "opt" rep= "repeat" > OPTIONS</arg>
<arg choice= "plain" > detach</arg>
<arg choice= "plain" > VOLUME</arg>
</cmdsynopsis>
2015-02-04 05:14:13 +03:00
<para > <filename > systemd-cryptsetup@.service</filename> </para>
2021-04-09 10:27:42 +03:00
<para > <filename > system-systemd\x2dcryptsetup.slice</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
2023-09-23 14:43:55 +03:00
<para > <filename > systemd-cryptsetup</filename> is used to set up (with <command > attach</command> ) and tear
down (with <command > detach</command> ) access to an encrypted block device. It is primarily used via
<filename > systemd-cryptsetup@.service</filename> during early boot, but may also be be called manually.
The positional arguments <parameter > VOLUME</parameter> , <parameter > SOURCEDEVICE</parameter> ,
<parameter > KEY-FILE</parameter> , and <parameter > CRYPTTAB-OPTIONS</parameter> have the same meaning as the
fields in <citerefentry > <refentrytitle > crypttab</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry> .
</para>
<para > <filename > systemd-cryptsetup@.service</filename> is a service responsible for providing access to
encrypted block devices. It is instantiated for each device that requires decryption.</para>
2021-04-09 10:27:42 +03:00
<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
2023-09-23 14:43:55 +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>
2020-04-30 00:10:22 +03:00
<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>
2023-09-23 14:43:55 +03:00
<listitem > <para > If the <varname > try-empty-password</varname> option is specified then unlocking the
volume with an empty password is attempted.</para> </listitem>
2020-04-30 00:10:22 +03:00
<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> ,
2023-10-02 21:49:04 +03:00
<citerefentry project= 'die-net' > <refentrytitle > cryptsetup</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> ,
<ulink url= "https://systemd.io/TPM2_PCR_MEASUREMENTS" > TPM2 PCR Measurements Made by systemd</ulink>
2015-02-04 05:14:13 +03:00
</para>
</refsect1>
2012-06-27 14:19:35 +04:00
</refentry>