ARM-software · athoelke · Jun 11, 2026 · Jun 11, 2026 · Jun 11, 2026 · Apr 15, 2026
@@ -3,6 +3,11 @@
 
 # IDE settings
 /.vscode
+# Local OS files
+.DS_Store
+# Python cache
+__pycache__/
+*.py[cod]
 # Generated documentation
 _build
 build
diff --git a/Makefile b/Makefile
@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates
+# SPDX-License-Identifier: Apache-2.0
+
+PSA_API_TOOL ?= tools
+
+# The location of psa-api-tool must be specified
+ifeq ($(wildcard $(PSA_API_TOOL)/make),)
+ $(error The 'PSA_API_TOOL' variable is not set, or does not point to a suitable installation of psa-api-tool)
+endif
+
+include $(PSA_API_TOOL)/make
@@ -11,6 +11,7 @@ This GitHub repository contains:
 *  Specification source files
 *  Reference copies of the PSA Certified API header files
 *  Examples of usage and implementation of the PSA Certified APIs
+*  Build tooling for rendering the specifications
 *  Discussions of updates to the specifications
 *  Proposed changes to the specifications
 
@@ -77,6 +78,32 @@ Crypto Driver Interface | [1.0 Alpha-1][crypto-driver-specs] | [doc/crypto-drive
 
 Reference header files for each minor version of each API are provided in the [headers/](headers) folder.
 
+## Building the specifications
+
+This repository includes the documentation build tooling in [tools/](tools). The top-level `Makefile` uses that local tool copy by default, so a normal build does not require a separate checkout of the build tools.
+
+The core HTML build path requires Python, Sphinx, and `make`. PDF output also requires a LaTeX toolchain with `pdflatex`. Regenerating figures can require additional tools, depending on the figure source format, including Graphviz, `wavedrompy`, PlantUML, Java, and `rsvg-convert`.
+
+Build one specification from the repository root with:
+
+```sh
+make doc/crypto/html
+make doc/crypto/pdf
+make doc/crypto/headers
+make doc/crypto/api-diff
+```
+
+Replace `doc/crypto` with another specification directory, such as `doc/attestation`, `doc/storage`, `doc/fwu`, `doc/status-code`, or `doc/crypto-driver`.
+
+Build one output format for every specification with:
+
+```sh
+make html
+make pdf
+```
+
+Generated output is written under [build/](build). The build guide in [tools/docs/using-psa-api-tool.md](tools/docs/using-psa-api-tool.md) describes the available targets, dependencies, and validation flow. The editing reference in [tools/docs/psa-api-tool-notes.md](tools/docs/psa-api-tool-notes.md) describes the custom directives, roles, and source conventions used by the specifications.
+
 ## Test Suite
 
 Test suites are available to validate compliance of API implementations against the specifications for Crypto, Attestation, and Secure Storage APIs, from:

@@ -5,7 +5,7 @@
 
 ' SUIT update using the FWU API
 
-!include atg-spec.pumh
+!include psa-spec.pumh
 
 box Network
 participant "Update server" as server

@@ -3,7 +3,7 @@
 
 @startuml
 
-!include atg-spec.pumh
+!include psa-spec.pumh
 
 ' Complex SUIT installation using the FWU API
 

@@ -3,7 +3,7 @@
 
 @startuml
 
-!include atg-spec.pumh
+!include psa-spec.pumh
 
 ' Complex SUIT installation using the FWU API, no boot
 

@@ -3,7 +3,7 @@
 
 @startuml
 
-!include atg-spec.pumh
+!include psa-spec.pumh
 
 ' title SUIT update : advanced installers
 

@@ -3,7 +3,7 @@
 
 @startuml
 
-!include atg-spec.pumh
+!include psa-spec.pumh
 
 ' title SUIT update : high-level flow
 

@@ -0,0 +1,12 @@
+.. SPDX-FileCopyrightText: Copyright 2018-2020, 2022-2026 Arm Limited and/or its affiliates
+.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
+
+.. include:: releases
+
+.. include:: references
+
+.. include:: terms
+
+.. include:: intro
+
+.. about::
@@ -0,0 +1,32 @@
+.. SPDX-FileCopyrightText: Copyright 2018-2020, 2022-2026 Arm Limited and/or its affiliates
+.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
+
+.. introduction::
+
+   This document is one of a set of resources that can help organizations develop products that meet the security requirements of GlobalPlatform's PSA Certified evaluation scheme. The PSA Certified scheme provides a framework and methodology that helps silicon manufacturers, system software providers and OEMs to develop more secure products. You can read more about PSA Certified here at :url:`www.psacertified.org`.
+
+   .. rubric:: About the |API|
+
+   The interface described in this document is a PSA Certified API, that provides a verifiable report of the state of the platform. The platform attestation service is provided by the :term:`Platform Root of Trust` and is described in :cite-title:`PSM`.
+
+   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`.
+   *  The associated Application Programming Interface (API). See :secref:`api`.
+
+   The |API| can be used either to directly produce verifiable evidence about the platform state in the context of a challenge-response interaction, or as a way to bootstrap trust in other attestation schemes. The PSA Certified framework provides the generic security features allowing OEM and service providers to integrate various attestation schemes on top of the Platform Root of Trust.
+
+   You can find additional resources relating to the |API| here at :url:`arm-software.github.io/psa-api/attestation`, and find other PSA Certified APIs here at :url:`arm-software.github.io/psa-api`.
+
+.. audience::
+
+   This document is intended primarily for the use of developers of:
+
+   *  Root of Trust Services and security frameworks that implement the |API|.
+   *  Root of Trust Services and Trusted Applications that implement attestation protocols which build upon the initial attestation provided by the |API|.
@@ -0,0 +1,35 @@
+.. SPDX-FileCopyrightText: Copyright 2018-2020, 2022-2025 Arm Limited and/or its affiliates
+.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
+
+.. reference:: PSA STAT
+   :title: PSA Certified Status code API
+   :kind: normative
+   :doc_id: Arm IHI 0097
+   :url: arm-software.github.io/psa-api/status-code
+
+.. reference:: RFC 9783
+   :title: Arm's Platform Security Architecture (PSA) Attestation Token
+   :kind: normative
+   :author: H. Tschofenig, S. Frost, M. Brossard, A. Shaw, and T. Fossati
+   :publication: June 2025
+   :url: tools.ietf.org/html/rfc9783
+
+.. reference:: PSM
+   :title: Platform Security Model
+   :kind: informative
+   :doc_id: JSADEN014
+   :author: PSA Certified
+   :url: psacertified.org/development-resources/building-in-security/threat-models/
+
+.. reference:: C99
+   :title: Programming Languages --- C
+   :kind: informative
+   :doc_id: ISO/IEC 9899:1999
+   :publication: December 1999
+   :url: www.iso.org/standard/29237.html
+
+.. reference:: RFC 2104
+   :title: HMAC: Keyed-Hashing for Message Authentication
+   :kind: informative
+   :publication: February 1997
+   :url: tools.ietf.org/html/rfc2104