About this document¶

Release information¶

The change history table lists the changes that have been made to this document.

Table 1 Document revision history¶
Date	Version	Confidentiality	Change
February 2019	1.0 beta 0	Non-confidential	Initial publication.
June 2019	1.0.0	Non-confidential	First stable release with 1.0 API finalized. Uses the PSA Certified API common error status codes. Modified the API parameters to align with other PSA Certified APIs. Updated the claims and lifecycle to match the latest Platform Security Model. Updated CBOR example in the appendix.
August 2019	1.0.1	Non-confidential	Recommend type byte 0x01 for arm_psa_UEID. Remove erroneous guidance regarding EAT’s origination claim.
February 2020	1.0.2	Non-confidential	Clarify the claim number of Instance ID. Permit COSE-Mac0 for signing tokens (with appropriate warning). Update URLs.
October 2022	1.0.3	Non-confidential	Relicensed as open source under CC BY-SA 4.0. CDDL definition added to the appendices. Example header file added to the appendices. Minor corrections and clarifications.

The detailed changes in each release are described in Document history.

PSA Certified Attestation API

License¶

Text and illustrations

Text and illustrations in this work are licensed under Attribution-ShareAlike 4.0 International (CC BY-SA 4.0). To view a copy of the license, visit creativecommons.org/licenses/by-sa/4.0.

Grant of patent license. Subject to the terms and conditions of this license (both the CC BY-SA 4.0 Public License and this Patent License), each Licensor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Licensed Material, where such license applies only to those patent claims licensable by such Licensor that are necessarily infringed by their contribution(s) alone or by combination of their contribution(s) with the Licensed Material to which such contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Licensed Material or a contribution incorporated within the Licensed Material constitutes direct or contributory patent infringement, then any licenses granted to You under this license for that Licensed Material shall terminate as of the date such litigation is filed.

The Arm trademarks featured here are registered trademarks or trademarks of Arm Limited (or its subsidiaries) in the US and/or elsewhere. All rights reserved. Please visit arm.com/company/policies/trademarks for more information about Arm’s trademarks.

About the license

The language in the additional patent license is largely identical to that in section 3 of the Apache License, Version 2.0 (Apache 2.0), with two exceptions:

Changes are made related to the defined terms, to align those defined terms with the terminology in CC BY-SA 4.0 rather than Apache 2.0 (for example, changing “Work” to “Licensed Material”).
The scope of the defensive termination clause is changed from “any patent licenses granted to You” to “any licenses granted to You”. This change is intended to help maintain a healthy ecosystem by providing additional protection to the community against patent litigation claims.

To view the full text of the Apache 2.0 license, visit apache.org/licenses/LICENSE-2.0.

Source code

Source code samples in this work are licensed under the Apache License, Version 2.0 (the “License”); you may not use such samples except in compliance with the License. You may obtain a copy of the License at apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and limitations under the License.

References¶

This document refers to the following documents.

Table 2 Documents referenced by this document¶
Ref	Document Number	Title
[PSM]	ARM DEN 0128	Platform Security Model. developer.arm.com/documentation/den0128
[PSA-STAT]	ARM IHI 0097	PSA Certified Status code API. arm-software.github.io/psa-api/status-code
[PSA-FF-M]	ARM DEN 0063	Arm® Platform Security Architecture Firmware Framework. pages.arm.com/psa-apis
[C99]		ISO/IEC, ISO/IEC 9899:1999 — Programming Languages — C, December 1999. www.iso.org/standard/29237.html
[EAT]		IETF Entity Attestation Token (EAT), Draft. datatracker.ietf.org/doc/draft-ietf-rats-eat
[PSATOKEN]		Arm’s Platform Security Architecture (PSA) Attestation Token, Draft. datatracker.ietf.org/doc/draft-tschofenig-rats-psa-token
[STD94]		Bormann, C. and P. Hoffman, Concise Binary Object Representation (CBOR), December 2020. rfc-editor.org/info/std94
[STD96]		Schaad, J., CBOR Object Signing and Encryption (COSE): Structures and Process, August 2022. rfc-editor.org/info/std96
[RFC8610]		IETF, Concise Data Definition Language (CDDL). tools.ietf.org/html/rfc8610
[EAN-13]		International Article Number. www.gs1.org/standards/barcodes/ean-upc

