SYSTEMD-PCRLOCK(8)		systemd-pcrlock		    SYSTEMD-PCRLOCK(8)

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

SYNOPSIS
       /usr/lib/systemd/systemd-pcrlock [OPTIONS...]

DESCRIPTION
       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.

       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.

       systemd-pcrlock uses as input for its analysis and prediction:

       •   The UEFI firmware TPM2 event log (i.e.
	   /sys/kernel/security/tpm0/binary_bios_measurements) of the current
	   boot.

       •   The userspace TPM2 event log (i.e.
	   /run/log/systemd/tpm2-measure.log) of the current boot.

       •   The current PCR state of the TPM2 chip.

       •   Boot component definition files (*.pcrlock and
	   *.pcrlock.d/*.pcrlock, see systemd.pcrlock(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.)

       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).

       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.

       The access policy logic requires a TPM2 device that implements the
       "PolicyAuthorizeNV" command, i.e. implements TPM 2.0 version 1.38 or
       newer.

COMMANDS
       The following commands are understood:

       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.

       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.

       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.

       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.

       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.

       remove-policy
	   Removes a previously generated policy. Deletes the
	   /var/lib/systemd/pcrlock.json file, and deallocates the NV index.

	   Added in version 255.

       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.

       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.

       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.

       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-firmware-config 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.

       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.

       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.

       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.

       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.

       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.

       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.

       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.

       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.

       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.

OPTIONS
       The following options are understood:

       --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.

       --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-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.

       --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.

       --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/pcrlock.d/,
	   /usr/lib/pcrlock.d/.

	   Added in version 255.

       --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.

       --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.

       --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.

       --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.

       --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.

       --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.

       --quiet
	   If specified suppresses output when invoked for is-supported.

	   Added in version 258.

       --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).

       --no-pager
	   Do not pipe output into a pager.

       -h, --help
	   Print a short help text and exit.

       --version
	   Print a short version string and exit.

EXIT STATUS
       On success, 0 is returned, a non-zero failure code otherwise.

SEE ALSO
       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)
	   https://trustedcomputinggroup.org/resource/canonical-event-log-
	   format/

systemd 258						    SYSTEMD-PCRLOCK(8)