2QUIC

Search docs

Find a documentation page

Runbook: TEE upgrade

Roll a new enclave image with updated PCR measurements without losing the identity key.

Why this is delicate

The KMS key policy is PCR-bound: only an enclave whose measured boot matches the expected PCRs can decrypt the wrapped identity key. Upgrading the enclave image changes the PCRs, which means the new image cannot decrypt the existing ciphertext until the policy is updated.

High-level flow

  1. Build and publish the new EIF artefact (sibling repo CI).
  2. Compute the new PCR values from the EIF.
  3. Update the KMS key policy to include the new PCRs alongside the current ones (additive, never replace until cutover succeeds).
  4. Deploy the new enclave to a canary host.
  5. Re-wrap the identity key under the updated policy (validator-cli rotate-identity).
  6. Verify the sign-probe stays green on the canary.
  7. Roll the upgrade out to remaining hosts in batches.
  8. Once 100% are on the new EIF, remove the old PCRs from the key policy.

TODO: pending content

  • Concrete validator-cli upgrade invocation (depends on validator-cli M9.x upgrade subcommand wiring).
  • PCR drift detection and alerting recipe.
  • Cutover ordering when multiple TEEs share the same KMS key.