---
v: 3

title: "Arm's Platform Security Architecture (PSA) Attestation Token"
abbrev: "PSA Attestation Token"
docname: draft-tschofenig-rats-psa-token-latest
category: info
submissionType: independent

ipr: trust200902
area: ""
workgroup: ""
keyword: Internet-Draft

stand_alone: yes

pi:
  rfcedstyle: yes
  toc: yes
  tocindent: yes
  sortrefs: yes
  symrefs: yes
  strict: yes
  comments: yes
  text-list-symbols: -o*+

author:
 -  name: Hannes Tschofenig
    organization:
    email: Hannes.Tschofenig@gmx.net
 -  name: Simon Frost
    organization: Arm Limited
    email: Simon.Frost@arm.com
 -  name: Mathias Brossard
    organization: Arm Limited
    email: Mathias.Brossard@arm.com
 -  name: Adrian Shaw
    organization: HP Labs
    email: adrianlshaw@acm.org
 -  name: Thomas Fossati
    organization: Linaro
    email: thomas.fossati@linaro.org

contributor:
 -  name: Laurence Lundblade
    organization: Security Theory LLC
    email: lgl@securitytheory.com
 -  name: Tamas Ban
    organization: Arm Limited
    email: Tamas.Ban@arm.com
 -  name: Sergei Trofimov
    organization: Arm Limited
    email: Sergei.Trofimov@arm.com

normative:
  PSA-SM:
    author:
      org: Arm
    title: Platform Security Model 1.1
    target: https://www.psacertified.org/app/uploads/2021/12/JSADEN014_PSA_Certified_SM_V1.1_BET0.pdf
    date: 01. Dec. 2021
  EAN-13:
    author:
      org: GS1
    title: International Article Number - EAN/UPC barcodes
    target: https://www.gs1.org/standards/barcodes/ean-upc
    date: 2019
  PSA-FF:
    author:
      org: Arm
    title: Platform Security Architecture Firmware Framework 1.0 (PSA-FF)
    target: https://developer.arm.com/documentation/den0063/a
    date: 20. Feb. 2019
  PSA-Cert-Guide:
    author:
      org: PSA Certified
    title: PSA Certified Level 2 Step by Step Guide Version 1.1
    target: https://www.psacertified.org/app/uploads/2020/07/JSADEN011-PSA_Certified_Level_2_Step-by-Step-1.1-20200403.pdf
    date: 2020
  STD94:
    -: cbor
    =: RFC8949
  STD96:
    -: cose
    =: RFC9052
  COSE-ALGS: RFC9053
  IANA-CWT:
    author:
      org: IANA
    title: CBOR Web Token (CWT) Claims
    target: https://www.iana.org/assignments/cwt/cwt.xhtml#claims-registry
    date: 2022
  X509: RFC5280
  EAT: I-D.ietf-rats-eat
  EAT-MEDIATYPES: I-D.ietf-rats-eat-media-type


informative:
  I-D.kdyxy-rats-tdx-eat-profile:
  I-D.mandyam-rats-qwestoken:
  TLS12-IoT: RFC7925
  TLS13-IoT: I-D.draft-ietf-uta-tls13-iot-profile
  COSE-X509: RFC9360
  RFC9334:
  IANA-CoAP-Content-Formats:
    author:
      org: IANA
    title: CoAP Content-Formats
    target: https://www.iana.org/assignments/core-parameters
    date: 2022
  TF-M:
    author:
      org: Linaro
    title: Trusted Firmware-M
    target: https://www.trustedfirmware.org/projects/tf-m/
    date: 2022
  IAT-VERIFIER:
    author:
      org: Linaro
    title: iat-verifier
    target: https://git.trustedfirmware.org/TF-M/tf-m-tools.git/tree/iat-verifier
    date: 2023
  Veraison:
    author:
      org: The Veraison Project
    title: Veraison psatoken package
    target: https://github.com/veraison/psatoken
    date: 2022
  Xclaim:
    author:
      ins: L. Lundblade
      name: Laurence Lundblade
    title: Xclaim
    target: https://github.com/laurencelundblade/xclaim
    date: 2022
  PSA:
    author:
      org: Arm
    title: Platform Security Architecture Resources
    target: https://developer.arm.com/architectures/security-architectures/platform-security-architecture/documentation
    date: 2022
  PSACertified:
    author:
      org: PSA Certified
    title: PSA Certified IoT Security Framework
    target: https://psacertified.org
    date: 2022
  PSA-API:
    author:
      org: Arm
    title: PSA Attestation API 1.0.3
    target: https://arm-software.github.io/psa-api/attestation/1.0/IHI0085-PSA_Certified_Attestation_API-1.0.3.pdf
    date: 2022
  PSA-Endorsements: I-D.fdb-rats-psa-endorsements
  RATS-CoRIM: I-D.ietf-rats-corim
  RATS-AR4SI: I-D.ietf-rats-ar4si
  PSA-OLD: I-D.tschofenig-rats-psa-token-07

entity:
  SELF: "RFCthis"

--- abstract

The Arm Platform Security Architecture (PSA) is a family of hardware and firmware
security specifications, as well as open-source reference implementations, to
help device makers and chip manufacturers build best-practice security into
products. Devices that are PSA compliant can produce attestation tokens
as described in this memo, which are the basis for many different
protocols, including secure provisioning and network access control.  This
document specifies the PSA attestation token structure and semantics.

