# systemd-pcrlock

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


## NOTES



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


* * *