Skip to content
Spinbox is experimental: APIs change and data may be lost. Status lists what is built and what proves it.

NitroTPM and runner authorization

View Markdown

A runner needs to prove two independent facts before the control plane trusts it:

  1. Which AWS instance is asking. The instance role signs an STS GetCallerIdentity request for this installation, its audience and its host id.
  2. What that instance booted. Its NitroTPM returns an AWS-signed attestation document with the measured boot values (PCR4, PCR7 and PCR12), the request’s hash and a public key made for this boot.

Neither proof is enough by itself. STS does not say what the instance booted; a TPM document does not say that the machine belongs to this installation. The control plane checks that both describe the same EC2 instance.

OpenTofu does not enable NitroTPM or distribute a TPM token. NitroTPM is part of the EC2 environment. The module instead declares the evidence it will accept:

What the module declaresRuntime use
The trusted PCR4, PCR7 and PCR12 values for each Spin OS build, with the statement its release signed of themOpenTofu writes the runner’s builds into host_attestation.runner of the control plane’s document; the control plane admits a runner only as one of them.
The runner’s instance role and the installation audienceSTS identifies the caller and binds its signed request to this installation and host.
KMS key policies conditioned on kms:RecipientAttestation:NitroTPMPCR*KMS releases an answer only to a machine whose attestation document carries an allowed complete PCR set.

The image measurements come from the release’s measurements.json, or from image_measurements when an installation uses its own images. A release is built again when what is under spin moves, and each build is a revision of it. The module accepts every revision of the installed release that is not revoked, so a machine of an earlier build goes on until it is replaced, but a build removed from that set can no longer join as a runner.

A runner joins at every boot: its credentials live in /run, so each boot creates a new boot key, signs the STS request with its instance role, and asks NitroTPM to attest to the hash of that exact request and to the boot public key. The control plane then verifies all of the following before issuing runner credentials:

  • AWS signed the attestation document and it is current.
  • Its PCR triplet is one of the trusted runner builds declared by the installation, and that build carries a statement its release signed of it. A build with nothing signed is not admitted.
  • Its nonce is the hash of the signed STS request, so it cannot be reused for another request.
  • Its public key is this boot’s key, so later runner credentials are tied to the attested boot.
  • The STS role is allowed by host_join, and the attested module id is the same EC2 instance that STS identified.

The first join records the host as that instance and the build it booted, and where it is (its machine type, zone, region, and whether AWS may reclaim it) as AWS describes the instance, never as the host’s own registration says. Every later boot is admitted again only from the same instance, proving the same build: a machine that joined as another host, or proves another build, is not the host that joined. A revoked host stays out however it proves who it is.

The control plane records the attestation with the runner’s boot key before it returns credentials. That record lets storage readers verify that a key which wrote an object belongs to an admitted, measured runner image.

The admission check decides whether a runner can participate in the control plane. KMS independently enforces whether it can open sensitive keys. For a volume or workload-identity key, the runner creates a short-lived recipient key, has NitroTPM attest to its public half, and sends that document to KMS. KMS encrypts its answer to that recipient only if the document’s PCRs match its key policy.

The same pattern protects the control plane’s encryption key: at each start it derives the key from KMS using an attested recipient. The key is not stored in the database, in OpenTofu state or in a machine image. It has versions: a rotation asks the same KMS key for a new secret under a new label, so what a rotation retires is a derived key that may have left a machine, while the KMS key’s private half never leaves KMS. A control-plane IAM role on a machine that booted an untrusted image is not enough to obtain it.

  • Copied IAM credentials on another machine. They can sign the STS request, but cannot produce a matching document from an allowed runner’s NitroTPM, nor make its module id match that other machine.
  • A runner booted from a changed disk or image. Changes affecting the measured kernel, command line or Secure Boot chain produce a PCR set the installation and KMS policy do not accept.
  • A captured registration proof. The nonce binds the proof to the signed request, and the boot key binds it to one boot; the control plane rejects a repeat registration from that boot.
  • An untrusted control-plane image reading installation secrets. KMS will not return the installation encryption key to its role without an allowed control-plane attestation.
  • A runner role alone opening volume or identity keys. A KMS decrypt requires an allowed recipient attestation as well as the narrowly scoped role/session that requested it.

NitroTPM attestation is a boot-time authorization boundary, not a cure for every compromise. In particular, it does not prevent malicious code that has already compromised a legitimate, running runner from using that runner’s current authority. It also does not prevent an AWS account administrator from changing IAM or KMS policy, and it relies on AWS’s Nitro attestation root.

The remaining boundaries are therefore still necessary: a verified, read-only Spin OS image; least-privilege IAM roles and permissions boundaries; per-workspace VM isolation; short-lived credentials; and KMS policies that name exact PCR combinations. Two limits are spelled out in what the security model does not protect: user data is not measured, so a machine started under the runners’ launch template with other user data might attest as a runner; and a control plane running other code with its own permissions is outside what attestation holds. See Supply chain, Data and encryption and Known gaps for the adjacent controls and their limits.

Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.