docs: update claims document for EAR tokens and InitData

The parsed claims document is out-of-date. The listed TCB Claims are ok,
but the document is still scoped to the old simple tokens somewhat.

Let's add some more information about the EAR token, including a
description of how the InitData is handled.

Also, let's rename the document, since parsed_claims was a term used in
the simple token.

Signed-off-by: Tobin Feldman-Fitzthum <[email protected]>

Author: fitzthum

attestation-service/docs/parsed_claims.md renamed to attestation-service/docs/claims.md

@@ -1,14 +1,63 @@
-# Parsed Claims
+# The Attestation Token
 
-After CoCo-AS verifies every evidence, a token with _parsed claims_ will be returned.
-_parsed claims_ is a key-value map inside the token, and it reflects the environment
-information that the evidence contains. Different platforms will have different
-key value members of the parsed claims. This document will show the whole key value
-list of different platforms.
+The Attestation Service generates an EAR attestation token, which contains many claims.
 
-All platforms will by default have two fixed claims:
-- `report_data`: report data when generating the evidence.
-- `init_data`: Hostdata when creating the TEE instance.
+For the general structure of the attestation token, refer to the [EAR specificication](https://datatracker.ietf.org/doc/draft-ietf-rats-ear/).
+
+Generally speaking, the attestation token will include an Appraisal for each device
+that is part of the TCB (including the CPU).
+These appraisals can be accessed through the `submods` field in the EAR Token.
+Each submod is given a generic key constructed from the CPU class and the device count.
+For instance, the CPU submod will be called `cpu0`.
+If a GPU has been attested as part of the guest, there will be a `gpu0` submod.
+If there is more than one GPU, there will be additional `gpuN` submods.
+
+`cpu0` is considered to be the primary attester and has some special
+information associated with it.
+
+# ReportData and InitData
+
+ReportData and InitData are two key Trustee concepts.
+ReportData refers to data provided by a guest at attestation time.
+This is sometimes called user data. The KBS protocol uses this
+field to measure the the nonce and Tee Public Key.
+During attestation Trustee will ensure that the corresponding
+field in the hardware evidence matches the report data values
+that are expected for a given connection.
+
+InitData is a more powerful and subtle concept. See the [InitData Specification]()
+for more information.
+The basic idea is that InitData is a generalization over boot-time configuration
+fields such as HostData (on SNP) or MRConfig (on TDX).
+InitData is used to provision dynamic, measured, but not secret 
+configuration data to the guest.
+The InitData plaintext is a TOML or JSON file containing this configuration
+while the InitData hash is the hash of this file which is added to the measuremet.
+A client can optionally provide the InitData plaintext to Trustee.
+If so, Trustee will check the plaintext against the hardware evidence
+and expose the InitData plaintext to the policy engine and as part of the
+attestation token.
+
+Both the InitData and ReportData will usually be included the attestation token.
+These fields will be available under the `AnnotatedEvidence` extension of the
+`cpu0` Appraisal.
+
+If the plaintext InitData is provided, some transformations will be applied
+to the InitData to make it more easy to consume.
+Specifically, if the InitData plaintext is provided as toml,
+some of the data fields in the InitData will be parsed into JSON.
+If the `cdh.toml` or `aa.toml` are present in the InitData,
+they will be parsed as JSON (although the keys will still be called `x.toml`).
+If `policy.rego` is present in the InitData and contains a `policy_data` claim
+at the end of the file, the `policy.rego` field will be removed from the InitData
+and replaced with the `policy_data` parsed as JSON. This will inserted
+with the key `agent_policy_claims`.
+
+# Hardware Claims
+
+The annotated evidence extension will also include hardware-specific claims
+extracted by the verifiers. These usually referred to as TCB Claims.
+The TCB Claims available on each platform are listed below.
 
 ## Sample