man: document new features

10 files changed, 603 insertions, 94 deletions

diff --git a/man/crypttab.xml b/man/crypttab.xml
index 0c0f091025..2062a5b8e7 100644
--- a/man/crypttab.xml
+++ b/man/crypttab.xml
@@ -45,13 +45,12 @@
     The first two fields are mandatory, the remaining two are
     optional.</para>
 
-    <para>Setting up encrypted block devices using this file supports
-    three encryption modes: LUKS, TrueCrypt and plain. See
-    <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-    for more information about each mode. When no mode is specified in
-    the options field and the block device contains a LUKS signature,
-    it is opened as a LUKS device; otherwise, it is assumed to be in
-    raw dm-crypt (plain mode) format.</para>
+    <para>Setting up encrypted block devices using this file supports four encryption modes: LUKS, TrueCrypt,
+    BitLocker and plain. See <citerefentry
+    project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
+    more information about each mode. When no mode is specified in the options field and the block device
+    contains a LUKS signature, it is opened as a LUKS device; otherwise, it is assumed to be in raw dm-crypt
+    (plain mode) format.</para>
 
     <para>The four fields of <filename>/etc/crypttab</filename> are defined as follows:</para>
 
@@ -65,9 +64,10 @@
       <literal>UUID=</literal> followed by the UUID.</para></listitem>
 
       <listitem><para>The third field specifies an absolute path to a file with the encryption
-      key. Optionally, the path may be followed by <literal>:</literal> and an fstab device specification
-      (e.g. starting with <literal>LABEL=</literal> or similar); in which case the path is taken relative to
-      the device file system root. If the field is not present or is <literal>none</literal> or
+      key. Optionally, the path may be followed by <literal>:</literal> and an
+      <filename>/etc/fstab</filename> style device specification (e.g. starting with
+      <literal>LABEL=</literal> or similar); in which case the path is taken relative to the specified
+      device's file system root. If the field is not present or is <literal>none</literal> or
       <literal>-</literal>, a key file named after the volume to unlock (i.e. the first column of the line),
       suffixed with <filename>.key</filename> is automatically loaded from the
       <filename>/etc/cryptsetup-keys.d/</filename> and <filename>/run/cryptsetup-keys.d/</filename>
@@ -83,6 +83,60 @@
       <listitem><para>The fourth field, if present, is a comma-delimited list of options. The supported
       options are listed below.</para></listitem>
     </orderedlist>
+  </refsect1>
+
+  <refsect1>
+    <title>Key Acquisition</title>
+
+    <para>Six different mechanisms for acquiring the decryption key or passphrase unlocking the encrypted
+    volume are supported. Specifically:</para>
+
+    <orderedlist>
+
+      <listitem><para>Most prominently, the user may be queried interactively during volume activation
+      (i.e. typically at boot), asking them to type in the necessary passphrase(s).</para></listitem>
+
+      <listitem><para>The (unencrypted) key may be read from a file on disk, possibly on removable media. The third field
+      of each line encodes the location, for details see above.</para></listitem>
+
+      <listitem><para>The (unencrypted) key may be requested from another service, by specifying an
+      <constant>AF_UNIX</constant> file system socket in place of a key file in the third field. For details
+      see above and below.</para></listitem>
+
+      <listitem><para>The key may be acquired via a PKCS#11 compatible hardware security token or
+      smartcard. In this case an encrypted key is stored on disk/removable media, acquired via
+      <constant>AF_UNIX</constant>, or stored in the LUKS2 JSON token metadata header. The encrypted key is
+      then decrypted by the PKCS#11 token with an RSA key stored on it, and then used to unlock the encrypted
+      volume. Use the <option>pkcs11-uri=</option> option described below to use this mechanism.</para></listitem>
+
+      <listitem><para>Similar, the key may be acquired via a FIDO2 compatible hardware security token (which
+      must implement the "hmac-secret" extension). In this case a (during enrollment) randomly generated key
+      is stored on disk/removable media, acquired via <constant>AF_UNIX</constant>, or stored in the LUKS2
+      JSON token metadata header. The random key is hashed via a keyed hash function (HMAC) on the FIDO2
+      token, using a secret key stored on the token that never leaves it. The resulting hash value is then
+      used as key to unlock the encrypted volume. Use the <option>fido2-device=</option> option described
+      below to use this mechanism.</para></listitem>
+
+      <listitem><para>Similar, the key may be acquired via a TPM2 security chip. In this case a (during
+      enrollment) randomly generated key — encrypted by an asymmetric key derived from the TPM2 chip's seed
+      key — is stored on disk/removable media, acquired via <constant>AF_UNIX</constant>, or stored in the
+      LUKS2 JSON token metadata header. Use the <option>tpm2-device=</option> option described below to use
+      this mechanism.</para></listitem>
+    </orderedlist>
+
+    <para>For the latter five mechanisms the source for the key material used for unlocking the volume is
+    primarily configured in the third field of each <filename>/etc/crypttab</filename> line, but may also
+    configured in <filename>/etc/cryptsetup-keys.d/</filename> and
+    <filename>/run/cryptsetup-keys.d/</filename> (see above) or in the LUKS2 JSON token header (in case of
+    the latter three). Use the
+    <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    tool to enroll PKCS#11, FIDO2 and TPM2 devices in LUKS2 volumes.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Supported Options</title>
+
+    <para>The following options may be used in the fourth field of each line:</para>
 
     <variablelist class='fstab-options'>
 
