Adding upstream version 256.upstream/256

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

1 files changed, 59 insertions, 27 deletions

diff --git a/man/systemd-pcrlock.xml b/man/systemd-pcrlock.xml
index a364dd3..19ba4c4 100644
--- a/man/systemd-pcrlock.xml
+++ b/man/systemd-pcrlock.xml
@@ -1,9 +1,10 @@
 <?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 -->
-<refentry id="systemd-pcrlock" xmlns:xi="http://www.w3.org/2001/XInclude" conditional='ENABLE_BOOTLOADER'>
+<refentry id="systemd-pcrlock" conditional='ENABLE_BOOTLOADER HAVE_OPENSSL HAVE_TPM2'
+          xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>systemd-pcrlock</title>
@@ -29,7 +30,7 @@
 
   <refsynopsisdiv>
     <cmdsynopsis>
-      <command>/usr/lib/systemd/systemd-pcrlock <arg choice="opt" rep="repeat">OPTIONS</arg></command>
+      <command>/usr/lib/systemd/systemd-pcrlock</command> <arg choice="opt" rep="repeat">OPTIONS</arg>
     </cmdsynopsis>
   </refsynopsisdiv>
 
@@ -61,7 +62,7 @@
       <filename>*.pcrlock.d/*.pcrlock</filename>, see
       <citerefentry><refentrytitle>systemd.pcrlock</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
       that each define expected measurements for one component of the boot process, permitting alternative
-      variants for each. (Variants may be used used to bless multiple kernel versions or boot loader versions
+      variants for each. (Variants may be used to bless multiple kernel versions or boot loader versions
       at the same time.)</para></listitem>
     </itemizedlist>
 
@@ -104,7 +105,7 @@
         <term><command>cel</command></term>
 
         <listitem><para>This reads the combined TPM2 event log and writes it to STDOUT in <ulink
-        url="https://trustedcomputinggroup.org/resource/canonical-event-log-format/">TCG Common Event Log
+        url="https://trustedcomputinggroup.org/resource/canonical-event-log-format/">TCG Canonical Event Log
         Format (CEL-JSON)</ulink> format.</para>
 
         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
@@ -155,6 +156,19 @@
         <para>If the new prediction matches the old this command terminates quickly and executes no further
         operation. (Unless <option>--force</option> is specified, see below.)</para>
 
+        <para>Starting with v256, a copy of the <filename>/var/lib/systemd/pcrlock.json</filename> policy
+        file is encoded in a credential (see
+        <citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
+        details) and written to the EFI System Partition or XBOOTLDR partition, in the
+        <filename>/loader/credentials/</filename> subdirectory. There it is picked up at boot by
+        <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
+        passed to the invoked initrd, where it can be used to unlock the root file system (which typically
+        contains <filename>/var/</filename>, which is where the primary copy of the policy is located, which
+        hence cannot be used to unlock the root file system). The credential file is named after the boot
+        entry token of the installation (see
+        <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>), which
+        is configurable via the <option>--entry-token=</option> switch, see below.</para>
+
         <xi:include href="version-info.xml" xpointer="v255"/>
         </listitem>
       </varlistentry>
@@ -266,7 +280,7 @@
       </varlistentry>
 
       <varlistentry>
-        <term><command>lock-gpt</command> <arg choice="opt"><replaceable>DEVICE</replaceable></arg></term>
+        <term><command>lock-gpt</command> <optional><replaceable>DEVICE</replaceable></optional></term>
         <term><command>unlock-gpt</command></term>
 
         <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on the GPT partition
@@ -282,7 +296,7 @@
       </varlistentry>
 
       <varlistentry>
-        <term><command>lock-pe</command> <arg choice="opt"><replaceable>BINARY</replaceable></arg></term>
+        <term><command>lock-pe</command> <optional><replaceable>BINARY</replaceable></optional></term>
         <term><command>unlock-pe</command></term>
 
         <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on the specified PE
@@ -301,7 +315,7 @@
       </varlistentry>
 
       <varlistentry>
-        <term><command>lock-uki</command> <arg choice="opt"><replaceable>UKI</replaceable></arg></term>
+        <term><command>lock-uki</command> <optional><replaceable>UKI</replaceable></optional></term>
         <term><command>unlock-uki</command></term>
 
         <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on the specified UKI PE
@@ -336,8 +350,8 @@
       </varlistentry>
 
       <varlistentry>
-        <term><command>lock-file-system</command> <arg choice="opt"><replaceable>PATH</replaceable></arg></term>
-        <term><command>unlock-file-system</command> <arg choice="opt"><replaceable>PATH</replaceable></arg></term>
+        <term><command>lock-file-system</command> <optional><replaceable>PATH</replaceable></optional></term>
+        <term><command>unlock-file-system</command> <optional><replaceable>PATH</replaceable></optional></term>
 
         <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on file system
         identity. This is useful for predicting measurements
@@ -353,7 +367,7 @@
       </varlistentry>
 
       <varlistentry>
-        <term><command>lock-kernel-cmdline</command> <arg choice="opt"><replaceable>FILE</replaceable></arg></term>
+        <term><command>lock-kernel-cmdline</command> <optional><replaceable>FILE</replaceable></optional></term>
         <term><command>unlock-kernel-cmdline</command></term>
 
         <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on
@@ -384,7 +398,7 @@
       </varlistentry>
 
       <varlistentry>
-        <term><command>lock-raw</command> <arg choice="opt"><replaceable>FILE</replaceable></arg></term>
+        <term><command>lock-raw</command> <optional><replaceable>FILE</replaceable></optional></term>
         <term><command>unlock-raw</command></term>
 
         <listitem><para>Generates/removes a <filename>.pcrlock</filename> file based on raw binary data. The
@@ -490,13 +504,16 @@
       <varlistentry>
         <term><option>--recovery-pin=</option></term>
 
-        <listitem><para>Takes a boolean. Defaults to false. Honoured by <command>make-policy</command>. If
-        true, will query the user for a PIN to unlock the TPM2 NV index with. If no policy was created before
-        this PIN is used to protect the newly allocated NV index. If a policy has been created before the PIN
-        is used to unlock write access to the NV index. If this option is not used a PIN is automatically
-        generated. Regardless if user supplied or automatically generated, it is stored in encrypted form in
-        the policy metadata file. The recovery PIN may be used to regain write access to an NV index in case
-        the access policy became out of date.</para>
+        <listitem><para>Takes one of <literal>hide</literal>, <literal>show</literal> or
+        <literal>query</literal>. Defaults to <literal>hide</literal>. Honoured by
+        <command>make-policy</command>. If <literal>query</literal>, will query the user for a PIN to unlock
+        the TPM2 NV index with. If no policy was created before, this PIN is used to protect the newly
+        allocated NV index. If a policy has been created before, the PIN is used to unlock write access to
+        the NV index. If either <literal>hide</literal> or <literal>show</literal> is used, a PIN is
+        automatically generated, and — only in case of <literal>show</literal> — displayed on
+        screen. Regardless if user supplied or automatically generated, it is stored in encrypted form in the
+        policy metadata file. The recovery PIN may be used to regain write access to an NV index in case the
+        access policy became out of date.</para>
 
         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
       </varlistentry>
@@ -531,6 +548,18 @@
         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>--entry-token=</option></term>
+
+        <listitem><para>Sets the boot entry token to use for the file name for the pcrlock policy credential
+        in the EFI System Partition or XBOOTLDR partition. See the
+        <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> option of
+        the same regarding expected values. This switch has an effect on the
+        <command>make-policy</command> command only.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+      </varlistentry>
+
       <xi:include href="standard-options.xml" xpointer="json" />
       <xi:include href="standard-options.xml" xpointer="no-pager" />
       <xi:include href="standard-options.xml" xpointer="help" />
@@ -546,14 +575,17 @@
 
   <refsect1>
     <title>See Also</title>
-    <para>
-      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd.pcrlock</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd-pcrmachine.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-     </para>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd.pcrlock</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-pcrmachine.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+     </simplelist></para>
   </refsect1>
 
 </refentry>