cryptenroll: hook up new TPM2 signed policies with cryptenroll

1 files changed, 45 insertions, 8 deletions

diff --git a/man/systemd-cryptenroll.xml b/man/systemd-cryptenroll.xml
index afde0fad7e..889dd39b03 100644
--- a/man/systemd-cryptenroll.xml
+++ b/man/systemd-cryptenroll.xml
@@ -347,17 +347,53 @@
         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>
+        <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></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.</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 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></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
@@ -411,7 +447,8 @@
       <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 project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
      </para>
   </refsect1>