The PSA attestation token is a profile of the Entity Attestation Token (EAT).
This specification describes what claims are used in an attestation token
generated by PSA compliant systems, how these claims get serialized to the
wire, and how they are cryptographically protected.

This informational document is published as an independent submission to improve
interoperability with Arm's architecture. It is not a standard nor
a product of the IETF.

--- middle

# Introduction

The Platform Security Architecture (PSA) {{PSA}} is a set of hardware and firmware
specifications, backed by reference implementations and a security
certification program {{PSACertified}}.  The security specifications have been published by Arm,
while the certification program and reference implementations are the result of
a collaborative effort by companies from multiple sectors, including evaluation
laboratories, IP semiconductor vendors and security consultancies.  The main objective of
the PSA initiative is to assist device manufacturers and chip makers in
incorporating best-practice security measures into their products.

Many devices now have trusted execution environments that provide a safe
space for security-sensitive code, such as cryptography, secure boot, secure
storage, and other essential security functions.  These security
functions are typically exposed through a narrow and well-defined interface,
and can be used by operating system libraries and applications.

As outlined in the RATS Architecture {{RFC9334}}, an Attester produces a signed collection
of Claims that constitutes Evidence about its target environment. This document focuses
on the output provided by PSA's Initial Attestation API {{PSA-API}}. This output
corresponds to Evidence in {{RFC9334}} and, as a design decision, the PSA attestation token
is a profile of the Entity Attestation Token (EAT) {{EAT}}. Note that there are other profiles
of EAT available, such as {{I-D.kdyxy-rats-tdx-eat-profile}} and {{I-D.mandyam-rats-qwestoken}},
for use with different use cases and by different attestation technologies.

Since the PSA tokens are also consumed by services outside the device, there is an actual
need to ensure interoperability. Interoperability needs are addressed here by
describing the exact syntax and semantics of the attestation claims, and
defining the way these claims are encoded and cryptographically protected.

Further details on concepts expressed below can be found in the PSA Security
Model documentation {{PSA-SM}}.

As mentioned in the abstract, this memo documents a vendor extension
to the RATS architecture, and is not a standard.

# Conventions and Definitions

{::boilerplate bcp14}

The terms Attester, Relying Party, Verifier, Attestation Result, Target Environment, Attesting Environment and Evidence
are defined in {{RFC9334}}. We use the term "receiver" to refer to Relying Parties
and Verifiers.

We use the terms Evidence, "PSA attestation token", and "PSA token" interchangeably.
The terms "sender" and Attester are used interchangeably. Likewise, we use the terms
Verifier and "verification service" interchangeably.

{: vspace="0"}
RoT:
: Root of Trust, the minimal set of software, hardware and data that has to be
implicitly trusted in the platform - there is no software or hardware at a
deeper level that can verify that the Root of Trust is authentic and
unmodified.  An example of RoT is an initial bootloader in ROM, which contains
cryptographic functions and credentials, running on a specific hardware
platform.

SPE:
: Secure Processing Environment, a platform's processing environment for
software that provides confidentiality and integrity for its runtime state,
from software and hardware, outside of the SPE. Contains trusted code and
trusted hardware.  (Equivalent to Trusted Execution Environment (TEE),
"secure world", or "secure enclave".)

NSPE:
: Non Secure Processing Environment, the security domain outside of the SPE,
the Application domain, typically containing the application firmware,
real-time operating systems, applications and general hardware.  (Equivalent to Rich Execution
Environment (REE), or "normal world".)

In this document, the structure of data is specified in Concise Data Definition Language (CDDL) {{!RFC8610}}.

