# Attestation Token

## Format of Token

The attestation token takes the format of what is becoming an industry standard: an entity attestation token (EAT).

For the purposes of this sample code, a variant of the Arm Platform Security Architecture attestation token has been chosen to provide the basic structure. More information is available at: https://www.psacertified.org/blog/what-is-an-entity-attestation-token/.

An EAT is a small blob of data that includes information items and is cryptographically signed. The signing secures the token itself, so that the mechanism that is transmitting the token does not have to provide any security. This allows IoT devices to securely introduce themselves to networks and to IoT platforms. The EAT is wrapped into a compact binary object representation (CBOR)-type message.

Each information item in this token in known as a claim, as shown in the "Items Included in Token" table. A claim is a data item, which is represented as a key-value pair.

Table: Items Included in Token
Item | Size (bytes) | Description
--- | --- | ---
Authentication Challenge | 32/48/64 | Input object of random bytes provided by the caller, intended to provide freshness to reports
Instance ID | 32 | Hash of public key that represents the unique identifier of the instance and is encoded as a byte string
Implementation ID | 32 | Represents the original implementation signer of the attestation key and identifies the contract between the report and verification. A verification service uses this claim to locate the details of the verification process. Consists of a value encoded as byte string.
Security Lifecycle | 4 | Positive ID corresponding to secure (0x3000) which represents the current lifecycle state of the instance
Client ID | 4 | Partition ID which, for the secure bootloader, is a positive value indicating it is a secure caller of the initial attestation API. The value is encoded as a signed integer.
Hardware Version | 16 | EAN-13, which can be used to reference the security level of the PSA-ROT via a certification website, and is encoded as a text string
Boot Seed | 32 | Byte string for the random value created at system boot time that allows differentiation of reports from different system sessions
Software Components:
ROM | 32 | SHA256 of ROM image
Bootloader | 32 | SHA256 of Bootloader
Application | 32 | SHA256 of Application

The size of the attestation token is governed by the fields outlined in the "Items Included in Token" table, and by how these values are encoded into a CBOR data stream. In addition, the EAT is wrapped into a signed format which includes a hash of the CBOR data, as well as a signature based on the size and type of the attestation key.

The "Example Token Sizes" table provides some example token sizes for different challenge and key sizes. All values are in bytes.

Table: Example Token Sizes
Key Size | 1024 |  |  |  |  | 2048 |  |  |  |  | 3072 |  |  |  |
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
Challenge Size | EAT | Hash | Sign | CBOR | Total | EAT | Hash | Sign | CBOR | Total | EAT | Hash | Sign | CBOR | Total
32 | 248 | 32 | 128 | 59 | 467 | 248 | 32 | 256 | 60 | 596 | 248 | 32 | 384 | 60 | 724
48 | 264 | 32 | 128 | 59 | 483 | 264 | 32 | 256 | 60 | 612 | 264 | 32 | 384 | 60 | 740
64 | 280 | 32 | 128 | 59 | 499 | 280 | 32 | 256 | 60 | 628 | 280 | 32 | 384 | 60 | 756

An example calculation can be found in the sample application source code in bl_eat.c.

NOTE: Some items in the EAT are provided as placeholder default values in the secure bootloader sample application. They are intended to be replaced as needed in a final product implementation.

## EAT Additional Details

EAT has the capabilities to provide the source of trust, using a cryptographically signed piece of data containing claims that are generated in the device Root of Trust (RoT). The main use is for the relying party to verify the claims made by the device, such as the following:

- The unique identity of the device
- Installed firmware on the device and its integrity status
- Security assurance and certification status (such as a PSA Certified level)
- Manufacturer of the device hardware

Using this information, the relying party can make informed decisions, such as whether the device is legitimate and should be trusted, or what services to enable based on the information it receives. This is shown in the "Relying Party Decision Diagram" figure.

Figure: Relying Party Decision Diagram

## Attestation Token Request

The "Attestation Token Request" figure shows the process of requesting an attestation token.

Figure: Attestation Token Request