@@ -125,10 +179,10 @@
         for possible values and the default value of this
         option.</para>
 
-        <para>Optionally, the path may be followed by <literal>:</literal> and an fstab device specification
-        (e.g. starting with <literal>UUID=</literal> or similar); in which case, the path is relative to the
-        device file system root. The device gets mounted automatically for LUKS device activation duration only.
-        </para></listitem>
+        <para>Optionally, the path may be followed by <literal>:</literal> and an
+        <filename>/etc/fstab</filename> device specification (e.g. starting with <literal>UUID=</literal> or
+        similar); in which case, the path is relative to the device file system root. The device gets mounted
+        automatically for LUKS device activation duration only.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -198,8 +252,8 @@
       <varlistentry>
         <term><option>bitlk</option></term>
 
-        <listitem><para>Decrypt Bitlocker drive. Encryption parameters
-        are deduced by cryptsetup from Bitlocker header.</para></listitem>
+        <listitem><para>Decrypt BitLocker drive. Encryption parameters
+        are deduced by cryptsetup from BitLocker header.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -269,7 +323,7 @@
       <varlistentry>
         <term><option>same-cpu-crypt</option></term>
 
-        <listitem><para>Perform encryption using the same cpu that IO was submitted on. The default is to use
+        <listitem><para>Perform encryption using the same CPU that IO was submitted on. The default is to use
         an unbound workqueue so that encryption work is automatically balanced between available CPUs.</para>
 
         <para>This requires kernel 4.0 or newer.</para>
@@ -451,15 +505,134 @@
       <varlistentry>
         <term><option>pkcs11-uri=</option></term>
 
-        <listitem><para>Takes a <ulink url="https://tools.ietf.org/html/rfc7512">RFC7512 PKCS#11 URI</ulink>
-        pointing to a private RSA key which is used to decrypt the key specified in the third column of the
-        line. This is useful for unlocking encrypted volumes through security tokens or smartcards. See below
-        for an example how to set up this mechanism for unlocking a LUKS volume with a YubiKey security
-        token. The specified URI can refer directly to a private RSA key stored on a token or alternatively
+        <listitem><para>Takes either the special value <literal>auto</literal> or an <ulink
+        url="https://tools.ietf.org/html/rfc7512">RFC7512 PKCS#11 URI</ulink> pointing to a private RSA key
+        which is used to decrypt the encrypted key specified in the third column of the line. This is useful
+        for unlocking encrypted volumes through PKCS#11 compatible security tokens or smartcards. See below
+        for an example how to set up this mechanism for unlocking a LUKS2 volume with a YubiKey security
+        token.</para>
+
+        <para>If specified as <literal>auto</literal> the volume must be of type LUKS2 and must carry PKCS#11
+        security token metadata in its LUKS2 JSON token section. In this mode the URI and the encrypted key
+        are automatically read from the LUKS2 JSON token header. Use
+        <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        as simple tool for enrolling PKCS#11 security tokens or smartcards in a way compatible with
+        <literal>auto</literal>. In this mode the third column of the line should remain empty (that is,
+        specified as <literal>-</literal>).</para>
+
+        <para>The specified URI can refer directly to a private RSA key stored on a token or alternatively
         just to a slot or token, in which case a search for a suitable private RSA key will be performed.  In
