Merging upstream version 4.23.0.

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

1 files changed, 49 insertions, 17 deletions

diff --git a/upstream/debian-unstable/man8/systemd-pcrlock.8 b/upstream/debian-unstable/man8/systemd-pcrlock.8
index b3206f6b..004515d3 100644
--- a/upstream/debian-unstable/man8/systemd-pcrlock.8
+++ b/upstream/debian-unstable/man8/systemd-pcrlock.8
@@ -1,5 +1,5 @@
 '\" t
-.TH "SYSTEMD\-PCRLOCK" "8" "" "systemd 255" "systemd-pcrlock"
+.TH "SYSTEMD\-PCRLOCK" "8" "" "systemd 256~rc3" "systemd-pcrlock"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -22,8 +22,8 @@
 .SH "NAME"
 systemd-pcrlock, systemd-pcrlock-file-system.service, systemd-pcrlock-firmware-code.service, systemd-pcrlock-firmware-config.service, systemd-pcrlock-machine-id.service, systemd-pcrlock-make-policy.service, systemd-pcrlock-secureboot-authority.service, systemd-pcrlock-secureboot-policy.service \- Analyze and predict TPM2 PCR states and generate an access policy from the prediction
 .SH "SYNOPSIS"
-.HP \w'\fB/usr/lib/systemd/systemd\-pcrlock\ \fR\fB[OPTIONS...]\fR\ 'u
-\fB/usr/lib/systemd/systemd\-pcrlock \fR\fB[OPTIONS...]\fR
+.HP \w'\fB/usr/lib/systemd/systemd\-pcrlock\fR\ 'u
+\fB/usr/lib/systemd/systemd\-pcrlock\fR [OPTIONS...]
 .SH "DESCRIPTION"
 .PP
 Note: this command is experimental for now\&. While it is likely to become a regular component of systemd, it might still change in behaviour and interface\&.
@@ -80,7 +80,7 @@ The current PCR state of the TPM2 chip\&.
 Boot component definition files (*\&.pcrlock
 and
 *\&.pcrlock\&.d/*\&.pcrlock, see
-\fBsystemd.pcrlock\fR(5)) 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 at the same time\&.)
+\fBsystemd.pcrlock\fR(5)) that each define expected measurements for one component of the boot process, permitting alternative variants for each\&. (Variants may be used to bless multiple kernel versions or boot loader versions at the same time\&.)
 .RE
 .PP
 It uses these inputs to generate a combined event log, validating it against the PCR states\&. It then attempts to recognize event log records and matches them against the defined components\&. For each PCR where this can be done comprehensively (i\&.e\&. where all listed records and all defined components have been matched) this may then be used to predict future PCR measurements, taking the alternative variants defined for each component into account\&. This prediction may then be converted into a TPM2 access policy (consisting of TPM2
@@ -120,7 +120,7 @@ Added in version 255\&.
 \fBcel\fR
 .RS 4
 This reads the combined TPM2 event log and writes it to STDOUT in
-\m[blue]\fBTCG Common Event Log Format (CEL\-JSON)\fR\m[]\&\s-2\u[1]\d\s+2
+\m[blue]\fBTCG Canonical Event Log Format (CEL\-JSON)\fR\m[]\&\s-2\u[1]\d\s+2
 format\&.
 .sp
 Added in version 255\&.
@@ -163,6 +163,20 @@ If the new prediction matches the old this command terminates quickly and execut
 \fB\-\-force\fR
 is specified, see below\&.)
 .sp
+Starting with v256, a copy of the
+/var/lib/systemd/pcrlock\&.json
+policy file is encoded in a credential (see
+\fBsystemd-creds\fR(1)
+for details) and written to the EFI System Partition or XBOOTLDR partition, in the
+/loader/credentials/
+subdirectory\&. There it is picked up at boot by
+\fBsystemd-stub\fR(7)
+and passed to the invoked initrd, where it can be used to unlock the root file system (which typically contains
+/var/, 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
+\fBbootctl\fR(1)), which is configurable via the
+\fB\-\-entry\-token=\fR
+switch, see below\&.
+.sp
 Added in version 255\&.
 .RE
 .PP
@@ -372,7 +386,7 @@ Generates/removes a
 \&.pcrlock
 file based on raw binary data\&. The data is either read from the specified file or from STDIN (if none is specified)\&. This requires that
 \fB\-\-pcrs=\fR
-is specified\&. The generated pcrlock file is written to the file specified via
+is specified\&. The generated \&.pcrlock file is written to the file specified via
 \fB\-\-pcrlock=\fR
 or to STDOUT (if none is specified)\&.
 .sp
@@ -410,7 +424,7 @@ Added in version 255\&.
 .PP
 \fB\-\-nv\-index=\fR
 .RS 4
-Specifies to NV index to store the policy in\&. Honoured by
+Specifies the NV index to store the policy in\&. Honoured by
 \fBmake\-policy\fR\&. If not specified the command will automatically pick a free NV index\&.
 .sp
 Added in version 255\&.
@@ -462,8 +476,20 @@ Added in version 255\&.
 .PP
 \fB\-\-recovery\-pin=\fR
 .RS 4
-Takes a boolean\&. Defaults to false\&. Honoured by
-\fBmake\-policy\fR\&. 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\&.
+Takes one of
+"hide",
+"show"
+or
+"query"\&. Defaults to
+"hide"\&. Honoured by
+\fBmake\-policy\fR\&. If
+"query", 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
+"hide"
+or
+"show"
+is used, a PIN is automatically generated, and \(em only in case of
+"show"
+\(em 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\&.
 .sp
 Added in version 255\&.
 .RE
@@ -493,7 +519,18 @@ If specified with
 Added in version 255\&.
 .RE
 .PP
-\fB\-\-json=\fR\fIMODE\fR
+\fB\-\-entry\-token=\fR
+.RS 4
+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
+\fBbootctl\fR(1)
+option of the same regarding expected values\&. This switch has an effect on the
+\fBmake\-policy\fR
+command only\&.
+.sp
+Added in version 256\&.
+.RE
+.PP
+\fB\-\-json=\fR\fB\fIMODE\fR\fR
 .RS 4
 Shows output formatted as JSON\&. Expects one of
 "short"
@@ -523,15 +560,10 @@ Print a short version string and exit\&.
 On success, 0 is returned, a non\-zero failure code otherwise\&.
 .SH "SEE ALSO"
 .PP
-\fBsystemd\fR(1),
-\fBsystemd.pcrlock\fR(5),
-\fBsystemd-cryptenroll\fR(1),
-\fBsystemd-cryptsetup@.service\fR(8),
-\fBsystemd-repart\fR(8),
-\fBsystemd-pcrmachine.service\fR(8)
+\fBsystemd\fR(1), \fBsystemd.pcrlock\fR(5), \fBsystemd-cryptenroll\fR(1), \fBsystemd-cryptsetup@.service\fR(8), \fBsystemd-repart\fR(8), \fBsystemd-pcrmachine.service\fR(8), \fBsystemd-creds\fR(1), \fBsystemd-stub\fR(7), \fBbootctl\fR(1)
 .SH "NOTES"
 .IP " 1." 4
-TCG Common Event Log Format (CEL-JSON)
+TCG Canonical Event Log Format (CEL-JSON)
 .RS 4
 \%https://trustedcomputinggroup.org/resource/canonical-event-log-format/
 .RE