systemd-pcrlock(8) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | COMMANDS | OPTIONS | EXIT STATUS | SEE ALSO | NOTES | COLOPHON

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

NAME         top

       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         top


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

DESCRIPTION         top

       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         top

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

           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 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
           [email protected](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 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         top

       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 overrides
           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 overrides
           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         top

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

SEE ALSO         top

       systemd(1), systemd.pcrlock(5), systemd-cryptenroll(1),
       [email protected](8), systemd-repart(8),
       systemd-pcrmachine.service(8), systemd-creds(1), systemd-stub(7),
       bootctl(1)

NOTES         top

        1. TCG Canonical Event Log Format (CEL-JSON)
           https://trustedcomputinggroup.org/resource/canonical-event-log-format/

COLOPHON         top

       This page is part of the systemd (systemd system and service
       manager) project.  Information about the project can be found at
       ⟨http://www.freedesktop.org/wiki/Software/systemd⟩.  If you have
       a bug report for this manual page, see
       ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://github.com/systemd/systemd.git⟩ on 2024-06-14.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2024-06-13.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       [email protected]

systemd 257~devel                                     SYSTEMD-PCRLOCK(8)

Pages that refer to this page: systemd.directives(7)systemd.index(7)