-        this case if multiple suitable objects are found the token is refused. The key configured in the
-        third column is passed as is to RSA decryption. The resulting decrypted key is then base64 encoded
-        before it is used to unlock the LUKS volume.</para></listitem>
+        this case if multiple suitable objects are found the token is refused. The encrypted key configured
+        in the third column of the line is passed as is (i.e. in binary form, unprocessed) to RSA
+        decryption. The resulting decrypted key is then Base64 encoded before it is used to unlock the LUKS
+        volume.</para>
+
+        <para>Use <command>systemd-cryptenroll --pkcs11-token-uri=list</command> to list all suitable PKCS#11
+        security tokens currently plugged in, along with their URIs.</para>
+
+        <para>Note that many newer security tokens that may be used as PKCS#11 security token typically also
+        implement the newer and simpler FIDO2 standard. Consider using <option>fido2-device=</option>
+        (described below) to enroll it via FIDO2 instead. Note that a security token enrolled via PKCS#11
+        cannot be used to unlock the volume via FIDO2, unless also enrolled via FIDO2, and vice
+        versa.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>fido2-device=</option></term>
+
+        <listitem><para>Takes either the special value <literal>auto</literal> or the path to a
+        <literal>hidraw</literal> device node (e.g. <filename>/dev/hidraw1</filename>) referring to a FIDO2
+        security token that implements the <literal>hmac-secret</literal> extension (most current hardware
+        security tokens do). See below for an example how to set up this mechanism for unlocking an encrypted
+        volume with a FIDO2 security token.</para>
+
+        <para>If specified as <literal>auto</literal> the FIDO2 token device is automatically discovered, as
+        it is plugged in.</para>
+
+        <para>FIDO2 volume unlocking requires a client ID hash (CID) to be configured via
+        <option>fido2-cid=</option> (see below) and a key to pass to the security token's HMAC functionality
+        (configured in the line's third column) to operate. If not configured and the volume is of type
+        LUKS2, the CID and the key are read from LUKS2 JSON token metadata instead. Use
+        <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        as simple tool for enrolling FIDO2 security tokens, compatible with this automatic mode, which is
+        only available for LUKS2 volumes.</para>
+
+        <para>Use <command>systemd-cryptenroll --fido2-device=list</command> to list all suitable FIDO2
+        security tokens currently plugged in, along with their device nodes.</para>
+
+        <para>This option implements the following mechanism: the configured key is hashed via they HMAC
+        keyed hash function the FIDO2 device implements, keyed by a secret key embedded on the device. The
+        resulting hash value is Base64 encoded and used to unlock the LUKS2 volume. As it should not be
+        possible to extract the secret from the hardware token, it should not be possible to retrieve the
+        hashed key given the configured key — without possessing the hardware token.</para>
+
+        <para>Note that many security tokens that implement FIDO2 also implement PKCS#11, suitable for
+        unlocking volumes via the <option>pkcs11-uri=</option> option described above. Typically the newer,
+        simpler FIDO2 standard is preferable.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>fido2-cid=</option></term>
+
+        <listitem><para>Takes a Base64 encoded FIDO2 client ID to use for the FIDO2 unlock operation. If
+        specified, but <option>fido2-device=</option> is not, <option>fido2-device=auto</option> is
+        implied. If <option>fido2-device=</option> is used but <option>fido2-cid=</option> is not, the volume
+        must be of LUKS2 type, and the CID is read from the LUKS2 JSON token header. Use
+        <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        for enrolling a FIDO2 token in the LUKS2 header compatible with this automatic
+        mode.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>fido2-rp=</option></term>
+
+        <listitem><para>Takes a string, configuring the FIDO2 Relying Party (rp) for the FIDO2 unlock
+        operation. If not specified <literal>io.systemd.cryptsetup</literal> is used, except if the the LUKS2
+        JSON token header contains a different value. It should normally not be necessary to override
+        this.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>tpm2-device=</option></term>
+
+        <listitem><para>Takes either the special value <literal>auto</literal> or the path to a device node
+        (e.g. <filename>/dev/tpmrm0</filename>) referring to a TPM2 security chip. See below for an example
+        how to set up this mechanism for unlocking an encrypted volume with a TPM2 chip.</para>
+
+        <para>Use <option>tpm2-pcrs=</option> (see below) to configure the set of TPM2 PCRs to bind the
+        volume unlocking to. Use
+        <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        as simple tool for enrolling TPM2 security chips in LUKS2 volumes.</para>
+
+        <para>If specified as <literal>auto</literal> the TPM2 device is automatically discovered. Use
+        <command>systemd-cryptenroll --tpm2-device=list</command> to list all suitable TPM2 devices currently
+        available, along with their device nodes.</para>
+
+        <para>This option implements the following mechanism: when enrolling a TPM2 device via
+        <command>systemd-cryptenroll</command> on a LUKS2 volume, a randomized key unlocking the volume is
+        generated on the host and loaded into the TPM2 chip where it is encrypted with an asymmetric
+        "primary" key pair derived from the TPM2's internal "seed" key. Neither the seed key nor the primary
+        key are permitted to ever leave the TPM2 chip — however, the now encrypted randomized key may. It is
+        saved in the LUKS2 volume JSON token header. When unlocking the encrypted volume, the primary key
+        pair is generated on the TPM2 chip again (which works as long as the chip's seed key is correctly
+        maintained by the TPM2 chip), which is then used to decrypt (on the TPM2 chip) the encrypted key from
+        the LUKS2 volume JSON token header saved there during enrollment. The resulting decrypted key is then
+        used to unlock the volume. When the randomized key is encrypted the current values of the selected
+        PCRs (see below) are included in the operation, so that different PCR state results in different
+        encrypted keys and the decrypted key can only be recovered if the same PCR state is
+        reproduced.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>tpm2-pcrs=</option></term>
+
+        <listitem><para>Takes a comma separated list of numeric TPM2 PCR (i.e. "Platform Configuration
+        Register") indexes to bind the TPM2 volume unlocking to. This option is only useful when TPM2
+        enrollment metadata is not available in the LUKS2 JSON token header already, the way
+        <command>systemd-cryptenroll</command> writes it there. If not used (and no metadata in the LUKS2
+        JSON token header defines it), defaults to a list of a single entry: PCR 7. Assign an empty string to
+        encode a policy that binds the key to no PCRs, making the key accessible to local programs regardless
+        of the current PCR state.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -523,7 +696,7 @@
     <programlisting><constant>NUL</constant> <replaceable>RANDOM</replaceable> <literal>/cryptsetup/</literal> <replaceable>VOLUME</replaceable></programlisting>
 
     <para>In other words: a <constant>NUL</constant> byte (as required for abstract namespace sockets),
-    followed by a random string (consisting of alphabenumeric characters only), followed by the literal
+    followed by a random string (consisting of alphanumeric characters only), followed by the literal
     string <literal>/cryptsetup/</literal>, followed by the name of the volume to acquire they key
     for. Example (for a volume <literal>myvol</literal>):</para>
 
@@ -533,11 +706,13 @@
     name with <citerefentry
     project='man-pages'><refentrytitle>getpeername</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
     and use it to determine which key to send, allowing a single listening socket to serve keys for a
-    multitude of volumes. If the PKCS#11 logic is used (see below) the socket source name is picked in
-    identical fashion, except that the literal string <literal>/cryptsetup-pkcs11/</literal> is used. This is
+    multitude of volumes. If the PKCS#11 logic is used (see above) the socket source name is picked in
+    identical fashion, except that the literal string <literal>/cryptsetup-pkcs11/</literal> is used (similar
+    for FIDO2: <literal>/cryptsetup-fido2/</literal> and TPM2: <literal>/cryptsetup-tpm2/</literal>). This is
     done so that services providing key material know that not a secret key is requested but an encrypted key
-    that will be decrypted via the PKCS#11 logic to acquire the final secret key.</para>
+    that will be decrypted via the PKCS#11/FIDO2/TPM2 logic to acquire the final secret key.</para>
   </refsect1>
+
   <refsect1>
     <title>Examples</title>
     <example>
@@ -556,25 +731,48 @@ external   /dev/sda3       keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchac
     </example>
 
     <example>
-      <title>Yubikey-based Volume Unlocking Example</title>
+      <title>Yubikey-based PKCS#11 Volume Unlocking Example</title>
 
       <para>The PKCS#11 logic allows hooking up any compatible security token that is capable of storing RSA
-      decryption keys. Here's an example how to set up a Yubikey security token for this purpose, using
-      <citerefentry project='debian'><refentrytitle>ykmap</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-      from the yubikey-manager project:</para>
+      decryption keys for unlocking an encrypted volume. Here's an example how to set up a Yubikey security
+      token for this purpose on a LUKS2 volume, using <citerefentry
+      project='debian'><refentrytitle>ykmap</refentrytitle><manvolnum>1</manvolnum></citerefentry> from the
+      yubikey-manager project to initialize the token and
+      <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      to add it in the LUKS2 volume:</para>
 
 <programlisting><xi:include href="yubikey-crypttab.sh" parse="text" /></programlisting>
 
-<para>A few notes on the above:</para>
+      <para>A few notes on the above:</para>
+
+      <itemizedlist>
+        <listitem><para>We use RSA2048, which is the longest key size current Yubikeys support</para></listitem>
+        <listitem><para>We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes,
+        <ulink url="https://developers.yubico.com/PIV/Introduction/Certificate_slots.html">see
+        documentation</ulink>.</para></listitem>
+      </itemizedlist>
+    </example>
+
+    <example>
+      <title>FIDO2 Volume Unlocking Example</title>
+
+      <para>The FIDO2 logic allows using any compatible FIDO2 security token that implements the
+      <literal>hmac-secret</literal> extension for unlocking an encrypted volume. Here's an example how to
+      set up a FIDO2 security token for this purpose for a LUKS2 volume, using
+      <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>:</para>
+
+<programlisting><xi:include href="fido2-crypttab.sh" parse="text" /></programlisting>
+    </example>
+
+    <example>
+      <title>TPM2 Volume Unlocking Example</title>
 
-<itemizedlist>
-  <listitem><para>We use RSA2048, which is the longest key size current Yubikeys support</para></listitem>
-  <listitem><para>LUKS key size must be shorter than 2048bit due to RSA padding, hence we use 128 bytes</para></listitem>
-  <listitem><para>We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes,
-  <ulink url="https://developers.yubico.com/PIV/Introduction/Certificate_slots.html">see
-  documentation</ulink>.</para></listitem>
-</itemizedlist>
+      <para>The TPM2 logic allows using any TPM2 chip supported by the Linux kernel for unlocking an
+      encrypted volume. Here's an example how to set up a TPM2 chip for this purpose for a LUKS2 volume,
+      using
+      <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>:</para>
 
+<programlisting><xi:include href="tpm2-crypttab.sh" parse="text" /></programlisting>
     </example>
   </refsect1>
 
@@ -584,6 +782,7 @@ external   /dev/sda3       keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchac
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
diff --git a/man/fido2-crypttab.sh b/man/fido2-crypttab.sh
new file mode 100644
index 0000000000..49e536cae8
--- /dev/null
+++ b/man/fido2-crypttab.sh
@@ -0,0 +1,10 @@
+# Enroll the security token in the LUKS2 volume. Replace /dev/sdXn by the
+# partition to use (e.g. /dev/sda1).
+sudo systemd-cryptenroll --fido2-device=auto /dev/sdXn
+
+# Test: Let's run systemd-cryptsetup to test if this worked.
+sudo /usr/lib/systemd/systemd-cryptsetup attach mytest /dev/sdXn - fido2-device=auto
+
+# If that worked, let's now add the same line persistently to /etc/crypttab,
+# for the future.
+sudo bash -c 'echo "mytest /dev/sdXn - fido2-device=auto" >> /etc/crypttab'
diff --git a/man/repart.d.xml b/man/repart.d.xml
index 6e31843a08..66debd336f 100644
--- a/man/repart.d.xml
+++ b/man/repart.d.xml
@@ -492,12 +492,19 @@
       <varlistentry>
         <term><varname>Encrypt=</varname></term>
 
-        <listitem><para>Takes a boolean parameter, defaulting to false. If true the partition will be
+        <listitem><para>Takes one of <literal>off</literal>, <literal>key-file</literal>,
+        <literal>tpm2</literal> and <literal>key-file+tpm2</literal> (alternatively, also accepts a boolean
+        value, which is mapped to <literal>off</literal> when false, and <literal>key-file</literal> when
+        true). Defaults to <literal>off</literal>. If not <literal>off</literal> the partition will be
         formatted with a LUKS2 superblock, before the blocks configured with <varname>CopyBlocks=</varname>
         are copied in or the file system configured with <varname>Format=</varname> is created.</para>
 
-        <para>The LUKS2 UUID is automatically derived from the partition UUID in a stable fashion. A single
-        key is added to the LUKS2 superblock, configurable with the <option>--key-file=</option> switch to
+        <para>The LUKS2 UUID is automatically derived from the partition UUID in a stable fashion. If
+        <literal>key-file</literal> or <literal>key-file+tpm2</literal> is used a key is added to the LUKS2
+        superblock, configurable with the <option>--key-file=</option> switch to
+        <command>systemd-repart</command>. If <literal>tpm2</literal> or <literal>key-file+tpm2</literal> is
+        used a key is added to the LUKS2 superblock that is enrolled to the local TPM2 chip, as configured
+        with the <option>--tpm2-device=</option> and <option>--tpm2-pcrs=</option> options to
         <command>systemd-repart</command>.</para>
 
         <para>When used this slightly alters the size allocation logic as the implicit, minimal size limits
@@ -627,7 +634,8 @@ SizeMaxBytes=64M
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-      <citerefentry project='man-pages'><refentrytitle>sfdisk</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      <citerefentry project='man-pages'><refentrytitle>sfdisk</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     </para>
   </refsect1>
 
diff --git a/man/rules/meson.build b/man/rules/meson.build
index 97136fe758..cada4305a7 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -825,6 +825,7 @@ manpages = [
   '8',
   ['systemd-coredump.socket', 'systemd-coredump@.service'],
   'ENABLE_COREDUMP'],
+ ['systemd-cryptenroll', '1', [], 'HAVE_LIBCRYPTSETUP'],
  ['systemd-cryptsetup-generator', '8', [], 'HAVE_LIBCRYPTSETUP'],
  ['systemd-cryptsetup@.service',
   '8',
diff --git a/man/systemd-cryptenroll.xml b/man/systemd-cryptenroll.xml
new file mode 100644
index 0000000000..17a546b256
--- /dev/null
+++ b/man/systemd-cryptenroll.xml
@@ -0,0 +1,284 @@
+<?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>
diff --git a/man/systemd-cryptsetup-generator.xml b/man/systemd-cryptsetup-generator.xml
index 4284f78c4e..e5c193f692 100644
--- a/man/systemd-cryptsetup-generator.xml
+++ b/man/systemd-cryptsetup-generator.xml
@@ -228,6 +228,7 @@
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     </para>
diff --git a/man/systemd-cryptsetup@.service.xml b/man/systemd-cryptsetup@.service.xml
index 216db7467c..c70d6a9d3e 100644
--- a/man/systemd-cryptsetup@.service.xml
+++ b/man/systemd-cryptsetup@.service.xml
@@ -50,13 +50,14 @@
 
     <orderedlist>
       <listitem><para>If a key file is explicitly configured (via the third column in
-      <filename>/etc/crypttab</filename>), a key read from it is used. If a PKCS#11 token is configured
-      (using the <varname>pkcs11-uri=</varname> option) the key is decrypted before use.</para></listitem>
+      <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>
 
       <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
-      too, if a PKCS#11 token is configured, any key found this way is decrypted before
+      too, if a PKCS#11/FIDO2/TPM2 token/device is configured, any key found this way is decrypted before
       use.</para></listitem>
 
       <listitem><para>If the <varname>try-empty-password</varname> option is specified it is then attempted
@@ -77,6 +78,7 @@
       <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>,
+      <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      </para>
   </refsect1>
diff --git a/man/systemd-repart.xml b/man/systemd-repart.xml
index 16add32b2d..858b5be66d 100644
--- a/man/systemd-repart.xml
+++ b/man/systemd-repart.xml
@@ -300,12 +300,23 @@
         <term><option>--key-file=</option></term>
 
         <listitem><para>Takes a file system path. Configures the encryption key to use when setting up LUKS2
-        volumes configured with the <varname>Encrypt=</varname> setting in partition files. Should refer to a
-        regular file containing the key, or an <constant>AF_UNIX</constant> stream socket in the file
-        system. In the latter case a connection is made to it and the key read from it. If this switch is not
-        specified the empty key (i.e. zero length key) is used. This behaviour is useful for setting up encrypted
-        partitions during early first boot that receive their user-supplied password only in a later setup
-        step.</para></listitem>
+        volumes configured with the <varname>Encrypt=key-file</varname> setting in partition files. Should
+        refer to a regular file containing the key, or an <constant>AF_UNIX</constant> stream socket in the
+        file system. In the latter case a connection is made to it and the key read from it. If this switch
+        is not specified the empty key (i.e. zero length key) is used. This behaviour is useful for setting
+        up encrypted partitions during early first boot that receive their user-supplied password only in a
+        later setup step.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--tpm2-device=</option></term>
+        <term><option>--tpm2-pcrs=</option></term>
+
+        <listitem><para>Configures the TPM2 device and list of PCRs to use for LUKS2 volumes configured with
+        the <varname>Encrypt=tpm2</varname> option. These options take the same parameters as the identically
+        named options to
+        <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        and have the same effect on partitions where TPM2 enrollment is requested.</para></listitem>
       </varlistentry>
 
       <xi:include href="standard-options.xml" xpointer="help" />
@@ -314,11 +325,18 @@
   </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>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+      <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     </para>
   </refsect1>
 
diff --git a/man/tpm2-crypttab.sh b/man/tpm2-crypttab.sh
new file mode 100644
index 0000000000..41db2aeddd
--- /dev/null
+++ b/man/tpm2-crypttab.sh
@@ -0,0 +1,10 @@
+# Enroll the TPM2 security chip in the LUKS2 volume, and bind it to PCR 7
+# only. Replace /dev/sdXn by the partition to use (e.g. /dev/sda1).
+sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=7 /dev/sdXn
+
+# Test: Let's run systemd-cryptsetup to test if this worked.
+sudo /usr/lib/systemd/systemd-cryptsetup attach mytest /dev/sdXn - tpm2-device=auto
+
+# If that worked, let's now add the same line persistently to /etc/crypttab,
+# for the future.
+sudo bash -c 'echo "mytest /dev/sdXn - tpm2-device=auto" >> /etc/crypttab'
diff --git a/man/yubikey-crypttab.sh b/man/yubikey-crypttab.sh
index 651246d6a1..05e581b32b 100644
--- a/man/yubikey-crypttab.sh
+++ b/man/yubikey-crypttab.sh
@@ -1,50 +1,26 @@
-# Make sure no one can read the files we generate but us
-umask 077
-
 # Destroy any old key on the Yubikey (careful!)
 ykman piv reset
 
-# Generate a new private/public key pair on the device, store the public key in 'pubkey.pem'.
+# Generate a new private/public key pair on the device, store the public key in
+# 'pubkey.pem'.
 ykman piv generate-key -a RSA2048 9d pubkey.pem
 
 # Create a self-signed certificate from this public key, and store it on the
-# device. The "subject" should be an arbitrary string to identify the token in
-# the p11tool output below.
+# device. The "subject" should be an arbitrary user-chosen string to identify
+# the token with.
 ykman piv generate-certificate --subject "Knobelei" 9d pubkey.pem
 
-# Check if the newly create key on the Yubikey shows up as token in PKCS#11. Have a look at the output, and
-# copy the resulting token URI to the clipboard.
-p11tool --list-tokens
-
-# Generate a (secret) random key to use as LUKS decryption key.
-dd if=/dev/urandom of=plaintext.bin bs=128 count=1
-
-# Encode the secret key also as base64 text (with all whitespace removed)
-base64 < plaintext.bin | tr -d '\n\r\t ' > plaintext.base64
-
-# Encrypt this newly generated (binary) LUKS decryption key using the public key whose private key is on the
-# Yubikey, store the result in /etc/cryptsetup-keys.d/mytest.key, where we'll look for it during boot.
-mkdir -p /etc/cryptsetup-keys.d
-sudo openssl rsautl -encrypt -pubin -inkey pubkey.pem -in plaintext.bin -out /etc/cryptsetup-keys.d/mytest.key
-
-# Configure the LUKS decryption key on the LUKS device. We use very low pbkdf settings since the key already
-# has quite a high quality (it comes directly from /dev/urandom after all), and thus we don't need to do much
-# key derivation. Replace /dev/sdXn by the partition to use (e.g. sda1)
-sudo cryptsetup luksAddKey /dev/sdXn plaintext.base64 --pbkdf=pbkdf2 --pbkdf-force-iterations=1000
-
-# Now securely delete the plain text LUKS key, we don't need it anymore, and since it contains secret key
-# material it should be removed from disk thoroughly.
-shred -u plaintext.bin plaintext.base64
-
-# We don't need the public key anymore either, let's remove it too. Since this one is not security
-# sensitive we just do a regular "rm" here.
+# We don't need the public key anymore, let's remove it. Since it is not
+# security sensitive we just do a regular "rm" here.
 rm pubkey.pem
 
-# Test: Let's run systemd-cryptsetup to test if this all worked. The option string should contain the full
-# PKCS#11 URI we have in the clipboard; it tells the tool how to decipher the encrypted LUKS key. Note that
-# systemd-cryptsetup automatically searches for the encrypted key in /etc/cryptsetup-keys.d/, hence we do
-# not need to specify the key file path explicitly here.
-sudo systemd-cryptsetup attach mytest /dev/sdXn - 'pkcs11-uri=pkcs11:…'
+# Enroll the freshly initialized security token in the LUKS2 volume. Replace
+# /dev/sdXn by the partition to use (e.g. /dev/sda1).
+sudo systemd-cryptenroll --pkcs11-token-uri=auto /dev/sdXn
+
+# Test: Let's run systemd-cryptsetup to test if this all worked.
+sudo /usr/lib/systemd/systemd-cryptsetup attach mytest /dev/sdXn - pkcs11-uri=auto
 
-# If that worked, let's now add the same line persistently to /etc/crypttab, for the future.
-sudo bash -c 'echo "mytest /dev/sdXn - \'pkcs11-uri=pkcs11:…\'" >> /etc/crypttab'
+# If that worked, let's now add the same line persistently to /etc/crypttab,
+# for the future.
+sudo bash -c 'echo "mytest /dev/sdXn - pkcs11-uri=auto" >> /etc/crypttab'