| SYSTEMD-PCRLOCK(8) | systemd-pcrlock | SYSTEMD-PCRLOCK(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 792u
/usr/lib/systemd/systemd-pcrlock [OPTIONS...]
.SH "EXPERIMENTAL"
.PP This component is experimental and subject to change without advance
notice. It will be stabilized and given a backward-compatibility guarantee
in a future release, but may also possibly be removed.
.SH "DESCRIPTION"
.PP systemd-pcrlock is a tool that may be used to analyze and predict
TPM2 PCR measurements, and generate TPM2 access policies from the prediction
which it stores in a TPM2 NV index (i.e. in the TPM2 non-volatile memory).
This may then be used to restrict access to TPM2 objects (such as disk
encryption keys) to system boot-ups in which only specific, trusted
components are used.
.PP systemd-pcrlock uses as input for its analysis and prediction:
.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 PolicyPCR and PolicyOR items),
which is then stored in an NV index in the TPM2. This may be used to then
lock secrets (such as disk encryption keys) to these policies (via a TPM2
PolicyAuthorizeNV policy).
.PP Use tools such as systemd-cryptenroll(1) or
systemd-repart(8) to bind disk encryption to such a
systemd-pcrlock TPM2 policy. Specifically, see the
--tpm2-pcrlock= switches of these tools.
.PP The access policy logic requires a TPM2 device that implements the
PolicyAuthorizeNV command, i.e. implements TPM 2.0 version 1.38 or
newer.
.SH "COMMANDS"
.PP The following commands are understood:
.PP log
This reads the combined TPM2 event log, validates it, matches it against the
current PCR values, and outputs both in tabular form. Combine with
--json= to generate output in JSON format.
Added in version 255.
.RE
.PP cel
This reads the combined TPM2 event log and writes it to STDOUT in TCG
Canonical Event Log Format (CEL-JSON)[1].
Added in version 255.
.RE
.PP list-components
Shows a list of component definitions and their variants, i.e. the *.pcrlock
files discovered in /var/lib/pcrlock.d/, /usr/lib/pcrlock.d/, and the other
supported directories. See systemd.pcrlock(5) for details on these
files and the full list of directories searched.
Added in version 255.
.RE
.PP predict
Predicts the PCR state on future boots. This will analyze the TPM2 event log
as described above, recognize components, and then generate all possible
resulting PCR values for all combinations of component variants. Note that
no prediction is made for PCRs whose value does not match the event log
records, for which unrecognized measurements are discovered or for which
components are defined that cannot be found in the event log. This is a
safety measure to ensure that any generated access policy can be fulfilled
correctly on current and future boots.
Added in version 255.
.RE
.PP make-policy
This predicts the PCR state for future boots, much like the predict
command above. It then uses this data to generate a TPM2 access policy which
it stores in a TPM2 NV index. The prediction and information about the used
TPM2 and its NV index are written to /var/lib/systemd/pcrlock.json.
The NV index is allocated on first invocation, and updated on subsequent
invocations.
The NV index contents may be changed (and thus the policy stored in it
updated) by providing an access PIN. This PIN is normally generated
automatically and stored in encrypted form (with an access policy binding it
to the NV index itself) in the aforementioned JSON policy file. This PIN may
be chosen by the user, via the --recovery-pin= switch. If specified
it may be used as alternative path of access to update the policy.
If the new prediction matches the old this command terminates quickly and
executes no further operation. (Unless --force is specified, see
below.)
Starting with v256, a copy of the /var/lib/systemd/pcrlock.json policy file
is encoded in a credential (see systemd-creds(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
systemd-stub(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 bootctl(1)), which is
configurable via the --entry-token= switch, see below.
Added in version 255.
.RE
.PP remove-policy
Removes a previously generated policy. Deletes the
/var/lib/systemd/pcrlock.json file, and deallocates the NV index.
Added in version 255.
.RE
.PP is-supported
Checks if the local TPM2 supports all functionality for
systemd-pcrlock to work correctly. This does similar tests as
systemd-analyze has-tpm2, but also checks for supported of the TPM2
operations requires by systemd-pcrlock. Outputs one of no, partial
(in case some parts of TPM2 support are available in hardware, firmware, OS,
but not complete), obsolete (if TPM2 support is available in hardware,
firmware and OS, but the operations required for systemd-pcrlock are
missing), yes. Returns an exit status of zero if full support is available,
otherwise non-zero.
If combined with --quiet, suppresses the output of the string.
Currently, this checks for support for the PolicAuthorizeNV TPM2 command, as
well as for support of the SHA-256 hash algorithm.
Added in version 258.
.RE
.PP lock-firmware-code, unlock-firmware-code
Generates/removes .pcrlock files based on the TPM2 event log of the current
boot covering all records for PCRs 0 ("platform-code") and 2
("external-code").
This operation allows locking the boot process to the current version of the
firmware of the system and its extension cards. This operation should only
be used if the system vendor does not provide suitable pcrlock data ahead of
time.
Note that this data only matches the current version of the firmware. If a
firmware update is applied this data will be out-of-date and any access
policy generated from it will no longer pass. It is thus recommended to
invoke unlock-firmware-code before doing a firmware update, followed
by make-policy to refresh the policy.
systemd-pcrlock lock-firmware-code is invoked automatically at boot
via the systemd-pcrlock-firmware-code.service unit, if enabled. This ensures
that an access policy managed by systemd-pcrlock is automatically
locked to the new firmware version whenever the policy has been relaxed
temporarily, in order to cover for firmware updates, as described above.
The files are only generated from the event log if the event log matches the
current TPM2 PCR state.
This writes/removes the files
/var/lib/pcrlock.d/250-firmware-code-early.pcrlock.d/generated.pcrlock and
/var/lib/pcrlock.d/550-firmware-code-late.pcrlock.d/generated.pcrlock.
Added in version 255.
.RE
.PP lock-firmware-config, unlock-firmware-config
This is similar to lock-firmware-code/unlock-firmware-code but
locks down the firmware configuration, i.e. PCRs 1
("platform-config") and 3 ("external-config").
This functionality should be used with care as in most scenarios a minor
firmware configuration change should not invalidate access policies to TPM2
objects. Also note that some systems measure unstable and unpredictable
information (e.g. current CPU voltages, temperatures, as part of SMBIOS
data) to these PCRs, which means this form of lockdown cannot be used
reliably on such systems. Use this functionality only if the system and
hardware is well known and does not suffer by these limitations, for example
in virtualized environments.
Use unlock-firmware-config before making firmware configuration
changes. If the systemd-pcrlock-firmware-config.service unit is enabled it
will automatically generate a pcrlock file from the new measurements.
This writes/removes the files
/var/lib/pcrlock.d/250-firmware-config-early.pcrlock.d/generated.pcrlock and
/var/lib/pcrlock.d/550-firmware-config-late.pcrlock.d/generated.pcrlock.
Added in version 255.
.RE
.PP lock-secureboot-policy, unlock-secureboot-policy
Generates/removes a .pcrlock file based on the SecureBoot policy currently
enforced. This looks at the SecureBoot, PK, KEK, db, dbx, dbt, dbr EFI
variables and predicts their measurements to PCR 7
("secure-boot-policy") on the next boot.
Use unlock-secureboot-policy before applying SecureBoot policy
updates. If the systemd-pcrlock-secureboot-policy.service unit is enabled it
will automatically generate a pcrlock file from the policy discovered.
This writes/removes the file
/var/lib/pcrlock.d/230-secureboot-policy.pcrlock.d/generated.pcrlock.
Added in version 255.
.RE
.PP lock-secureboot-authority, unlock-secureboot-authority
Generates/removes a .pcrlock file based on the SecureBoot authorities used to
validate the boot path. SecureBoot authorities are the specific SecureBoot
database entries that where used to validate the UEFI PE binaries executed
at boot. This looks at the event log of the current boot, and uses relevant
measurements on PCR 7 ("secure-boot-policy").
This writes/removes the file
/var/lib/pcrlock.d/620-secureboot-authority.pcrlock.d/generated.pcrlock.
Added in version 255.
.RE
.PP lock-gpt [DEVICE], unlock-gpt
Generates/removes a .pcrlock file based on the GPT partition table of the
specified disk. If no disk is specified automatically determines the block
device backing the root file system. This locks the state of the disk
partitioning of the booted medium, which firmware measures to PCR 5
("boot-loader-config").
This writes/removes the file
/var/lib/pcrlock.d/600-gpt.pcrlock.d/generated.pcrlock.
Added in version 255.
.RE
.PP lock-pe [BINARY], unlock-pe
Generates/removes a .pcrlock file based on the specified PE binary. This is
useful for predicting measurements the firmware makes to PCR 4
("boot-loader-code") if the specified binary is part of the UEFI
boot process. Use this on boot loader binaries and suchlike. Use
lock-uki (see below) for PE binaries that are unified kernel images
(UKIs).
Expects a path to the PE binary as argument. If not specified, reads the
binary from STDIN instead.
The pcrlock file to write must be specified via the --pcrlock=
switch.
Added in version 255.
.RE
.PP lock-uki [UKI], unlock-uki
Generates/removes a .pcrlock file based on the specified UKI PE binary. This
is useful for predicting measurements the firmware makes to PCR 4
("boot-loader-code"), and systemd-stub(7) makes to PCR 11
("kernel-boot"), if the specified UKI is booted. This is a
superset of lock-pe.
Expects a path to the UKI PE binary as argument. If not specified, reads the
binary from STDIN instead.
The pcrlock file to write must be specified via the --pcrlock=
switch.
Added in version 255.
.RE
.PP lock-machine-id, unlock-machine-id
Generates/removes a .pcrlock file based on /etc/machine-id. This is useful
for predicting measurements systemd-pcrmachine.service(8) makes to
PCR 15 ("system-identity").
This writes/removes the file /var/lib/pcrlock.d/820-machine-id.pcrlock.
Added in version 255.
.RE
.PP lock-file-system [PATH], unlock-file-system
[PATH]
Generates/removes a .pcrlock file based on file system identity. This is
useful for predicting measurements systemd-pcrfs@.service(8) makes to
PCR 15 ("system-identity") for the root and /var/ file
systems.
This writes/removes the files /var/lib/pcrlock.d/830-root-file-system.pcrlock
and /var/lib/pcrlock.d/840-file-system-path.pcrlock.
Added in version 255.
.RE
.PP lock-kernel-cmdline [FILE],
unlock-kernel-cmdline
Generates/removes a .pcrlock file based on /proc/cmdline (or the specified
file if given). This is useful for predicting measurements the Linux kernel
makes to PCR 9 ("kernel-initrd").
This writes/removes the file
/var/lib/pcrlock.d/710-kernel-cmdline.pcrlock/generated.pcrlock.
Added in version 255.
.RE
.PP lock-kernel-initrd FILE, unlock-kernel-initrd
Generates/removes a .pcrlock file based on a kernel initrd cpio archive. This
is useful for predicting measurements the Linux kernel makes to PCR 9
("kernel-initrd"). Do not use for systemd-stub(7) UKIs, as
the initrd is combined dynamically from various sources and hence does not
take a single input, like this command.
This writes/removes the file
/var/lib/pcrlock.d/720-kernel-initrd.pcrlock/generated.pcrlock.
Added in version 255.
.RE
.PP lock-raw [FILE], unlock-raw
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 --pcrs= is specified. The generated .pcrlock file
is written to the file specified via --pcrlock= or to STDOUT (if none
is specified).
Added in version 255.
.RE
.SH "OPTIONS"
.PP The following options are understood:
.PP --full
Show full hash value instead of abbreviating to 7 characters.
Added in version 262.
.RE
.PP --raw-description
When displaying the TPM2 event log do not attempt to decode the records to
provide a friendly event log description string. Instead, show the binary
payload data in escaped form.
Added in version 255.
.RE
.PP --pcr=
Specifies the PCR number to use. May be specified more than once to select
multiple PCRs.
This is used by lock-raw and lock-pe to select the PCR to lock
against.
If used with predict and make-policy this will override which
PCRs to include in the prediction and policy. If unspecified this defaults
to PCRs 0-5, 7, 11, 13-15. Note that these commands will not include any
PCRs in the prediction/policy (even if specified explicitly) if there are
measurements in the event log that do not match the current PCR value, or
there are unrecognized measurements in the event log, or components define
measurements not seen in the event log.
Added in version 255.
.RE
.PP --nv-index=
Specifies the NV index to store the policy in. Honoured by
make-policy. If not specified, the command will automatically pick a
free NV index.
Added in version 255.
.RE
.PP --components=
Takes a path to read *.pcrlock and *.pcrlock.d/*.pcrlock files from. May be
used more than once to specify multiple such directories. If not specified,
defaults to /etc/pcrlock.d/, /run/pcrlock.d/, /var/lib/pcrlock.d/,
/usr/local/lib/pcrlock.d/, /usr/lib/pcrlock.d/.
Added in version 255.
.RE
.PP --location=
Takes either a string or a colon-separated pair of strings. Configures up to
which point in the sorted list of defined components to analyze/predict PCRs
to. Typically, the systemd-pcrlock tool is invoked from a fully
booted system after boot-up and before shutdown. This means various
components that are defined for shutdown have not been measured yet, and
should not be searched for. This option allows one to restrict which
components are considered for analysis (taking only components before some
point into account, ignoring components after them). The expected string is
ordered against the filenames of the components defined. Any components with
a lexicographically later name are ignored. This logic applies to the
log, predict, and make-policy verbs. If a
colon-separated pair of strings are specified then they select which phases
of the boot to include in the prediction/policy. The first string defines
where the first prediction shall be made, and the second string defines
where the last prediction shall be made. All such predictions are then
combined into one set.
If used with list-components the selected location range will be
highlighted in the component list.
Defaults to 760-:940-, which means the policies generated by default will
basically cover the whole runtime of the OS userspace, from the initrd (as
760- closely follows 750-enter-initrd.pcrlock) until (and including) the
main runtime of the system (as 940- is closely followed by
950-shutdown.pcrlock). See systemd.pcrlock(5) for a full list of
well-known components, that illustrate where this range is placed by
default.
Added in version 255.
.RE
.PP --recovery-pin=
Takes one of hide, show or query. Defaults to hide. Honoured by
make-policy. 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 — only in case of
show — 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.
Added in version 255.
.RE
.PP --pcrlock=
Takes a file system path as argument. If specified, configures where to write
the generated pcrlock data to. Honoured by the various lock-*
commands. If not specified, a default path is generally used, as documented
above.
Added in version 255.
.RE
.PP --policy=
Takes a file system path as argument. If specified, configures where to write
pcrlock policy metadata to. If not specified, defaults to
/var/lib/systemd/pcrlock.json.
Added in version 255.
.RE
.PP --force
If specified with make-policy, the predicted policy will be written to
the NV index even if it is detected to be the same as the previously stored
one.
Added in version 255.
.RE
.PP --entry-token=
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
bootctl(1) option of the same regarding expected values. This switch
has an effect on the make-policy command only.
Added in version 256.
.RE
.PP --quiet
If specified suppresses output when invoked for is-supported.
Added in version 258.
.RE
.PP --strict=
Takes a boolean. Defaults to false. Honoured by make-policy and
predict. If true all specified PCRs must be included in the policy
otherwise the command returns failure.
Added in version 262.
.RE
.PP --json=MODE
Shows output formatted as JSON. Expects one of short (for the shortest
possible output without any redundant whitespace or line breaks), pretty
(for a pretty version of the same, with indentation and line breaks) or off
(to turn off JSON output, the default).
.RE
.PP --no-pager
Do not pipe output into a pager.
.RE
.PP -h, --help
Print a short help text and exit.
.RE
.PP --version
Print a short version string and exit.
.RE
.SH "EXIT STATUS"
.PP On success, 0 is returned, a non-zero failure code otherwise.
.SH "SEE ALSO"
.PP systemd(1), systemd.pcrlock(5),
systemd-cryptenroll(1), systemd-cryptsetup@.service(8),
systemd-repart(8), systemd-pcrmachine.service(8),
systemd-creds(1), systemd-stub(7), bootctl(1)
NOTES
- 1.
- TCG Canonical Event Log Format (CEL-JSON)
| systemd 262.2 |