Merging upstream version 256.

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

1 files changed, 65 insertions, 32 deletions

diff --git a/man/crypttab.xml b/man/crypttab.xml
index 126d3a0..955111f 100644
--- a/man/crypttab.xml
+++ b/man/crypttab.xml
@@ -1,7 +1,7 @@
 <?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">
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 <!--
   SPDX-License-Identifier: LGPL-2.1-or-later
 
@@ -104,10 +104,14 @@
       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>
+      smartcard. In this case a saved key used in unlock process is stored on disk/removable media, acquired via
+      <constant>AF_UNIX</constant>, or stored in the LUKS2 JSON token metadata header. For RSA, the saved key
+      is an encrypted volume key. The encrypted volume key is then decrypted by the PKCS#11 token with an RSA
+      private key stored on it, and used to unlock the encrypted volume. For elliptic-curve (EC) cryptography,
+      the saved key is the public key generated in enrollment process. The public key is then used to derive
+      a shared secret with a private key stored in the PKCS#11 token. The derived shared secret is then used
+      to unlock the volume. Use the <option>pkcs11-uri=</option> option described below to use this mechanism.
+      </para></listitem>
 
       <listitem><para>Similarly, the key may be acquired via a FIDO2 compatible hardware security token
       (which must implement the "hmac-secret" extension). In this case a key generated randomly during
@@ -257,6 +261,29 @@
       </varlistentry>
 
       <varlistentry>
+        <term><option>link-volume-key=</option></term>
+
+        <listitem><para>Specifies the kernel keyring and key description
+        (see <citerefentry project='man-pages'><refentrytitle>keyrings</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
+        where LUKS2 volume key gets linked during device activation. The kernel keyring
+        description and key description must be separated by <literal>::</literal>.</para>
+
+        <para>The kernel keyring part can be a string description or a predefined
+        kernel keyring prefixed with <literal>@</literal> (e.g.: to use <literal>@s</literal> session or
+        <literal>@u</literal> user keyring directly). The type prefix text in the kernel keyring description
+        is not required. The specified kernel keyring must already exist at the time of device activation.</para>
+
+        <para>The key part is a string description optionally prefixed by a <literal>%key_type:</literal>.
+        If no type is specified, the <literal>user</literal> type key is linked by default. See
+        <citerefentry project='man-pages'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        for more information on key descriptions (KEY IDENTIFIERS section).</para>
+
+        <para>Note that the linked volume key is not cleaned up automatically when the device is detached.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><option>luks</option></term>
 
         <listitem><para>Force LUKS mode. When this mode is used, the
@@ -322,7 +349,9 @@
         unsuccessful. Note that other units that depend on the unlocked device may still fail. In
         particular, if the device is used for a mount point, the mount point itself also needs to
         have the <option>nofail</option> option, or the boot will fail if the device is not unlocked
-        successfully.</para>
+        successfully. If a keyfile and/or a <option>header</option> are specified, the dependencies on
+        their respective directories will also not be fatal, so that umounting said directories will
+        not cause the generated cryptset unit to be deactivated.</para>
 
         <xi:include href="version-info.xml" xpointer="v186"/></listitem>
       </varlistentry>
@@ -452,10 +481,12 @@
         <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
         This option implies <option>plain</option>.</para>
 
-        <para>WARNING: Using the <option>swap</option> option will
-        destroy the contents of the named partition during every boot,
-        so make sure the underlying block device is specified
-        correctly.</para>
+        <warning>
+          <para>Using the <option>swap</option> option will
+          destroy the contents of the named partition during every boot,
+          so make sure the underlying block device is specified
+          correctly.</para>
+        </warning>
 
         <xi:include href="version-info.xml" xpointer="v186"/></listitem>
       </varlistentry>
@@ -585,8 +616,10 @@
         <literal>btrfs</literal>. If no argument is specified defaults to <literal>ext4</literal>. This
         option implies <option>plain</option>.</para>
 
-        <para>WARNING: Using the <option>tmp</option> option will destroy the contents of the named partition
-        during every boot, so make sure the underlying block device is specified correctly.</para>
+        <warning>
+          <para>Using the <option>tmp</option> option will destroy the contents of the named partition
+          during every boot, so make sure the underlying block device is specified correctly.</para>
+        </warning>
 
         <xi:include href="version-info.xml" xpointer="v186"/></listitem>
       </varlistentry>
@@ -641,7 +674,7 @@
         <term><option>pkcs11-uri=</option></term>
 
         <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
+        url="https://tools.ietf.org/html/rfc7512">RFC7512 PKCS#11 URI</ulink> pointing to a private 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
@@ -651,16 +684,16 @@
         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
+        as a 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 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>The specified URI can refer directly to a private key stored on a token or alternatively
+        just to a slot or token, in which case a search for a suitable private key will be performed.  In
+        this case if multiple suitable objects are found the token is refused. The keyfile configured
+        in the third column of the line is used as is (i.e. in binary form, unprocessed). The resulting
+        decrypted key (for RSA) or derived shared secret (for ECC) 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>
@@ -967,8 +1000,8 @@ external   /dev/sda3       keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchac
       <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 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
+      or EC cryptographic 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>
@@ -1012,16 +1045,16 @@ external   /dev/sda3       keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchac
 
   <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>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>,
-      <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-    </para>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+      <member><citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+    </simplelist></para>
   </refsect1>
 
 </refentry>