From: Grigori Goronzy <greg@chown.ath.cx>
Date: Fri, 18 Feb 2022 11:51:00 +0000 (+0100)
Subject: cryptenroll: add TPM2 PIN documentation
X-Git-Tag: v251-rc1~139^2~2
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=caeb5604f9fd8e7aa43c7a1c853f8a7597240b17;p=thirdparty%2Fsystemd.git

cryptenroll: add TPM2 PIN documentation
---

diff --git a/man/systemd-cryptenroll.xml b/man/systemd-cryptenroll.xml
index d5fdb54cdd1..58a46267680 100644
--- a/man/systemd-cryptenroll.xml
+++ b/man/systemd-cryptenroll.xml
@@ -299,6 +299,24 @@
         signatures likely will validate against pre-existing certificates.</para></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><refentrytitle>tpm2_getcap</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
+        <citerefentry><refentrytitle>tpm2_dictionarylockout</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        commands, respectively.</para></listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><option>--wipe-slot=</option><arg rep="repeat">SLOT</arg></term>