PCR Policies vs Authorized Policies¶

The simplest approach to sealing a secret against an expected system state using the TPM is to create what is called a "PCR Policy". This policy essentially requires a given set of PCRs to contain a specific set of values. This policy can be used to "seal" a secret, ie encrypt it using a key only the TPM has access to.

At some point, for example during the boot process, the boot loader will attempt to unseal this sealed secret. If the TPM's PCRs contain the expected values at this point in time, unsealing will succeed. If they do not contain the expected values, unsealing will either fail, or produce gibberish.

While regular PCR policies are sound and simple, they are not very flexible, unfortunately. For example, transparently handling updates of the boot loader is rather difficult because we would first have to retrieve the secret before we're able to re-seal it to the future set of PCR values. This is where Authorized Policies come in.

TPM Authorized Policies provide a mechanism by which a secret is not sealed to a set of specific PCR values, but to a list of PCR indices, and a public RSA key. This combination (PCR indices and public key) is called an Authorized Policy.

The owner of the system can then use the secret RSA key to "authorize" a specific set of PCR values, which is in essence a digital signature.

When unsealing the secret during system boot, the boot loader would present the TPM with the original Authorized Policy, and the signed set of PCR values. The TPM then essentially compares the current set of PCR values (as selected by the policy) to the authorized set of values, and verify the authorization's signature using the public key from the policy. If the PCR values match, and the signature checks out, it will be able to unseal the secret.

The benefit of this approach is that you can now seal the secret (such as a LUKS password) once - and when we later update the boot loader, shim loader etc, we just have to authorize the new set of PCR values using the RSA secret key.

Policy File Formats¶

To make things a little more complex, different file formats are being used to store policies and sealed secrets, depending on the implementation. The current standard is the so-called TPM2.0 key file format described in https://www.hansenpartnership.com/draft-bottomley-tpm2-keys.html. This format combines key material and policies into a single, ASN.1 encoded file.

In addition, file formats have been used in the past that stored TPM object in a native format defined in the TPM specification.

Finally, the systemd-boot implementation for unlocking disk partitions stores policies in a JSON formatted file, which can be fed to the systemd-cryptenroll tool. This file will contain any number of signed policies that we want systemd-cryptsetup to recognize during boot time. Each entry contains the list of PCRs that compose the PCR policy, a finger print of the public key, the hash of the policy and the signature (in base64) of the PCR policy.

pcr-oracle supports all three implementations. The target implementation can be selected using the --target-platform option, which accepts tpm2.0, systemd and oldgrub as arguments, respectively.

The default format is tpm2.0.

RSA Key File Formats¶

By default, pcr-oracle stores private RSA keys as PEM files and public RSA keys in native TPM encoded format. This behavior can be tuned, however. When it detects a file name that has a .pem extension, it will automatically assume that the caller expects the file to be in PEM format.

In addition, you can explicitly force a specific file format by prefixing the entire path by either pem: opr native:, respectively.

TPM Self-test¶

To perform a TPM self-test, simply execute pcr-oracle like this:

# pcr-oracle self-test

The reason this subcommand exists is that it allows an installer to set up full disk encryption without having to pull in all of tpm-tools.

TPM RSA key size test¶

To perform a TPM RSA key size test, simply execute pcr-oracle like this:

# pcr-oracle --rsa-bits 2048 rsa-test

This subcommand allows external programs, such as fde-tools, to find out the largest supported RSA key size.

Prediction Mode¶

In prediction mode, pcr-oracle is invoked like this:

# pcr-oracle --from eventlog \


        --before --stop-event grub-command=tpm2_key_protector_init \


        predict 0,2,4,7,9

This would create a PCR prediction for registers 0, 2, 3, 7, and 9 by scanning the current TPM event log until the point where grub executes a command called tpm2_key_protector_init.

As it processes the log, it will recompute the hash values for certain events to match the latest changes that were made to the system. For instance, for EFI Boot Variable events, it will consult the current value of a EFI variable and rehash it. The same holds for EFI Boot Service Application events for grub2 or shim; or for EFI GPT events.

In the example above, pcr-oracle will print the predicted values to standard output. If you want to process these values with a tool from the tpm2.0-tools package, you may prefer binary output, which you can select by invoking the tool with --format binary.

Sealing Against PCR Policies¶

In order to seal a secret againt a predicted set of PCRs, one would typically invoke pcr-oracle like this:

# pcr-oracle --from eventlog \


        --target-platform oldgrub \


        --before --stop-event grub-command=tpm2_key_protector_init \


        --input secret --output sealed \


        seal-secret 0,2,4,7,9

Note that the size of the secret to be sealed must not exceed 128 bytes.

The reverse operation looks like this:

# pcr-oracle --input sealed --output recovered \


        --target-platform oldgrub \


        unseal-secret 0,2,4,7,9

This will instruct the TPM to unseal the given sealed data, computing the policy hash using the current values of the indicated PCRs.

Sealing Against Authorized Policies¶

