Add platform certification documentation
Adds documents about the TS project relationship with PSA Certified
and SystemReady certification programmes.
Signed-off-by: Julian Hall <julian.hall@arm.com>
Change-Id: I7e8294bd3a9a2c8c2b4bad2e2ca8b2f26cb157b7
diff --git a/docs/certification/index.rst b/docs/certification/index.rst
index 067f6e6..58f8f1f 100644
--- a/docs/certification/index.rst
+++ b/docs/certification/index.rst
@@ -1,12 +1,24 @@
Platform Certification
======================
+Various certification programmes exist to help platform vendors produce hardware
+and firmware that meets defined requirements for security and feature compatibility.
+By conforming to a set of testable criteria, platform vendors can make assurances to
+customers about the capabilities and security of their products.
+
+The Trusted Services project is an upstream source for service related components
+that can be integrated into platform firmware. Many of these components are important
+building blocks for meeting certification requirements. Reuse of components by
+downstream platform integration projects will help drive quality and security
+improvements, especially in areas covered by relevant certification programmes.
+
+Currently, the following certification programmes have been adopted by downstream
+platform integration projects:
.. toctree::
:maxdepth: 1
- :caption: Contents:
- psa
- ff-a
+ psa-certified
+ system-ready
--------------
diff --git a/docs/certification/psa-certified.rst b/docs/certification/psa-certified.rst
new file mode 100644
index 0000000..b1bce4c
--- /dev/null
+++ b/docs/certification/psa-certified.rst
@@ -0,0 +1,77 @@
+PSA Certified
+=============
+PSA Certified provides a framework for securing connected devices. Certification demonstrates
+that security best practices have been implemented, based on an independent security assessment.
+For more information, see: `PSA Certified`_.
+
+PSA Certified defines ten security goals that form the foundation for device security. The
+certification process involves an assessment that these security goals have been met. The
+Trusted Services project includes service provider components and reference integrations
+that a system integrator may use as the basis for creating a platform that meets these goals.
+
+PSA Goals
+---------
+The following table lists the ten security goals and how the Trusted Services
+project helps to achieve them:
+
+.. list-table::
+ :widths: 1 2
+ :header-rows: 1
+
+ * - PSA Certified Goal
+ - Trusted Services Contribution
+ * - Unique Identification
+ - | A unique device identity, assigned during manufacture, may be stored securely
+ | using the Secure Storage trusted service with a suitable platform provided backend.
+ * - Security Lifecycle
+ - | The Attestation trusted service provides an extensible framework for adding claims
+ | to a signed attestation report. The security lifecycle state claim is planned to be
+ | added in a future release.
+ * - Attestation
+ - | A remote third-party may obtain a trusted view of the security state of a device by
+ | obtaining a signed attestation token from the Attestation service.
+ * - Secure Boot
+ - | Secure boot relies on a hardware trust anchor such as a public key hash programmed into
+ | an OTP eFuse array. For firmware that uses TF-A, all firmware components are verified
+ | during the early boot phase.
+ * - Secure Update
+ - | Involves cooperation of a trusted service with other firmware components such as the
+ | boot loader.
+ * - Anti-Rollback
+ - | The Secure Storage service provider can be used with arbitrary storage backends, allowing
+ | platform specific storage to be used. Where the necessary hardware is available, roll-back
+ | protected storage can be provided with a suitable backend.
+ * - Isolation
+ - | The trusted services architectural model assumes that service isolation is implemented using
+ | a hardware backed secure processing environment. A secure partition managed by a Secure
+ | Partition Manager is one method for realizing isolation.
+ * - Interaction
+ - | The FF-A specification defines messaging and memory management primitives that enable
+ | secure interaction between partitions. Importantly, the secure partition manager provides
+ | a trusted view of the identity of a message sender, allowing access to be controlled.
+ * - Secure Storage
+ - | The Secure Storage service provider uses a pre-configured storage backend to provide
+ | an object store with suitable security properties. Two deployments of the secure storage
+ | provider (Internal Trusted Storage and Protected Storage) are included with platform
+ | specific storage backends.
+ * - Cryptographic Service
+ - | The Crypto service provider implements a rich set of cryptographic operations using
+ | a protected key store. Key usage is controlled based on the least privileges principle
+ | where usage flags constrain permitted operations.
+
+Conformance Test Support
+------------------------
+To support API level conformance testing, the `PSA Arch Test project`_ provides a rich set
+of test suites that allow service implementations to be tested. To facilitate running of
+PSA functional API tests, the psa-api-test deployment (see: :ref:`Test Executables`) is
+supported which integrates test suites with service clients. This can be used to run tests
+on a platform and collect tests results to provide visibility to an external assessor.
+
+--------------
+
+.. _`PSA Certified`: https://www.psacertified.org/
+.. _`PSA Arch Test project`: https://github.com/ARM-software/psa-arch-tests.git.
+
+*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/certification/psa.rst b/docs/certification/psa.rst
deleted file mode 100644
index c99e1c2..0000000
--- a/docs/certification/psa.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-Platform Security Architecture
-==============================
-
-Trusted Services is the home of the |PSA| reference implementation. The PSA partitions are implemented based on the |FF-A|
-specification.
-
-For background information on |PSA| please visit the `PSA homepage`_. If you are looking for information on certified products
-please visit `www.psacertified.org`_
-
---------------
-
-.. _`PSA homepage`: https://developer.arm.com/architectures/security-architectures/platform-security-architecture
-.. _`www.psacertified.org`: https://www.psacertified.org/certified-products/
-.. _`Hafnium project`: https://www.trustedfirmware.org/projects/hafnium/
-
-*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*
-
-SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/certification/system-ready.rst b/docs/certification/system-ready.rst
new file mode 100644
index 0000000..f41625a
--- /dev/null
+++ b/docs/certification/system-ready.rst
@@ -0,0 +1,27 @@
+SystemReady
+===========
+Arm SystemReady is a compliance certification programme that aims to promote a standardized
+view of a platform and its firmware (see: `Arm SystemReady`_). SystemReady may be applied across
+different classes of device, represented by different SystemReady bands, from resource constrained
+IoT devices through to servers. By standardizing the platform and its firmware, generic operating
+systems can be expected to 'just work' on any compliant device.
+
+SystemReady leverages existing open standards such as UEFI. The Trusted Services project
+includes service level components that enable UEFI SMM services to be realized, backed by PSA
+root-of-trust services. As an alternative to EDK2 StMM, the smm-gateway deployment presents
+UEFI compliant SMM service endpoints, backed by the generic Secure Storage and Crypto services.
+For more information, see:
+
+ * :ref:`Secure Partition Images`
+ * :ref:`UEFI SMM Services`
+
+The UEFI features supported by smm-gateway are designed to meet SystemReady requirements for
+the IR band (embedded IoT).
+
+--------------
+
+.. _`Arm SystemReady`: https://developer.arm.com/architectures/system-architectures/arm-systemready
+
+*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/environments/index.rst b/docs/environments/index.rst
index adb9008..599e88e 100644
--- a/docs/environments/index.rst
+++ b/docs/environments/index.rst
@@ -2,10 +2,10 @@
============
Depending on Arm architecture and SoC capabilities, there may be different options for
-implementing hardware-backed isolation for protecting security sensitive workloads. The
-Trusted Services project decouples service related components from any particular
-environment, enabling services to be deployed in different environments. This section
-provides information about supported secure processing environments.
+implementing hardware-backed isolation for protecting security sensitive workloads and
+their assets. The Trusted Services project decouples service related components from
+any particular environment, enabling services to be deployed in different environments.
+This section provides information about supported secure processing environments.
.. toctree::
:maxdepth: 1
diff --git a/docs/environments/secure-partitions/ff-a/index.rst b/docs/environments/secure-partitions/ff-a/index.rst
index 5c7dc03..e474433 100644
--- a/docs/environments/secure-partitions/ff-a/index.rst
+++ b/docs/environments/secure-partitions/ff-a/index.rst
@@ -1,13 +1,15 @@
Firmware Framework for Armv8-A
==============================
+The |FF-A| specification defines a software architecture that isolates Secure world firmware images from each other. The
+specification defines interfaces that standardize communication between various images. This includes communication
+between images in the Secure world and Normal world.
-|FF-A| is a standard which *"describes interfaces that standardize communication between the various software images. This
-includes communication between images in the Secure world and Normal world."*
+The Trusted Services project includes service providers that may be deployed within FF-A S-EL0 secure partitions. This
+includes service providers that form the security foundations needed for meeting PSA Certified requirements. Other secure
+partitions are available such as the SMM Gateway to provide Secure world backing for UEFI services.
-Trusted Services is the home of the FF-A S-EL0 Secure Partitions implementing PSA functionality. The component :ref:`libsp`
-captures helpful abstractions to allow easy FF-A compliant S-EL0 SP development. S-EL0 SPs are SPMC agonistic and can be used
-with an SPMC running in any higher secure exception level (S-EL1 - S-EL3). Currently the solution is tested with an SPMC
-running at S-SEL1 integrated into OP-TEE OS.
+The component :ref:`libsp` captures helpful abstractions to allow easy FF-A compliant S-EL0 SP development. S-EL0 SPs
+are SPMC agonistic and can be used with an SPMC running in any higher secure exception level (S-EL1 - S-EL3).
--------------
diff --git a/docs/environments/secure-partitions/index.rst b/docs/environments/secure-partitions/index.rst
index d57b103..5680a92 100644
--- a/docs/environments/secure-partitions/index.rst
+++ b/docs/environments/secure-partitions/index.rst
@@ -4,15 +4,15 @@
:term:`Secure Partitions<Secure Partition>` are defined by the :term:`FF-A` standard
Secure partitions are isolated processing environments managed by a Secure Partition Manager (SPM).
-An SPM performs the role of hypervisor for the Arm Secure state and is responsible for managing
+An SPM performs the role of hypervisor for the Arm Secure State and is responsible for managing
SP initialization, memory management and messaging. The Arm Firmware Framework for A-Profile (FF-A)
specification (`FF-A Specification`_) defines the set of firmware features that enable the use of
secure partitions for protecting sensitive workloads.
The Armv8.4 architecture introduces the virtualization extension in the Secure state. For silicon
based on Armv8.4 (or above) that implement the Secure-EL2 extension, the `Hafnium Project`_
-provides a reference SPM implementation. For pre-Arm8.4 silicon, the `OP-TEE Project`_ provides
-an alternative reference SPM implementation.
+provides a reference SPMC implementation. For pre-Arm8.4 silicon, the `OP-TEE Project`_ provides
+an alternative reference SPMC implementation.
Within the Trusted Services, the environments realized by the two reference SPM implementations
are named as follows:
diff --git a/docs/environments/secure-partitions/spm/hafnium/index.rst b/docs/environments/secure-partitions/spm/hafnium/index.rst
index 88cbbcc..e6559c7 100644
--- a/docs/environments/secure-partitions/spm/hafnium/index.rst
+++ b/docs/environments/secure-partitions/spm/hafnium/index.rst
@@ -5,8 +5,15 @@
:maxdepth: 1
:caption: Contents:
+*Note: The Arm Total Compute solution is the current reference for running SPs for meeting
+PSA Certified requirements under Hafnium. The 'hfsp_shim' environment is used for deploying
+service providers under Hafnium. Files related to this environment are still in-flux and
+have not yet been up-streamed to TS.* See `Total Compute`_
+
--------------
+.. _`Total Compute`: https://developer.arm.com/tools-and-software/open-source-software/arm-platforms-software/total-compute-solution
+
*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause