systemd-pcrlock-firmware-code.service(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:

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

Added in version 255.

cel

Added in version 255.

list-components

Added in version 255.

predict

Added in version 255.

make-policy

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

Added in version 255.

lock-firmware-code, unlock-firmware-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 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

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

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

This writes/removes the file /var/lib/pcrlock.d/600-gpt.pcrlock.d/generated.pcrlock.

Added in version 255.

lock-pe [BINARY], unlock-pe

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

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

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]

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

This writes/removes the file /var/lib/pcrlock.d/710-kernel-cmdline.pcrlock/generated.pcrlock.

Added in version 255.

lock-kernel-initrdFILE, unlock-kernel-initrd

This writes/removes the file /var/lib/pcrlock.d/720-kernel-initrd.pcrlock/generated.pcrlock.

Added in version 255.

lock-raw [FILE], unlock-raw

Added in version 255.

OPTIONS#

The following options are understood:

--raw-description

Added in version 255.

--pcr=

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=

Added in version 255.

--components=

Added in version 255.

--location=

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=

Added in version 255.

--pcrlock=

Added in version 255.

--policy=

Added in version 255.

--force

Added in version 255.

--entry-token=

Added in version 256.

--json=MODE

--no-pager

-h, --help

--version

EXIT STATUS#

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

SEE ALSO#

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#

1.

TCG Canonical Event Log Format (CEL-JSON)