RATS H. Tschofenig, Ed.
Internet-Draft S. Frost
Intended status: Standards Track M. Brossard
Expires: October 10, 2019 A. Shaw
Arm Limited
April 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 October 10, 2019.

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

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 |  | | TF-M Core|  |
                        | | 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 RFC 2119 [RFC2119].

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, 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
Challenge Yes Input object from the caller. For example, this can be a cryptographic nonce, a hash of locally attested data, or both. 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.
Verification Service Indicator No Information 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.
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 Represents the original implementation signer of the attestation key and identifies the contract between the report and verification. A verification service will use this claim to locate the details of the verification process.
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 defined in the PSA Firmware Framework (PSA-FF) [PSA-FF].
Security Lifecycle Yes Represents the current lifecycle state of the PSA RoT. The state is represented by a 16-bit unsigned integer that is divided to convey a major state and a minor state. A major state is defined by [PSA-SM]. A minor state is ‘IMPLEMENTATION DEFINED’. The encoding is: version[15:8] - PSA 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, NON_PSA_ROT_DEBUG or RECOVERABLE_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 system sessions.
Software Components Yes (unless the No Software Measurements claim is specified) A list of software components that represent the entire software state of the system. This claim is recommended in order to comply with the rules outlined in the [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.

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.
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.mandyam-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 Impl. 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)
-75007 No Software Measurements arm_psa_no_sw_measurements Unsigned integer
-75008 Challenge arm_psa_nonce Byte string
-75009 Instance ID arm_psa_UEID Byte string
-75010 Verification Service Indicator arm_psa_origination Byte string or StringOrURI

Each map entry of the software component claim MUST have the following types for each key value:

  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)

The following key values will be present in the software components claim: 1 (Type), 2 (Measurement Value), 4 (Version) and 5 (Signer ID). Keys 3 (Reserved) and 6 (Measurement Description) will not be present. Instead of a referenced Measurement Description it is defined that all cases, the software measurement value is taken as a SHA256 hash of the software image, prior to it executing in place.

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.mandyam-eat] Mandyam, G., Lundblade, L., Lundblade, L., Ballesteros, M. and J. O'Donoghue, "The Entity Attestation Token (EAT)", Internet-Draft draft-mandyam-eat-01, November 2018.
[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.
[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, 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