Skip to main content

​
Introduction

This procedure explains how to view, set, and reset the device-level PCR (Platform Configuration Register) policy for a node using ZCLI. Operators use this procedure to customize which PCR indexes EVE-OS (Edge Virtualization Engine) uses when sealing the vault encryption key into the TPM, or to remove a custom policy after making changes. A node that has no device-level PCR policy uses the project or system default. When you set a policy, ZCLI compares it against a recommended set of PCR indexes (0, 1, 2, 3, 4, 6, 7, 8, 9, 13, and 14) and warns you about any differences. PCR 5 is never allowed in a policy because its value changes across reboots. For background on what PCR policies are and why they matter, see Flexible PCR Policy and TPM PCR Index Security Implications.

​
Prerequisites

  • Node with a TPM 2.0 implementation (discrete or firmware) and SHA-256 PCR bank support.
  • ZCLI installed and configured with access to Edge Infrastructure Services.
  • You have the SysManager or SysAdmin role in your enterprise. See Manage Roles.
  • Remote attestation configured for the project.

​
View the Current PCR Policy

Run the following command to retrieve the device-level PCR policy for a specific node. Replace <name> with the node name, or use --uuid=<uuid> with the node’s UUID instead.
The output displays the node name, the policy version, the PCR indexes in the policy, and a description of each index:
If the node has no device-level policy, ZCLI displays the following message instead:

​
Set the PCR Policy

Apply a custom PCR policy to a node. The --pcrs option is required. Use the node name, or use --uuid=<uuid> instead.

​
Specify PCR indexes

The --pcrs value accepts individual indexes, ranges, or a combination of both, separated by commas. Comma-separated list. Specify indexes directly:
Range notation. Use a hyphen for consecutive indexes:
ZCLI rejects the list and does not contact Edge Infrastructure Services if any of the following are true:
  • An index is outside the range 0 to 15.
  • The list includes PCR 5.
  • The list includes the same index more than once, including through overlapping ranges.
  • The list does not include PCR 0.
  • A range is malformed, or its start is greater than its end.

​
ZCLI Security Safeguards

​
Policy change review

When you run pcr-policy set, ZCLI first displays the node name and the new policy. If the node already has a device-level policy, ZCLI also lists the indexes that the new policy removes or adds compared to the current one:
If the new policy is identical to the current one, ZCLI displays No changes vs current policy. and stops. Add --force to apply the policy anyway.

​
Security warnings

ZCLI then compares the new policy against the recommended set (0, 1, 2, 3, 4, 6, 7, 8, 9, 13, and 14). If the new policy leaves out any recommended index, ZCLI lists those indexes with the following warning:
If the new policy includes an index outside the recommended set, ZCLI lists those indexes with the following note:
Add an index outside the recommended set (10, 11, 12, or 15) only if your platform firmware or a trusted component measures into it in a stable way.

​
Confirmation

ZCLI asks you to confirm before it applies the policy. Enter y to apply the policy, or any other key to cancel:
After the policy is applied, ZCLI displays the following message and increments the policy version by one:

​
Skip the prompts in scripts

For scripted workflows, specify both --force and --confirm-risks to skip the warnings and the confirmation prompt. If you specify only one of the two flags, ZCLI still displays the warnings and asks for confirmation.

​
Reset the PCR Policy

Remove the device-level PCR policy from a node. After the reset, the node uses the project or system default policy. Use the node name, or use --uuid=<uuid> instead.
ZCLI asks you to confirm the reset. Enter y to continue. To skip the prompt, add -f:
After the reset, ZCLI displays the following message:
If the node has no device-level policy, ZCLI displays Edge node '<node-name>' has no device-level PCR policy to reset. and makes no change.

​
Verify the Configuration

After a set or reset operation, run the show command to confirm the result:
After a set operation, confirm that PCR indices lists the expected indexes and that Policy version has increased by one. After a reset operation, confirm that the output says the node has no device-level PCR policy. In the normal case, a policy change does not interrupt the node. When EVE-OS receives the new policy it unseals the vault key under the old policy and re-seals it under the new one, without a reboot and without contacting Edge Infrastructure Services for attestation. If the vault does become inaccessible after a policy change, it means the local unseal failed because the PCR values had already drifted from those recorded at the last sealing. In that case EVE-OS first tries to recover the correct policy locally by testing candidate PCR subsets against the sealed key. If that also fails, EVE-OS initiates remote attestation to retrieve the backup vault key from Edge Infrastructure Services and re-seals it under the current policy.

​
In This Series