Acceptance policies, TPM classes & assurance tiers

Every enrolled device is classified into one root-of-trust class, derived from its hardware key's certificate (the EK cert issuer + the TCG manufacturer identifier) or, for mobile, from the platform attestation. Classes roll up into groups you author policy against:

The class governs the acceptance decision, and it surfaces in the verdict: an accepted hardware or firmware device satisfies the real-device and oem-keyed entries of assuranceClaimsMet, and its root-of-trust tier shows up in the hardware dimension of device.trustworthinessVector. Branch on those in your own code even when the policy already accepted the device.

You don't have to author anything. Select a built-in by name from the dashboard, pin it to an API key, or name it per-call as the policy argument to rh.verify(). The appraisal is run against it server→server, so the verdict you get back already reflects it.

Need something between the built-ins? Register a named policy (you get back a UUID you reference afterwards; the policy lives server-side, you don't ship a rule blob in every request). The coarse form is a few fields:

// Authorization: Bearer rh_sk_live_…   (Owner role)
{
  "name": "My app — accept hardware + Nitro",
  "description": "Hardware and firmware TPMs everywhere; AWS NitroTPM for our CI runners.",
  "acceptedClassGroups": ["hardware", "firmware-tpm", "mobile-hardware"],
  "acceptedSpecificClasses": ["cloud-vtpm-aws-nitro"],
  "unacceptedBehavior": "reject",          // "reject" | "warn"
  "requireCloudCrossValidation": true,
  "minAcr": "urn:rootherald:device:high",
  "minimumEarStatus": "affirming",
  "mode": "strict"
}
// → 201 Created (PolicyDetail):
// {
//   "id": "8f3a…",
//   "name": "My app — accept hardware + Nitro",
//   "isBuiltIn": false,
//   "version": 1,
//   "acceptedClassGroups": ["hardware", "firmware-tpm", "mobile-hardware"],
//   "acceptedSpecificClasses": ["cloud-vtpm-aws-nitro"],
//   "unacceptedBehavior": "reject",
//   "requireCloudCrossValidation": true,
//   "minAcr": "urn:rootherald:device:high",
//   "mode": "strict"
// }

acceptedClassGroups takes group names (hardware, cloud-vtpm, …); acceptedSpecificClasses pins individual vendor classes (e.g. cloud-vtpm-aws-nitro). Anything outside the accepted set is governed by unacceptedBehavior: "warn" lets out-of-set devices through with a warn verdict and a degraded trustworthiness vector (useful for shadow-banning or review queues), while "reject" blocks them outright.

A separate axis from TPM class. The acr value says what the authenticationachieved. Root Herald treats a policy ACR floor as a hard requirement: a device that can't meet minAcr fails the policy rather than passing at a weaker tier. The acr returned in the verdict is the single tier the device actually satisfied, never a silently-weaker result.

Higher tiers subsume lower ones. The acr in the verdict is the single tier that was actually satisfied, never a preference list, never a partial match.

If your policy accepts a cloud-vtpm class and requireCloudCrossValidationis on (the default), the device must additionally submit cloud-provider instance-identity evidence so the verifier can bind "this virtual TPM" to "this specific instance, in this account": the defence against relaying a vTPM attestation from a different instance.

The cloud evidence is bundled into the opaque blob the keyless client collects. Your server submits it with rh.verify() (naming a cloud-cross-validating policy) and reads the resulting device verdict returned directly.

cloudEvidence: {
  provider: "aws",
  nitroAttestationDocument: body.nitroDoc,        // CBOR/COSE, from the Nitro hypervisor
  ec2InstanceIdentityDocument: body.iid,          // from IMDSv2
  ec2InstanceIdentitySignature: body.iidSig,
  getInstanceTpmEkPubResult: body.ekPub,          // from the EC2 GetInstanceTpmEkPub API
}

Azure (provider: "azure", IMDS attested document) and GCP (provider: "gcp", GCE instance identity token) follow the same pattern. The verifier checks the cloud doc chains to that cloud's root, the EK matches what was enrolled, and the instance/account/region are what you expect.

For server/workload attestation generally, also consider cloud-native primitives (AWS Nitro Enclaves attestation documents, SPIFFE/SPIRE, cloud workload identity). A hardware TPM is the wrong tool for "is this container the workload I expect?". Root Herald is strongest for endpoint devices.