Skip to content

docs,dev-docs: document firmware upgrades and change of PIID #2590

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sespiros wants to merge 2 commits into
base: main
Choose a base branch
from
+23 −0
Open

docs,dev-docs: document firmware upgrades and change of PIID #2590

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f02a17a
dev-docs: note that bare-metal runner specs go stale
sespiros Aug 17, 2026
aaa4221
docs: warn that firmware updates invalidate TDX reference values
sespiros Aug 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions dev-docs/e2e/bare-metal-runner.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -336,6 +336,11 @@ Add a file [`dev-docs/e2e/<host>/manifest.json`](../e2e) with the values for the
If the runner is using k3s and the embedded mirror registry, add a corresponding configuration file at `dev-docs/e2e/<host>/contrast-imagepuller.toml`.
Push the branch and run the `update_bm_tcb_specs` workflow on that branch.

These values aren't set once and forgotten.
Updating a TDX host's firmware regenerates the platform's SGX provisioning keys, which changes the PIID, so `AllowedPIIDs` goes stale and the platform has to be registered with Intel again before it can produce quotes at all.
Replacing the TDX module changes `MrSeam`.
Both are covered in the wiki under `infrastructure/firmware_upgrade.md`.

## Sync Server

**This step only applies to servers owned by Edgeless Systems that don't have an application load balancer.**
Expand Down
9 changes: 9 additions & 0 deletions docs/docs/architecture/components/manifest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -347,6 +347,15 @@ The following command will print a JSON document, containing the hex-encoded PII
cut -d, -f6 pckid_retrieval.csv | poe-gen-tool extract --type pm /dev/stdin
```

:::warning

The `PIID` is derived from the platform's SGX provisioning keys.
Updating the platform firmware can regenerate those keys, which changes the `PIID` and requires the platform to be registered with Intel again.

@charludo charludo Aug 18, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Updating the platform firmware can regenerate those keys, which changes the `PIID` and requires the platform to be registered with Intel again.
Updating the platform firmware can regenerate those keys, which changes the `PIID` and requires the platform to be re-registered with Intel.

Until it's registered, Intel doesn't issue PCK certificates for the platform, so it can't produce quotes at all.

@charludo charludo Aug 18, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Until it's registered, Intel doesn't issue PCK certificates for the platform, so it can't produce quotes at all.
Until the re-registration is completed, Intel doesn't issue PCK certificates for the platform, which therefore can't produce quotes at all.

Nit: too many it's :D

After a firmware update, re-extract the `PIID` and update this list.

:::

### `ReferenceValues.tdx.*.MemoryIntegrity` {#tdx-memory-integrity}

The `MemoryIntegrity` field controls verification of the TDX memory integrity mode (see [TDX Module Spec], chapter 16).
Expand Down
9 changes: 9 additions & 0 deletions docs/docs/howto/cluster-setup/bare-metal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,15 @@ Follow Intel's [TDX Enabling Guide](https://cc-enabling.trustedservices.intel.co
When deciding to update the Intel TDX module, be aware that the latest module might be incompatible with your CPU or host firmware.
Make sure to keep a backup of all files you're overwriting in this step until you're sure that the new module works correctly.

:::warning

Updating platform firmware can regenerate the platform's SGX provisioning keys, giving the platform a new PPID, QE ID and `PIID`.
Intel doesn't issue PCK certificates for an unregistered platform, so the host can't produce attestation quotes and confidential VMs fail to start.

After a firmware update, register the platform again using Intel's `PCKIDRetrievalTool`, then update the [`MrSeam`](../../architecture/components/manifest.md#tdx-mr-seam) and [`AllowedPIIDs`](../../architecture/components/manifest.md#tdx-allowed-piids) values in your manifest, since a firmware update can change both.

:::

</TabItem>
</Tabs>

Expand Down
Loading