[thirdparty/systemd.git] / man / systemd-cryptenroll.xml

<?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-cryptenroll" xmlns:xi="http://www.w3.org/2001/XInclude" conditional='HAVE_LIBCRYPTSETUP'>

  <refentryinfo>
    <title>systemd-cryptenroll</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>systemd-cryptenroll</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>systemd-cryptenroll</refname>
    <refpurpose>Enroll PKCS#11, FIDO2, TPM2 token/devices to LUKS2 encrypted volumes</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>systemd-cryptenroll <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">DEVICE</arg></command>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><command>systemd-cryptenroll</command> is a tool for enrolling hardware security tokens and devices into a
    LUKS2 encrypted volume, which may then be used to unlock the volume during boot. Specifically, it supports
    tokens and credentials of the following kind to be enrolled:</para>

    <orderedlist>
      <listitem><para>PKCS#11 security tokens and smartcards that may carry an RSA key pair (e.g. various YubiKeys)</para></listitem>

      <listitem><para>FIDO2 security tokens that implement the <literal>hmac-secret</literal> extension (most FIDO2 keys, including YubiKeys)</para></listitem>

      <listitem><para>TPM2 security devices</para></listitem>

      <listitem><para>Recovery keys. These are similar to regular passphrases, however are randomly generated
      on the computer and thus generally have higher entropy than user chosen passphrases. Their character
      set has been designed to ensure they are easy to type in, while having high entropy. They may also be
      scanned off screen using QR codes. Recovery keys may be used for unlocking LUKS2 volumes wherever
      passphrases are accepted. They are intended to be used in combination with an enrolled hardware
      security token, as a recovery option when the token is lost.</para></listitem>

      <listitem><para>Regular passphrases</para></listitem>
    </orderedlist>

    <para>In addition, the tool may be used to enumerate currently enrolled security tokens and wipe a subset
    of them. The latter may be combined with the enrollment operation of a new security token, in order to
    update or replace enrollments.</para>

    <para>The tool supports only LUKS2 volumes, as it stores token meta-information in the LUKS2 JSON token
    area, which is not available in other encryption formats.</para>
  </refsect1>

  <refsect1>
    <title>Options</title>

    <para>The following options are understood:</para>

    <variablelist>
      <varlistentry>
        <term><option>--password</option></term>

        <listitem><para>Enroll a regular password/passphrase. This command is mostly equivalent to
        <command>cryptsetup luksAddKey</command>, however may be combined with
        <option>--wipe-slot=</option> in one call, see below.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--recovery-key</option></term>

        <listitem><para>Enroll a recovery key. Recovery keys are most identical to passphrases, but are
        computer generated instead of human chosen, and thus have a guaranteed high entropy. The key uses a
        character set that is easy to type in, and may be scanned off screen via a QR code.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--pkcs11-token-uri=</option><replaceable>URI</replaceable></term>

        <listitem><para>Enroll a PKCS#11 security token or smartcard (e.g. a YubiKey). Expects a PKCS#11
        smart card URI referring to the token. Alternatively the special value <literal>auto</literal> may
        be specified, in order to automatically determine the URI of a currently plugged in security token
        (of which there must be exactly one). The special value <literal>list</literal> may be used to
        enumerate all suitable PKCS#11 tokens currently plugged in. The security token must contain an RSA
        key pair which is used to encrypt the randomly generated key that is used to unlock the LUKS2
        volume. The encrypted key is then stored in the LUKS2 JSON token header area.</para>

        <para>In order to unlock a LUKS2 volume with an enrolled PKCS#11 security token, specify the
        <option>pkcs11-uri=</option> option in the respective <filename>/etc/crypttab</filename> line:</para>

        <programlisting>myvolume /dev/sda1 - pkcs11-uri=auto</programlisting>

        <para>See
        <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a
        more comprehensive example of a <command>systemd-cryptenroll</command> invocation and its matching
        <filename>/etc/crypttab</filename> line.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--fido2-device=</option><replaceable>PATH</replaceable></term>

        <listitem><para>Enroll a FIDO2 security token that implements the <literal>hmac-secret</literal>
        extension (e.g. a YubiKey). Expects a <filename>hidraw</filename> device referring to the FIDO2
        device (e.g. <filename>/dev/hidraw1</filename>). Alternatively the special value
        <literal>auto</literal> may be specified, in order to automatically determine the device node of a
        currently plugged in security token (of which there must be exactly one). The special value
        <literal>list</literal> may be used to enumerate all suitable FIDO2 tokens currently plugged in. Note
        that many hardware security tokens that implement FIDO2 also implement the older PKCS#11
        standard. Typically FIDO2 is preferable, given it's simpler to use and more modern.</para>

        <para>In order to unlock a LUKS2 volume with an enrolled FIDO2 security token, specify the
        <option>fido2-device=</option> option in the respective <filename>/etc/crypttab</filename> line:</para>

        <programlisting>myvolume /dev/sda1 - fido2-device=auto</programlisting>

        <para>See
        <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a
        more comprehensive example of a <command>systemd-cryptenroll</command> invocation and its matching
        <filename>/etc/crypttab</filename> line.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--tpm2-device=</option><replaceable>PATH</replaceable></term>

        <listitem><para>Enroll a TPM2 security chip. Expects a device node path referring to the TPM2 chip
        (e.g. <filename>/dev/tpmrm0</filename>). Alternatively the special value <literal>auto</literal> may
        be specified, in order to automatically determine the device node of a currently discovered TPM2
        device (of which there must be exactly one). The special value <literal>list</literal> may be used to
        enumerate all suitable TPM2 devices currently discovered.</para>

        <para>In order to unlock a LUKS2 volume with an enrolled TPM2 security chip, specify the
        <option>tpm2-device=</option> option in the respective <filename>/etc/crypttab</filename> line:</para>

        <programlisting>myvolume /dev/sda1 - tpm2-device=auto</programlisting>

        <para>See
        <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a
        more comprehensive example of a <command>systemd-cryptenroll</command> invocation and its matching
        <filename>/etc/crypttab</filename> line.</para>

        <para>Use <option>--tpm2-pcrs=</option> (see below) to configure which TPM2 PCR indexes to bind the
        enrollment to.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--tpm2-pcrs=</option><arg rep="repeat">PCR</arg></term>

        <listitem><para>Configures the TPM2 PCRs (Platform Configuration Registers) to bind the enrollment
        requested via <option>--tpm2-device=</option> to. Takes a comma separated list of numeric PCR indexes
        in the range 0…23. If not used, defaults to PCR 7 only. If an empty string is specified, binds the
        enrollment to no PCRs at all. PCRs allow binding the enrollment to specific software versions and
        system state, so that the enrolled unlocking key is only accessible (may be "unsealed") if specific
        trusted software and/or configuration is used.</para></listitem>

        <table>
          <title>Well-known PCR Definitions</title>

          <tgroup cols='2' align='left' colsep='1' rowsep='1'>
            <colspec colname="pcr" />
            <colspec colname="definition" />

            <thead>
              <row>
                <entry>PCR</entry>
                <entry>Explanation</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>0</entry>
                <entry>Core system firmware executable code; changes on firmware updates</entry>
              </row>

              <row>
                <entry>1</entry>
                <entry>Core system firmware data/host platform configuration; typically contains serial and model numbers, changes on basic hardware/CPU/RAM replacements</entry>
              </row>

              <row>
                <entry>2</entry>
                <entry>Extended or pluggable executable code; includes option ROMs on pluggable hardware</entry>
              </row>

              <row>
                <entry>3</entry>
                <entry>Extended or pluggable firmware data; includes information about pluggable hardware</entry>
              </row>

              <row>
                <entry>4</entry>
                <entry>Boot loader; changes on boot loader updates</entry>
              </row>

              <row>
                <entry>5</entry>
                <entry>GPT/Partition table; changes when the partitions are added, modified or removed</entry>
              </row>

              <row>
                <entry>6</entry>
                <entry>Power state events; changes on system suspend/sleep</entry>
              </row>

              <row>
                <entry>7</entry>
                <entry>Secure boot state; changes when UEFI SecureBoot mode is enabled/disabled</entry>
              </row>

              <row>
                <entry>8</entry>
                <entry><citerefentry><refentrytitle>sd-boot</refentrytitle><manvolnum>8</manvolnum></citerefentry> measures the kernel command line in this PCR.</entry>
              </row>
            </tbody>
          </tgroup>
        </table>

      </varlistentry>

      <varlistentry>
        <term><option>--wipe-slot=</option><arg rep="repeat">SLOT</arg></term>

        <listitem><para>Wipes one or more LUKS2 key slots. Takes a comma separated list of numeric slot
        indexes, or the special strings <literal>all</literal> (for wiping all key slots),
        <literal>empty</literal> (for wiping all key slots that are unlocked by an empty passphrase),
        <literal>password</literal> (for wiping all key slots that are unlocked by a traditional passphrase),
        <literal>recovery</literal> (for wiping all key slots that are unlocked by a recovery key),
        <literal>pkcs11</literal> (for wiping all key slots that are unlocked by a PKCS#11 token),
        <literal>fido2</literal> (for wiping all key slots that are unlocked by a FIDO2 token),
        <literal>tpm2</literal> (for wiping all key slots that are unlocked by a TPM2 chip), or any
        combination of these strings or numeric indexes, in which case all slots matching either are
        wiped. As safety precaution an operation that wipes all slots without exception (so that the volume
        cannot be unlocked at all anymore, unless the volume key is known) is refused.</para>

        <para>This switch may be used alone, in which case only the requested wipe operation is executed. It
        may also be used in combination with any of the enrollment options listed above, in which case the
        enrollment is completed first, and only when successful the wipe operation executed — and the newly
        added slot is always excluded from the wiping. Combining enrollment and slot wiping may thus be used to
        update existing enrollments:</para>

        <programlisting>systemd-cryptenroll /dev/sda1 --wipe-slot=tpm2 --tpm2-device=auto</programlisting>

        <para>The above command will enroll the TPM2 chip, and then wipe all previously crated TPM2
        enrollments on the LUKS2 volume, leaving only the newly created one. Combining wiping and enrollment
        may also be used to replace enrollments of different types, for example for changing from a PKCS#11
        enrollment to a FIDO2 one:</para>

        <programlisting>systemd-cryptenroll /dev/sda1 --wipe-slot=pkcs11 --fido2-device=auto</programlisting>

        <para>Or for replacing an enrolled empty password by TPM2:</para>

        <programlisting>systemd-cryptenroll /dev/sda1 --wipe-slot=empty --tpm2-device=auto</programlisting>
        </listitem>
      </varlistentry>

      <xi:include href="standard-options.xml" xpointer="help" />
      <xi:include href="standard-options.xml" xpointer="version" />
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Exit status</title>

    <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     </para>
  </refsect1>

</refentry>
Commit	Line	Data
cf1e172d LP	1	<?xml version="1.0"?>
	2	<!---nxml--->
	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-or-later -->
	6	<refentry id="systemd-cryptenroll" xmlns:xi="http://www.w3.org/2001/XInclude" conditional='HAVE_LIBCRYPTSETUP'>
	7
	8	<refentryinfo>
	9	<title>systemd-cryptenroll</title>
	10	<productname>systemd</productname>
	11	</refentryinfo>
	12
	13	<refmeta>
	14	<refentrytitle>systemd-cryptenroll</refentrytitle>
	15	<manvolnum>1</manvolnum>
	16	</refmeta>
	17
	18	<refnamediv>
	19	<refname>systemd-cryptenroll</refname>
	20	<refpurpose>Enroll PKCS#11, FIDO2, TPM2 token/devices to LUKS2 encrypted volumes</refpurpose>
	21	</refnamediv>
	22
	23	<refsynopsisdiv>
	24	<cmdsynopsis>
	25	<command>systemd-cryptenroll <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">DEVICE</arg></command>
	26	</cmdsynopsis>
	27	</refsynopsisdiv>
	28
	29	<refsect1>
	30	<title>Description</title>
	31
	32	<para><command>systemd-cryptenroll</command> is a tool for enrolling hardware security tokens and devices into a
	33	LUKS2 encrypted volume, which may then be used to unlock the volume during boot. Specifically, it supports
	34	tokens and credentials of the following kind to be enrolled:</para>
	35
	36	<orderedlist>
	37	<listitem><para>PKCS#11 security tokens and smartcards that may carry an RSA key pair (e.g. various YubiKeys)</para></listitem>
	38
	39	<listitem><para>FIDO2 security tokens that implement the <literal>hmac-secret</literal> extension (most FIDO2 keys, including YubiKeys)</para></listitem>
	40
	41	<listitem><para>TPM2 security devices</para></listitem>
	42
	43	<listitem><para>Recovery keys. These are similar to regular passphrases, however are randomly generated
	44	on the computer and thus generally have higher entropy than user chosen passphrases. Their character
	45	set has been designed to ensure they are easy to type in, while having high entropy. They may also be
	46	scanned off screen using QR codes. Recovery keys may be used for unlocking LUKS2 volumes wherever
	47	passphrases are accepted. They are intended to be used in combination with an enrolled hardware
	48	security token, as a recovery option when the token is lost.</para></listitem>
	49
	50	<listitem><para>Regular passphrases</para></listitem>
	51	</orderedlist>
	52
	53	<para>In addition, the tool may be used to enumerate currently enrolled security tokens and wipe a subset
	54	of them. The latter may be combined with the enrollment operation of a new security token, in order to
	55	update or replace enrollments.</para>
	56
	57	<para>The tool supports only LUKS2 volumes, as it stores token meta-information in the LUKS2 JSON token
	58	area, which is not available in other encryption formats.</para>
	59	</refsect1>
	60
	61	<refsect1>
	62	<title>Options</title>
	63
	64	<para>The following options are understood:</para>
65
66	<variablelist>
67	<varlistentry>
68	<term><option>--password</option></term>
69
70	<listitem><para>Enroll a regular password/passphrase. This command is mostly equivalent to
71	<command>cryptsetup luksAddKey</command>, however may be combined with
72	<option>--wipe-slot=</option> in one call, see below.</para></listitem>
73	</varlistentry>
74
75	<varlistentry>
76	<term><option>--recovery-key</option></term>
77
78	<listitem><para>Enroll a recovery key. Recovery keys are most identical to passphrases, but are
79	computer generated instead of human chosen, and thus have a guaranteed high entropy. The key uses a
80	character set that is easy to type in, and may be scanned off screen via a QR code.</para></listitem>
81	</varlistentry>
82
83	<varlistentry>
84	<term><option>--pkcs11-token-uri=</option><replaceable>URI</replaceable></term>
85
86	<listitem><para>Enroll a PKCS#11 security token or smartcard (e.g. a YubiKey). Expects a PKCS#11
87	smart card URI referring to the token. Alternatively the special value <literal>auto</literal> may
88	be specified, in order to automatically determine the URI of a currently plugged in security token
89	(of which there must be exactly one). The special value <literal>list</literal> may be used to
90	enumerate all suitable PKCS#11 tokens currently plugged in. The security token must contain an RSA
91	key pair which is used to encrypt the randomly generated key that is used to unlock the LUKS2
92	volume. The encrypted key is then stored in the LUKS2 JSON token header area.</para>
93
94	<para>In order to unlock a LUKS2 volume with an enrolled PKCS#11 security token, specify the
95	<option>pkcs11-uri=</option> option in the respective <filename>/etc/crypttab</filename> line:</para>
96
97	<programlisting>myvolume /dev/sda1 - pkcs11-uri=auto</programlisting>
98
99	<para>See
100	<citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a
101	more comprehensive example of a <command>systemd-cryptenroll</command> invocation and its matching
102	<filename>/etc/crypttab</filename> line.</para></listitem>
103	</varlistentry>
104
105	<varlistentry>
106	<term><option>--fido2-device=</option><replaceable>PATH</replaceable></term>
107
108	<listitem><para>Enroll a FIDO2 security token that implements the <literal>hmac-secret</literal>
109	extension (e.g. a YubiKey). Expects a <filename>hidraw</filename> device referring to the FIDO2
110	device (e.g. <filename>/dev/hidraw1</filename>). Alternatively the special value
111	<literal>auto</literal> may be specified, in order to automatically determine the device node of a
112	currently plugged in security token (of which there must be exactly one). The special value
113	<literal>list</literal> may be used to enumerate all suitable FIDO2 tokens currently plugged in. Note
114	that many hardware security tokens that implement FIDO2 also implement the older PKCS#11
115	standard. Typically FIDO2 is preferable, given it's simpler to use and more modern.</para>
116
117	<para>In order to unlock a LUKS2 volume with an enrolled FIDO2 security token, specify the
118	<option>fido2-device=</option> option in the respective <filename>/etc/crypttab</filename> line:</para>
119
120	<programlisting>myvolume /dev/sda1 - fido2-device=auto</programlisting>
121
122	<para>See
123	<citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a
124	more comprehensive example of a <command>systemd-cryptenroll</command> invocation and its matching
125	<filename>/etc/crypttab</filename> line.</para></listitem>
126	</varlistentry>
127
128	<varlistentry>
129	<term><option>--tpm2-device=</option><replaceable>PATH</replaceable></term>
130
131	<listitem><para>Enroll a TPM2 security chip. Expects a device node path referring to the TPM2 chip
132	(e.g. <filename>/dev/tpmrm0</filename>). Alternatively the special value <literal>auto</literal> may
133	be specified, in order to automatically determine the device node of a currently discovered TPM2
134	device (of which there must be exactly one). The special value <literal>list</literal> may be used to
135	enumerate all suitable TPM2 devices currently discovered.</para>
136
137	<para>In order to unlock a LUKS2 volume with an enrolled TPM2 security chip, specify the
138	<option>tpm2-device=</option> option in the respective <filename>/etc/crypttab</filename> line:</para>
139
140	<programlisting>myvolume /dev/sda1 - tpm2-device=auto</programlisting>
141
142	<para>See
143	<citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a
144	more comprehensive example of a <command>systemd-cryptenroll</command> invocation and its matching
145	<filename>/etc/crypttab</filename> line.</para>
146
147	<para>Use <option>--tpm2-pcrs=</option> (see below) to configure which TPM2 PCR indexes to bind the
148	enrollment to.</para></listitem>
149	</varlistentry>
150
151	<varlistentry>
152	<term><option>--tpm2-pcrs=</option><arg rep="repeat">PCR</arg></term>
153
154	<listitem><para>Configures the TPM2 PCRs (Platform Configuration Registers) to bind the enrollment
155	requested via <option>--tpm2-device=</option> to. Takes a comma separated list of numeric PCR indexes
156	in the range 0…23. If not used, defaults to PCR 7 only. If an empty string is specified, binds the
157	enrollment to no PCRs at all. PCRs allow binding the enrollment to specific software versions and
158	system state, so that the enrolled unlocking key is only accessible (may be "unsealed") if specific
159	trusted software and/or configuration is used.</para></listitem>
160
161	<table>
162	<title>Well-known PCR Definitions</title>
163
164	<tgroup cols='2' align='left' colsep='1' rowsep='1'>
165	<colspec colname="pcr" />
166	<colspec colname="definition" />
167
168	<thead>
169	<row>
170	<entry>PCR</entry>
171	<entry>Explanation</entry>
172	</row>
173	</thead>
174
175	<tbody>
176	<row>
177	<entry>0</entry>
178	<entry>Core system firmware executable code; changes on firmware updates</entry>
179	</row>
180
181	<row>
182	<entry>1</entry>
183	<entry>Core system firmware data/host platform configuration; typically contains serial and model numbers, changes on basic hardware/CPU/RAM replacements</entry>
184	</row>
185
186	<row>
187	<entry>2</entry>
188	<entry>Extended or pluggable executable code; includes option ROMs on pluggable hardware</entry>
189	</row>
190
191	<row>
192	<entry>3</entry>
193	<entry>Extended or pluggable firmware data; includes information about pluggable hardware</entry>
194	</row>
195
196	<row>
197	<entry>4</entry>
198	<entry>Boot loader; changes on boot loader updates</entry>
199	</row>
200
201	<row>
202	<entry>5</entry>
203	<entry>GPT/Partition table; changes when the partitions are added, modified or removed</entry>
204	</row>
205
206	<row>
207	<entry>6</entry>
208	<entry>Power state events; changes on system suspend/sleep</entry>
209	</row>
210
211	<row>
212	<entry>7</entry>
213	<entry>Secure boot state; changes when UEFI SecureBoot mode is enabled/disabled</entry>
214	</row>
215
216	<row>
217	<entry>8</entry>
218	<entry><citerefentry><refentrytitle>sd-boot</refentrytitle><manvolnum>8</manvolnum></citerefentry> measures the kernel command line in this PCR.</entry>
219	</row>
220	</tbody>
221	</tgroup>
222	</table>
223
224	</varlistentry>
225
226	<varlistentry>
227	<term><option>--wipe-slot=</option><arg rep="repeat">SLOT</arg></term>
228
229	<listitem><para>Wipes one or more LUKS2 key slots. Takes a comma separated list of numeric slot
230	indexes, or the special strings <literal>all</literal> (for wiping all key slots),
231	<literal>empty</literal> (for wiping all key slots that are unlocked by an empty passphrase),
232	<literal>password</literal> (for wiping all key slots that are unlocked by a traditional passphrase),
233	<literal>recovery</literal> (for wiping all key slots that are unlocked by a recovery key),
234	<literal>pkcs11</literal> (for wiping all key slots that are unlocked by a PKCS#11 token),
235	<literal>fido2</literal> (for wiping all key slots that are unlocked by a FIDO2 token),
236	<literal>tpm2</literal> (for wiping all key slots that are unlocked by a TPM2 chip), or any
237	combination of these strings or numeric indexes, in which case all slots matching either are
238	wiped. As safety precaution an operation that wipes all slots without exception (so that the volume
239	cannot be unlocked at all anymore, unless the volume key is known) is refused.</para>
240
241	<para>This switch may be used alone, in which case only the requested wipe operation is executed. It
242	may also be used in combination with any of the enrollment options listed above, in which case the
243	enrollment is completed first, and only when successful the wipe operation executed — and the newly
244	added slot is always excluded from the wiping. Combining enrollment and slot wiping may thus be used to
245	update existing enrollments:</para>
246
247	<programlisting>systemd-cryptenroll /dev/sda1 --wipe-slot=tpm2 --tpm2-device=auto</programlisting>
248
249	<para>The above command will enroll the TPM2 chip, and then wipe all previously crated TPM2
250	enrollments on the LUKS2 volume, leaving only the newly created one. Combining wiping and enrollment
251	may also be used to replace enrollments of different types, for example for changing from a PKCS#11
252	enrollment to a FIDO2 one:</para>
253
254	<programlisting>systemd-cryptenroll /dev/sda1 --wipe-slot=pkcs11 --fido2-device=auto</programlisting>
255
256	<para>Or for replacing an enrolled empty password by TPM2:</para>
257
258	<programlisting>systemd-cryptenroll /dev/sda1 --wipe-slot=empty --tpm2-device=auto</programlisting>
259	</listitem>
260	</varlistentry>
261
262	<xi:include href="standard-options.xml" xpointer="help" />
263	<xi:include href="standard-options.xml" xpointer="version" />
264	</variablelist>
265
266	</refsect1>
267
268	<refsect1>
269	<title>Exit status</title>
270
271	<para>On success, 0 is returned, a non-zero failure code otherwise.</para>
272	</refsect1>
273
274	<refsect1>
275	<title>See Also</title>
276	<para>
277	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
278	<citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
279	<citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
280	<citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
281	</para>
282	</refsect1>
283
284	</refentry>