Prepare Attestation API for publication as v2.0

doc/attestation/about.rst

@@ -1,27 +1,13 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2020, 2022-2025 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-FileCopyrightText: Copyright 2018-2020, 2022-2026 Arm Limited and/or its affiliates <open-source-office@arm.com>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. Releases of this specification
 
-.. release:: 1.0 beta 0
-    :date: February 2019
-    :confidentiality: Non-confidential
-
-    Initial publication.
-
 .. release:: 1.0.0
     :date: June 2019
     :confidentiality: 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.
+    First stable release with finalized 1.0 API.
 
 .. release:: 1.0.1
     :date: August 2019
@@ -60,7 +46,7 @@
     GlobalPlatform governance of PSA Certified evaluation scheme.
 
 .. release:: 2.0.0
-    :date: ? 2024
+    :date: May 2026
     :confidentiality: Non-confidential
 
     Updated attestation token format to the PSA attestation token.

doc/attestation/api.db/psa/initial_attestation.h

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: Copyright 2018-2020, 2022-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
+// SPDX-FileCopyrightText: Copyright 2018-2020, 2022-2026 Arm Limited and/or its affiliates <open-source-office@arm.com>
 // SPDX-License-Identifier: Apache-2.0
 
 #define PSA_INITIAL_ATTEST_API_VERSION_MAJOR 2

doc/attestation/api/api.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2020, 2022-2025 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-FileCopyrightText: Copyright 2018-2020, 2022-2026 Arm Limited and/or its affiliates <open-source-office@arm.com>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. _api:
@@ -7,7 +7,7 @@ API reference
 =============
 
 .. header:: psa/initial_attestation
-    :copyright: Copyright 2018-2020, 2022-2025 Arm Limited and/or its affiliates <open-source-office@arm.com>
+    :copyright: Copyright 2018-2020, 2022-2026 Arm Limited and/or its affiliates <open-source-office@arm.com>
     :license: Apache-2.0
     :c++:
     :guard:
@@ -182,7 +182,7 @@ Attestation
 
    .. output:: *token_size
 
-      On success, the maximum size of an attestation token in bytes when using the specified ``challenge_size``
+      On success, the size of an attestation token in bytes when using the specified ``challenge_size``
 
    .. return:: psa_status_t
 

doc/attestation/appendix/example-header.rst

@@ -16,7 +16,7 @@ This appendix provides a example of the :file:`psa/initial_attestation.h` header
 
    The header will not compile without these missing definitions, and might require reordering to satisfy C compilation rules.
 
-psa/inital_attestation.h
-~~~~~~~~~~~~~~~~~~~~~~~~
+psa/initial_attestation.h
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. insert-header:: psa/initial_attestation

doc/attestation/appendix/history.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2020, 2022-2025 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-FileCopyrightText: Copyright 2018-2020, 2022-2026 Arm Limited and/or its affiliates <open-source-office@arm.com>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. _document-history:
@@ -9,48 +9,31 @@ Document history
 ..  list-table::
     :class: longtable
     :header-rows: 1
-    :widths: 3 17
+    :widths: 4 16
 
     * - Date
       - Changes
 
-    * - 2019-02-25
-      - *1.0 Beta 0*
-
-        * First public version for review
-
-    * - 2019-06-12
+    * - June 2019
       - *1.0.0*
 
         * First stable release
-        * The API functions now use the shared ``psa_status_t`` return type.
-        * Error values now use shared error codes, which are now defined in :file:`psa/error.h`.
-        * Input parameters are now separate from output parameters. There are no longer any in/out parameters.
-        * Size types have been replaced with ``size_t`` instead of ``uint32_t``.
-        * Some parameter names have been changed to improve legibility.
-        * The description of the Implementation ID claim has been rewritten to better match the definition in PSM.
-        * Signer ID is no longer a mandatory part of the Software Components claim. However, it is needed for PSM compliance.
-        * Explicitly describe which optional claims are required for PSM compliance.
-        * Added lifecycle state (``PSA_LIFECYCLE_ASSEMBLY_AND_TEST``).
-        * Clarifications and improvements to the description of some API elements and to the structure of the document.
-        * Updated CBOR example in the appendix.
-        * Added macro ``PSA_INITIAL_ATTEST_MAX_TOKEN_SIZE``.
-
-    * - 2019-08-16
+
+    * - August 2019
       - *1.0.1*
 
         * Fixed typos and descriptions based on feedback.
         * Recommend type byte 0x01 for arm_psa_UEID.
         * Remove erroneous guidance regarding EAT's origination claim - it should not be used to find a verification service.
 
