search..
No manual entry for -- in section 8
troff:<standard input>:215: warning [p 3, 6.2i]: cannot break line
troff:<standard input>:217: warning [p 3, 6.5i]: cannot break line
troff:<standard input>:237: warning [p 3, 10.7i]: cannot break line
troff:<standard input>:239: warning [p 3, 11.0i]: cannot break line
troff:<standard input>:257: warning [p 4, 2.3i]: cannot break line
troff:<standard input>:269: warning [p 4, 4.5i]: cannot break line
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:

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

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

       o   The current PCR state of the TPM2 chip.

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

       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 temporarilytroff:<standard input>:567: warning [p 7, 11.5i]: cannot break line
, 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/lib/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.

       --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 257.13						     SYSTEMD-PCRLOCK(8)