| Internet-Draft | PSA Attestation Token | September 2022 |
| Tschofenig, et al. | Expires 10 March 2023 | [Page] |
The Platform Security Architecture (PSA) is a family of hardware and firmwaresecurity specifications, as well as open-source reference implementations, tohelp device makers and chip manufacturers build best-practice security intoproducts. Devices that are PSA compliant are able to produce attestation tokensas described in this memo, which are the basis for a number of differentprotocols, including secure provisioning and network access control. Thisdocument specifies the PSA attestation token structure and semantics.¶
The PSA attestation token is a profiled Entity Attestation Token (EAT).¶
This specification describes what claims are used in an attestation tokengenerated by PSA compliant systems, how these claims get serialized to thewire, and how they are cryptographically protected.¶
Source for this draft and an issue tracker can be found athttps://github.com/thomas-fossati/draft-psa-token.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is athttps://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 10 March 2023.¶
Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.¶
Trusted execution environments are now present in many devices, which provide asafe environment to place security sensitive code such as cryptography, secureboot, secure storage, and other essential security functions. These securityfunctions are typically exposed through a narrow and well-defined interface,and can be used by operating system libraries and applications. Various APIshave been developed by Arm as part of the Platform Security Architecture[PSA] framework. This document focuses on the output provided by PSA'sInitial Attestation API. Since the tokens are also consumed by services outsidethe device, there is an actual need to ensure interoperability.Interoperability needs are addressed here by describing the exact syntax andsemantics of the attestation claims, and defining the way these claims areencoded and cryptographically protected.¶
Further details on concepts expressed below can be found in the PSA SecurityModel documentation[PSA-SM].¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALLNOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED","MAY", and "OPTIONAL" in this document are to be interpreted asdescribed in BCP 14[RFC2119][RFC8174] when, and only when, theyappear in all capitals, as shown here.¶
Root of Trust, the minimal set of software, hardware and data that has to beimplicitly trusted in the platform - there is no software or hardware at adeeper level that can verify that the Root of Trust is authentic andunmodified. An example of RoT is an initial bootloader in ROM, which containscryptographic functions and credentials, running on a specific hardwareplatform.¶
Secure Processing Environment, a platform's processing environment forsoftware that provides confidentiality and integrity for its runtime state,from software and hardware, outside of the SPE. Contains trusted code andtrusted hardware. (Equivalent to Trusted Execution Environment (TEE), or"secure world".)¶
Non Secure Processing Environment, the security domain outside of the SPE,the Application domain, typically containing the application firmware,operating systems, and general hardware. (Equivalent to Rich ExecutionEnvironment (REE), or "normal world".)¶
Figure 1 outlines the structure of the PSA Attester according tothe conceptual model described inSection 3.1 of [I-D.ietf-rats-architecture].¶
The PSA Attester is a relatively straightforward embodiment of the RATSAttester with exactly one Attesting Environment and one Target Environment.¶
The Attesting Environment is responsible for collecting the information to berepresented in PSA claims and to assemble them into Evidence. It is made of twocooperating components:¶
The Target Environment can be broken down into four macro "objects", some ofwhich may or may not be present depending on the device architecture:¶
A reference implementation of the PSA Attester is provided by[TF-M].¶
This section describes the claims to be used in a PSA attestation token.¶
CDDL[RFC8610] along with text descriptions is used to define each claimindependent of encoding. The following CDDL type(s) are reused by differentclaims:¶
psa-hash-type = bytes .size 32 / bytes .size 48 / bytes .size 64¶
The Nonce claim is used to carry the challenge provided by the caller to demonstrate freshness of the generated token.¶
The EAT[I-D.ietf-rats-eat]nonce (claim key 10) is used. The followingconstraints apply to thenonce-type:¶
This claim MUST be present in a PSA attestation token.¶
psa-nonce = ( nonce-label => psa-hash-type)¶
The Client ID claim represents the security domain of the caller.¶
In PSA, a security domain is represented by a signedinteger whereby negative values represent callers from the NSPE and wherepositive 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 toensure that a security domain, i.e., an attestation endpoint, cannot spoof areport from another security domain.¶
This claim MUST be present in a PSA attestation token.¶
psa-client-id-nspe-type = -2147483648...0psa-client-id-spe-type = 1..2147483647psa-client-id-type = psa-client-id-nspe-type / psa-client-id-spe-typepsa-client-id = ( psa-client-id-key => psa-client-id-type)¶
The Instance ID claim represents the unique identifier of the InitialAttestation Key (IAK). The full definition is in[PSA-SM].¶
The EATueid (claim key 256) of type RAND is used. The following constraintsapply to theueid-type:¶
This claim MUST be present in a PSA attestation token.¶
psa-instance-id-type = bytes .size 33psa-instance-id = ( ueid-label => psa-instance-id-type)¶
The Implementation ID claim uniquely identifies the implementation of theimmutable PSA RoT. A verification service uses this claim to locate thedetails of the PSA RoT implementation from an Endorser or manufacturer.Such details are used by a verification service to determine the security propertiesor certification status of the PSA RoT implementation.¶
The value and format of the ID is decided bythe manufacturer or a particular certification scheme. For example, the IDcould 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 claimSection 4.2.1.¶
psa-implementation-id-type = bytes .size 32psa-implementation-id = ( psa-implementation-id-key => psa-implementation-id-type)¶
The Certification Reference claim is used to link the class of chip and PSA RoTof the attesting device to an associated entry in the PSA Certificationdatabase. It MUST be represented as a string made of nineteen numericcharacters: a thirteen-digit[EAN-13], followed by a dash "-", followed bythe five-digit versioning information described in[PSA-Cert-Guide].¶
Linking to the PSA Certification entry can still be achieved if this claim isnot present in the token by making an association at a Verifier between thereference value and other token claim values - for example, the ImplementationID.¶
psa-certification-reference-type = text .regexp "[0-9]{13}-[0-9]{5}"psa-certification-reference = ( ? psa-certification-reference-key => psa-certification-reference-type)¶The Security Lifecycle claim represents the current lifecycle state of the PSARoT. The state is represented by an integer that is divided to convey a majorstate and a minor state. A major state is mandatory and defined by[PSA-SM].A minor state is optional and 'IMPLEMENTATION DEFINED'. The PSA securitylifecycle state and implementation state are encoded as follows:¶
The PSA lifecycle states are illustrated inFigure 2. For PSA,a Verifier can only trust reports from the PSA RoT when it is in SECURED orNON_PSA_ROT_DEBUG major states.¶
This claim MUST be present in a PSA attestation token.¶
psa-lifecycle-unknown-type = 0x0000..0x00ffpsa-lifecycle-assembly-and-test-type = 0x1000..0x10ffpsa-lifecycle-psa-rot-provisioning-type = 0x2000..0x20ffpsa-lifecycle-secured-type = 0x3000..0x30ffpsa-lifecycle-non-psa-rot-debug-type = 0x4000..0x40ffpsa-lifecycle-recoverable-psa-rot-debug-type = 0x5000..0x50ffpsa-lifecycle-decommissioned-type = 0x6000..0x60ffpsa-lifecycle-type = psa-lifecycle-unknown-type / psa-lifecycle-assembly-and-test-type / psa-lifecycle-psa-rot-provisioning-type / psa-lifecycle-secured-type / psa-lifecycle-non-psa-rot-debug-type / psa-lifecycle-recoverable-psa-rot-debug-type / psa-lifecycle-decommissioned-typepsa-lifecycle = ( psa-lifecycle-key => psa-lifecycle-type)¶
The Boot Seed claim represents a value created at system boot time thatwill allow differentiation of reports from different boot sessions.¶
This claim MAY be present in a PSA attestation token.¶
If present, it MUST be between 8 and 32 bytes.¶
psa-boot-seed-type = bytes .size (8..32)psa-boot-seed = ( psa-boot-seed-key => psa-boot-seed-type)¶
The Software Components claim is a list of software components that includesall the software loaded by the PSA RoT. This claim SHALL be included inattestation tokens produced by an implementation conformant with[PSA-SM].¶
Each entry in the Software Components list describes one software componentusing the attributes described in the following subsections. Unless explicitlystated, the presence of an attribute is OPTIONAL.¶
Note that, as described in[I-D.ietf-rats-architecture], a relying partywill typically see the result of the verification process from the Verifier inform of an attestation result, rather than the "naked" PSA token from theattesting endpoint. Therefore, a relying party is not expected to understandthe Software Components claim. Instead, it is for the Verifier to check thisclaim against the available endorsements and provide an answer in form of an"high level" attestation result, which may or may not include the originalSoftware Components claim.¶
psa-software-component = { ? &(measurement-type: 1) => text &(measurement-value: 2) => psa-hash-type ? &(version: 4) => text &(signer-id: 5) => psa-hash-type ? &(measurement-desc: 6) => text}psa-software-components = ( psa-software-components-key => [ + psa-software-component ])¶The Measurement Type attribute (key=1) is short string representing the role ofthis software component.¶
The following measurement types MAY be used:¶
The Measurement Value attribute (key=2) represents a hash of the invariantsoftware component in memory at startup time. The value MUST be a cryptographichash of 256 bits or stronger.¶
This attribute MUST be present in a PSA software component.¶
The Version attribute (key=4) is the issued software version in the form of atext string. The value of this attribute will correspond to the entry in theoriginal signed manifest of the component.¶
The Signer ID attribute (key=5) is the hash of a signing authority public keyfor the software component. The value of this attribute will correspond to theentry in the original manifest for the component. This can be used by aVerifier 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].¶
The Measurement Description attribute (key=6) contains a string identifying thehash algorithm used to compute the corresponding Measurement Value. The stringSHOULD be encoded according to[IANA-HashFunctionTextualNames].¶
The Verification Service Indicator claim is a hint used by a relying party tolocate a verification service for the token. The value is a text string thatcan be used to locate the service (typically, a URL specifying the address ofthe verification service API). A Relying Party may choose to ignore this claimin favor of other information.¶
psa-verification-service-indicator-type = textpsa-verification-service-indicator = ( ? psa-verification-service-indicator-key => psa-verification-service-indicator-type)¶
The Profile Definition claim encodes the unique identifier that corresponds tothe EAT profile described by this document. This allows a receiver to assignthe intended semantics to the rest of the claims found in the token.¶
The EATprofile (claim key 265) is used. The following constraintsapply to its type:¶
This claim MUST be present in a PSA attestation token.¶
SeeSection 5, for considerations about backwards compatibilitywith previous versions of the PSA attestation token format.¶
psa-profile-type = "http://arm.com/psa/2.0.0"psa-profile = ( profile-label => psa-profile-type)¶
A previous version of this specification (identified by thePSA_IOT_PROFILE_1profile) used claim key values from the "private use range" of the CWT Claimsregistry. These claim keys have now been retired and their use is deprecated.¶
Table 1 provides the mappings between the deprecated and new claimkeys.¶
| PSA_IOT_PROFILE_1 | http://arm.com/psa/2.0.0 | |
|---|---|---|
| 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 | 2397 |
| Certification Reference | -75005 | 2398 |
| Software Components | -75006 | 2399 |
| Verification Service Indicator | -75010 | 2400 |
The new profile introduces three further changes:¶
Unless compatibility with existing infrastructure is a concern, emitters (e.g.,devices that implement the PSA Attestation API) SHOULD produce tokens withthe claim keys specified in this document.¶
To simplify the transition to the token format described in thisdocument it is RECOMMENDED that receivers (e.g., PSA Attestation Verifiers)accept tokens encoded according to the old profile (PSA_IOT_PROFILE_1) as well asto the new profile (http://arm.com/psa/2.0.0), at least for the time needed totheir clients to upgrade.¶
The PSA attestation token is encoded in CBOR[RFC8949] format. Onlydefinite-length string, arrays, and maps are allowed.¶
Cryptographic protection is obtained by wrapping thepsa-token map in a COSEWeb Token (CWT)[RFC8392]. For asymmetric key algorithms, the signaturestructure MUST be COSE_Sign1. For symmetric key algorithms, the signaturestructure MUST be COSE_Mac0.¶
Acknowledging the variety of markets, regulations and use cases in which thePSA attestation token can be used, this specification does not impose anystrong requirement on the cryptographic algorithms that need to be supported byAttesters and Verifiers. It is assumed that the flexibility provided by theCOSE format is sufficient to deal with the level of cryptographic agilityneeded to adapt to specific use cases. For interoperability considerations, itis RECOMMENDED that commonly adopted algorithms are used, such as thosediscussed in[COSE-ALGS]). It is expected that receivers (Verifiers andRelying Parties) will accept a wider range of algorithms, while Attesters wouldproduce PSA tokens using only one such algorithm.¶
The CWT CBOR tag (61) is not used. An application that needs to exchange PSAattestation tokens can wrap the serialised COSE_Sign1 or COSE_Mac0 in the mediatype defined inSection 12.2 or the CoAP Content-Format defined inSection 12.3.¶
The PSA Token supports the freshness models for attestation Evidence based onnonces and epoch handles (Section 10.2 and 10.3 of[I-D.ietf-rats-architecture]) using thenonce claim to convey the nonce orepoch handle supplied by the Verifier. No further assumption on the specificremote attestation protocol is made.¶
psa-token = { psa-nonce psa-instance-id psa-verification-service-indicator psa-profile psa-implementation-id psa-client-id psa-lifecycle psa-certification-reference ? psa-boot-seed psa-software-components}psa-client-id-key = 2394psa-lifecycle-key = 2395psa-implementation-id-key = 2396psa-boot-seed-key = 2397psa-certification-reference-key = 2398psa-software-components-key = 2399psa-verification-service-indicator-key = 2400nonce-label = 10ueid-label = 256profile-label = 265psa-hash-type = bytes .size 32 / bytes .size 48 / bytes .size 64psa-boot-seed-type = bytes .size (8..32)psa-boot-seed = ( psa-boot-seed-key => psa-boot-seed-type)psa-client-id-nspe-type = -2147483648...0psa-client-id-spe-type = 1..2147483647psa-client-id-type = psa-client-id-nspe-type / psa-client-id-spe-typepsa-client-id = ( psa-client-id-key => psa-client-id-type)psa-certification-reference-type = text .regexp "[0-9]{13}-[0-9]{5}"psa-certification-reference = ( ? psa-certification-reference-key => psa-certification-reference-type)psa-implementation-id-type = bytes .size 32psa-implementation-id = ( psa-implementation-id-key => psa-implementation-id-type)psa-instance-id-type = bytes .size 33psa-instance-id = ( ueid-label => psa-instance-id-type)psa-nonce = ( nonce-label => psa-hash-type)psa-profile-type = "http://arm.com/psa/2.0.0"psa-profile = ( profile-label => psa-profile-type)psa-lifecycle-unknown-type = 0x0000..0x00ffpsa-lifecycle-assembly-and-test-type = 0x1000..0x10ffpsa-lifecycle-psa-rot-provisioning-type = 0x2000..0x20ffpsa-lifecycle-secured-type = 0x3000..0x30ffpsa-lifecycle-non-psa-rot-debug-type = 0x4000..0x40ffpsa-lifecycle-recoverable-psa-rot-debug-type = 0x5000..0x50ffpsa-lifecycle-decommissioned-type = 0x6000..0x60ffpsa-lifecycle-type = psa-lifecycle-unknown-type / psa-lifecycle-assembly-and-test-type / psa-lifecycle-psa-rot-provisioning-type / psa-lifecycle-secured-type / psa-lifecycle-non-psa-rot-debug-type / psa-lifecycle-recoverable-psa-rot-debug-type / psa-lifecycle-decommissioned-typepsa-lifecycle = ( psa-lifecycle-key => psa-lifecycle-type)psa-software-component = { ? &(measurement-type: 1) => text &(measurement-value: 2) => psa-hash-type ? &(version: 4) => text &(signer-id: 5) => psa-hash-type ? &(measurement-desc: 6) => text}psa-software-components = ( psa-software-components-key => [ + psa-software-component ])psa-verification-service-indicator-type = textpsa-verification-service-indicator = ( ? psa-verification-service-indicator-key => psa-verification-service-indicator-type)¶Implementations of this specification are provided by the TrustedFirmware-M project[TF-M], the Veraison project[Veraison], and the Xclaim[Xclaim] library. All three implementations are released as open-source software.¶
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 specificationprofiles those options and allows signatures using public key cryptography aswell as message authentication codes (MACs). COSE_Sign1 is used for digitalsignatures 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 associatedinfrastructure costs for key management and protocol complexities.¶
Attestation tokens contain information that may be unique to a device andtherefore they may allow to single out an individual device for trackingpurposes. Deployments that have privacy requirements must take appropriatemeasures to ensure that the token is only used to provision anonymous/pseudonymkeys.¶
To verify the token, the primary need is to check correct encoding and signingas detailed inSection 6. In particular, the InstanceID claim is used (together with the kid in the COSE header, if present)to assist in locating the public key used to verify the signature covering the CWT token.The key used for verification is supplied to the Verifier by an authorizedEndorser along with the corresponding Attester's Instance ID.¶
In addition, the Verifier will typically operate a policy where values of someof the claims in this profile can be compared to reference values, registeredwith the Verifier for a given deployment, in order to confirm that the deviceis endorsed by the manufacturer supply chain. The policy may require that therelevant claims must have a match to a registered reference value. All claimsmay be worthy of additional appraisal. It is likely that most deploymentswould include a policy with appraisal for the following claims:¶
The protocol used to convey Endorsements and Reference Values to the Verifieris not in scope for this document.¶
IANA has registered the following claims in the "CBOR Web Token (CWT) Claims"registry[IANA-CWT].¶
IANA is requested to register the "application/psa-attestation-token" mediatype[RFC2046] in the "Media Types" registry[IANA-MediaTypes] in themanner described in RFC 6838[RFC6838], which can be used to indicate thatthe content is a PSA Attestation Token.¶
Additional information:¶
IANA is requested to register the CoAP Content-Format ID for the"application/psa-attestation-token" media type in the "CoAP Content-Formats"registry[IANA-CoAP-Content-Formats].¶
The following example shows a PSA attestation token for an hypothetical systemcomprising two measured software components (a boot loader and a trusted RTOS).The attesting device is in a lifecycle stateSection 4.3.1 ofSECURED. The attestation has been requested from a client residing in theSPE:¶
{ / eat_profile / 265: "http://arm.com/psa/2.0.0", / psa-client-id / 2394: 2147483647, / psa-security-lifecycle / 2395: 12288, / psa-implementation-id / 2396: h'0000000000000000000000000000000000000000000000000000000000000000', / psa-boot-seed / 2397: h'0000000000000000', / psa-certification-reference / 2398: "1234567890123-12345", / psa-software-components / 2399: [ { / measurement value / 2: h'0303030303030303030303030303030303030303030303030303030303030303', / signer ID / 5: h'0404040404040404040404040404040404040404040404040404040404040404' } ], / nonce / 10: h'0101010101010101010101010101010101010101010101010101010101010101', / ueid / 256: h'010202020202020202020202020202020202020202020202020202020202020202', / psa-vsi / 2400: "https://veraison.example/v1/challenge-response"}¶The JWK representation of the IAK used for creating the COSE Sign1 signatureover the PSA token is:¶
{ "kty": "EC", "crv": "P-256", "x": "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4", "y": "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM", "d": "870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE"}¶The resulting COSE object is:¶
18( [ / protected / h'A10126', / unprotected / {}, / payload / h'AA1901097818687474703A2F2F61726D2E636F6D2F7073612F322E302E3019095A1A7FFFFFFF19095B19300019095C5820000000000000000000000000000000000000000000000000000000000000000019095D48000000000000000019095E73313233343536373839303132332D313233343519095F81A2025820030303030303030303030303030303030303030303030303030303030303030305582004040404040404040404040404040404040404040404040404040404040404040A582001010101010101010101010101010101010101010101010101010101010101011901005821010202020202020202020202020202020202020202020202020202020202020202190960782E68747470733A2F2F7665726169736F6E2E6578616D706C652F76312F6368616C6C656E67652D726573706F6E7365', / signature / h'56F50D131FA83979AE064E76E70DC75C070B6D991AEC08ADF9F41CAB7F1B7E2C47F67DACA8BB49E3119B7BAE77AEC6C89162713E0CC6D0E7327831E67F32841A' ])¶Thanks to Carsten Bormann for help with the CDDL and Nicholas Wood for ideasand comments.¶
draft-tschofenig-rats-psa-token-10
| Document | Document type | This is an older version of an Internet-Draft that was ultimately published asRFC 9783. This document is an Internet-Draft (I-D). Anyone may submit an I-D to the IETF. This I-D isnot endorsed by the IETF and hasno formal standing in theIETF standards process. | |
|---|---|---|---|
| Select version | |||
| Compare versions | |||
| Authors | Hannes Tschofenig,Simon Frost,Mathias Brossard,Adrian L. Shaw,Thomas Fossati | ||
| RFC stream | (None) | ||
| Other formats |