# PSA Attester Model
{: #sec-psa-attester-model }

{{fig-psa-attester}} outlines the structure of the PSA Attester according to
the conceptual model described in {{Section 3.1 of RFC9334}}.

~~~ aasvg
{::include art/psa-attester.ascii-art}
~~~
{: #fig-psa-attester title="PSA Attester" }

The PSA Attester is a relatively straightforward embodiment of the RATS
Attester with exactly one Attesting Environment and one or more Target Environments.

The Attesting Environment is responsible for collecting the information to be
represented in PSA claims and to assemble them into Evidence. It is made of two
cooperating components:

* The Main Bootloader, executing at boot-time, measures the Target Environments - i.e., loaded software
  components, and all the relevant PSA RoT parameters -, and stores the recorded
  information in secure memory (Main Boot State). See {{fig-psa-attester-boot}}.

~~~ aasvg
{::include art/psa-boot.ascii-art}
~~~
{: #fig-psa-attester-boot
   title="PSA Attester Boot Phase"
   align="center" }

* The Initial Attestation Service (executing at run-time in SPE) answers
  requests coming from NSPE via the PSA attestation API {{PSA-API}}, collects
  and formats the claims from Main Boot State, and uses the Initial Attestation
  Key (IAK) to sign them and produce Evidence. See {{fig-psa-attester-runtime}}.

The word "Initial" in "Initial Attestation Service" refers to a limited set of
Target Environments, namely those representing the first, foundational stages
establishing the chain of trust of a PSA device.
Collecting measurements from Target Environments after this initial phase is outside the scope of this specification. Extensions of this specification could collect up-to-date measurements from additional Target Environments and define additional claims for use within those environments, but these are, by definition, custom.

~~~ aasvg
{::include art/psa-runtime.ascii-art}
~~~
{: #fig-psa-attester-runtime
   title="PSA Attester Run-time Phase"
   align="center" }

The Target Environments can be of four types, some of
which may or may not be present depending on the device architecture:

* (A subset of) the PSA RoT parameters, including Instance and Implementation
  IDs.

* The updateable PSA RoT, including the Secure Partition Manager and all PSA
  RoT services.

* The (optional) Application RoT, that is any application-defined security
  service, possibly making use of the PSA RoT services.

* The loader of the application software running in NSPE.

A reference implementation of the PSA Attester is provided by {{TF-M}}.

# PSA Claims
{: #sec-psa-claims }

This section describes the claims to be used in a PSA attestation token.
A more comprehensive treatment of the EAT profile(s) defined by PSA is found in {{sec-profiles}}.

CDDL {{!RFC8610}} along with text descriptions is used to define each claim
independent of encoding.  The following CDDL type(s) are reused by different
claims:

~~~
{::include cddl/psa-common-types.cddl}
~~~

Two conventions are used to encode the Right-Hand-Side (RHS) of a claim: the postfix `-label` is used for EAT-defined claims, and the postfix `-key` for PSA-originated claims.

## Caller Claims

### Nonce
{: #sec-nonce-claim}

The Nonce claim is used to carry the challenge provided by the caller to demonstrate freshness of the generated token.

The EAT {{EAT}} `nonce` (claim key 10) is used.  Since the EAT nonce claim offers flexiblity for different
attestation technologies, this specifications applies the following constraints
 to the `nonce-type`:

* The length MUST be either 32, 48, or 64 bytes.
* Only a single nonce value is conveyed. The array notation MUST NOT be used for encoding the nonce value.


This claim MUST be present in a PSA attestation token.

~~~
{::include cddl/psa-nonce.cddl}
~~~

### Client ID
{: #sec-client-id}

The Client ID claim represents the security domain of the caller.

In PSA, a security domain is represented by a signed
integer whereby negative values represent callers from the NSPE and where
positive IDs represent callers from the SPE. The value 0 is not permitted.

For an example definition of client IDs, see the PSA Firmware Framework {{PSA-FF}}.

It is essential that this claim is checked in the verification process to
ensure that a security domain, i.e., an attestation endpoint, cannot spoof a
report from another security domain.

This claim MUST be present in a PSA attestation token.

~~~
{::include cddl/psa-client-id.cddl}
~~~

## Target Identification Claims

### Instance ID
{: #sec-instance-id-claim}

The Instance ID claim represents the unique identifier of the Initial
Attestation Key (IAK).  The full definition is in {{PSA-SM}}.

The EAT `ueid` (claim key 256) of type RAND is used.  The following constraints
apply to the `ueid-type`:

* The length MUST be 33 bytes.
* The first byte MUST be 0x01 (RAND) followed by the 32-byte unique identifier of the IAK. {{PSA-API}} provides implementation options for deriving the IAK unique identifier from the IAK itself.

This claim MUST be present in a PSA attestation token.

~~~
{::include cddl/psa-instance-id.cddl}
~~~

### Implementation ID
{: #sec-implementation-id}

The Implementation ID claim uniquely identifies the hardware assembly of the
immutable PSA RoT. A verification service uses this claim to locate the
details of the PSA RoT implementation from an Endorser or manufacturer.
Such details are used by a verification service to determine the security properties
or certification status of the PSA RoT implementation.

The value and format of the ID is decided by
the manufacturer or a particular certification scheme. For example, the ID
could take the form of a product serial number,
database ID, or other appropriate identifier.

This claim MUST be present in a PSA attestation token.

Note that this identifies the PSA RoT implementation, not a particular instance.
To uniquely identify an instance, see the Instance ID claim {{sec-instance-id-claim}}.

~~~
{::include cddl/psa-implementation-id.cddl}
~~~

### Certification Reference
{: #sec-certification-reference}

The Certification Reference claim is used to link the class of chip and PSA RoT
of the attesting device to an associated entry in the PSA Certification
database. It MUST be represented as a string made of nineteen numeric
characters: a thirteen-digit {{EAN-13}}, followed by a dash "-", followed by
the five-digit versioning information described in {{PSA-Cert-Guide}}.

Linking to the PSA Certification entry can still be achieved if this claim is
not present in the token by making an association at a Verifier between the
reference value and other token claim values - for example, the Implementation
ID.

This claim MAY be present in a PSA attestation token.

~~~
{::include cddl/psa-certification-reference.cddl}
~~~

## Target State Claims

### Security Lifecycle
{: #sec-security-lifecycle }

The Security Lifecycle claim represents the current lifecycle state of the PSA
RoT. The state is represented by an integer that is divided to convey a major
state and a minor state. A major state is mandatory and defined by {{PSA-SM}}.
A minor state is optional and 'IMPLEMENTATION DEFINED'. The PSA security
lifecycle state and implementation state are encoded as follows:

* major\[15:8\] - PSA security lifecycle state, and
* minor\[7:0\] - IMPLEMENTATION DEFINED state.

The PSA lifecycle states are illustrated in {{fig-lifecycle-states}}. For PSA,
a Verifier can only trust reports from the PSA RoT when it is in SECURED or
NON_PSA_ROT_DEBUG major states.

This claim MUST be present in a PSA attestation token.

~~~ aasvg
{::include art/psa-lifecycle.ascii-art}
~~~
{: #fig-lifecycle-states title="PSA Lifecycle States" }

The CDDL representation is shown below.
{{tab-states-map}} provides the mappings between {{fig-lifecycle-states}} and the data model.

~~~
{::include cddl/psa-security-lifecycle.cddl}
~~~

`psa-lifecycle-unknown-type` is not shown in {{fig-lifecycle-states}}; it represents an invalid state that must not occur in a system.

| CDDL | Lifecycle States |
|------|------------------|
| `psa-lifecycle-unknown-type`                   | |
| `psa-lifecycle-assembly-and-test-type`         |  Assembly and Test |
| `psa-lifecycle-psa-rot-provisioning-type`      |  PSA RoT Provisioning |
| `psa-lifecycle-secured-type`                   |  Secured |
| `psa-lifecycle-non-psa-rot-debug-type`         |  Non-Recoverable PSA RoT Debug |
| `psa-lifecycle-recoverable-psa-rot-debug-type` |  Recoverable PSA RoT Debug |
| `psa-lifecycle-decommissioned-type`            |  Decommissioned |
{: #tab-states-map title="Lifecycle States Mappings"}

### Boot Seed
{: #sec-boot-seed }

The Boot Seed claim contains a value created at system boot time
that allows differentiation of attestation reports from different
boot sessions of a particular entity (i.e., a certain Instance ID).

The EAT `bootseed` (claim key 268) is used.
The following constraints apply to the `binary-data` type:

* The length MUST be between 8 and 32 bytes.

This claim MAY be present in a PSA attestation token.

~~~
{::include cddl/psa-boot-seed.cddl}
~~~

## Software Inventory Claims

### Software Components
{: #sec-sw-components }

The Software Components claim is a list of software components that includes
all the software (both code and configuration) loaded by the PSA RoT.  This
claim MUST be included in attestation tokens produced by an implementation
conformant with {{PSA-SM}}.

Each entry in the Software Components list describes one software component
using the attributes described in the following subsections.  Unless explicitly
stated, the presence of an attribute is OPTIONAL.

Note that, as described in {{RFC9334}}, a relying party will typically see the
result of the appraisal process from the Verifier in form of an Attestation
Result, rather than the PSA token from the attesting endpoint.
Therefore, a relying party is not expected to understand the Software
Components claim.  Instead, it is for the Verifier to check this claim against
the available Reference Values and provide an answer in form of an "high level"
Attestation Result, which may or may not include the original Software
Components claim.

~~~
{::include cddl/psa-software-components.cddl}
~~~

#### Measurement Type

The Measurement Type attribute (key=1) is a short string representing the role of
this software component.

The following measurement types MAY be used for code measurements:

* "BL": a Boot Loader
* "PRoT": a component of the PSA Root of Trust
* "ARoT": a component of the Application Root of Trust
* "App": a component of the NSPE application
* "TS": a component of a Trusted Subsystem

The same labels with a "_CONFIG" postfix (e.g., "PRoT_CONFIG") MAY be used for
configuration measurements.

This attribute SHOULD be present in a PSA software component unless
there is a very good reason to leave it out - for example in networks
with severely constrained bandwidth, where sparing a few bytes really
makes a difference.

#### Measurement Value

The Measurement Value attribute (key=2) 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.

This attribute MUST be present in a PSA software component.

#### Version

The Version attribute (key=4) is the issued software version in the form of a
text string. The value of this attribute will correspond to the entry in the
original signed manifest of the component.

#### Signer ID

The Signer ID attribute (key=5) uniquely identifies the signer of the software component. The identification is typically accomplished by hashing the signer's public key.
The value of this attribute will correspond 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 attribute MUST be present in a PSA software component to be compliant with
{{PSA-SM}}.

#### Measurement Description

The Measurement Description attribute (key=6) contains a string identifying the
hash algorithm used to compute the corresponding Measurement Value.  The string
SHOULD be encoded according to "Hash Name String" in the "Named Information Hash Algorithm Registry" {{!IANA.named-information}}.

## Verification Claims

The following claims are part of the PSA token (and therefore still Evidence)
but aim to help receivers, including relying parties, with the
processing of the received attestation Evidence.

### Verification Service Indicator
{: #sec-verification-service-indicator}

The Verification Service Indicator claim is a hint used by a relying party to
locate a verification service for the token. The value is a text string that
can be used to locate the service (typically, a URL specifying the address of
the verification service API). A Relying Party may choose to ignore this claim
in favor of other information.

~~~
{::include cddl/psa-verification-service-indicator.cddl}
~~~

It is assumed that the relying party is pre-configured with a list of trusted
verification services and that the contents of this hint can be used to look
up the correct one. Under no circumstances must the relying party be tricked
into contacting an unknown and untrusted verification service since the
returned Attestation Result cannot be relied on.

Note: This hint requires the relying party to parse the content of the
PSA token. Since the relying party may not be in possession of a trust
anchor to verify the digital signature, it uses the hint in the same way
as it would treat any other information provided by an external party,
which includes attacker-provided data.

### Profile Definition
{: #sec-profile-definition-claim}

The Profile Definition claim encodes the unique identifier that corresponds to
the EAT profile described by this document.  This allows a receiver to assign
the intended semantics to the rest of the claims found in the token.

The EAT `eat_profile` (claim key 265) is used.

The URI encoding MUST be used.

The value MUST be `tag:psacertified.org,2023:psa#tfm` for the profile defined in {{sec-tfm-profile}}.

Future profiles derived from the baseline PSA profile SHALL create their unique value, as described in {{sec-profile-uri-structure}}.

This claim MUST be present in a PSA attestation token.

See {{sec-backwards-compat}}, for considerations about backwards compatibility
with previous versions of the PSA attestation token format.

~~~
{::include cddl/psa-profile.cddl}
~~~

#### URI Structure for the Derived Profile Identifiers
{: #sec-profile-uri-structure}

A new profile is associated with a unique string.

The string MUST use the URI fragment syntax defined in {{Section 3.5 of !RFC3986}}.

The string SHOULD be short to avoid unnecessary overhead.

To avoid collisions, profile authors SHOULD communicate upfront their intent to use a certain string using the enquiry form on the {{PSACertified}} website.

To derive the value to be used for the `eat_profile` claim, the string is added as a fragment to the `tag:psacertified.org,2023:psa` tag URI {{!RFC4151}}.

For example, an hypothetical profile using only COSE_Mac0 with the AES Message Authentication Code (AES-MAC) may decide to use the string "aes-mac".  The `eat_profile` value would then be: `tag:psacertified.org,2023:psa#aes-mac`.

## Backwards Compatibility Considerations
{: #sec-backwards-compat}

A previous version of this specification {{PSA-OLD}}, identified by the `PSA_IOT_PROFILE_1`
profile, used claim key values from the "private use range" of the CWT Claims
registry.  These claim keys have now been deprecated.

{{tab-claim-map}} provides the mappings between the deprecated and new claim
keys.

| | PSA_IOT_PROFILE_1 | tag:psacertified.org,2023:psa#tfm |
|-|-------------------|--------------------------|
| Nonce | -75008 | 10 (EAT nonce) |
| Instance ID | -75009 | 256 (EAT euid) |
| Profile Definition | -75000 | 265 (EAT eat_profile) |
| Client ID | -75001 | 2394 |
| Security Lifecycle | -75002 | 2395 |
| Implementation ID | -75003 | 2396 |
| Boot Seed | -75004 | 268 (EAT bootseed) |
| Certification Reference | -75005 | 2398 |
| Software Components | -75006 | 2399 |
| Verification Service Indicator | -75010 | 2400 |
{: #tab-claim-map title="Claim Key Mappings"}

The new profile introduces three further changes:

* the "Boot Seed" claim is now optional and of variable length (see
  {{sec-boot-seed}}),
* the "No Software Measurements" claim has been retired,
* the "Certification Reference" claim syntax changed from EAN-13 to EAN-13+5 (see
  {{sec-certification-reference}}).

To simplify the transition to the token format described in this
document it is RECOMMENDED that Verifiers
accept tokens encoded according to the old profile (`PSA_IOT_PROFILE_1`) as well as
to the profile defined in this document (`tag:psacertified.org,2023:psa#tfm`), at least for the time needed to
their devices to upgrade.

# Profiles
{: #sec-profiles}

This document defines a baseline with common requirements that all PSA profiles must satisfy.
(Note that this does not apply to {{PSA-OLD}}.)

This document also defines a "TFM" profile ({{sec-tfm-profile}}) that builds on the baseline while constraining the use of COSE algorithms to improve interoperability between Attesters and Verifiers.

Baseline and TFM are what EAT calls a "partial" and "full" profile, respectively. See {{Section 6.2 of EAT}} for further details regarding profiles.

## Baseline Profile

### Token Encoding and Signing
{: #sec-token-encoding-and-signing}

The PSA attestation token is encoded in CBOR {{STD94}} format.
The CBOR representation of a PSA token MUST be "valid" according to the definition in {{Section 1.2 of STD94}}.
Besides, only definite-length string, arrays, and maps are allowed.
Given that a PSA Attester is typically found in a constrained device, it MAY
NOT emit CBOR preferred serializations ({{Section 4.1 of STD94}}).
Therefore, the Verifier MUST be a variation-tolerant CBOR decoder.

Cryptographic protection is obtained by wrapping the `psa-token` claims-set in a COSE
Web Token (CWT) {{!RFC8392}}.  For asymmetric key algorithms, the signature
structure MUST be a tagged (18) COSE_Sign1.  For symmetric key algorithms, the signature
structure MUST be a tagged (17) COSE_Mac0.

Acknowledging the variety of markets, regulations and use cases in which the
PSA attestation token can be used, the baseline profile does not impose any
strong requirement on the cryptographic algorithms that need to be supported by
Attesters and Verifiers.  The flexibility provided by the COSE format should be
sufficient to deal with the level of cryptographic agility needed to adapt to
specific use cases.  It is RECOMMENDED that commonly adopted algorithms are
used, such as those discussed in {{COSE-ALGS}}.  It is expected that receivers
will accept a wider range of algorithms, while Attesters would produce PSA tokens
using only one such algorithm.

The CWT CBOR tag (61) is not used.  An application that needs to exchange PSA
attestation tokens can wrap the serialised COSE_Sign1 or COSE_Mac0 in the media
type defined in {{sec-iana-media-types}} or the CoAP Content-Format defined in
{{sec-iana-coap-content-format}}.

A PSA token is always directly signed by the PSA RoT.  Therefore, a PSA
claims-set ({{sec-psa-claims}}) is never carried in a Detached EAT bundle
({{Section 5 of EAT}}).

### Freshness Model

The PSA token supports the freshness models for attestation Evidence based on
nonces and epoch handles ({{Section 10.2 and Section 10.3 of RFC9334}}) using
the `nonce` claim to convey the nonce or epoch handle supplied by the Verifier.
No further assumption on the specific remote attestation protocol is made.

Note that use of epoch handles is constrained by the type restrictions imposed by the `eat_nonce` syntax.
For use in PSA tokens, it must be possible to encode the epoch handle as an opaque binary string between 8 and 64 octets.

### Synopsis

{{tbl-baseline-profile}} presents a concise view of the requirements described in the preceding sections.

| Issue | Profile Definition |
| CBOR/JSON | CBOR MUST be used  |
| CBOR Encoding | Definite length maps and arrays MUST be used |
| CBOR Encoding | Definite length strings MUST be used |
| CBOR Serialization | Variant serialization MAY be used |
| COSE Protection | COSE_Sign1 and/or COSE_Mac0 MUST be used |
| Algorithms | {{COSE-ALGS}} SHOULD be used |
| Detached EAT Bundle Usage | Detached EAT bundles MUST NOT be sent |
| Verification Key Identification | Any identification method listed in {{Appendix F.1 of EAT}} |
| Endorsements | See {{sec-psa-endorsements}} |
| Freshness | nonce or epoch ID based |
| Claims | Those defined in {{sec-psa-claims}}. As per general EAT rules, the receiver MUST NOT error out on claims it does not understand. |
{: #tbl-baseline-profile title="Baseline Profile"}

## Profile TFM
{: #sec-tfm-profile}

This profile is appropriate for the code base implemented in {{TF-M}} and should apply for most derivative implementations. If an implementation changes the requirements described below then, to ensure interoperability, a different profile value should be used ({{sec-profile-uri-structure}}). This includes a restriction of the profile to a subset of the COSE Protection scheme requirements.

{{tbl-tfm-profile}} presents a concise view of the requirements.

The value of the `eat_profile` MUST be `tag:psacertified.org,2023:psa#tfm`.

| Issue | Profile Definition |
| CBOR/JSON | See {{baseline-profile}} |
| CBOR Encoding | See {{baseline-profile}} |
| CBOR Encoding | See {{baseline-profile}} |
| CBOR Serialization | See {{baseline-profile}} |
| COSE Protection | COSE_Sign1 or COSE_Mac0 MUST be used |
| Algorithms | The receiver MUST accept ES256, ES384 and ES512 with COSE_Sign1 and HMAC256/256, HMAC384/384 and HMAC512/512 with COSE_Mac0; the sender MUST send one of these |
| Detached EAT Bundle Usage | See {{baseline-profile}} |
| Verification Key Identification | Claim-Based Key Identification ({{Appendix F.1.4 of EAT}}) using Instance ID |
| Endorsements | See {{sec-psa-endorsements}} |
| Freshness | See {{baseline-profile}} |
| Claims | See {{baseline-profile}} |
{: #tbl-tfm-profile title="TF-M Profile"}

# Collated CDDL

~~~
{::include cddl/psa-attestation.cddl}
~~~

# Scalability Considerations
{: #sec-scalability}

IAKs (see {{sec-psa-attester-model}}) can be either raw public keys or certified public keys.

Certified public keys require the manufacturer to run the certification
authority (CA) that issues X.509 certs for the IAKs.  (Note that operating a CA
is a complex and expensive task that may be unaffordable to certain
manufacturers.)

Using certified public keys offers better scalability properties when compared to using raw public keys, namely:

* storage requirements for the Verifier are minimised - the same
  manufacturer's trust anchor is used for any number of devices,
* the provisioning model is simpler and more robust since there is no need to
  notify the Verifier about each newly manufactured device,

Furthermore, existing and well-understood revocation mechanisms can be readily used.

The IAK's X.509 cert can be inlined in the PSA token using the `x5chain` COSE
header parameter {{COSE-X509}} at the cost of an increase in the PSA token
size.  {{Section 4.4 of TLS12-IoT}} and {{Section 15 of TLS13-IoT}} provide
guidance for profiling X.509 certs used in IoT deployments.
Note that the exact split between pre-provisioned and inlined certs may vary
depending on the specific deployment.  In that respect, `x5chain` is quite
flexible: it can contain the end-entity (EE) cert only, the EE and a partial
chain, or the EE and the full chain up to the trust anchor (see {{Section 2 of
COSE-X509}} for the details).
Constraints around network bandwidth and computing resources available to endpoints, such as network buffers, may dictate a reasonable split point.

# PSA Token Verification

To verify the token, the primary need is to check correct encoding and signing
as detailed in {{sec-token-encoding-and-signing}}.
The key used for verification is either supplied to the Verifier by an
authorized Endorser along with the corresponding Attester's Instance ID or
inlined in the token using the `x5chain` header parameter as described in
{{sec-scalability}}.
If the IAK is a raw public key, the Instance ID claim is
used to assist in
locating the key used to verify the signature covering the CWT token.
If the IAK is a certified public key, X.509 path construction and validation
({{Section 6 of X509}}) up to a trusted CA MUST be successful before the key is
used to verify the token signature.  This also includes revocation checking.

In addition, the Verifier will typically operate a policy where values of some
of the claims in this profile can be compared to reference values, registered
with the Verifier for a given deployment, in order to confirm that the device
is endorsed by the manufacturer supply chain.  The policy may require that the
relevant claims must have a match to a registered reference value.  All claims
may be worthy of additional appraisal.  It is likely that most deployments
would include a policy with appraisal for the following claims:

* Implementation ID - the value of the Implementation ID can be used to
  identify the verification requirements of the deployment.
* Software Component, Measurement Value - this value can uniquely identify a
  firmware release from the supply chain. In some cases, a Verifier may
  maintain a record for a series of firmware releases, being patches to an
  original baseline release. A verification policy may then allow this value to
  match any point on that release sequence or expect some minimum level of
  maturity related to the sequence.
* Software Component, Signer ID - where present in a deployment, this could
  allow a Verifier to operate a more general policy than that for Measurement
  Value as above, by allowing a token to contain any firmware entries signed by
  a known Signer ID, without checking for a uniquely registered version.
* Certification Reference - if present, this value could be used as a hint to
  locate security certification information associated with the attesting
  device. An example could be a reference to a {{PSACertified}} certificate.

## AR4SI Trustworthiness Claims Mappings

{{RATS-AR4SI}} defines an information model that Verifiers can employ to
produce Attestation Results.
AR4SI provides a set of standardized appraisal categories and tiers that
greatly simplifies the task of writing Relying Party policies in multi-attester
environments.

The contents of {{tab-ar4si-map}} are intended as guidance for implementing a
PSA Verifier that computes its results using AR4SI.
The table describes which PSA Evidence claims (if any) are related to which
AR4SI trustworthiness claim, and therefore what the Verifier must consider when
deciding if and how to appraise a certain feature associated with the PSA
Attester.

Trustworthiness Vector claims | Related PSA claims
---|---
`configuration` | Software Components ({{sec-sw-components}})
`executables` | ditto
`file-system` | N/A
`hardware` | Implementation ID ({{sec-implementation-id}})
`instance-identity` | Instance ID ({{sec-instance-id-claim}}).  The Security Lifecycle ({{sec-security-lifecycle}}) can also impact the derived identity.
`runtime-opaque` | Indirectly derived from `executables`, `hardware`, and `instance-identity`.  The Security Lifecycle ({{sec-security-lifecycle}}) can also be relevant: for example, any debug state will expose otherwise protected memory.
`sourced-data` | N/A
`storage-opaque` | Indirectly derived from `executables`, `hardware`, and `instance-identity`.
{: #tab-ar4si-map title="AR4SI Claims mappings"}

This document does not prescribe what value must be chosen based on each
possible situation: when assigning specific Trustworthiness Claim values, an
implementation is expected to follow the algorithm described in {{Section 2.3.3
of RATS-AR4SI}}.

## Endorsements, Reference Values and Verification Key Material
{: #sec-psa-endorsements}

{{PSA-Endorsements}} defines a protocol based on the {{RATS-CoRIM}} data model
that can be used to convey PSA Endorsements, Reference Values and verification
key material to the Verifier.

# Implementation Status

[^rfc-ed-note] please remove this section before pubblication.

Implementations of this specification are provided by the Trusted
Firmware-M project {{TF-M}}, {{IAT-VERIFIER}}, the Veraison project {{Veraison}}, and the Xclaim
{{Xclaim}} library.  All four implementations are released as open-source software.

# Security and Privacy Considerations

This specification re-uses the EAT specification and therefore the CWT specification.
Hence, the security and privacy considerations of those specifications apply here as well.

Since CWTs offer different ways to protect the token, this specification
profiles those options and allows signatures using public key cryptography as
well as message authentication codes (MACs). COSE_Sign1 is used for digital
signatures and COSE_Mac0 for MACs, as defined in the COSE specification {{STD96}}.
Note, however, that the use of MAC authentication is NOT RECOMMENDED due to the associated
infrastructure costs for key management and protocol complexities.

A PSA Attester MUST NOT provide Evidence to an untrusted
challenger, as it may allow attackers to interpose and trick the Verifier into
believing the attacker is a legitimate Attester.
This is especially relevant to protocols that use PSA attestation tokens to authenticate the attester to a relying party.

Attestation tokens contain information that may be unique to a device and
therefore they may allow to single out an individual device for tracking
purposes.  Deployments that have privacy requirements must take appropriate
measures to ensure that the token is only used to provision anonymous/pseudonym
keys.

# IANA Considerations

## CBOR Web Token Claims Registration

IANA is requested to make permanent the following claims that have been
assigned via early allocation in the "CBOR Web Token (CWT) Claims" registry
{{IANA-CWT}}.

### Client ID Claim

* Claim Name: psa-client-id
* Claim Description: PSA Client ID
* JWT Claim Name: N/A
* Claim Key: 2394
* Claim Value Type(s): signed integer
* Change Controller: Hannes Tschofenig
* Specification Document(s): {{sec-client-id}} of {{&SELF}}

### Security Lifecycle Claim

* Claim Name: psa-security-lifecycle
* Claim Description: PSA Security Lifecycle
* JWT Claim Name: N/A
* Claim Key: 2395
* Claim Value Type(s): unsigned integer
* Change Controller: Hannes Tschofenig
* Specification Document(s): {{sec-security-lifecycle}} of {{&SELF}}

### Implementation ID Claim

* Claim Name: psa-implementation-id
* Claim Description: PSA Implementation ID
* JWT Claim Name: N/A
* Claim Key: 2396
* Claim Value Type(s): byte string
* Change Controller: Hannes Tschofenig
* Specification Document(s): {{sec-implementation-id}} of {{&SELF}}

### Certification Reference Claim

* Claim Name: psa-certification-reference
* Claim Description: PSA Certification Reference
* JWT Claim Name: N/A
* Claim Key: 2398
* Claim Value Type(s): text string
* Change Controller: Hannes Tschofenig
* Specification Document(s): {{sec-certification-reference}} of {{&SELF}}

### Software Components Claim

* Claim Name: psa-software-components
* Claim Description: PSA Software Components
* JWT Claim Name: N/A
* Claim Key: 2399
* Claim Value Type(s): array
* Change Controller: Hannes Tschofenig
* Specification Document(s): {{sec-sw-components}} of {{&SELF}}

### Verification Service Indicator Claim

* Claim Name: psa-verification-service-indicator
* Claim Description: PSA Verification Service Indicator
* JWT Claim Name: N/A
* Claim Key: 2400
* Claim Value Type(s): text string
* Change Controller: Hannes Tschofenig
* Specification Document(s): {{sec-verification-service-indicator}} of {{&SELF}}

## Media Types
{: #sec-iana-media-types}

No new media type registration is requested.
To indicate that the transmitted content is a PSA attestation token,
applications can use the `application/eat+cwt` media type defined in
{{EAT-MEDIATYPES}} with the `eat_profile` parameter set to
`tag:psacertified.org,2023:psa#tfm` (or `tag:psacertified.org,2019:psa#legacy` if the token is encoded
according to the old profile, see {{sec-backwards-compat}}).

## CoAP Content-Formats Registration
{: #sec-iana-coap-content-format}

IANA is requested to register two CoAP Content-Format IDs in the "CoAP
Content-Formats" registry {{IANA-CoAP-Content-Formats}}:

* One for the `application/eat+cwt` media type with the `eat_profile` parameter
  equal to `tag:psacertified.org,2023:psa#tfm`
* Another for the `application/eat+cwt` media type with the `eat_profile`
  parameter equal to `tag:psacertified.org,2019:psa#legacy`

The Content-Formats should be allocated from the First Come First Served range (10000-64999).

### Registry Contents

*  Media Type: `application/eat+cwt; eat_profile="tag:psacertified.org,2023:psa#tfm"`
*  Encoding: -
*  Id: [[To-be-assigned by IANA]]
*  Reference: {{&SELF}}

*  Media Type: `application/eat+cwt; eat_profile="tag:psacertified.org,2019:psa#legacy"`
*  Encoding: -
*  Id: [[To-be-assigned by IANA]]
*  Reference: {{&SELF}}

--- back

# Examples

The following examples show PSA attestation tokens for an hypothetical system
comprising a single measured software component.
The attesting device is in a lifecycle state ({{sec-security-lifecycle}}) of
SECURED.  The attestation has been requested from a client residing in the
SPE.

The example in {{ex-sign1}} illustrates the case where the IAK is an asymmetric key.  A COSE Sign1 envelope is used to wrap the PSA claims-set.

{{ex-mac0}} illustrates the case where the IAK is a symmetric key and a COSE Mac0 envelope is used instead.

The claims sets are identical, except for the Instance ID which is synthesized from the key material.

The examples have been created using the `iat-verifier` tool {{IAT-VERIFIER}}.

## COSE Sign1 Token {#ex-sign1}

~~~
{::include cddl/example/sign1-claims.diag}
~~~

The JWK representation of the IAK used for creating the COSE Sign1 signature
over the PSA token is:

~~~
{::include cddl/example/tfm-es-iak.json}
~~~

The resulting COSE object is:

~~~
{::include cddl/example/psa-sign1.diag}
~~~

which has the following base16 encoding:

~~~
{::include cddl/example/psa-sign1.hex}
~~~

## COSE Mac0 Token {#ex-mac0}

~~~
{::include cddl/example/mac0-claims.diag}
~~~

The JWK representation of the IAK used for creating the COSE Mac0 signature
over the PSA token is:

~~~
{::include cddl/example/tfm-hs-iak.json}
~~~

The resulting COSE object is:

~~~
{::include cddl/example/psa-mac0.diag}
~~~

which has the following base16 encoding:

~~~
{::include cddl/example/psa-mac0.hex}
~~~

# Acknowledgments
{:numbered="false"}

Thank you Carsten Bormann for help with the CDDL.
Thanks to
Nicholas Wood,
Eliot Lear,
Yaron Sheffer,
Kathleen Moriarty and
Ned Smith
for ideas, comments and suggestions.

[^rfc-ed-note]: RFC Editor: