RATS H. Tschofenig, Ed.
Internet-Draft S. Frost
Intended status: Standards Track M. Brossard
Expires: January 9, 2020 A. Shaw
T. Fossati
Arm Limited
July 08, 2019

Arm's Platform Security Architecture (PSA) Attestation Token


The 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 systems.

This document specifies token format and claims used in the attestation API of the Arm Platform Security Architecture (PSA).

At its core, the Entity Attestation Token (EAT) format is used and populated with a set of claims. This specification describes what claims are used by the PSA and what has been implemented within Arm Trusted Firmware-M.

Status of This Memo

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 at https://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 January 9, 2020.

Copyright Notice

Copyright (c) 2019 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. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English.

Table of Contents

1. Introduction

Modern hardware for Internet of Things devices contain trusted execution environments and in case of the Arm v8-M architecture TrustZone support. TrustZone on these low end microcontrollers allows the separation between a normal world and a secure world where security sensitive code resides in the secure world and is executed by applications running on the normal world using a well-defined API. Various APIs have been developed by Arm as part of the Platform Security Architecture [PSA]; 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, interoperability needs arise. In this specification these interoperability needs are addressed by a combination of

Further details on concepts expressed below can be found within the PSA Security Model documentation [PSA-SM].

Figure 1 shows the architecture graphically. Apps on the IoT device communicate with services on the secure world using a defined API. The attestation API exposes tokens, as described in this document, and those tokens may be presented to network or application services.

                        |  Normal World   |   Secure World   |
                        |                 |        +-+       |
                        |                 |        |A|       |
                        |                 |        |T|       |
                        |                 |        |T|       |
                        |                 |        |E| +-+   |
                        |                 |    +-+ |S| |S|   |
                        |                 |    |C| |T| |T|   |
+----------+            |                 |    |R| |A| |O|   |
| Network  |            | +----------+    |    |Y| |T| |R|   |
| and App  |<=============| Apps     | +--+--+ |P| |I| |A|   |
| Services |            | +----------+ |P |  | |T| |O| |G|   |
+----------+            | +----------+ |S |  | |O| |N| |E|   |
                        | |Middleware| |A |  | +-+ +-+ +-+   |
                        | +----------+ |  |  | +----------+  |
                        | +----------+ |A |  | |          |  |
                        | |          | |P |  | |   SPM    |  |
                        | | RTOS and | |I |  | +----------+  |
                        | | Drivers  | +--+--+ +----------+  |
                        | |          |    |    |   Boot   |  |
                        | +----------+    |    |  Loader  |  |
                        |                 |    +----------+  |
                        |          H A R D|W A R E           |

                               Internet of Things Device

Figure 1: Software Architecture

2. Conventions and Terminology

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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

2.1. Glossary

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.

3. Information Model

Table 1 describes the utilized claims.

Information Model of PSA Attestation Claims.
Claim Mandatory Description
Auth Challenge Yes Input 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 ID Yes Represents 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 [PSA-SM].
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 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 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 full definition of the partition ID is given in [PSA-FF].
Security Lifecycle Yes 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 encoding is: version[15:8] - PSA security lifecycle state, and version[7:0] - IMPLEMENTATION DEFINED state. The PSA lifecycle states are listed below. 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 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 PSA RoT 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 will 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 PSA Root of Trust. This claim is needed for the rules outlined in [PSA-SM]. The software components are further explained below.
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 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 [PSA-SM].

The PSA lifecycle states consist of the following values:

Table 2 shows the structure of each software component entry in the Software Components claim.

Software Components Claims.
Key ID Type Mandatory Description
1 Measurement Type No A short string representing the role of this software component (e.g. ‘BL’ for Boot Loader).
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 will correspond to the entry in the original signed manifest of the component.
5 Signer ID No The 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 [PSA-SM].
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 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:

4. Token Encoding

The report is represented as a token, which must be formatted in accordance to the Entity Attestation Token (EAT) [I-D.ietf-rats-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 [RFC7049] format.

5. Claims

The token is modelled to include custom values that correspond to the following claims suggested in the EAT specification:

Later 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 Key Claim Description Claim Name CBOR Value Type
-75000 Profile Definition arm_psa_profile_id Text string
-75001 Client ID arm_psa_partition_id Unsigned integer or Negative integer
-75002 Security Lifecycle arm_psa_security_lifecycle Unsigned integer
-75003 Implementation ID arm_psa_implementation_id Byte string (>=32 bytes)
-75004 Boot Seed arm_psa_boot_seed Byte string (>=32 bytes)
-75005 Hardware Version arm_psa_hw_version Text string
-75006 Software Components arm_psa_sw_components Array of map entries (compound map claim). See below for allowed key-values.
-75007 No Software Measurements arm_psa_no_sw_measurements Unsigned integer
-75008 Auth Challenge arm_psa_nonce Byte string
-75009 Instance ID arm_psa_UEID Byte string
-75010 Verification Service Indicator arm_psa_origination Byte string

When using the Software Components claim each key value MUST correspond to the following types:

  1. Text string (type)
  2. Byte string (measurement, >=32 bytes)
  3. Reserved
  4. Text string (version)
  5. Byte string (signer ID, >=32 bytes)
  6. Text string (measurement description)

6. Example

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:

Key using COSE format (base64-encoded):


Example of EAT token (base64-encoded):


Same token using extended CBOR diagnostic format:

  / protected / h'a10126' / {
      \ alg \ 1: -7 \ ECDSA 256 \
    } / ,
  / unprotected / {},
  / payload / h'a93a000124fb5820000102030405060708090a0b0c0d0e0f1011121
  31' / {
     / arm_psa_boot_seed / -75004: h'000102030405060708090a0b0c0d0e0f10
     / arm_psa_implementation_id / -75003: h'000102030405060708090a0b0c
     / arm_psa_sw_components / -75006: [
            / measurement / 2: h'000102030405060708090a0b0c0d0e0f101112
            / version / 4: "3.1.4",
            / signerID / 5: h'000102030405060708090a0b0c0d0e0f101112131
            / type / 1: "BL"
            / measurement / 2: h'000102030405060708090a0b0c0d0e0f101112
            / version / 4: "1.1",
            / signerID / 5: h'000102030405060708090a0b0c0d0e0f101112131
            / type / 1: "PRoT"
            / measurement / 2: h'000102030405060708090a0b0c0d0e0f101112
            / version / 4: "1.0",
            / signerID / 5: h'000102030405060708090a0b0c0d0e0f101112131
            / type / 1: "ARoT"
            / measurement / 2: h'000102030405060708090a0b0c0d0e0f101112
            / version / 4: "2.2",
            / signerID / 5: h'000102030405060708090a0b0c0d0e0f101112131
            / type / 1: "App"
      / arm_psa_security_lifecycle / -75002: 12288 / SECURED /,
      / arm_psa_nonce / -75008: h'000102030405060708090a0b0c0d0e0f10111
      / arm_psa_origination / -75010: "psa_verifier",
      / arm_psa_partition_id / -75001: -1,
      / arm_psa_UEID / -75009: h'01000102030405060708090a0b0c0d0e0f1011
      / arm_psa_profile_id / -75000: "PSA_IoT_PROFILE_1"
    } / ,
  / signature / h'58860508ee7e8cc48eba872dbb5d694a542b1322ad0d51023c197

7. Security and Privacy Considerations

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 [RFC8152]. The COSE type MUST be COSE-Sign1.

Attestation tokens contain information that may be unique to a device and therefore they may allow single out an individual device for tracking purposes. Implementation must take 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.

8. IANA Considerations

IANA is requested to allocate the claims defined in Section 5 to the [RFC8392] created CBOR Web Token (CWT) Claims registry [IANA-CWT]. The change controller are the authors and the reference is this document.

9. References

9.1. Normative References

[I-D.ietf-rats-eat] Mandyam, G., Lundblade, L., Ballesteros, M. and J. O'Donoghue, "The Entity Attestation Token (EAT)", Internet-Draft draft-ietf-rats-eat-01, July 2019.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, October 2013.
[RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", RFC 8152, DOI 10.17487/RFC8152, July 2017.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017.
[RFC8392] Jones, M., Wahlstroem, E., Erdtman, S. and H. Tschofenig, "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, May 2018.

9.2. Informative References

[EAN-13] GS1, "International Article Number - EAN/UPC barcodes", 2019.
[IANA-CWT] IANA, "CBOR Web Token (CWT) Claims", 2019.
[PSA] Arm, "Platform Security Architecture Resources", 2019.
[PSA-FF] Arm, "Platform Security Architecture Firmware Framework 1.0 (PSA-FF)", February 2019.
[PSA-SM] Arm, "Platform Security Architecture Security Model 1.0 (PSA-SM)", February 2019.
[TF-M] Linaro, "Trusted Firmware", 2019.

Appendix A. Contributors

We would like to thank the following supporters for their contributions:

* Laurence Lundblade
  Security Theory LLC
* Tamas Ban
  Arm Limited

Appendix B. Reference Implementation

Trusted Firmware M (TF-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).

Authors' Addresses

Hannes Tschofenig (editor) Arm Limited EMail: hannes.tschofenig@arm.com
Simon Frost Arm Limited EMail: Simon.Frost@arm.com
Mathias Brossard Arm Limited EMail: Mathias.Brossard@arm.com
Adrian Shaw Arm Limited EMail: Adrian.Shaw@arm.com
Thomas Fossati Arm Limited EMail: thomas.fossati@arm.com