Arm's Platform Security Architecture (PSA) Attestation TokenArm Limitedhannes.tschofenig@arm.comArm LimitedSimon.Frost@arm.comArm LimitedMathias.Brossard@arm.comArm LimitedAdrian.Shaw@arm.comArm Limitedthomas.fossati@arm.com
Security
RATSInternet-DraftThe insecurity of IoT systems is a widely known and discussed problem. The Arm Platform Security Architecture (PSA) is being developed to address this challenge by making it easier to build secure IoT systems.This document specifies token format and claims used in the attestation API of the Arm Platform Security Architecture (PSA).At its core, the CWT (COSE Web Token) format is used and populated with a set of claims, in a way similar to EAT (Entity Attestation Token). This specification describes what claims are used by PSA compliant systems and what has been implemented within Arm Trusted Firmware-M.Modern hardware for Internet of Things devices contain trusted execution environments and in case of the Arm v8-M architecture TrustZone support. On these low end microcontrollers, TrustZone enables the separation between a “normal world” and a “secure world” where security sensitive code resides in the “secure world” and applications running in the “normal world” request secure services using a well-defined API. Various APIs have been developed by Arm as part of the Platform Security Architecture programme; this document focuses on the functionality provided by the attestation API. Since the tokens exposed via the attestation API are also consumed by services outside the device, there is an actual need for making them interoperable. In this specification these interoperability needs are addressed 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 . provides a view of the architectural components and how they interact. Applications on the IoT device communicate with services residing in the “secure world” by means of a well-defined API. The attestation API produces tokens, as described in this document, and those tokens may be presented to network or application services.The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL
NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”,
“MAY”, and “OPTIONAL” in this document are to be interpreted as
described in BCP 14 when, and only when, they
appear in all capitals, as shown here.
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.
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 the Secure Partition Manager (SPM), the Secure Partitions and the trusted hardware.
Non Secure Processing Environment, the security domain outside of the SPE, the Application domain, typically containing the application firmware and hardware. describes the mandatory and optional claims in the report.ClaimMandatoryDescriptionAuth ChallengeYesInput object from the caller. For example, this can be a cryptographic nonce, a hash of locally attested data. The length must be 32, 48, or 64 bytes.Instance IDYesRepresents the unique identifier of the instance. It is a hash of the public key corresponding to the Initial Attestation Key. The full definition is in .Verification Service IndicatorNoA 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 DefinitionNoContains 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 IDYesUniquely identifies the underlying immutable PSA RoT. 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.Client IDYesRepresents 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 full definition of the partition ID is given in .Security LifecycleYesRepresents 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 . A minor state is optional and ‘IMPLEMENTATION DEFINED’. The encoding is: version[15:8] - PSA security lifecycle state, and version[7:0] - IMPLEMENTATION DEFINED state. The PSA lifecycle states are listed in . For PSA, a remote verifier can only trust reports from the PSA RoT when it is in SECURED or NON_PSA_ROT_DEBUG major states.Hardware versionNoProvides 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 PSA RoT to the data on a certification website. It must be represented as a thirteen-digit Boot SeedYesRepresents a random value created at system boot time that will allow differentiation of reports from different boot sessions.Software ComponentsYes (unless the No Software Measurements claim is specified)A list of software components that represent all the software loaded by the PSA Root of Trust. This claim is needed for the rules outlined in . The software components are further detailed in .No Software MeasurementsYes (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 will be mandatory to include this claim to indicate this is a deliberate state. This claim is intended for devices that are not compliant with .The PSA lifecycle states consist of the following values:PSA_LIFECYCLE_UNKNOWN (0x0000u)PSA_LIFECYCLE_ASSEMBLY_AND_TEST (0x1000u)PSA_LIFECYCLE_PSA_ROT_PROVISIONING (0x2000u)PSA_LIFECYCLE_SECURED (0x3000u)PSA_LIFECYCLE_NON_PSA_ROT_DEBUG (0x4000u)PSA_LIFECYCLE_RECOVERABLE_PSA_ROT_DEBUG (0x5000u)PSA_LIFECYCLE_DECOMMISSIONED (0x6000u)Each software component in the Software Components claim MUST include the required properties of .Key IDTypeMandatoryDescription1Measurement TypeNoA short string representing the role of this software component (e.g. ‘BL’ for Boot Loader).2Measurement valueYesRepresents a hash of the invariant software component in memory at startup time. The value must be a cryptographic hash of 256 bits or stronger.3ReservedNoReserved4VersionNoThe issued software version in the form of a text string. The value of this claim will correspond to the entry in the original signed manifest of the component.5Signer IDNoThe hash of a signing authority public key for the software component. The value of this claim 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 field must be present to be compliant with .6Measurement descriptionNoDescription of the way in which the measurement value of the software component is computed. The value will be 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 will normally be excluded, unless there was an exception to the default measurement described in the profile for a specific component.The following measurement types are current defined:‘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 SubsystemThe report is encoded as a COSE Web Token (CWT) , similar to the Entity Attestation Token (EAT) . 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 in CBOR format.The token is modelled to include custom values that correspond to the following claims suggested in the EAT specification:nonce (mandatory); arm_psa_nonce is used insteadUEID (mandatory); arm_psa_UEID is used insteadorigination (recommended); arm_psa_origination is used insteadLater revisions of this documents might phase out those custom claims to be replaced by the EAT standard claims.As noted, some fields must be at least 32 bytes long to provide sufficient cryptographic strength.Claim KeyClaim DescriptionClaim NameCBOR Value Type-75000Profile Definitionarm_psa_profile_idText string-75001Client IDarm_psa_partition_idUnsigned integer or Negative integer-75002Security Lifecyclearm_psa_security_lifecycleUnsigned integer-75003Implementation IDarm_psa_implementation_idByte string (>=32 bytes)-75004Boot Seedarm_psa_boot_seedByte string (>=32 bytes)-75005Hardware Versionarm_psa_hw_versionText string-75006Software Componentsarm_psa_sw_componentsArray of map entries (compound map claim). See below for allowed key-values.-75007No Software Measurementsarm_psa_no_sw_measurementsUnsigned integer-75008Auth Challengearm_psa_nonceByte string-75009Instance IDarm_psa_UEIDByte string-75010Verification Service Indicatorarm_psa_originationByte stringWhen using the Software Components claim each key value MUST correspond to the following types:Text string (type)Byte string (measurement, >=32 bytes)ReservedText string (version)Byte string (signer ID, >=32 bytes)Text string (measurement description)The following example shows an attestation token that was produced
for a device that has a single-stage bootloader, and an RTOS with a device
management client. From a code point of view, the RTOS and the device
management client form a single binary.EC key using curve P-256 with:x: 0xdcf0d0f4bcd5e26a54ee36cad660d283d12abc5f7307de58689e77cd60452e75y: 0x8cbadb5fe9f89a7107e5a2e8ea44ec1b09b7da2a1a82a0252a4c1c26ee1ed7cfd: 0xc74670bcb7e85b3803efb428940492e73e3fe9d4f7b5a8ad5e480cbdbcb554c2Key using COSE format (base64-encoded):Example of EAT token (base64-encoded):Same token using extended CBOR diagnostic format:This specification re-uses the CWT and the EAT 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 only uses public key cryptography. The token MUST be signed following the structure of the COSE specification . The COSE type MUST be COSE-Sign1.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. Implementation must take appropriate measures to ensure that only those claims are included that fulfil the purpose of the application and that users of those devices consent to the data sharing.IANA is requested to allocate the claims defined in to the CBOR Web Token (CWT) Claims registry . The change controller are the authors and the reference is this document.Key words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.CBOR Web Token (CWT)CBOR Web Token (CWT) is a compact means of representing claims to be transferred between two parties. The claims in a CWT are encoded in the Concise Binary Object Representation (CBOR), and CBOR Object Signing and Encryption (COSE) is used for added application-layer security protection. A claim is a piece of information asserted about a subject and is represented as a name/value pair consisting of a claim name and a claim value. CWT is derived from JSON Web Token (JWT) but uses CBOR rather than JSON.CBOR Object Signing and Encryption (COSE)Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need for the ability to have basic security services defined for this data format. This document defines the CBOR Object Signing and Encryption (COSE) protocol. This specification describes how to create and process signatures, message authentication codes, and encryption using CBOR for serialization. This specification additionally describes how to represent cryptographic keys using CBOR.Concise Binary Object Representation (CBOR)The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack.Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.The Entity Attestation Token (EAT)An Entity Attestation Token (EAT) provides a signed (attested) set of claims that describe state and characteristics of an entity, typically a device like a phone or an IoT device. These claims are used by a relying party to determine how much it wishes to trust the entity. An EAT is either a CWT or JWT with some attestation-oriented claims. To a large degree, all this document does is extend CWT and JWT. Contributing TBDTrusted FirmwareLinaroCBOR Web Token (CWT) ClaimsIANAInternational Article Number - EAN/UPC barcodesGS1Platform Security Architecture ResourcesArmPlatform Security Architecture Firmware Framework 1.0 (PSA-FF)ArmPlatform Security Architecture Security Model 1.0 (PSA-SM)ArmWe would like to thank the following supporters for their contributions:Trusted Firmware M (TF-M) is the name of the open source project that provides
a reference implementation of PSA APIs and an SPM, created for the latest Arm v8-M microcontrollers
with TrustZone technology. TF-M provides foundational firmware components that silicon
manufacturers and OEMs can build on (including trusted boot, secure device initialisation
and secure function invocation).