The following sequence of commands seals a secret against an authorized policy, and then authorized a set of PCR values by signing them into a signed policy:

# pcr-oracle \


        --target-platform oldgrub \


        --private-key policy-key.pem \


        --auth authorized.policy \


        create-authorized-policy 0,2,4,7,9
# pcr-oracle \


        --target-platform oldgrub \


        --auth authorized.policy \


        --input file-containing-secret \


        --output sealed-secret \


        seal-secret
# pcr-oracle \


        --target-platform oldgrub \


        --private-key policy-key.pem \


        --from eventlog \


        --before --stop-event grub-command=tpm2_key_protector_init \


        --output signed.policy \


        sign 0,2,4,7,9

The first of these commands creates the authorized policy and writes it to a file named authorized.policy. This file, along with the public portion of the RSA key, needs to be stored somewhere in a location that is accessible at the time we need to unlock the LUKS key.

The second command seals the secret against this policy. The clear text is stored in file-containing-secret, the encrypted secret is stored in sealed-secret.

Finally, the third command uses the prediction logic of pcr-oracle to predict a specific set of PCR values, in exactly the same way described in the section above on prediction mode. It then uses the given RSA key to sign these values and store the result in signed.policy.

Depending on the boot loader used, it may be helpful to provide the public portion of the RSA key in a format that is trivial to handle. For instance, it would be overkill to add DER parsing of RSA keys to grub. In a case like that, you want the key to be available in a form that can be fed to the TPM chip more or less directly. pcr-oracle supports this via its store-public-key subcommand:

# pcr-oracle \


        --private-key policy-key.pem \


        --public-key policy-pubkey \


        store-public-key

This command will read the RSA private key from the PEM file, and write the public key as a TPM2B_PUBLIC object to the indicated output file policy-pubkey.

Alternatively, if you want the public key to be stored as PEM formatted key, simply specify the file name of the public key with a .pem extension:

# pcr-oracle \


        --private-key policy-key.pem \


        --public-key policy-pubkey.pem \


        store-public-key

For details, please see section RSA Key File Formats.

Using the TPM2.0 Policy File Format¶

The following will seal a secret against PCR 0,2,4,7, and write the result to sealed-pcr.tpm using the new tpm2.0 format:

# pcr-oracle \
	--target-platform=tpm2.0 \
	--input secret \
	--output sealed-pcr.tpm \
	seal-secret 0,2,4,7

To seal a secret for an authorized policy:

# pcr-oracle \
	--target-platform=tpm2.0 \
	--auth authorized.policy \
	--input secret \
	--output sealed-auth.tpm \
	seal-secret

To sign the policy against PCR 0,2,4,7 for sealed-auth.tpm:

# pcr-oracle \
	--target-platform=tpm2.0 \
	--policy-name "sealing test" \
	--private-key policy-key.pem \
	--input sealed-auth.tpm \
	--output sealed-auth-signed.tpm \
	sign 0,2,4,7

Generating a Signed Policy for Systemd¶

When using systemd-boot instead of grub2, you would create an authorized policy as above, and seal your secret LUKS key against that. The main difference is in the way the signed policy is stored:

# pcr-oracle \
	--target-platform=systemd \
	--private-key policy-key.pem \
	--from eventlog \
	--output tpm2-pcr-signature.json \
	sign 0,2,4,7,9,12

This will predict a set of PCR values, sign them using the specified private key, and then store the signature in tpm2-pcr-signature.json. Note that this command will not overwrite the JSON file, it will update it by adding a new entry. If there already is an entry for the predicted set of PCR values, this will merely update the public key fingerprint and signature.

These policies can then be enrolled for future system boots using systemd-cryptenroll:

# systemd-cryptenroll \
	--tpm2-device=auto \
	--tpm2-public-key=public-key.pem \
	--tpm2-public-key-pcrs="0,2,4,7,9,12" 	--tpm2-signature=tpm2-pcr-signature.json \
	/dev/sda3

Creating and Replaying Test Cases¶

Firmwares tend to be buggy, like every piece of code, and UEFI firmwares are no different. In order to create a broad base of test cases to validate pcr-oracle against, it comes with support for creating and replaying test cases.

A test case is mostly a dump of the data that pcr-oracle processes when re-hashing the events from the TPM event log. This includes the content of UEFI variables such as Boot entries, variables related to Secure Boot, GPT headers, full copies of any EFI Applications loaded during bootup (such as shim.efi, grub.efi), and hashes for other files loaded by the boot loader (such as grub.cfg, or the kernel and initrd).

The following command will create a test case and store it in a directory tree at /tmp/pcr-oracle.test:

# pcr-oracle --from eventlog --verify current -d \


        --create-testcase /tmp/pcr-oracle.test \


        predict all

If you want to submit your test case, please use tar to archive the test case and create an issue in the github issue tracker at github.com/okirch/pcr-oracle.

To replay a test case, you can do this:

# pcr-oracle --from eventlog --verify current -d \


        --replay-testcase /tmp/pcr-oracle.test \


        predict all