3. Initial Attestation report¶
This section begins with a description of the information model for the report and then describes the expected format.
3.1. Information model¶
The following table describes the mandatory and optional claims in the report:
Claim |
Mandatory |
Description |
---|---|---|
Auth challenge |
Yes |
Input object from the caller. For example, this can be a cryptographic nonce or a hash of locally attested data. The length must be 32, 48, or 64 bytes. This is the |
Instance ID |
Yes |
Represents the unique identifier of the instance:
The use of the IAK is also discussed in [PSM]. |
Verification service indicator |
No |
A hint used by a relying party to locate a validation service for the token. The value is a text string that can be used to locate the service or a URL specifying the address of the service. A verifier may choose to ignore this claim in favor of other information. |
Profile definition |
No |
Contains the name of a document that describes the ‘profile’ of the report. The document name may include versioning. The value for this specification is PSA_IOT_PROFILE_1. |
Implementation ID |
Yes |
Uniquely identifies the underlying Immutable Platform Root of Trust. A verification service can use this claim to locate the details of the verification process. Such details include the implementation’s origin and associated certification state. The full definition is in [PSM]. |
Client ID |
Yes |
Represents the Partition ID of the caller. It is a signed integer whereby negative values represent callers from the NSPE and where positive IDs represent callers from the SPE. The value It is essential that this claim is checked in the verification process to ensure that a security domain cannot spoof a report from another security domain. |
Security Lifecycle |
Yes |
Represents the current lifecycle state of the Platform Root of Trust (PRoT). The state is represented by an integer that is partitioned to convey a major state and a minor state. The major state is mandatory and defined by [PSM]. The minor state is optional and implementation defined. The PRoT security lifecycle state and implementation state are encoded as follows:
The PRoT security lifecycle states consist of the following values:
For PSA Certified, a remote verifier can only trust reports from the PRoT when it has a major state that is SECURED or NON_PSA_ROT_DEBUG. |
Hardware version |
No |
Provides metadata linking the token to the GDSII that went to fabrication for this instance. It can be used to link the class of chip and PRoT to the data on a certification website. It must be represented as a thirteen-digit [EAN-13]. |
Boot seed |
Yes |
Represents a random value created at system boot time that can allow differentiation of reports from different boot sessions. |
Software components |
Yes (unless the No Software Measurements claim is specified) |
A list of software components that represent all the software loaded by the PRoT. This claim is needed for the rules outlined in [PSM]. Each entry has the following fields: 1. Measurement type 2. Measurement value 3. Version 4. Signer ID 5. Measurement description The full definition of the software component is described in Software components. This claim is required to be compliant with [PSM]. |
No Software Measurements |
Yes (if no software components specified) |
In the event that the implementation does not contain any software measurements then the Software Components claim above can be omitted but instead it is mandatory to include this claim to indicate this is a deliberate state. This claim is intended for devices that are not compliant with [PSM]. |
3.1.1. Software components¶
Each software component in the Software Components claim must include the required properties of the following table:
Key ID |
Type |
Required |
Description |
---|---|---|---|
1 |
Measurement type |
No |
A short string representing the role of this software component (e.g. ‘BL’ for boot loader). Expected types may include:
|
2 |
Measurement value |
Yes |
Represents a hash of the invariant software component in memory at startup time. The value must be a cryptographic hash of 256 bits or stronger. |
3 |
Reserved |
No |
Reserved |
4 |
Version |
No |
The issued software version in the form of a text string. The value of this claim corresponds to the entry in the original signed manifest of the component. This field must be present to be compliant with [PSM]. |
5 |
Signer ID |
No |
The hash of a signing authority public key for the software component. The value of this claim corresponds to the entry in the original manifest for the component. This can be used by a verifier to ensure the components were signed by an expected trusted source. This field must be present to be compliant with [PSM]. |
6 |
Measurement description |
No |
Description of the software component, which represents the way in which the measurement value of the software component is computed. The value is a text string containing an abbreviated description (or name) of the measurement method which can be used to lookup the details of the method in a profile document. This claim may normally be excluded, unless there is an exception to the default measurement described in the profile for a specific component. |
3.2. Report format and signing¶
This section describes the specific representation, encoding and signing of the information described in the Information Model.
3.2.1. Token encoding¶
The report is represented as a token, which must be formatted in accordance to IETF Entity Attestation Token (EAT) [EAT] draft specification. The token consists of a series of claims declaring evidence as to the nature of the instance of hardware and software. The claims are encoded with the CBOR format, defined in Concise Binary Object Representation (CBOR) [STD94].
3.2.2. Signing¶
The token is signed following the structure defined in CBOR Object Signing and Encryption (COSE): Structures and Process [STD96] specification:
For asymmetric key algorithms, the signature structure must be COSE-Sign1. An asymmetric key algorithm is needed to achieve all the use cases defined in Use cases and rationale.
For symmetric key algorithms, the structure must be COSE-Mac0.
Warning
A symmetric key is strongly discouraged due to the associated infrastructure costs for key management and operational complexities. It may also restrict the ability to interoperate with scenarios that involve third parties (see Use cases and rationale).
3.2.3. EAT standard claims¶
The token is modelled to include custom values that correspond to the following EAT standard claims (as expressed in the draft EAT proposal):
nonce (mandatory); arm_psa_nonce is used instead
UEID (mandatory); arm_psa_UEID is used instead
A future version of the profile, corresponding to an issued standard, might declare support for both custom and standard claims as a transitionary state towards exclusive use of standard claims.
3.2.4. EAT custom claims¶
The token can include the following EAT custom claims. Custom claims for the Attestation API have a root identity of -75000.
Some fields must be at least 32 bytes to provide sufficient cryptographic strength.
Key ID |
Type |
Name |
CBOR type |
---|---|---|---|
-75000 |
Profile Definition |
|
Text string |
-75001 |
Client ID |
|
Unsigned integer or Negative integer |
-75002 |
Security Lifecycle |
|
Unsigned integer |
-75003 |
Implementation ID |
|
Byte string (>=32 bytes) |
-75004 |
Boot seed |
|
Byte string (>=32 bytes) |
-75005 |
Hardware version |
|
Text string |
-75006 |
Software components (compound map claim) |
|
Array of map entries. The map entries have the following types:
See Software components for details. |
-75007 |
No software measurements |
|
Unsigned integer (the recommended value is |
-75008 |
Auth challenge |
|
Byte string |
-75009 |
Instance ID |
|
Byte string (the type byte should be set to |
-75010 |
Verification service indicator |
|
Text string |
An example report can be found in Example report.