man: document cryptenroll limitations

Let's document this for now. We should be able to lift these limitations
sooner or later, at which point we can drop this documentation again.

These two limitations are a pitfall that people should be aware of,
before going FIDO2-only.

See: #20230 #19208
(cherry picked from commit 0bada3f8b72e07bc8926b28957681abb5622039a)
(cherry picked from commit 17555384e5ea114a6e207561ec8050b906498f74)

diff --git a/man/systemd-cryptenroll.xml b/man/systemd-cryptenroll.xml
index b9bbe4ccaf4b8ec628bd8001bdc77d175077a63b..46c4b923298e804d2c1ccb1133efdf12dd111de1 100644 (file)
--- a/man/systemd-cryptenroll.xml
+++ b/man/systemd-cryptenroll.xml
@@ -58,6 +58,23 @@
     area, which is not available in other encryption formats.</para>
   </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 or recovery key (i.e. one of the latter two key types). For
+    example, it's currently not possible to unlock a device with a FIDO2 key in order to enroll a new FIDO2
+    key. Instead, in order to enroll a new FIDO2 key, it is necessary to provide an already enrolled regular
+    passphrase or recovery key. Thus, if in future key roll-over is desired it's generally recommended to
+    combine TPM2, FIDO2, PKCS#11 key enrollment with enrolling a regular passphrase or recovery key.</para>
+
+    <para>Also note that support for enrolling multiple FIDO2 tokens is currently not too useful, as while
+    unlocking <command>systemd-cryptsetup</command> cannot identify which token is currently plugged in and
+    thus does not know which authentication request to send to the device. This limitation does not apply to
+    tokens enrolled via PKCS#11 — because tokens of this type may be identified immediately, before
+    authentication.</para>
+  </refsect1>
+
   <refsect1>
     <title>Options</title>