Terms and abbreviations¶

This document uses the following terms and abbreviations.

Table 3 Terms and abbreviations¶
Term	Meaning
CBOR	See Concise Binary Object Representation.
Concise Binary Object Representation (CBOR)	A format for encoding binary objects in a bitstream, defined in Concise Binary Object Representation (CBOR) [STD94].
EAT	See Entity Attestation Token.
Entity Attestation Token (EAT)	A report format for attestation tokens, defined in IETF Entity Attestation Token (EAT) [EAT].
IAK	See Initial Attestation Key.
Immutable Platform Root of Trust	Part of the Platform Root of Trust, which is inherently trusted. This refers to the hardware and firmware that cannot be updated on a production device. See Platform Security Model [PSM].
Implementation Defined	Behavior that is not defined by this specification, but is defined and documented by individual implementations. Application developers can choose to depend on IMPLEMENTATION DEFINED behavior, but must be aware that their code might not be portable to another implementation.
Initial Attestation Key (IAK)	Typically, the Initial Attestation Key is a secret private key from an asymmetric key-pair accessible only to the Initial Attestation service within the Platform Root of Trust. See Platform Security Model [PSM].
Non-secure Processing Environment (NSPE)	This is the security domain outside of the Secure Processing Environment. It is the application domain, typically containing the application firmware and hardware.
NSPE	See Non-secure Processing Environment.
Platform Root of Trust (PRoT)	The overall trust anchor for the system. This ensures the platform is securely booted and configured, and establishes the secure environments required to protect security services. See Platform Security Model [PSM].
PRoT	See Platform Root of Trust.
PSA	Platform Security Architecture
Secure Processing Environment (SPE)	This is the security domain that includes the Platform Root of Trust domain.
SPE	See Secure Processing Environment.

Potential for change¶

The contents of this specification are stable for version 1.0.

The following may change in updates to the version 1.0 specification:

Small optional feature additions.
Clarifications.

Significant additions, or any changes that affect the compatibility of the interfaces defined in this specification will only be included in a new major or minor version of the specification.

Conventions¶

Typographical conventions¶

The typographical conventions are:

italic

Introduces special terminology, and denotes citations.

monospace

Used for assembler syntax descriptions, pseudocode, and source code examples.

Also used in the main text for instruction mnemonics and for references to other items appearing in assembler syntax descriptions, pseudocode, and source code examples.

small capitals

Used for some common terms such as implementation defined.

Used for a few terms that have specific technical meanings, and are included in the Terms and abbreviations.

Red text

Indicates an open issue.

Blue text

Indicates a link. This can be

A cross-reference to another location within the document
A URL, for example example.com

Numbers¶

Numbers are normally written in decimal. Binary numbers are preceded by 0b, and hexadecimal numbers by 0x.

In both cases, the prefix and the associated value are written in a monospace font, for example 0xFFFF0000. To improve readability, long numbers can be written with an underscore separator between every four characters, for example 0xFFFF_0000_0000_0000. Ignore any underscores when interpreting the value of a number.

Current status and anticipated changes¶

The token format defined within this specification has been superseded by the attestation token format defined in Arm's Platform Security Architecture (PSA) Attestation Token [PSATOKEN]. A future update to this specification will incorporate the new token definition.

Feedback¶

We welcome feedback on the PSA Certified API documentation.

If you have comments on the content of this book, visit github.com/arm-software/psa-api/issues to create a new issue at the PSA Certified API GitHub project. Give:

The title (Attestation API).
The number and issue (IHI 0085 1.0.3).
The location in the document to which your comments apply.
A concise explanation of your comments.

We also welcome general suggestions for additions and improvements.