Adding upstream version 255.4.upstream/255.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 657 insertions, 0 deletions

diff --git a/man/systemd-cryptenroll.xml b/man/systemd-cryptenroll.xml
new file mode 100644
index 0000000..8fd885c
--- /dev/null
+++ b/man/systemd-cryptenroll.xml
@@ -0,0 +1,657 @@
+<?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</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
+      <arg choice="opt">DEVICE</arg>
+    </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>Regular passphrases</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>
+    </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>
+
+    <refsect2>
+      <title>TPM2 PCRs and policies</title>
+
+      <para>PCRs allow binding of the encryption of secrets to specific software versions and system state,
+      so that the enrolled key is only accessible (may be "unsealed") if specific trusted software and/or
+      configuration is used. Such bindings may be created with the option <option>--tpm2-pcrs=</option>
+      described below.</para>
+
+      <para>Secrets may also be bound indirectly: a signed policy for a state of some combination of PCR
+      values is provided, and the secret is bound to the public part of the key used to sign this policy.
+      This means that the owner of a key can generate a sequence of signed policies, for specific software
+      versions and system states, and the secret can be decrypted as long as the machine state matches one of
+      those policies. For example, a vendor may provide such a policy for each kernel+initrd update, allowing
+      users to encrypt secrets so that they can be decrypted when running any kernel+initrd signed by the
+      vendor. Such bindings may be created with the options <option>--tpm2-public-key=</option>,
+      <option>--tpm2-public-key-pcrs=</option>, <option>--tpm2-signature=</option> described below.
+      </para>
+
+      <para>See <ulink url="https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/">Linux TPM
+      PCR Registry</ulink> for an authoritative list of PCRs and how they are updated. The table below
+      contains a quick reference, describing in particular the PCRs modified by systemd.</para>
+
+      <table>
+        <title>Well-known PCR Definitions</title>
+
+        <!-- See: https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/ -->
+        <!-- See: https://github.com/rhboot/shim/blob/main/README.tpm -->
+        <!-- See: https://www.gnu.org/software/grub/manual/grub/html_node/Measured-Boot.html -->
+        <!-- See: https://sourceforge.net/p/linux-ima/wiki/Home/ -->
+        <!-- See: https://github.com/tianocore-docs/edk2-TrustedBootChain/blob/main/4_Other_Trusted_Boot_Chains.md -->
+        <!-- See: https://wiki.archlinux.org/title/Trusted_Platform_Module#Accessing_PCR_registers -->
+
+        <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+          <colspec colname="pcr" />
+          <colspec colname="name" />
+          <colspec colname="definition" />
+
+          <thead>
+            <row>
+              <entry>PCR</entry>
+              <entry>name</entry>
+              <entry>Explanation</entry>
+            </row>
+          </thead>
+
+          <tbody>
+            <row>
+              <entry>0</entry>
+              <entry>platform-code</entry>
+              <entry>Core system firmware executable code; changes on firmware updates</entry>
+            </row>
+
+            <row>
+              <entry>1</entry>
+              <entry>platform-config</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>external-code</entry>
+              <entry>Extended or pluggable executable code; includes option ROMs on pluggable hardware</entry>
+            </row>
+
+            <row>
+              <entry>3</entry>
+              <entry>external-config</entry>
+              <entry>Extended or pluggable firmware data; includes information about pluggable hardware</entry>
+            </row>
+
+            <row>
+              <entry>4</entry>
+              <entry>boot-loader-code</entry>
+              <entry>Boot loader and additional drivers, PE binaries invoked by the boot loader; changes on boot loader updates. <citerefentry><refentrytitle>sd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures system extension images read from the ESP here too (see <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>).</entry>
+            </row>
+
+            <row>
+              <entry>5</entry>
+              <entry>boot-loader-config</entry>
+              <entry>GPT/Partition table; changes when the partitions are added, modified, or removed</entry>
+            </row>
+
+            <row>
+              <entry>7</entry>
+              <entry>secure-boot-policy</entry>
+              <entry>Secure Boot state; changes when UEFI SecureBoot mode is enabled/disabled, or firmware certificates (PK, KEK, db, dbx, …) changes.</entry>
+            </row>
+
+            <row>
+              <entry>9</entry>
+              <entry>kernel-initrd</entry>
+              <entry>The Linux kernel measures all initrds it receives into this PCR.</entry>
+              <!-- Strictly speaking only Linux >= 5.17 using the LOAD_FILE2 protocol, see https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=f046fff8bc4c4d8f8a478022e76e40b818f692df -->
+            </row>
+
+            <row>
+              <entry>10</entry>
+              <entry>ima</entry>
+              <entry>The IMA project measures its runtime state into this PCR.</entry>
+            </row>
+
+            <row>
+              <entry>11</entry>
+              <entry>kernel-boot</entry>
+              <entry><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures the ELF kernel image, embedded initrd and other payload of the PE image it is placed in into this PCR. <citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> measures boot phase strings into this PCR at various milestones of the boot process.</entry>
+            </row>
+
+            <row>
+              <entry>12</entry>
+              <entry>kernel-config</entry>
+              <entry><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures the kernel command line into this PCR. <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures any manually specified kernel command line (i.e. a kernel command line that overrides the one embedded in the unified PE image) and loaded credentials into this PCR.</entry>
+            </row>
+
+            <row>
+              <entry>13</entry>
+              <entry>sysexts</entry>
+              <entry><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures any <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry> images it passes to the booted kernel into this PCR.</entry>
+            </row>
+
+            <row>
+              <entry>14</entry>
+              <entry>shim-policy</entry>
+              <entry>The shim project measures its "MOK" certificates and hashes into this PCR.</entry>
+            </row>
+
+            <row>
+              <entry>15</entry>
+              <entry>system-identity</entry>
+              <entry><citerefentry><refentrytitle>systemd-cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> optionally measures the volume key of activated LUKS volumes into this PCR. <citerefentry><refentrytitle>systemd-pcrmachine.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> measures the <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> into this PCR. <citerefentry><refentrytitle>systemd-pcrfs@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> measures mount points, file system UUIDs, labels, partition UUIDs of the root and <filename>/var/</filename> filesystems into this PCR.</entry>
+            </row>
+
+            <row>
+              <entry>16</entry>
+              <entry>debug</entry>
+              <entry>Debug</entry>
+            </row>
+
+            <row>
+              <entry>23</entry>
+              <entry>application-support</entry>
+              <entry>Application Support</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+
+      <para>In general, encrypted volumes would be bound to some combination of PCRs 7, 11, and 14 (if
+      shim/MOK is used). In order to allow firmware and OS version updates, it is typically not advisable to
+      use PCRs such as 0 and 2, since the program code they cover should already be covered indirectly
+      through the certificates measured into PCR 7. Validation through certificates hashes is typically
+      preferable over validation through direct measurements as it is less brittle in context of OS/firmware
+      updates: the measurements will change on every update, but signatures should remain unchanged. See the
+      <ulink url="https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/">Linux TPM PCR
+      Registry</ulink> for more discussion.</para>
+    </refsect2>
+  </refsect1>
+
+  <refsect1>
+    <title>Limitations</title>
+
+    <para>Note that currently when enrolling a new key of one of the five supported types listed above, it is
+    required to first provide a passphrase, a recovery key or a FIDO2 token. It's currently not supported to
+    unlock a device with a TPM2/PKCS#11 key in order to enroll a new TPM2/PKCS#11 key. Thus, if in future key
+    roll-over is desired it's generally recommended to ensure a passphrase, a recovery key or a FIDO2 token
+    is always enrolled.</para>
+
+    <para>Also note that support for enrolling multiple FIDO2 tokens is currently limited. When multiple FIDO2
+    tokens are enrolled, <command>systemd-cryptseup</command> will perform pre-flight requests to attempt to
+    identify which of the enrolled tokens are currently plugged in. However, this is not possible for FIDO2
+    tokens with user verification (UV, usually via biometrics), in which case it will fall back to attempting
+    each enrolled token one by one. This will result in multiple prompts for PIN and user verification. This
+    limitation does not apply to PKCS#11 tokens.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Compatibility</title>
+
+    <para>Security technology both in systemd and in the general industry constantly evolves. In order to
+    provide best security guarantees, the way TPM2, FIDO2, PKCS#11 devices are enrolled is regularly updated
+    in newer versions of systemd. Whenever this happens the following compatibility guarantees are given:</para>
+
+    <itemizedlist>
+      <listitem><para>Old enrollments continue to be supported and may be unlocked with newer versions of
+      <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
+
+      <listitem><para>The opposite is not guaranteed however: it might not be possible to unlock volumes with
+      enrollments done with a newer version of <command>systemd-cryptenroll</command> with an older version
+      of <command>systemd-cryptsetup</command>.</para></listitem>
+    </itemizedlist>
+
+    <para>That said, it is generally recommended to use matching versions of
+    <command>systemd-cryptenroll</command> and <command>systemd-cryptsetup</command>, since this is best
+    tested and supported.</para>
+
+    <para>It might be advisable to re-enroll existing enrollments to take benefit of newer security features,
+    as they are added to systemd.</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>
+
+        <xi:include href="version-info.xml" xpointer="v248"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--recovery-key</option></term>
+
+        <listitem><para>Enroll a recovery key. Recovery keys are mostly identical to passphrases, but are
+        computer-generated instead of being chosen by a human, 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>
+
+        <xi:include href="version-info.xml" xpointer="v248"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--unlock-key-file=</option><replaceable>PATH</replaceable></term>
+
+        <listitem><para>Use a file instead of a password/passphrase read from stdin to unlock the volume.
+        Expects the PATH to the file containing your key to unlock the volume. Currently there is nothing like
+        <option>--key-file-offset=</option> or <option>--key-file-size=</option> so this file has to only
+        contain the full key.</para>
+
+        <xi:include href="version-info.xml" xpointer="v252"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--unlock-fido2-device=</option><replaceable>PATH</replaceable></term>
+
+        <listitem><para>Use a FIDO2 device instead of a password/passphrase read from stdin to unlock the
+        volume. 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). This automatic discovery is unsupported if
+        <option>--fido2-device=</option> option is also specified.</para>
+
+        <xi:include href="version-info.xml" xpointer="v253"/></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
+        smartcard 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>
+
+        <xi:include href="version-info.xml" xpointer="v248"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--fido2-credential-algorithm=</option><replaceable>STRING</replaceable></term>
+        <listitem><para>Specify COSE algorithm used in credential generation. The default value is
+        <literal>es256</literal>. Supported values are <literal>es256</literal>, <literal>rs256</literal>
+        and <literal>eddsa</literal>.</para>
+
+        <para><literal>es256</literal> denotes ECDSA over NIST P-256 with SHA-256. <literal>rs256</literal>
+        denotes 2048-bit RSA with PKCS#1.5 padding and SHA-256. <literal>eddsa</literal> denotes
+        EDDSA over Curve25519 with SHA-512.</para>
+
+        <para>Note that your authenticator may not support some algorithms.</para>
+
+        <xi:include href="version-info.xml" xpointer="v251"/></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). This automatic discovery
+        is unsupported if <option>--unlock-fido2-device=</option> option is also specified. 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>
+
+        <xi:include href="version-info.xml" xpointer="v248"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--fido2-with-client-pin=</option><replaceable>BOOL</replaceable></term>
+
+        <listitem><para>When enrolling a FIDO2 security token, controls whether to require the user to enter
+        a PIN when unlocking the volume (the FIDO2 <literal>clientPin</literal> feature). Defaults to
+        <literal>yes</literal>. (Note: this setting is without effect if the security token does not support
+        the <literal>clientPin</literal> feature at all, or does not allow enabling or disabling
+        it.)</para>
+
+        <xi:include href="version-info.xml" xpointer="v249"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--fido2-with-user-presence=</option><replaceable>BOOL</replaceable></term>
+
+        <listitem><para>When enrolling a FIDO2 security token, controls whether to require the user to
+        verify presence (tap the token, the FIDO2 <literal>up</literal> feature) when unlocking the volume.
+        Defaults to <literal>yes</literal>. (Note: this setting is without effect if the security token does not support
+        the <literal>up</literal> feature at all, or does not allow enabling or disabling it.)
+        </para>
+
+        <xi:include href="version-info.xml" xpointer="v249"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--fido2-with-user-verification=</option><replaceable>BOOL</replaceable></term>
+
+        <listitem><para>When enrolling a FIDO2 security token, controls whether to require user verification
+        when unlocking the volume (the FIDO2 <literal>uv</literal> feature). Defaults to
+        <literal>no</literal>. (Note: this setting is without effect if the security token does not support
+        the <literal>uv</literal> feature at all, or does not allow enabling or disabling it.)</para>
+
+        <xi:include href="version-info.xml" xpointer="v249"/></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>
+
+        <xi:include href="version-info.xml" xpointer="v248"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--tpm2-device-key=</option><replaceable>PATH</replaceable></term>
+
+        <listitem><para>Enroll a TPM2 security chip using its public key. Expects a path referring to the
+        TPM2 public key in TPM2B_PUBLIC format. This cannot be used with <option>--tpm2-device=</option>, as
+        it performs the same operation, but without connecting to the TPM2 security chip; instead the
+        enrollment is calculated using the provided TPM2 key. This is useful in situations where the TPM2
+        security chip is not available at the time of enrollment.</para>
+
+        <para>The key, in most cases, should be the Storage Root Key (SRK) from a local TPM2 security
+        chip. If a key from a different handle (not the SRK) is used, you must specify its handle index using
+        <option>--tpm2-seal-key-handle=</option>.</para>
+
+        <para>The
+        <citerefentry><refentrytitle>systemd-tpm2-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+        service writes the SRK to <filename>/run/systemd/tpm2-srk-public-key.tpm2b_public</filename>
+        automatically during boot, in the correct format.</para>
+
+        <para>Alternatively, you may use <command>systemd-analyze srk</command> to retrieve the SRK from the
+        TPM2 security chip explicitly. See
+        <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        for details. Example:</para>
+
+        <programlisting>systemd-analyze srk &gt; srk.tpm2b_public</programlisting>
+
+        <xi:include href="version-info.xml" xpointer="v255"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--tpm2-seal-key-handle=</option><replaceable>HANDLE</replaceable></term>
+
+        <listitem><para>Configures which parent key to use for sealing, using the TPM handle (index) of the
+        key. This is used to "seal" (encrypt) a secret and must be used later to "unseal" (decrypt) the
+        secret. Expects a hexadecimal 32bit integer, optionally prefixed with
+        <literal>0x</literal>. Allowable values are any handle index in the persistent
+        (<literal>0x81000000</literal>-<literal>0x81ffffff</literal>) or transient
+        (<literal>0x80000000</literal>-<literal>0x80ffffff</literal>) ranges. Since transient handles are
+        lost after a TPM reset, and may be flushed during TPM context switching, they should not be used
+        except for very specific use cases, e.g. testing.</para>
+
+        <para>The default is the Storage Root Key (SRK) handle index <literal>0x81000001</literal>. A value
+        of 0 will use the default. For the SRK handle, a new key will be created and stored in the TPM if one
+        does not already exist; for any other handle, the key must already exist in the TPM at the specified
+        handle index.</para>
+
+        <para>This should not be changed unless you know what you are doing.</para>
+
+        <xi:include href="version-info.xml" xpointer="v255"/></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 to when
+        enrollment is requested via <option>--tpm2-device=</option>. Takes a list of PCR entries, where each
+        entry starts with a name or numeric index in the range 0…23, optionally followed by
+        <literal>:</literal> and a hash algorithm name (specifying the PCR bank), optionally followed by
+        <literal>=</literal> and a hash digest value. Multiple PCR entries are separated by
+        <literal>+</literal>. If not specified, the default is to use PCR 7 only. If an empty string is
+        specified, binds the enrollment to no PCRs at all. See the table above for a list of available
+        PCRs.</para>
+
+        <para>Example: <option>--tpm2-pcrs=boot-loader-code+platform-config+boot-loader-config</option>
+        specifies that PCR registers 4, 1, and 5 should be used.</para>
+        <para>Example: <option>--tpm2-pcrs=7:sha256</option> specifies that PCR register 7 from the SHA256
+        bank should be used.</para>
+        <para>Example: <option>--tpm2-pcrs=4:sha1=3a3f780f11a4b49969fcaa80cd6e3957c33b2275</option>
+        specifies that PCR register 4 from the SHA1 bank should be used, and a hash digest value of
+        3a3f780f11a4b49969fcaa80cd6e3957c33b2275 will be used instead of reading the current PCR
+        value.</para>
+
+        <xi:include href="version-info.xml" xpointer="v248"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--tpm2-with-pin=</option><replaceable>BOOL</replaceable></term>
+
+        <listitem><para>When enrolling a TPM2 device, controls whether to require the user to enter a PIN
+        when unlocking the volume in addition to PCR binding, based on TPM2 policy authentication. Defaults
+        to <literal>no</literal>. Despite being called PIN, any character can be used, not just numbers.
+        </para>
+
+        <para>Note that incorrect PIN entry when unlocking increments the TPM dictionary attack lockout
+        mechanism, and may lock out users for a prolonged time, depending on its configuration. The lockout
+        mechanism is a global property of the TPM, <command>systemd-cryptenroll</command> does not control or
+        configure the lockout mechanism. You may use tpm2-tss tools to inspect or configure the dictionary
+        attack lockout, with <citerefentry
+        project='mankier'><refentrytitle>tpm2_getcap</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        and <citerefentry
+        project='mankier'><refentrytitle>tpm2_dictionarylockout</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        commands, respectively.</para>
+
+        <xi:include href="version-info.xml" xpointer="v251"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--tpm2-public-key=</option><arg>PATH</arg></term>
+        <term><option>--tpm2-public-key-pcrs=</option><arg rep="repeat">PCR</arg></term>
+        <term><option>--tpm2-signature=</option><arg>PATH</arg></term>
+
+        <listitem><para>Configures a TPM2 signed PCR policy to bind encryption to. The
+        <option>--tpm2-public-key=</option> option accepts a path to a PEM encoded RSA public key, to bind
+        the encryption to. If this is not specified explicitly, but a file
+        <filename>tpm2-pcr-public-key.pem</filename> exists in one of the directories
+        <filename>/etc/systemd/</filename>, <filename>/run/systemd/</filename>,
+        <filename>/usr/lib/systemd/</filename> (searched in this order), it is automatically used. The
+        <option>--tpm2-public-key-pcrs=</option> option takes a list of TPM2 PCR indexes to bind to (same
+        syntax as <option>--tpm2-pcrs=</option> described above). If not specified defaults to 11 (i.e. this
+        binds the policy to any unified kernel image for which a PCR signature can be provided).</para>
+
+        <para>Note the difference between <option>--tpm2-pcrs=</option> and
+        <option>--tpm2-public-key-pcrs=</option>: the former binds decryption to the current, specific PCR
+        values; the latter binds decryption to any set of PCR values for which a signature by the specified
+        public key can be provided. The latter is hence more useful in scenarios where software updates shell
+        be possible without losing access to all previously encrypted LUKS2 volumes. Like with
+        <option>--tpm2-pcrs=</option>, names defined in the table above can also be used to specify the
+        registers, for instance
+        <option>--tpm2-public-key-pcrs=boot-loader-code+system-identity</option>.</para>
+
+        <para>The <option>--tpm2-signature=</option> option takes a path to a TPM2 PCR signature file as
+        generated by the
+        <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        tool. If this is not specified explicitly, a suitable signature file
+        <filename>tpm2-pcr-signature.json</filename> is searched for in <filename>/etc/systemd/</filename>,
+        <filename>/run/systemd/</filename>, <filename>/usr/lib/systemd/</filename> (in this order) and used.
+        If a signature file is specified or found it is used to verify if the volume can be unlocked with it
+        given the current PCR state, before the new slot is written to disk. This is intended as safety net
+        to ensure that access to a volume is not lost if a public key is enrolled for which no valid
+        signature for the current PCR state is available. If the supplied signature does not unlock the
+        current PCR state and public key combination, no slot is enrolled and the operation will fail. If no
+        signature file is specified or found no such safety verification is done.</para>
+
+        <xi:include href="version-info.xml" xpointer="v252"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--tpm2-pcrlock=</option><arg>PATH</arg></term>
+
+        <listitem><para>Configures a TPM2 pcrlock policy to bind encryption to. Expects a path to a pcrlock
+        policy file as generated by the
+        <citerefentry><refentrytitle>systemd-pcrlock</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        tool. If a TPM2 device is enrolled and this option is not used but a file
+        <filename>pcrlock.json</filename> is found in <filename>/run/systemd/</filename> or
+        <filename>/var/lib/systemd/</filename> it is automatically used. Assign an empty string to turn this
+        behaviour off.</para>
+
+        <xi:include href="version-info.xml" xpointer="v255"/></listitem>
+      </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 created 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>
+
+        <xi:include href="version-info.xml" xpointer="v248"/>
+        </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>Examples</title>
+
+    <para><citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> and
+    <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    contain various examples employing <command>systemd-cryptenroll</command>.</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>,
+      <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+     </para>
+  </refsect1>
+
+</refentry>