creds-tool: expose new signed PCR policies in creds tool, too

1 files changed, 36 insertions, 1 deletions

diff --git a/man/systemd-creds.xml b/man/systemd-creds.xml
index 7592961f63..d9b30a7e96 100644
--- a/man/systemd-creds.xml
+++ b/man/systemd-creds.xml
@@ -334,6 +334,40 @@
       </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>
+
+        <listitem><para>Configures a TPM2 signed PCR policy to bind encryption to, for use with the
+        <command>encrypt</command> command. 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 shall
+        be possible without losing access to all previously encrypted secrets.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--tpm2-signature=</option><arg>PATH</arg></term>
+
+        <listitem><para>Takes a path to a TPM2 PCR signature file as generated by the
+        <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        tool and that may be used to allow the <command>decrypt</command> command to decrypt credentials that
+        are bound to specific signed PCR values. If this this is not specified explicitly, and a credential
+        with a signed PCR policy is attempted to be decrypted, 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.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><option>--quiet</option></term>
         <term><option>-q</option></term>
 
@@ -413,7 +447,8 @@ SetCredentialEncrypted=mysql-password: \
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+      <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     </para>
   </refsect1>