-    * - 2020-02-06
+    * - February 2020
       - *1.0.2*
 
         * Clarify the claim number of Instance ID
         * Permit COSE-Mac0 for signing tokens (with appropriate warning)
         * Update URLs
 
-    * - 2022-10-17
+    * - October 2022
       - *1.0.3*
 
         * Relicensed the document under Attribution-ShareAlike 4.0 International with a patent license derived from Apache License 2.0. See :secref:`license`.
@@ -59,12 +42,12 @@ Document history
         * Instance ID definition for symmetric keys has been improved. The specific constructions are now recommended rather than normative.
         * Clarified the optionality of map entries in the Software Components claim.
 
-    * - 2025-09-23
+    * - September 2025
       - *1.0.4*
 
         * Updated introduction to reflect GlobalPlatform assuming the governance of the PSA Certified evaluation scheme.
 
-    * - 2025-??-??
+    * - May 2026
       - *2.0.0*
 
         * Update the API to use the PSA attestation token, defined in :rfc-title:`9783`. The token and report format, CDDL definition, and example token are no longer required in this specification.

doc/attestation/conf.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright 2018-2020, 2022-2025 Arm Limited and/or its affiliates <open-source-office@arm.com>
+# SPDX-FileCopyrightText: Copyright 2018-2020, 2022-2026 Arm Limited and/or its affiliates <open-source-office@arm.com>
 # SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 # PSA Certified API document configuration
@@ -15,7 +15,7 @@
     'author': 'Arm Limited',
 
     # Document copyright date, default to year of 'date'
-    'copyright_date': '2018-2020, 2022-2025',
+    'copyright_date': '2018-2020, 2022-2026',
     'copyright': 'Arm Limited and/or its affiliates',
 
     # Arm document identifier, marked as open issue if not provided
@@ -31,7 +31,7 @@
     # Identifies the sequence number of a release candidate of the same issue
     # default to None
     'release_candidate': None,
-    'draft': True,
+    #'draft': True,
 
     # Arm document confidentiality. Must be either Non-confidential or Confidential
     # Marked as open issue if not provided
@@ -42,7 +42,7 @@
     'license': 'psa-certified-api-license',
 
     # Document date, default to build date
-    #'date': '23/09/2025',
+    'date': 'May 2026',
 
     # psa_spec: default header file for API definitions
     # default to None, and can be set in documentation source

doc/attestation/index.rst

@@ -7,14 +7,6 @@
 
         This document is part of the PSA Certified API specifications. It defines interfaces to provide an attestation service for the Root of Trust.
 
-    .. banner:: **DRAFT**
-
-        This is a draft version of the documentation.
-
-        Some of the content might be incomplete, including changes and additions to the API.
-
-        It also includes material that is not present in published versions of the specification, providing rationale and commentary on work in progress.
-
 ..  front-matter::
 
     about

doc/attestation/overview/intro.rst

@@ -17,6 +17,10 @@ The interface described in this document is a PSA Certified API, that provides a
 
 The format of the attestation report that is produced by the |API| is specified in :rfc-title:`9783`.
 
+.. note::
+
+   Version 2.0 of this specification is not compatible with any 1.0 version, as a result of the change in format of the attestation report that is generated by this API.
+
 This document includes:
 
 -  A set of common use cases. See :secref:`use cases`.

doc/attestation/overview/use-cases.rst

@@ -8,7 +8,7 @@ Use cases and rationale
 
 The following subsections describe the primary use cases that this version of |API| aims to support. Other use cases are also possible.
 
-The :term:`Platform Root of Trust` (PRoT) reports information, known as claims, that can be used to determine the exact implementation of the PRoT and its security state. If the PRoT loads other components then it also includes information about what it has loaded. Other components outside of the PRoT can add additional information to the report by calling the provided API, which will include and sign the additional information. The PRoT signs attestation reports using the :term:`Initial Attestation Key` (IAK).
+The :term:`Platform Root of Trust` (PRoT) reports information, known as claims, that can be used to determine the exact implementation of the PRoT and its security state. If the PRoT loads other components then it also includes information about what it has loaded. Other components outside of the PRoT can bind additional information to the report by incorporating that information, or a hash of it, into the challenge passed to the attestation API. The PRoT signs attestation reports using the :term:`Initial Attestation Key` (IAK).
 
 Device enrolment
 ----------------