Docs: Restructuring and new layout
This patch implements a set of user-experiences aimed
changes.It modifies the documentation structure and
switches to a more reactive design for the rtd theme.
* The documentation layout has been redesigned to be more
intuitive,easier to maintain and and scale.
* The landing page introduces a new dashboard.
* Introduced dedicated space for release documents, and
changelog has been modified to directly source content
from referenced documents.
* Added quick-link navigation for items that need emphasis.
* Relevant design documents can now be grouped in suf-folders.
* There is dedicated space for custom platform, and third
party tools documents.
* Wildcard and regex matching has been introduced to indexes.
Change-Id: Ib02d17d5d26187d397ba17317788cf2a01401b07
Signed-off-by: Minos Galanakis <minos.galanakis@arm.com>
diff --git a/docs/reference/changelog.rst b/docs/reference/changelog.rst
new file mode 100644
index 0000000..2502261
--- /dev/null
+++ b/docs/reference/changelog.rst
@@ -0,0 +1,12 @@
+##########################
+Change Log & Release Notes
+##########################
+
+This document contains a summary of the new features, changes, fixes and known
+issues in each release of Trusted Firmware-M.
+
+.. include:: ../reference/releases/1.0.rst
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst
new file mode 100644
index 0000000..73e91aa
--- /dev/null
+++ b/docs/reference/glossary.rst
@@ -0,0 +1,165 @@
+###################################
+Glossary of terms and abbreviations
+###################################
+
+************
+TF-M related
+************
+.. glossary::
+
+ Application RoT
+ Application Root of Trust
+ `PSA term`_. The security domain in which additional security services
+ are implemented.
+
+ HAL
+ Hardware Abstraction Layer
+ Interface to abstract hardware-oriented operations and provides a set of
+ APIs to the upper layers.
+
+ RoT
+ Root of Trust
+ `PSA term`_. This is the minimal set of software, hardware and data that
+ is 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.
+
+ RoT Service
+ Root of Trust Service.
+ `PSA term`_. A set of related security operations that are implemented
+ in a Secure Partition.
+
+ NSPE : TF-M related
+ Non Secure Processing Enviroment
+ `PSA term`_. In TF-M this means non secure domain typically running an
+ OS using services provided by TF-M.
+
+ PSA
+ `PSA term`_. Platform Security Architecture.
+
+ PSA-FF
+ `PSA term`_. Platform Security Architecture Firmware Framework.
+
+ PSA-FF-M
+ `PSA term`_. Platform Security Architecture Firmware Framework for M.
+
+ PSA RoT
+ PSA Root of Trust
+ `PSA term`_. This defines the most trusted security domain within a PSA
+ system.
+
+ SFN : TF-M related
+ Secure Function
+ The function entry to a secure service. Multiple SFN per SS are
+ permitted.
+
+ SP : TF-M related
+ Secure Partition
+ A logical container for secure services.
+
+ SPE : TF-M related
+ Secure Processing Environment
+ `PSA term`_. In TF-M this means the secure domain protected by TF-M.
+
+ SPM : TF-M related
+ Secure Partition Manager
+ The TF-M component responsible for enumeration, management and isolation
+ of multiple Secure Partitions within the TEE.
+
+ SPRT : TF-M related
+ Secure Partition Runtime
+ The TF-M component responsible for Secure Partition runtime
+ functionalities.
+
+ SPRTL : TF-M related
+ Secure Partition Runtime Library
+ A library contains the SPRT code and data.
+
+ SS : TF-M related
+ Secure Service
+ A component within the TEE that is atomic from a security/trust point of
+ view, i.e. which is viewed as a single entity from a TF-M point of view.
+
+ PS : TF-M related
+ Protected Storage
+ Protected storage service provided by TF-M.
+
+ ITS : TF-M related
+ Internal Trusted Storage
+ Internal Trusted Storage service provided by TF-M.
+
+ TFM
+ TF-M
+ Trusted Firmware-M
+ Trusted Firmware for M-class
+ ARM TF-M provides a reference implementation of secure world software
+ for ARMv8-M.
+
+ TBSA-M
+ Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M
+ TBSA term. See `Trusted Base System Architecture for Armv6-M, Armv7-M
+ and Armv8-M`_
+
+****************
+SSE-200 platform
+****************
+.. glossary::
+
+ MPC : SSE-200 platform
+ Memory Protection Controller
+ Bus slave-side security controller for memory regions.
+
+ PPC : SSE-200 platform
+ Peripheral Protection Controller
+ Bus slave-side security controller for peripheral access.
+
+************
+v8M-specific
+************
+.. glossary::
+
+ S/NS : v8M-specific
+ Secure/Non-secure
+ The separation provided by TrustZone hardware components in the system.
+
+ SAU : v8M-specific
+ Secure Attribution Unit
+ Hardware component providing isolation between Secure, Non-secure
+ Callable and Non-secure addresses.
+
+***************
+M-class Generic
+***************
+.. glossary::
+
+ AAPCS
+ ARM Architecture Procedure Call Standard
+ The AAPCS defines how subroutines can be separately written, separately
+ compiled, and separately assembled to work together. It describes a
+ contract between a calling routine and a called routine
+
+ MPU : M-class Generic
+ Memory Protection Unit
+ Hardware component providing privilege control.
+
+ SVC
+ SuperVisor Call
+ ARMv7M assembly instruction to call a privileged handler function
+
+*********
+Reference
+*********
+
+| `PSA Firmware_Framework for M`_
+
+.. _PSA Firmware_Framework for M: https://pages.arm.com/psa-resources-ff.html
+
+.. _PSA term: `PSA Firmware_Framework for M`_
+
+| `Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M`_
+
+.. _Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M: https://pages.arm.com/psa-resources-tbsa-m.html
+
+--------------
+
+*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
new file mode 100644
index 0000000..02c1077
--- /dev/null
+++ b/docs/reference/index.rst
@@ -0,0 +1,16 @@
+Reference
+=========
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+ :numbered:
+
+ changelog
+ glossary
+ */index
+ /tools/index
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/releases/1.0.rst b/docs/reference/releases/1.0.rst
new file mode 100644
index 0000000..48903f5
--- /dev/null
+++ b/docs/reference/releases/1.0.rst
@@ -0,0 +1,144 @@
+***********
+Version 1.0
+***********
+
+New Features
+============
+- First major release.
+
+- A Secure FW with support for PSA Level 1 and 2 isolation on Armv8-M
+ using TrustZone extension and Dual-core Cortex-M config.
+
+- The PSA Firmware Framework (PSA FF)/Dev API interfaces exposed by the
+ Secure FW to NS side.
+
+- A secure FW model with NS application example.
+
+- Secure services running within this SPE
+
+ - Secure Storage Service (PSA Protected Storage API - 1.0.0)
+ - Attestation (PSA Attestation API 1.0.0)
+ - Crypto Service (PSA API 1.0-beta-3)
+ - TF-M Audit Log
+ - Platform Service
+ - Internal Trusted Storage (PSA API 1.0.0)
+
+- PSA IPC support
+
+- Support for Armv8-M mainline and baseline and Dual-core Cortex-M systems.
+
+- Testcases running baremetal and with RTX to test the functionality.
+
+- BL2 bootloader for image authentication based on SHA256 and RSA-3072
+ digital signature.
+
+- Build system based on CMake, supporting ARMCLANG and GNU Arm.
+
+- Support for integrated CryptoCell-312 cryptographic hardware accelerator
+ on Musca-B1 platform.
+
+- Meets requirements for Updatable RoT for PSA Functional API, Level 1 and
+ Level 2 Certifications in the feature list.
+
+Platforms supported
+===================
+Current release has been tested on:
+
+ - Cortex M33 based SSE-200 system:
+
+ - `FPGA image loaded on MPS2 board.
+ <https://developer.arm.com/products/system-design/development-boards/cortex-m-prototyping-systems/mps2>`__
+ - `Fast model FVP_MPS2_AEMv8M.
+ <https://developer.arm.com/products/system-design/fixed-virtual-platforms>`__
+ - `Musca-A test chip board.
+ <https://developer.arm.com/products/system-design/development-boards/iot-test-chips-and-boards/musca-a-test-chip-board>`__
+ - `Musca-B1 test chip board.
+ <https://developer.arm.com/products/system-design/development-boards/iot-test-chips-and-boards/musca-b-test-chip-board>`__
+ - `Musca-S1 test chip board.`
+ - `FPGA image loaded on MPS3 board.
+ <https://developer.arm.com/tools-and-software/development-boards/fpga-prototyping-boards/mps3>`__
+ - `Arm DesignStart FPGA on AWS Cloud.
+ <https://developer.arm.com/docs/101965/0102/arm-designstart-fpga-on-cloud-arm-ds-getting-started>`__
+
+ - Cortex M23 based IoT Kit system:
+
+ - `FPGA image loaded on MPS2 board.
+ <https://developer.arm.com/products/system-design/development-boards/cortex-m-prototyping-systems/mps2>`__
+
+Other supported platforms:
+
+ - Dual Core Cortex-M system:
+
+ - `Cypress PSoc64.
+ <https://www.cypress.com/documentation/product-brochures/cypress-psoc-64-secure-microcontrollers>`__
+
+Platform Limitations
+====================
+- The PSA Arch Tests need to be split into several binaries to load onto
+ Musca-A board because of low memory available to the NS world to use.
+
+- The Regression tests on MPS3 AN524 FPGA takes about 40 minutes to complete.
+ This is because AN524 uses QSPI Flash for runtime memory as the RAM is small.
+ The slow speed of QSPI device causes the tests to run slowly.
+
+- Warm reset of eFlash is not permitted on Musca-B1 due to HW bug
+ https://community.arm.com/developer/tools-software/oss-platforms/w/docs/426/musca-b1-warm-reset-of-eflash
+ As TF-M is executed in place from eFlash on Musca-B1, there is good chance
+ that a warm reset of the board will have unexpected (even non-deterministic)
+ effects on code execution. Hence the PSA Arch FF tests, which rely of warm
+ reset of Musca-B1 were executed on RAM FS using "-DSST_RAM_FS=ON" config.
+
+Known issues
+============
+Some open issues exist and will not be fixed in this release.
+
+.. list-table::
+
+ * - AN521 FVP soft reset via AIRCR does not reset MPC / PPC / MPU and will
+ cause boot failure. This is known issue for AN521 FVP. This will cause
+ the system to not boot after a warm reset during PSA Arch FF testing.
+ - Issue : https://developer.trustedfirmware.org/T692
+
+ * - PSA Arch Crypto tests have several known failures.
+ - See this link for detailed analysis of the failures : https://github.com/ARM-software/psa-arch-tests/blob/master/api-tests/docs/test_failure_analysis.md
+
+ * - There are 2 additional failures for PSA-Arch Crypto tests with CC-312
+ other than the known failures. This is due to limitation of CC-312
+ implementation as it does not support MD_NONE hashing mode causing the
+ additional failures.
+ - The issue details are captured here : https://developer.trustedfirmware.org/T691
+
+ * - PS test case 2002 and 1002 does not fail on Musca-B1 flash when
+ run for second time without erasing flash. The WRITE_ONCE assets created
+ by SST module should not be updatable but after reboot, the update seems
+ to happen and is not expected. This issue will happen on any platform
+ using persistent storage for SST.
+ - Issue created : https://developer.trustedfirmware.org/T693
+
+ * - Boot up fails if there is unexpected data in flash on Musca-A. The boot
+ is successful and the tests pass if all the associated (SST/ITS/NV
+ Counter) flash areas are erased.
+ - Issue created : https://developer.trustedfirmware.org/T694
+
+ * - If the flash is not erased, boot fails on Musca-B1 when SST
+ is using flash for Minsizerel config.
+ - Issue created : https://developer.trustedfirmware.org/T695
+
+ * - When SST/ITS are using Flash on Musca-B1, PSA Arch FF test fails due
+ to known warm reset limitation in the platform. But after the failure,
+ Musca-B1 boot fails to boot. This could be related to general issues of
+ the SST module when Flash data is inconsistent.
+ - Issue created : https://developer.trustedfirmware.org/T696
+
+ * - The eflash driver on Musca-B1 can return random failures hence
+ triggering random failures during PSA Arch ITS and PSA Arch PS tests.
+ This happens when ITS/SST is configured to use flash.
+ - Issue created : https://developer.trustedfirmware.org/T697
+
+ * - Release build of PSA Arch Crypto tests have a different number of tests
+ when built for AN521 FVP. This is an issue in the PSA Arch Crypto tests.
+ - Issue created for PSA Arch Tests project : https://github.com/ARM-software/psa-arch-tests/issues/169
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/releases/index.rst b/docs/reference/releases/index.rst
new file mode 100644
index 0000000..dc8aecb
--- /dev/null
+++ b/docs/reference/releases/index.rst
@@ -0,0 +1,12 @@
+Releases
+========
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/core_test_services_integration_guide.rst b/docs/reference/services/core_test_services_integration_guide.rst
new file mode 100644
index 0000000..ee0b3fa
--- /dev/null
+++ b/docs/reference/services/core_test_services_integration_guide.rst
@@ -0,0 +1,118 @@
+###########################
+Core Test integration guide
+###########################
+
+************
+Introduction
+************
+
+The core test suites test some of the features of the TF-M core. There are
+multiple services that are used by the core test suites. The services are
+defined in the ``test/test_services`` folder.
+
+Currently there are two test suites, *interactive* and *positive*. The positive
+test suite can be run, by building using ``ConfigCoreTest.cmake`` as cmake
+config file. The interactive test suite is only available by manually setting
+CORE_TEST_INTERACTIVE to ON in the following block in ``CommonConfig.cmake``:
+
+.. code-block:: cmake
+
+ if (CORE_TEST)
+ set(CORE_TEST_POSITIVE ON)
+ set(CORE_TEST_INTERACTIVE OFF)
+ endif()
+
+A platform can skip Core Test by setting ``CORE_TEST`` to ``OFF`` in its cmake
+configuration file, even though ``CORE_TEST`` is enabled by default in current
+configuration.
+
+After making the change, the tests can be run by building using
+``ConfigCoreTest.cmake`` as cmake config file.
+
+**************************
+Platform specific features
+**************************
+For certain test cases the core test services rely on platform functionality.
+The required features are:
+
+- Access to LEDs or registers that can be used as scratch registers for
+ read/write access tests
+- Get a button state that can be pressed by the user to simulate a secure
+ service with an arbitrarily long blocking execution.
+- Access to a timer that is able to interrupt the core running TF-M.
+
+The functionality that have to be implemented by the platform is described in
+``platform/include/tfm_plat_test.h``. For details see the documentation of the
+functions.
+
+It is the responsibility of the platform implementation to ensure that the
+resources needed for the core test services are properly linked to the service.
+This can be achieved by using the
+``TFM_LINK_SET_<memory_type>_IN_PARTITION_SECTION(...)`` macros in
+``platform/include/tfm_plat_defs.h``. More details regarding the usage of these
+macros are available in the header file.
+
+It is possible that a platform implementation mocks the implementation of some
+or all of the functions, by returning the values expected by the test cases,
+without actually executing the action expected by the test. A platform can also
+set the corresponding control flag to ``OFF`` to skip a test case. For example,
+A platform can skip peripheral access test case by setting
+``TFM_ENABLE_PERIPH_ACCESS_TEST`` to ``OFF`` in its cmake configuration file.
+
+******************
+IRQ handling tests
+******************
+
+The IRQ handling test currently tests the following scenarios:
+
+- NS code execution is interrupted by a secure IRQ (``IRQ_TEST_SCENARIO_1``)
+- S code execution is interrupted by a secure IRQ, The handler is not the
+ interrupted service (``IRQ_TEST_SCENARIO_2``)
+- S code execution is interrupted by a secure IRQ, The handler is the
+ interrupted service (``IRQ_TEST_SCENARIO_3``)
+- S code waits for an interrupt (calling ``psa_wait()``), the handler is in
+ the service that is waiting, ``psa_eoi()`` is called after ``psa_wait()``
+ returns (``IRQ_TEST_SCENARIO_4``)
+- S code waits for a non-secure interrupt to be triggered
+ (``IRQ_TEST_SCENARIO_5``)
+
+The following test services participate in the test execution:
+
+- ``TFM_IRQ_TEST_1`` has the role of the interrupted partition with the IRQ
+ handler
+- ``TFM_SP_CORE_TEST_2`` has the role of the interrupted partition without the
+ IRQ handler
+
+All the test executions are initiated from the NS positive test suite. For each
+scenario the non-secure testcase calls the following secure functions in order:
+
+#. prepare_test_scenario for ``TFM_IRQ_TEST_1``
+#. prepare_test_scenario for ``TFM_SP_CORE_TEST_2``
+#. prepare_test_scenario_ns
+#. execute_test_scenario for ``TFM_IRQ_TEST_1``
+#. execute_test_scenario for ``TFM_SP_CORE_TEST_2``
+#. execute_test_scenario_ns
+
+For scenarios 1-4 during the steps above the ``TFM_IRQ_TEST_1`` sets up a timer
+with a convenient init value, and depending on the scenario, one of the
+services, or the NS code enters a busy wait waiting for the timer interrupt to
+be raised. In case of ``IRQ_TEST_SCENARIO_3``, when ``PSA API`` is used, the
+execute_test_scenario request of the NS code is only replied when the IRQ is
+handled, so no explicit busy wait is required. In all the other cases, handling
+of the irq is signalled to the waiting party by setting a variable in a
+non-secure memory location.
+
+For scenario 5 a Non-secure timer is set up and ``TFM_SP_CORE_TEST_2`` waits for
+it to be triggered
+
+A platform can skip IRQ handling test by setting ``TFM_ENABLE_IRQ_TEST`` to
+``OFF`` in its cmake configuration file.
+
+The irq test services also demonstrate how to use the ``IRQ_TEST_TOOL_*``
+(``IRQ_TEST_TOOL_CODE_LOCATION``) macros. These macros should be defined to
+substitute empty string, and are used by the ``tools\generate_breakpoints.py``
+script in the `IRQ testing tool <https://git.trustedfirmware.org/TF-M/tf-m-tools.git/tree/irq_test_tool>`_.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/index.rst b/docs/reference/services/index.rst
new file mode 100644
index 0000000..30a2a8a
--- /dev/null
+++ b/docs/reference/services/index.rst
@@ -0,0 +1,12 @@
+Services
+=========
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/tfm_attestation_integration_guide.rst b/docs/reference/services/tfm_attestation_integration_guide.rst
new file mode 100644
index 0000000..83e6703
--- /dev/null
+++ b/docs/reference/services/tfm_attestation_integration_guide.rst
@@ -0,0 +1,515 @@
+#############################################
+Initial Attestation Service Integration Guide
+#############################################
+
+************
+Introduction
+************
+TF-M Initial Attestation Service allows the application to prove the device
+identity during an authentication process to a verification entity. The initial
+attestation service can create a token on request, which contains a fix set of
+device specific data. Device must contain an attestation key pair, which is
+unique per device. The token is signed with the private part of attestation key
+pair. The public part of the key pair is known by the verification entity. The
+public key is used to verify the token authenticity. The data items in the token
+used to verify the device integrity and assess its trustworthiness. Attestation
+key provisioning is out of scope for the attestation service and is expected to
+take part during manufacturing of the device.
+
+***************************************
+Claims in the initial attestation token
+***************************************
+The initial attestation token is formed of claims. A claim is a data item,
+which is represented in a key - value structure. The following fixed set of
+claims are included in the token:
+
+ - **Auth challenge**: Input object from caller. Can be a single nonce from
+ server or hash of nonce and attested data. It is intended to provide
+ freshness to report and the caller has responsibility to arrange
+ this. Allowed length: 32, 48, 64 bytes. The claim is modeled to be
+ eventually represented by the EAT standard claim nonce. Until such a
+ time as that standard exists, the claim will be represented by a custom
+ claim. Value is encoded as byte string.
+
+ - **Instance ID**: It represents the unique identifier of the instance. In
+ the PSA definition it is a hash of the public attestation key of the
+ instance. The claim is modeled to be eventually represented by the EAT
+ standard claim UEID of type GUID. Until such a time as that standard
+ exists, the claim will be represented by a custom claim Value is encoded
+ as byte string.
+
+ - **Verification service indicator**: Optional, recommended claim. It
+ is 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. The claim is modelled to
+ be eventually represented by the EAT standard claim origination. Until
+ such a time as that standard exists, the claim will be represented by
+ a custom claim. Value is encoded as text string.
+
+ - **Profile definition**: Optional, recommended claim. It contains the
+ name of a document that describes the 'profile' of the token, being
+ a full description of the claims, their usage, verification and token
+ signing. The document name may include versioning. Custom claim with a
+ value encoded as text string.
+
+ - **Implementation ID**: Uniquely identifies the underlying immutable PSA
+ RoT. A verification service can use this claim to locate the details of
+ the verification process. Such details include the implementation’s origin
+ and associated certification state. Custom claim with a value encoded as
+ byte string.
+
+ - **Client ID**: The partition ID of that secure partition or non-secure
+ thread who called the initial attestation API. Custom claim with a value
+ encoded as a `signed` integer. Negative number represents non-secure
+ caller, positive numbers represents secure callers, zero is invalid.
+
+ - **Security lifecycle**: It represents the current lifecycle state of
+ the instance. Custom claim with a value encoded as an integer.
+
+ - **Hardware version**: Optional claim. Globally unique number in EAN-13
+ format identifying the GDSII that went to fabrication, HW and ROM. It can
+ be used to reference the security level of the PSA-ROT via a certification
+ website. Custom claim with a value is encoded as text string.
+
+ - **Boot seed**: It represents a random value created at system boot
+ time that will allow differentiation of reports from different system
+ sessions. The size is 32 bytes. Custom claim with a value is encoded as
+ byte string.
+
+ - **Software components**: Optional, but required in order to be compliant
+ with the PSA-SM. It represents the software state of the system. The value
+ of the claim is an array of CBOR map entries, with one entry per software
+ component within the device. Each map contains multiple claims that
+ describe evidence about the details of the software component.
+
+ - **No software measurements**: Optional, but required if no software
+ component claims are made. In the event that the implementation does not
+ contain any software measurements then it is mandatory to include this
+ claim to indicate this is a deliberate state. Custom claim with a value
+ encoded as an unsigned integer set to 1.
+
+Each software component claim can include the following properties. Any property
+that is not optional must be included:
+
+ - **Measurement type**: Optional claim. It represents the role of the
+ software component. Value is encoded as short(!) text string.
+
+ - **Measurement value**: It represents a hash of the invariant software
+ component in memory at start-up time. The value must be a cryptographic
+ hash of 256 bits or stronger. Value is encoded as byte string.
+
+ - **Version**: Optional claim. It represents the issued software
+ version. Value is encoded as text string.
+
+ - **Signer ID**: Optional claim, but required in order to be compliant with
+ the PSA-SM. It represents the hash of a signing authority public key.
+ Value is encoded as byte string.
+
+ - **Measurement description**: Optional claim. It represents the way in
+ which the measurement value of the software component is computed. Value
+ is encoded as text string containing an abbreviated description (name)
+ of the measurement method.
+
+*********************************************
+Initial attestation token (IAT) data encoding
+*********************************************
+The initial attestation token is planned to be aligned with future version of
+`Entity Attestation Token <https://tools.ietf.org/html/draft-mandyam-eat-01>`__
+format. The token is encoded according to the
+`CBOR <https://tools.ietf.org/html/rfc7049>`__ format and signed according to
+`COSE <https://tools.ietf.org/html/rfc8152>`__ standard.
+
+**************
+Code structure
+**************
+The PSA interface for the Initial Attestation Service is located in
+``interface/include``. The only header to be included by applications that want
+to use functions from the PSA API is ``psa/initial_attestation.h``.
+
+The TF-M Initial Attestation Service source files are located in
+``secure_fw/partitions/initial_attestation``.
+The CBOR library is located in ``lib/ext/qcbor`` folder.
+
+Service source files
+====================
+- CBOR library
+ - ``lib/ext/qcbor`` This library is used to create a proper CBOR token.
+ It can be used on 32-bit and 64-bit machines. It was designed to suite
+ constrained devices with low memory usage and without dynamic memory
+ allocation.
+ It is a fork of this external `QCBOR library <https://github.com/laurencelundblade/QCBOR>`__.
+ - ``lib/ext/qcbor/inc/qcbor.h``: Public API documentation of CBOR
+ library.
+
+- COSE library:
+ - ``lib/t_cose``: This library is used to sign a CBOR token and create
+ the COSE header and signature around the initial attestation token. Only
+ a subset of the `COSE <https://tools.ietf.org/html/rfc8152>`__ standard
+ is implemented. Only the cose_sign1 signature schema is supported.
+ - ``lib/t_cose/src/t_cose_crypto.h``: Expose an API to bind ``t_cose``
+ library with available crypto library in the device.
+ - ``lib/t_cose/src/t_cose_psa_crypto.c``: Implements the exposed API
+ and ports ``t_cose`` to the PSA Crypto API.
+- Initial Attestation Service:
+ - ``attestation_core.c`` : Implements core functionalities such as
+ implementation of APIs, retrieval of claims and token creation.
+ - ``attest_token.c``: Implements the token creation function such as
+ start and finish token creation and adding claims to the token.
+ - ``attestation_key.c``: Get the attestation key from platform layer
+ and register it to the TF-M Crypto service for further usage.
+ - ``tfm_attestation.c``: Implements the SPM abstraction layer, and bind
+ the attestation service to the SPM implementation in TF-M project.
+ - ``tfm_attestation_secure_api.c``: Implements the secure API layer to
+ allow other services in the secure domain to request functionalities
+ from the attestation service using the PSA API interface.
+ - ``tfm_attestation_req_mngr.c``: Includes the initialization entry of
+ attestation service and handles attestation service requests in IPC
+ model.
+
+Service interface definitions
+=============================
+- **Boot loader interface**: The attestation service might include data
+ in the token about the distinct software components in the device. This data
+ is provided by the boot loader and must be encoded in the TLV format,
+ definition is described below in the boot loader interface paragraph. Possible
+ claims in the boot status are describe above in the software components
+ paragraph.
+- **Hardware abstraction layer**:
+ - Headers are located in ``platform/include`` folder.
+ - ``tfm_attest_hal.h``: Expose an API to get the following claims:
+ security lifecycle, verification service indicator, profile definition.
+ - ``tfm_plat_boot_seed.h``: Expose an API to get the boot seed claim.
+ - ``tfm_plat_device_id.h``: Expose an API to get the following claims:
+ implementation ID, hardware version, instance ID.
+- **SPM interface**:
+ - ``attestation.h``: Expose an API to bind attestation service to an SPM
+ implementation.
+- **PSA interface**:
+ - ``psa/initial_attestation.h``: Public API definition of initial
+ attestation service.
+- **Crypto interface**:
+ - ``t_cose_crypto.h``: Expose an API to bind the ``t_cose`` implementation
+ to any cryptographic library.
+ - ``tfm_plat_crypto_keys.h``: Expose an API to get the attestation key from
+ platform layer.
+
+PSA interface
+=============
+The TF-M Initial Attestation Service exposes the following PSA
+interface:
+
+.. code-block:: c
+
+ psa_status_t
+ psa_initial_attest_get_token(const uint8_t *auth_challenge,
+ size_t challenge_size,
+ uint8_t *token_buf,
+ size_t token_buf_size,
+ size_t *token_size);
+
+ psa_status_t
+ psa_initial_attest_get_token_size(size_t challenge_size,
+ size_t *token_size);
+
+ psa_status_t
+ tfm_initial_attest_get_public_key(uint8_t *public_key,
+ size_t public_key_buf_size,
+ size_t *public_key_len,
+ psa_ecc_curve_t *elliptic_curve_type);
+
+The caller must allocate a large enough buffer, where the token is going to be
+created by Initial Attestation Service. The size of the created token is highly
+dependent on the number of software components in the system and the provided
+attributes of these. The ``psa_initial_attest_get_token_size()`` function can be
+called to get the exact size of the created token.
+
+System integrators might need to port these interfaces to a custom secure
+partition manager implementation (SPM). Implementations in TF-M project can be
+found here:
+
+- ``interface/src/tfm_initial_attestation_func_api.c``: non-secure interface
+ implementation for library model
+- ``interface/src/tfm_initial_attestation_ipc_api.c``: non-secure interface
+ implementation for IPC model
+- ``secure_fw/partitions/initial_attestation/tfm_attestation_secure_api.c``:
+ secure interface implementation
+
+Secure Partition Manager (SPM) interface
+========================================
+The Initial Attestation Service defines the following interface towards the
+secure partition manager (SPM). System integrators **must** port this interface
+according to their SPM implementation.
+
+.. code:: c
+
+ enum psa_attest_err_t
+ attest_get_boot_data(uint8_t major_type, void *ptr, uint32_t len);
+
+ enum psa_attest_err_t
+ attest_get_caller_client_id(int32_t *caller_id);
+
+- ``attest_get_boot_data()``: Service can retrieve the relevant data from shared
+ memory area between boot loader and runtime software. It might be the case
+ that only SPM has direct access to the shared memory area, therefore this
+ function can be used to copy the service related data from shared memory to
+ a local memory buffer. In TF-M implementation this function must be called
+ during service initialization phase, because the shared memory region is
+ deliberately overlapping with secure main stack to spare some memory and reuse
+ this area during execution. If boot loader is not available in the system to
+ provide attributes of software components then this function must be
+ implemented in a way that just initialize service's memory buffer to:
+
+ .. code-block:: c
+
+ struct shared_data_tlv_header *tlv_header = (struct shared_data_tlv_header *)ptr;
+ tlv_header->tlv_magic = 2016;
+ tlv_header->tlv_tot_len = sizeof(struct shared_data_tlv_header *tlv_header);
+
+- ``attest_get_caller_client_id()``: Retrieves the ID of the caller thread.
+- ``tfm_client.h``: Service relies on the following external definitions, which
+ must be present or included in this header file:
+
+ .. code-block:: c
+
+ typedef struct psa_invec {
+ const void *base;
+ size_t len;
+ } psa_invec;
+
+ typedef struct psa_outvec {
+ void *base;
+ size_t len;
+ } psa_outvec;
+
+Hardware abstraction layer
+==========================
+The following API definitions are intended to retrieve the platform specific
+claims. System integrators **must** implement these interface according to their
+SoC and software design. Detailed definition of the claims are above
+in the claims in the initial attestation token paragraph.
+
+- ``tfm_attest_hal_get_security_lifecycle()``: Get the security lifecycle of the
+ device.
+- ``tfm_attest_hal_get_verification_service()``: Get the verification
+ service indicator for initial attestation.
+- ``tfm_attest_hal_get_profile_definition()``: Get the name of the profile
+ definition document for initial attestation.
+- ``tfm_plat_get_boot_seed()``: Get the boot seed, which is a constant random
+ number during a boot cycle.
+- ``tfm_plat_get_implementation_id``: Get the implementation ID of the
+ device.
+- ``tfm_plat_get_hw_version``: Get the hardware version of the device.
+
+Boot loader interface
+=====================
+It is **recommended** to have a secure boot loader in the boot chain, which is
+capable of measuring the runtime firmware components (calculates the hash value
+of firmware images) and provide other attributes of these (version, type, etc).
+If the used boot loader is not capable of sharing these information with the
+runtime software then the ``BOOT_DATA_AVAILABLE`` compiler flag **must** be
+set to OFF (see `Related compile time options`_).
+
+The shared data between boot loader and runtime software is TLV encoded. The
+definition of TLV structure is described in ``bl2/include/tfm_boot_status.h``.
+The shared data is stored in a well known location in secure internal memory
+and this is a contract between boot loader and runtime SW.
+
+The structure of shared data must be the following:
+
+- At the beginning there must be a header: ``struct shared_data_tlv_header``
+ This contains a magic number and a size field which covers the entire size
+ of the shared data area including this header.
+
+ .. code-block:: c
+
+ struct shared_data_tlv_header {
+ uint16_t tlv_magic;
+ uint16_t tlv_tot_len;
+ };
+
+- After the header there come the entries which are composed from an
+ entry header structure: ``struct shared_data_tlv_entry`` and the data. In
+ the entry header is a type field ``tlv_type`` which identify the consumer of
+ the entry in the runtime software and specify the subtype of that data item.
+ There is a size field ``tlv_len`` which covers the size of the entry header
+ and the data. After this structure comes the actual data.
+
+ .. code-block:: c
+
+ struct shared_data_tlv_entry {
+ uint16_t tlv_type;
+ uint16_t tlv_len;
+ };
+
+- Arbitrary number and size of data entry can be in the shared memory
+ area.
+
+The figure below gives of overview about the ``tlv_type`` field in the entry
+header. The ``tlv_type`` always composed from a major and minorbnumber. Major
+number identifies the addressee in runtime software, which the databentry is
+sent to. Minor number used to encode more info about the data entry. The actual
+definition of minor number could change per major number. In case of boot
+status data, which is going to be processed by initial attestation service
+the minor number is split further to two part: ``sw_module`` and ``claim``. The
+``sw_module`` identifies the SW component in the system which the data item
+belongs to and the ``claim`` part identifies the exact type of the data.
+
+``tlv_type`` description::
+
+ |------------------------------------------------ |
+ | tlv_type (16 bits) |
+ |-------------------------------------------------|
+ | tlv_major(4 bits) | tlv_minor(12 bits) |
+ |-------------------------------------------------|
+ | MAJOR_IAS | sw_module(6 bits) | claim(6 bits) |
+ |-------------------------------------------------|
+ | MAJOR_CORE | TBD |
+ |-------------------------------------------------|
+
+Overall structure of shared data::
+
+ ---------------------------------------------------------------
+ | Magic number(uint16_t) | Shared data total length(uint16_t) |
+ ---------------------------------------------------------------
+ | Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) |
+ ---------------------------------------------------------------
+ | Raw data |
+ ---------------------------------------------------------------
+ | . |
+ | . |
+ | . |
+ ---------------------------------------------------------------
+ | Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) |
+ ---------------------------------------------------------------
+ | Raw data |
+ ---------------------------------------------------------------
+
+Crypto interface
+================
+Device **must** contain an asymmetric key pair. The private part of it is used
+to sign the initial attestation token. Current implementation supports only the
+ECDSA P256 signature over SHA256. The public part of the key pair is used to
+create the key identifier (kid) in the unprotected part of the COSE header. The
+kid is used by verification entity to look up the corresponding public key to
+verify the signature in the token. The `t_cose` part of the initial attestation
+service implements the signature generation and kid creation. But the actual
+calculation of token's hash and signature is done by the Crypto service in the
+device. System integrators might need to re-implement the following functions
+if they want to use initial attestation service with a different cryptographic
+library than Crypto service:
+
+- ``t_cose_crypto_pub_key_sign()``: Calculates the signature over a hash value.
+- ``t_cose_crypto_get_ec_pub_key()``: Get the public key to create the key
+ identifier.
+- ``t_cose_crypto_hash_start()``: Start a multipart hash operation.
+- ``t_cose_crypto_hash_update()``: Add a message fragment to a multipart hash
+ operation.
+- ``t_cose_crypto_hash_finish()``:Finish the calculation of the hash of a
+ message.
+
+Interface needed by verification code:
+
+- ``t_cose_crypto_pub_key_verify()``: Verify the signature over a hash value.
+
+Key handling
+------------
+The provisioning of the initial attestation key is out of scope of the service
+and this document. It is assumed that device maker provisions the unique
+asymmetric key pair during the manufacturing process. The following API is
+defined to retrieve the attestation key pair from platform layer. Software
+integrators **must** port this interface according to their SoC design and make
+sure that key pair is available by Crypto service:
+
+- ``tfm_plat_get_initial_attest_key()``: Retrieve the initial attestation key
+ pair from platform layer.
+
+In TF-M project the attestation key is retrieved by initial attestation service.
+The key is registered and unregistered to the Crypto service by attestation
+service with ``psa_import_key()`` and ``psa_destroy_key()`` API calls for
+further usage. See in ``attestation_key.c``. In other implementation if the
+attestation key is directly retrieved by the Crypto service then this key
+handling is not necessary.
+
+Initial Attestation Service compile time options
+================================================
+There is a defined set of flags that can be used to compile in/out certain
+service features. The ``CommonConfig.cmake`` file sets the default values of
+those flags. The list of flags are:
+
+- ``ATTEST_INCLUDE_OPTIONAL_CLAIMS``: Include also the optional claims to the
+ attestation token. Default value: ON.
+- ``ATTEST_INCLUDE_TEST_CODE``: Test code is removed from COSE library and from
+ attestation test suite if it is OFF. Its default value depends on the build
+ type. It is ON if build type is ``Debug``, otherwise OFF (different kinds
+ of ``Release`` builds).
+- ``ATTEST_INCLUDE_COSE_KEY_ID``: COSE key-id is an optional field in the COSE
+ unprotected header. Key-id is calculated and added to the COSE header based
+ on the value of this flag. Default value: OFF.
+- ``ATTEST_CLAIM_VALUE_CHECK``: Check attestation claims against hard-coded
+ values found in ``platform/ext/common/template/attest_hal.c``. Default value
+ is OFF. Set to ON in a platform's CMake file if the attest HAL is not yet
+ properly ported to it.
+
+Related compile time options
+----------------------------
+- ``BOOT_DATA_AVAILABLE``: The boot data is expected to be present in the shared
+ data area between the boot loader and the runtime firmware when it's ON.
+ Otherwise, when it's OFF does not check the content of the shared data area.
+ Also assume that the TLV header is present and valid (the magic number is
+ correct) and there are no other data entries. Its default value depends on
+ the BL2 flag.
+
+************
+Verification
+************
+The initial attestation token is verified by the attestation test suite in
+``test/suites/attestation``. The test suite is responsible for verifying the
+token signature and parsing the token to verify its encoding and the presence of
+the mandatory claims. This test suite can be executed on the device. It is part
+of the regression test suite. When the user builds TF-M with any of the
+``ConfigRegression*.cmake`` configurations then this test is executed
+automatically. The test suite is configurable in the
+``test/suites/attestation/attest_token_test_values.h`` header file. In this file
+there are two attributes for each claim which are configurable (more details
+in the header file):
+
+ - Requirements of presence: optional or mandatory
+ - Expected value: Value check can be disabled or expected value can be provided
+ here.
+
+There is another possibility to verify the attestation token. This addresses
+the off-device testing when the token is already retrieved from the device and
+verification is done on the requester side. There is a Python script for this
+purpose in ``tools/iat-verifier``. It does the same checking as the
+attestation test suite. The following steps describe how to simulate an
+off-device token verification on a host computer. It is described how to
+retrieve an initial attestation token when TF-M code is executed on FVP
+and how to use the iat_verifier script to check the token. This example assumes
+that user has license for DS-5 and FVP models:
+
+ - Build TF-M with any of the ``ConfigRegression*.cmake`` build configurations
+ for MPS2 AN521 platform. More info in
+ :doc:`tfm_build_instruction </docs/getting_started/tfm_build_instruction>`.
+ - Lunch FVP model in DS-5. More info in
+ :doc:`tfm_user_guide </docs/getting_started/tfm_user_guide>`.
+ - Set a breakpoint in ``test/suites/attestation/attest_token_test.c``
+ in ``decode_test_internal(..)`` after the ``token_main_alt(..)`` returned,
+ i.e. on line 859. Execute the code in the model until the breakpoint hits
+ second time. At this point the console prints the following message:
+ ``ECDSA signature test of attest token``.
+ - At this point the token resides in the model memory and can be dumped to host
+ computer.
+ - The ADDRESS and SIZE attributes of the initial attestation token is stored in
+ the ``completed_token`` local variable. Their value can be extracted in the
+ ``(x)=Variables`` debug window.
+ - Apply this command in the ``Commands`` debug window to dump the token in
+ binary format to the host computer:
+ ``dump memory <PATH>/iat_01.cbor <ADDRESS> +<SIZE>``
+ - Execute this command on the host computer to verify the token:
+ ``check_iat -p -K -k platform/ext/common/template/tfm_initial_attestation_key.pem <PATH>/iat_01.cbor``
+ - Documentation of the iat-verifier can be found
+ :doc:`here </tools/iat-verifier/README>`.
+
+--------------
+
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/tfm_audit_integration_guide.rst b/docs/reference/services/tfm_audit_integration_guide.rst
new file mode 100644
index 0000000..248f0f9
--- /dev/null
+++ b/docs/reference/services/tfm_audit_integration_guide.rst
@@ -0,0 +1,134 @@
+#######################################
+Audit Logging Service Integration Guide
+#######################################
+
+************
+Introduction
+************
+TF-M Audit logging service allows secure services in the system to log critical
+system events and information that have security implications. This is required
+to post analyse the system behaviour, system events and triage system issues
+offline. This offers a mitigation against the repudiation threat.
+
+The types of information that can be logged are the ID of the entity that
+originated a secure service request, or the relevant output or data
+associated to the authentication mechanism that the requesting service
+has performed on the entity that originated the request. The possible types of
+information that can be logged can be easily extended to accommodate various
+requirements from other secure services.
+
+***************************
+Current service limitations
+***************************
+
+- **Policy manager** - Currently, there is no policy manager implemented, which
+ means that there are no restrictions on the entities which can add or remove
+ items from the log. Also, the item replacement in the log is just replacing
+ older elements first.
+
+- **Encryption** - Support for encryption and authentication is not available
+ yet.
+
+- **Permanent storage** - Currently the Audit Logging service supports only a
+ RAM based storage of the log, permanent storage is not supported yet.
+
+
+**************
+Code structure
+**************
+The PSA interfaces for the Audit logging service are located in
+``interface/include``.
+
+The TF-M Audit logging service source files are located in
+``secure_fw/partitions/audit_logging``.
+
+PSA interfaces
+==============
+The TF-M Audit logging service exposes the following PSA interfaces:
+
+.. code-block:: c
+
+ enum psa_audit_err psa_audit_retrieve_record(const uint32_t record_index,
+ const uint32_t buffer_size, const uint8_t *token, const uint32_t token_size,
+ uint8_t *buffer, uint32_t *record_size);
+
+ enum psa_audit_err psa_audit_get_info(uint32_t *num_records, uint32_t
+ *size);
+
+ enum psa_audit_err psa_audit_get_record_info(const uint32_t record_index,
+ uint32_t *size);
+
+ enum psa_audit_err psa_audit_delete_record(const uint32_t record_index,
+ const uint8_t *token, const uint32_t token_size);
+
+The TF-M Audit logging service exposes an additional PSA interface which can
+only be called from secure services:
+
+.. code-block:: c
+
+ enum psa_audit_err psa_audit_add_record(const struct psa_audit_record
+ *record);
+
+Service source files
+====================
+
+- ``audit_core.c`` : This file implements core functionalities such as log
+ management, record addition and deletion and extraction of record information.
+- ``audit_wrappers.c`` : This file implements TF-M compatible wrappers in case
+ they are needed by the functions exported by the core.
+
+*********************************
+Audit logging service integration
+*********************************
+In this section, a brief description of each field of a log record is given,
+with an example on how to perform a logging request from a secure service.
+The secure service that requests the addition of a record to the log has to
+provide data as described by the ``psa_audit_record`` type, defined in
+``interface\include\psa_audit_defs.h``:
+
+.. code-block:: c
+
+ /*!
+ * \struct psa_audit_record
+ *
+ * \brief This structure contains the record that is added to the audit log
+ * by the requesting secure service
+ */
+ struct psa_audit_record {
+ uint32_t size; /*!< Size in bytes of the id and payload fields */
+ uint32_t id; /*!< ID of the record */
+ uint8_t payload[]; /*!< Flexible array member for payload */
+ };
+
+Each field is described as follows:
+
+- ``size`` - This is the size, in bytes, of the ``id`` and ``payload[]`` fields
+ that follow. Given that the ``payload[]`` field is optional, in the current
+ implementation the minimum value to be provided in ``size`` is 4 bytes;
+- ``id`` - This field is meant to be used to store an ID of the log record from
+ the requesting service
+- ``payload[]`` - The payload is an optional content which can be made
+ of one or more Type-Length-Value entries as described by the following type:
+
+.. code-block:: c
+
+ /*!
+ * \struct audit_tlv_entry
+ *
+ * \brief TLV entry structure with a flexible
+ * array member
+ */
+ struct audit_tlv_entry {
+ enum audit_tlv_type type;
+ uint32_t length;
+ uint8_t value[];
+ };
+
+The possible TLV types described by ``enum audit_tlv_type`` can be extended by
+system integrators modifying ``audit_core.h`` as needed. A logging request is
+performed by a secure service which calls the
+Secure-only API function ``psa_audit_add_record()``.
+
+--------------
+
+*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/tfm_crypto_integration_guide.rst b/docs/reference/services/tfm_crypto_integration_guide.rst
new file mode 100644
index 0000000..4065930
--- /dev/null
+++ b/docs/reference/services/tfm_crypto_integration_guide.rst
@@ -0,0 +1,93 @@
+################################
+Crypto Service Integration Guide
+################################
+
+************
+Introduction
+************
+TF-M Crypto service allows application to use cryptography primitives such as
+symmetric and asymmetric ciphers, hash, message authentication codes (MACs) and
+authenticated encryption with associated data (AEAD).
+
+**************
+Code structure
+**************
+The PSA interfaces for the Crypto service are located in ``interface/include``.
+The only header to be included by applications that want to use functions from
+the PSA API is ``psa/crypto.h``.
+The TF-M Crypto service source files are located in
+``secure_fw/partitions/crypto``.
+
+PSA interfaces
+==============
+The TF-M Crypto service exposes the PSA interfaces detailed in the header
+``psa/crypto.h``. This header, in turn, includes several other headers which
+are not meant to be included directly by user applications. For a detailed
+description of the PSA API interface, please refer to the comments in the
+``psa/crypto.h`` header itself.
+
+Service source files
+====================
+- ``crypto_cipher.c`` : This module handles requests for symmetric cipher
+ operations
+- ``crypto_hash.c`` : This module handles requests for hashing operations
+- ``crypto_mac.c`` : This module handles requests for MAC operations
+- ``crypto_aead.c`` : This module handles requests for AEAD operations
+- ``crypto_key_derivation.c`` : This module handles requests for key derivation
+ related operations
+- ``crypto_key.c`` : This module handles requests for key related operations
+- ``crypto_asymmetric.c`` : This module handles requests for asymmetric
+ cryptographic operations
+- ``crypto_init.c`` : This module provides basic functions to initialise the
+ secure service during TF-M boot. When the service is built for IPC mode
+ compatibility, this layer handles as well the connection requests and the
+ proper dispatching of requests to the corresponding functions, and it holds
+ the internal buffer used to allocate temporarily the IOVECs needed. The size
+ of this buffer is controlled by the ``TFM_CRYPTO_IOVEC_BUFFER_SIZE`` define.
+ This module also provides a static buffer which is used by the Mbed Crypto
+ library for its own allocations. The size of this buffer is controlled by
+ the ``TFM_CRYPTO_ENGINE_BUF_SIZE`` define
+- ``crypto_alloc.c`` : This module is required for the allocation and release of
+ crypto operation contexts in the SPE. The ``TFM_CRYPTO_CONC_OPER_NUM``,
+ defined in this file, determines how many concurrent contexts are supported
+ for multipart operations (8 for the current implementation). For multipart
+ cipher/hash/MAC/generator operations, a context is associated to the handle
+ provided during the setup phase, and is explicitly cleared only following a
+ termination or an abort
+- ``tfm_crypto_secure_api.c`` : This module implements the PSA Crypto API
+ client interface exposed to the Secure Processing Environment
+- ``tfm_crypto_api.c`` : This module is contained in ``interface/src`` and
+ implements the PSA Crypto API client interface exposed to the Non-Secure
+ Processing Environment.
+- ``tfm_mbedcrypto_alt.c`` : This module contains alternative implementations of
+ Mbed Crypto functions. Decryption code is skipped in AES CCM mode in Profile
+ Small by default.
+
+**************************
+Crypto service integration
+**************************
+In this section, a brief description of the required flow of operation for the
+functionalities exported by the PSA Crypto interface is given, with particular
+focus on the TF-M Crypto service specific operations. For the details of the
+generic PSA Crypto interface operations, please refer directly to the header
+``psa/crypto.h``.
+
+Most of the PSA Crypto multipart APIs require an operation context to be
+allocated by the application and then to be passed as a pointer during the
+following API calls. These operation contexts are of four main types described
+below:
+
+- ``psa_key_derivation_operation_t`` - Operation context for key derivation
+- ``psa_hash_operation_t`` - Operation context for multipart hash operations
+- ``psa_mac_operation_t`` - Operation context for multipart MAC operations
+- ``psa_cipher_operation_t`` - Operation context for multipart cipher operations
+
+The user applications are not allowed to make any assumption about the original
+types behind these typedefs, which are defined inside ``psa/crypto.h``.
+In the scope of the TF-M Crypto service, these types are regarded as handles to
+the corresponding implementation defined structures which are stored in the
+Secure world.
+
+--------------
+
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/tfm_its_integration_guide.rst b/docs/reference/services/tfm_its_integration_guide.rst
new file mode 100644
index 0000000..f6b2dec
--- /dev/null
+++ b/docs/reference/services/tfm_its_integration_guide.rst
@@ -0,0 +1,296 @@
+#######################################################
+TF-M Internal Trusted Storage Service Integration Guide
+#######################################################
+
+************
+Introduction
+************
+TF-M Internal Trusted Storage (ITS) service implements PSA Internal Trusted
+Storage APIs.
+
+The service is backed by hardware isolation of the flash access domain and
+relies on hardware to isolate the flash area from access by the Non-secure
+Processing Environment, as well as the Application Root of Trust at higher
+levels of isolation.
+
+The current ITS service design relies on hardware abstraction provided by TF-M.
+The ITS service provides a non-hierarchical storage model, as a filesystem,
+where all the assets are managed by a linearly indexed list of metadata.
+
+The design addresses the following high level requirements as well:
+
+- **Confidentiality** - Resistance to unauthorised accesses through
+ hardware/software attacks. Assumed to be provided by the internal flash
+ device, backed by hardware isolation.
+
+- **Access Authentication** - Mechanism to establish requester's identity (a
+ non-secure entity, secure entity, or a remote server).
+
+- **Integrity** - Resistance to tampering by attackers with physical access is
+ assumed to be provided by the internal flash device itself, while resistance
+ to tampering by Non-secure or App RoT attackers also requires hardware
+ isolation.
+
+- **Reliability** - Resistance to power failure scenarios and incomplete write
+ cycles.
+
+- **Configurability** - High level of configurability to scale up/down memory
+ footprint to cater for a variety of devices with varying requirements.
+
+- **Performance** - Optimized to be used for resource constrained devices with
+ very small silicon footprint, the PPA (power, performance, area) should be
+ optimal.
+
+*******************************
+Current ITS Service Limitations
+*******************************
+- **Fragmentation** - The current design does not support fragmentation, as an
+ asset is stored in a contiguous space in a block. This means that the maximum
+ asset size can only be up-to a block size. Each block can potentially store
+ multiple assets.
+ A delete operation implicitly moves all the assets towards the top of the
+ block to avoid fragmentation within block. However, this may also result in
+ unutilized space at the end of each block.
+
+- **Non-hierarchical storage model** - The current design uses a
+ non-hierarchical storage model, as a filesystem, where all the assets are
+ managed by a linearly indexed list of metadata. This model locates the
+ metadata in blocks which are always stored in the same flash location. That
+ increases the number of writes in a specific flash location as every change in
+ the storage area requires a metadata update.
+
+- **Protection against physical storage medium failure** - Complete handling of
+ inherent failures of storage mediums (e.g. bad blocks in a NAND based device)
+ is not supported by the current design.
+
+- **Lifecycle management** - Currently, it does not support any subscription
+ based keys and certificates required in a secure lifecycle management. Hence,
+ an asset's validity time-stamp can not be invalidated based on the system
+ time.
+
+- **Provisioning vs user/device data** - In the current design, all assets are
+ treated in the same manner. In an alternative design, it may be required to
+ create separate partitions for provisioning content and user/device generated
+ content. This is to allow safe update of provisioning data during firmware
+ updates without the need to wipe out the user/device generated data.
+
+**************
+Code Structure
+**************
+TF-M Internal Trusted Storage service code is located in
+``secure_fw/partitions/internal_trusted_storage/`` and is divided as follows:
+
+ - Core files
+ - Flash filesystem interfaces
+ - Flash interfaces
+
+The PSA ITS interfaces for the TF-M ITS service are located in
+``interface/include/psa``.
+
+PSA Internal Trusted Storage Interfaces
+=======================================
+
+The TF-M ITS service exposes the following mandatory PSA ITS interfaces
+version 1.0:
+
+.. code-block:: c
+
+ psa_status_t psa_its_set(psa_storage_uid_t uid, size_t data_length, const void *p_data, psa_storage_create_flags_t create_flags);
+ psa_status_t psa_its_get(psa_storage_uid_t uid, size_t data_offset, size_t data_size, void *p_data, size_t *p_data_length);
+ psa_status_t psa_its_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info);
+ psa_status_t psa_its_remove(psa_storage_uid_t uid);
+
+These PSA ITS interfaces and TF-M ITS types are defined and documented in
+``interface/include/psa/storage_common.h``,
+``interface/include/psa/internal_trusted_storage.h``, and
+``interface/include/tfm_its_defs.h``
+
+Core Files
+==========
+- ``tfm_its_req_mngr.c`` - Contains the ITS request manager implementation which
+ handles all requests which arrive to the service. This layer extracts the
+ arguments from the input and output vectors, and it calls the internal trusted
+ storage layer with the provided parameters.
+
+- ``tfm_internal_trusted_storage.c`` - Contains the TF-M internal trusted
+ storage API implementations which are the entry points to the ITS service.
+ Allocates a filesystem context for ITS and makes appropriate fs calls. Also
+ handles requests from the PS partition with a separate fs context.
+
+- ``its_utils.c`` - Contains common and basic functionalities used across the
+ ITS service code.
+
+Flash Filesystem Interface
+==========================
+- ``flash_fs/its_flash_fs.h`` - Abstracts the flash filesystem operations used
+ by the internal trusted storage service. The purpose of this abstraction is to
+ have the ability to plug-in other filesystems or filesystem proxies
+ (supplicant).
+
+- ``flash_fs/its_flash_fs.c`` - Contains the ``its_flash_fs`` implementation for
+ the required interfaces.
+
+- ``flash_fs/its_flash_fs_mbloc.c`` - Contains the metadata block manipulation
+ functions required to implement the ``its_flash_fs`` interfaces in
+ ``flash_fs/its_flash_fs.c``.
+
+- ``flash_fs/its_flash_fs_dbloc.c`` - Contains the data block manipulation
+ functions required to implement the ``its_flash_fs`` interfaces in
+ ``flash_fs/its_flash_fs.c``.
+
+The system integrator **may** replace this implementation with its own
+flash filesystem implementation or filesystem proxy (supplicant).
+
+Flash Interface
+===============
+- ``flash/its_flash.h`` - Abstracts the flash operations for the internal
+ trusted storage service. Defines the ``struct its_flash_info_t`` type, which
+ is used as a parameter to the filesystem to provide information about the
+ flash device in use, such as the block size and number of blocks available.
+
+- ``flash/its_flash.c`` - Contains the ``its_flash`` implementations common to
+ all flash types.
+
+- ``flash/its_flash_nand.c`` - Implements the ITS flash interface for a NAND
+ flash device, on top of the CMSIS flash interface implemented by the target.
+ This implementation writes entire block updates in one-shot, so the CMSIS
+ flash implementation **must** be able to detect incomplete writes and return
+ an error the next time the block is read.
+
+- ``flash/its_flash_nor.c`` - Implements the ITS flash interface for a NOR flash
+ device, on top of the CMSIS flash interface implemented by the target.
+
+- ``flash/its_flash_ram.c`` - Implements the ITS flash interface for an emulated
+ flash device using RAM, on top of the CMSIS flash interface implemented by the
+ target.
+
+- ``flash/its_flash_info_internal.c`` - Defines an instance of the
+ ``struct its_flash_info_t`` type for the internal flash device based on
+ target-specific definitions.
+
+- ``flash/its_flash_info_external.c`` - Defines an instance of the
+ ``struct its_flash_info_t`` type for the external flash device, used only to
+ handle requests from the PS partition.
+
+The CMSIS flash interface **must** be implemented for each target based on its
+flash controller.
+
+The ITS flash interface depends on target-specific definitions from
+``platform/ext/target/<TARGET_NAME>/partition/flash_layout.h``.
+Please see the `Internal Trusted Storage Service Definitions` section for
+details.
+
+*****************************
+ITS Service Integration Guide
+*****************************
+This section describes mandatory (i.e. **must** implement) or optional
+(i.e. **may** implement) interfaces which the system integrator has to take in
+to account in order to integrate the internal trusted storage service in a new
+platform.
+
+Maximum Asset Size
+==================
+An asset is stored in a contiguous space in a block/sector. The maximum size of
+an asset can be up-to the size of the data block/sector.
+
+Internal Trusted Storage Service Definitions
+============================================
+The ITS service requires the following platform definitions:
+
+- ``ITS_FLASH_AREA_ADDR`` - Defines the flash address where the internal trusted
+ storage area starts.
+- ``ITS_FLASH_AREA_SIZE`` - Defines the size of the dedicated flash area for
+ internal trusted storage in bytes.
+- ``ITS_SECTOR_SIZE`` - Defines the size of the flash sectors (the smallest
+ erasable unit) in bytes.
+- ``ITS_SECTORS_PER_BLOCK`` - Defines the number of contiguous ITS_SECTOR_SIZE
+ to form a logical block in the filesystem.
+- ``ITS_FLASH_DEV_NAME`` - Specifies the flash device used by ITS to store the
+ data.
+- ``ITS_FLASH_PROGRAM_UNIT`` - Defines the smallest flash programmable unit in
+ bytes. Valid values are powers of two between 1 and ``ITS_SECTOR_SIZE``
+ inclusive.
+- ``ITS_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the
+ ITS area. This size is used to define the temporary buffers used by ITS to
+ read/write the asset content from/to flash. The memory used by the temporary
+ buffers is allocated statically as ITS does not use dynamic memory allocation.
+- ``ITS_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the
+ ITS area. This number is used to dimension statically the filesystem metadata
+ tables in RAM (fast access) and flash (persistent storage). The memory used by
+ the filesystem metadata tables is allocated statically as ITS does not use
+ dynamic memory allocation.
+
+The sectors reserved to be used as internal trusted storage **must** be
+contiguous sectors starting at ``ITS_FLASH_AREA_ADDR``.
+
+Target must provide a header file, called ``flash_layout.h``, which defines the
+information explained above. The defines must be named as they are specified
+above.
+
+More information about the ``flash_layout.h`` content, not ITS related, is
+available in :doc:`platform readme </platform/ext/readme>` along with other
+platform information.
+
+The following optional platform definitions may also be defined in
+``flash_layout.h`` or set at build time in ``platform/ext/<TARGET_NAME>.cmake``:
+
+- ``ITS_BUF_SIZE``- Defines the size of the partition's internal data transfer
+ buffer. If not provided, then ``ITS_MAX_ASSET_SIZE`` is used to allow asset
+ data to be copied between the client and the filesystem in one iteration.
+ Reducing the buffer size will decrease the RAM usage of the partition at the
+ expense of latency, as data will be copied in multiple iterations. *Note:*
+ when data is copied in multiple iterations, the atomicity property of the
+ filesystem is lost in the case of an asynchronous power failure.
+- ``ITS_MAX_BLOCK_DATA_COPY`` - Defines the buffer size used when copying data
+ between blocks, in bytes. If not provided, defaults to 256. Increasing this
+ value will increase the memory footprint of the service.
+
+Flash Interface
+===============
+For ITS service operations, a contiguous set of blocks must be earmarked for
+the internal trusted storage area. The design requires either 2 blocks, or any
+number of blocks greater than or equal to 4. Total number of blocks can not be
+0, 1 or 3. This is a design choice limitation to provide power failure safe
+update operations.
+
+For API specification, please check:
+``secure_fw/partitions/internal_trusted_storage/flash/its_flash.h``
+
+ITS Service Features Flags
+==========================
+ITS service defines a set of flags that can be used to compile in/out certain
+ITS service features. The ``CommonConfig.cmake`` file sets the default values
+of those flags. However, those flags values can be overwritten by setting them
+in ``platform/ext/<TARGET_NAME>.cmake`` based on the target capabilities or
+needs. The list of ITS services flags are:
+
+- ``ITS_CREATE_FLASH_LAYOUT``- this flag indicates that it is required
+ to create an ITS flash layout. If this flag is set, ITS service will
+ generate an empty and valid ITS flash layout to store assets. It will
+ erase all data located in the assigned ITS memory area before generating
+ the ITS layout. This flag is required to be set if the ITS memory area
+ is located in a non-persistent memory. This flag can be set if the ITS
+ memory area is located in a persistent memory without a valid ITS flash
+ layout in it. That is the case when it is the first time in the device
+ life that the ITS service is executed.
+- ``ITS_VALIDATE_METADATA_FROM_FLASH``- this flag allows to
+ enable/disable the validation mechanism to check the metadata store in flash
+ every time the flash data is read from flash. This validation is required
+ if the flash is not hardware protected against data corruption.
+- ``ITS_RAM_FS``- this flag allows to enable/disable the use of RAM
+ instead of the flash to store the FS in internal trusted storage service. This
+ flag is set by default in the regression tests, if it is not defined by the
+ platform. The ITS regression tests reduce the life of the flash memory
+ as they write/erase multiple times in the memory.
+
+ .. Note::
+ If this flag is manually disabled when running the regression tests,
+ then the storage flash area should also be erased before running the tests
+ to ensure they run successfully. The type of storage flash area is platform
+ specific (QSPI, eFlash, etc.) and it is described in corresponding
+ flash_layout.h
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2020, Cypress Semiconductor Corporation. All rights reserved.*
diff --git a/docs/reference/services/tfm_platform_integration_guide.rst b/docs/reference/services/tfm_platform_integration_guide.rst
new file mode 100644
index 0000000..7858435
--- /dev/null
+++ b/docs/reference/services/tfm_platform_integration_guide.rst
@@ -0,0 +1,113 @@
+##################################
+Platform Service Integration Guide
+##################################
+
+************
+Introduction
+************
+TF-M Platform service is a trusted service which allows secure partitions and
+non-secure applications to interact with some platform-specific components.
+There are a number of features which requires some interaction with
+platform-specific components which are at the same time essential for the
+security of the system.
+Therefore, those components need to be handled by a secure partition which is
+part of the trusted compute base.
+
+These platform-specific components include system reset, power management,
+Debug, GPIO, etc.
+
+************************
+TF-M Platform interfaces
+************************
+The TF-M interfaces for the Platform service are located in
+``interface/include/``.
+The TF-M Platform service source files are located in
+``secure_fw/partitions/platform``.
+
+*********************
+TF-M Platform service
+*********************
+The Platform service interfaces and types are defined and documented in
+``interface/include/tfm_platform_api.h``
+
+- ``platform_sp.h/c`` : These files define and implement functionalities related
+ to the platform service
+- ``tfm_platform_secure_api.c`` : This file implements ``tfm_platform_api.h``
+ functions to be called from the secure partitions. This is the entry point
+ when the secure partitions request an action to the Platform service
+ (e.g system reset).
+
+************
+Platform HAL
+************
+
+The Platform Service relies on a platform-specific implementation to
+perform some functionalities. Mandatory functionality (e.g. system reset)
+that are required to be implemented for a platform to be supported by TF-M have
+their dedicated HAL API functions. Additional platform-specific services can be
+provided using the IOCTL function call.
+
+For API specification, please check: ``platform/include/tfm_platform_system.h``
+
+An implementation is provided in all the supported platforms. Please, check
+``platform/ext/target/<SPECIFIC_TARGET_FOLDER>/services/src/tfm_platform_system.c``
+for examples.
+
+The API **must** be implemented by the system integrators for their targets.
+
+IOCTL
+=====
+
+A single entry point to platform-specific code across the HAL is provided by the
+IOCTL service and HAL function:
+
+.. code-block:: c
+
+ enum tfm_platform_err_t tfm_platform_hal_ioctl(tfm_platform_ioctl_req_t request,
+ psa_invec *in_vec,
+ psa_outvec *out_vec);
+
+A request type is provided by the client, with additional parameters contained
+in the optional ``in_vec`` parameter. An optional output buffer can be passed to
+the service in ``out_vec``.
+An IOCTL request type not supported on a particular platform should return
+``TFM_PLATFORM_ERR_NOT_SUPPORTED``
+
+Non-Volatile counters
+=====================
+
+The Platform Service provides an abstracted service for exposing the NV counters
+to the secure world. The following operations are supported:
+
+- Increment a counter.
+- Read a counter value to a preallocated buffer.
+
+.. code-block:: c
+
+ enum tfm_platform_err_t
+ tfm_platform_nv_counter_increment(uint32_t counter_id);
+
+ enum tfm_platform_err_t
+ tfm_platform_nv_counter_read(uint32_t counter_id,
+ uint32_t size, uint8_t *val);
+
+The range of counters id is defined in :
+``platform/include/tfm_plat_nv_counters.h``
+
+For Level 2,3 isolation implementations, secure partitions in the
+Application Root of Trust, should have ``TFM_SP_PLATFORM_NV_COUNTER`` set as a
+dependency for access to the NV counter API.
+
+***************************
+Current Service Limitations
+***************************
+- **system reset** - The system reset functionality is only supported in
+ isolation level 1. Currently the mechanism by which PSA-RoT services should
+ run in privileged mode in level 3 is not in place due to an ongoing work in
+ TF-M Core. So, the ``NVIC_SystemReset`` call performed by the service is
+ expected to generate a memory fault when it tries to access the ``SCB->AIRCR``
+ register in level 3 isolation.
+
+--------------
+
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/tfm_ps_integration_guide.rst b/docs/reference/services/tfm_ps_integration_guide.rst
new file mode 100644
index 0000000..4da23a5
--- /dev/null
+++ b/docs/reference/services/tfm_ps_integration_guide.rst
@@ -0,0 +1,361 @@
+###########################################
+Protected Storage Service Integration Guide
+###########################################
+
+************
+Introduction
+************
+TF-M Protected Storage (PS) service implements PSA Protected Storage APIs.
+
+The service is backed by hardware isolation of the flash access domain and, in
+the current version, relies on hardware to isolate the flash area from
+non-secure access. In absence of hardware level isolation, the secrecy and
+integrity of data is still maintained.
+
+The PS service implements an AES-GCM based AEAD encryption policy, as a
+reference, to protect data integrity and authenticity.
+
+PS reuses the non-hierarchical filesystem provided by the TF-M Internal Trusted
+Storage service to store encrypted, authenticated objects on the external flash
+device.
+
+The design addresses the following high level requirements as well:
+
+- **Confidentiality** - Resistance to unauthorised accesses through
+ hardware/software attacks.
+
+- **Access Authentication** - Mechanism to establish requester's identity (a
+ non-secure entity, secure entity, or a remote server).
+
+- **Integrity** - Resistant to tampering by either the normal users of a product,
+ package, or system or others with physical access to it. If the content of the
+ protected storage is changed maliciously, the service is able to detect it.
+
+- **Reliability** - Resistant to power failure scenarios and incomplete write
+ cycles.
+
+- **Configurability** - High level configurability to scale up/down memory
+ footprint to cater for a variety of devices with varying security
+ requirements.
+
+- **Performance** - Optimized to be used for resource constrained devices with
+ very small silicon footprint, the PPA (power, performance, area) should be
+ optimal.
+
+******************************
+Current PS Service Limitations
+******************************
+- **Fragmentation** - The current design does not support fragmentation, as an
+ asset is stored in a contiguous space in a block. This means that the maximum
+ asset size can only be up-to a block size. Detailed information about the
+ maximum asset size can be found in the section `Maximum asset size` below.
+ Each block can potentially store multiple assets.
+ A delete operation implicitly moves all the assets towards the top of the block
+ to avoid fragmentation within block. However, this may also result in
+ unutilized space at the end of each block.
+
+- **Asset size limitation** - An asset is stored in a contiguous space in a
+ block/sector. Hence, the maximum asset size can be up-to the size of the
+ data block/sector. Detailed information about the maximum asset size can be
+ found in the section `Maximum asset size` below.
+
+- **Non-hierarchical storage model** - The current design uses a
+ non-hierarchical storage model, as a filesystem, where all the assets are
+ managed by a linearly indexed list of metadata. This model locates the
+ metadata in blocks which are always stored in the same flash location. That
+ increases the number of writes in a specific flash location as every change in
+ the storage area requires a metadata update.
+
+- **PSA internal trusted storage API** - In the current design, the service does
+ not use the PSA Internal Trusted Storage API to write the rollback protection
+ values stored in the internal storage.
+
+- **Protection against physical storage medium failure** - Complete handling of
+ inherent failures of storage mediums (e.g. bad blocks in a NAND based device)
+ is not supported by the current design.
+
+- **Key diversification** - In a more robust design, each asset would be
+ encrypted through a different key.
+
+- **Lifecycle management** - Currently, it does not support any subscription
+ based keys and certificates required in a secure lifecycle management. Hence,
+ an asset's validity time-stamp can not be invalidated based on the system
+ time.
+
+- **Provisioning vs user/device data** - In the current design, all assets are
+ treated in the same manner. In an alternative design, it may be required to
+ create separate partitions for provisioning content and user/device generated
+ content. This is to allow safe update of provisioning data during firmware
+ updates without the need to wipe out the user/device generated data.
+
+**************
+Code Structure
+**************
+Protected storage service code is located in
+``secure_fw/partitions/protected_storage/`` and is divided as follows:
+
+ - Core files
+ - Cryptographic interfaces
+ - Non-volatile (NV) counters interfaces
+
+The PSA PS interfaces for PS service are located in ``interface/include/psa``
+
+PSA Protected Storage Interfaces
+================================
+
+The PS service exposes the following mandatory PSA PS interfaces, version 1.0:
+
+.. code-block:: c
+
+ psa_status_t psa_ps_set(psa_storage_uid_t uid, size_t data_length, const void *p_data, psa_storage_create_flags_t create_flags);
+ psa_status_t psa_ps_get(psa_storage_uid_t uid, size_t data_offset, size_t data_size, void *p_data, size_t *p_data_length);
+ psa_status_t psa_ps_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info);
+ psa_status_t psa_ps_remove(psa_storage_uid_t uid);
+ uint32_t psa_ps_get_support(void);
+
+For the moment, it does not support the extended version of those APIs.
+
+These PSA PS interfaces and PS TF-M types are defined and documented in
+``interface/include/psa/protected_storage.h``,
+``interface/include/psa/storage_common.h`` and
+``interface/include/tfm_ps_defs.h``
+
+Core Files
+==========
+- ``tfm_ps_req_mngr.c`` - Contains the PS request manager implementation which
+ handles all requests which arrive to the service. This layer extracts the
+ arguments from the input and output vectors, and it calls the protected
+ storage layer with the provided parameters.
+
+- ``tfm_protected_storage.c`` - Contains the TF-M protected storage API
+ implementations which are the entry points to the PS service.
+
+- ``ps_object_system.c`` - Contains the object system implementation to manage
+ all objects in PS area.
+
+- ``ps_object_table.c`` - Contains the object system table implementation which
+ complements the object system to manage all object in the PS area.
+ The object table has an entry for each object stored in the object system
+ and keeps track of its version and owner.
+
+- ``ps_encrypted_object.c`` - Contains an implementation to manipulate
+ encrypted objects in the PS object system.
+
+- ``ps_utils.c`` - Contains common and basic functionalities used across the
+ PS service code.
+
+Flash Filesystem and Flash Interfaces
+=====================================
+The PS service reuses the non-hierarchical filesystem and flash interfaces
+provided by the TF-M Internal Trusted Storage service. It stores encrypted,
+authenticated objects on the external flash device by making service calls to
+the ITS service. When the ITS service receives requests from the PS partition,
+it handles the request by using a separate filesystem context initialised to use
+the external flash device.
+
+The ITS filesystem and flash interfaces and their implementation can be found in
+``secure_fw/partitions/internal_trusted_storage/flash_fs`` and
+``secure_fw/partitions/internal_trusted_storage/flash`` respectively. More
+information about the filesystem and flash interfaces can be found in the
+:doc:`ITS integration guide
+</docs/reference/services/tfm_its_integration_guide>`.
+
+The structure containing info about the external flash device, used by the ITS
+service to handle requests from the PS partition, is defined in
+``secure_fw/partitions/internal_trusted_storage/flash/its_flash_info_external.c``,
+which depends on target-specific definitions from
+``platform/ext/target/<TARGET_NAME>/partition/flash_layout.h``. Please see the
+`Protected Storage Service Definitions` section for details.
+
+Cryptographic Interface
+=======================
+- ``crypto/ps_crypto_interface.h`` - Abstracts the cryptographic operations for
+ the protected storage service.
+
+- ``crypto/ps_crypto_interface.c`` - Implements the PS service cryptographic
+ operations with calls to the TF-M Crypto service.
+
+Non-volatile (NV) Counters Interface
+====================================
+The current PS service provides rollback protection based on NV
+counters.
+PS defines and implements the following NV counters functionalities:
+
+- ``nv_counters/ps_nv_counters.h`` - Abstracts PS non-volatile
+ counters operations. This API detaches the use of NV counters from the TF-M NV
+ counters implementation, provided by the platform, and provides a mechanism to
+ compile in a different API implementation for test purposes. A PS test suite
+ **may** provide its own custom implementation to be able to test different PS
+ service use cases.
+
+- ``nv_counters/ps_nv_counters.c`` - Implements the PS NV counters interfaces
+ based on TF-M NV counters implementation provided by the platform.
+
+****************************
+PS Service Integration Guide
+****************************
+This section describes mandatory (i.e. **must** implement) or optional
+(i.e. **may** implement) interfaces which the system integrator have to take
+in to account in order to integrate the protected storage service in a new
+platform.
+
+Maximum Asset Size
+==================
+An asset is stored in a contiguous space in a block/sector. The maximum
+size of an asset can be up-to the size of the data block/sector minus the object
+header size (``PS_OBJECT_HEADER_SIZE``) which is defined in
+``ps_object_defs.h``. The ``PS_OBJECT_HEADER_SIZE`` changes based on the
+``PS_ENCRYPTION`` flag status.
+
+Protected Storage Service Definitions
+=====================================
+The PS service requires the following platform definitions:
+
+- ``PS_FLASH_AREA_ADDR`` - Defines the flash address where the protected storage
+ area starts.
+- ``PS_FLASH_AREA_SIZE`` - Defines the size of the dedicated flash area
+ for protected storage in bytes.
+- ``PS_SECTOR_SIZE`` - Defines the size of the flash sectors (the smallest
+ erasable unit) in bytes.
+- ``PS_SECTORS_PER_BLOCK`` - Defines the number of contiguous PS_SECTOR_SIZE
+ to form a logical block in the filesystem.
+- ``PS_FLASH_DEV_NAME`` - Specifies the flash device used by PS to store the
+ data.
+- ``PS_FLASH_PROGRAM_UNIT`` - Defines the smallest flash programmable unit in
+ bytes. Valid values are powers of two between 1 and ``PS_SECTOR_SIZE``
+ inclusive.
+- ``PS_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the
+ PS area. This size is used to define the temporary buffers used by PS to
+ read/write the asset content from/to flash. The memory used by the temporary
+ buffers is allocated statically as PS does not use dynamic memory allocation.
+- ``PS_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the
+ PS area. This number is used to dimension statically the object table size in
+ RAM (fast access) and flash (persistent storage). The memory used by the
+ object table is allocated statically as PS does not use dynamic memory
+ allocation.
+
+The sectors reserved to be used as protected storage **must** be contiguous
+sectors starting at ``PS_FLASH_AREA_ADDR``.
+
+The design requires either 2 blocks, or any number of blocks greater than or
+equal to 4. Total number of blocks can not be 0, 1 or 3. This is a design choice
+limitation to provide power failure safe update operations.
+
+Target must provide a header file, called ``flash_layout.h``, which defines the
+information explained above. The defines must be named as they are specified
+above.
+
+More information about the ``flash_layout.h`` content, not PS related, is
+available in :doc:`platform readme </platform/ext/readme>` along with other
+platform information.
+
+TF-M NV Counter Interface
+=========================
+To have a platform independent way to access the NV counters, TF-M defines a
+platform NV counter interface. For API specification, please check:
+``platform/include/tfm_plat_nv_counters.h``
+
+The system integrators **may** implement this interface based on the target
+capabilities and set the ``PS_ROLLBACK_PROTECTION`` flag to compile in
+the rollback protection code.
+
+Secret Platform Unique Key
+==========================
+The encryption policy relies on a secret hardware unique key (HUK) per device.
+It is system integrator's responsibility to provide an implementation which
+**must** be a non-mutable target implementation.
+For API specification, please check:
+``platform/include/tfm_plat_crypto_keys.h``
+
+A stub implementation is provided in
+``platform/ext/common/template/crypto_keys.c``
+
+Non-Secure Identity Manager
+===========================
+TF-M core tracks the current client IDs running in the secure or non-secure
+processing environment. It provides a dedicated API to retrieve the client ID
+which performs the service request.
+
+:doc:`NS client identification documentation </docs/getting_started/tfm_ns_client_identification>`
+provides further details on how client identification works.
+
+PS service uses that TF-M core API to retrieve the client ID and associate it
+as the owner of an asset. Only the owner can read, write or delete that asset
+based on the creation flags.
+
+The :doc:`integration guide </docs/getting_started/tfm_integration_guide>` provides further
+details of non-secure implementation requirements for TF-M.
+
+Cryptographic Interface
+=======================
+The reference encryption policy is built on AES-GCM, and it **may** be replaced
+by a vendor specific implementation.
+
+The PS service abstracts all the cryptographic requirements and specifies the
+required cryptographic interface in
+``secure_fw/partitions/protected_storage/crypto/ps_crypto_interface.h``
+
+The PS service cryptographic operations are implemented in
+``secure_fw/partitions/protected_storage/crypto/ps_crypto_interface.c``, using
+calls to the TF-M Crypto service.
+
+PS Service Features Flags
+=========================
+PS service defines a set of flags that can be used to compile in/out certain
+PS service features. The ``CommonConfig.cmake`` file sets the default values
+of those flags. However, those flags values can be overwritten by setting them
+in ``platform/ext/<TARGET_NAME>.cmake`` based on the target capabilities or
+needs. The list of PS services flags are:
+
+- ``PS_ENCRYPTION``- this flag allows to enable/disable encryption
+ option to encrypt the protected storage data.
+- ``PS_CREATE_FLASH_LAYOUT``- this flag indicates that it is required
+ to create a PS flash layout. If this flag is set, PS service will
+ generate an empty and valid PS flash layout to store assets. It will
+ erase all data located in the assigned PS memory area before generating
+ the PS layout. This flag is required to be set if the PS memory area
+ is located in a non-persistent memory. This flag can be set if the PS
+ memory area is located in a persistent memory without a valid PS flash
+ layout in it. That is the case when it is the first time in the device
+ life that the PS service is executed.
+- ``PS_VALIDATE_METADATA_FROM_FLASH``- this flag allows to
+ enable/disable the validation mechanism to check the metadata store in flash
+ every time the flash data is read from flash. This validation is required
+ if the flash is not hardware protected against malicious writes. In case
+ the flash is protected against malicious writes (i.e embedded flash, etc),
+ this validation can be disabled in order to reduce the validation overhead.
+- ``PS_ROLLBACK_PROTECTION``- this flag allows to enable/disable
+ rollback protection in protected storage service. This flag takes effect only
+ if the target has non-volatile counters and ``PS_ENCRYPTION`` flag is on.
+- ``PS_RAM_FS``- this flag allows to enable/disable the use of RAM
+ instead of the flash to store the FS in protected storage service. This flag
+ is set by default in the regression tests, if it is not defined by the
+ platform. The PS regression tests reduce the life of the flash memory
+ as they write/erase multiple times in the memory.
+
+ .. Note::
+ If this flag is manually disabled when running the regression tests,
+ then the storage flash area should also be erased before running the tests
+ to ensure they run successfully. The type of storage flash area is platform
+ specific (QSPI, eFlash, etc.) and it is described in corresponding
+ flash_layout.h
+
+- ``PS_TEST_NV_COUNTERS``- this flag enables the virtual
+ implementation of the PS NV counters interface in
+ ``test/suites/ps/secure/nv_counters``, which emulates NV counters in
+ RAM, and disables the hardware implementation of NV counters provided by
+ the secure service. This flag is enabled by default when building the
+ regression tests and disabled by default otherwise. This flag can be
+ overridden to ``OFF`` when building the regression tests. In this case,
+ the PS rollback protection test suite will not be built, as it relies
+ on extra functionality provided by the virtual NV counters to simulate
+ different rollback scenarios. The remainder of the PS test suites will
+ run using the hardware NV counters. Please note that running the tests in
+ this configuration will quickly increase the hardware NV counter values,
+ which cannot be decreased again.
+ Overriding this flag from its default value of ``OFF`` when not
+ building the regression tests is not currently supported.
+
+--------------
+
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/tfm_secure_partition_addition.rst b/docs/reference/services/tfm_secure_partition_addition.rst
new file mode 100644
index 0000000..774220a
--- /dev/null
+++ b/docs/reference/services/tfm_secure_partition_addition.rst
@@ -0,0 +1,352 @@
+#######################
+Adding Secure Partition
+#######################
+
+***********************
+Terms and abbreviations
+***********************
+This document uses the following terms and abbreviations.
+
+.. table:: term table
+ :widths: auto
+
+ ================== ==================================
+ **Term** **Meaning**
+ ================== ==================================
+ FF Firmware Framework
+ ID Identifier
+ IPC Interprocess communication
+ IPC model The secure IPC framework
+ irqs Interrupt requests
+ Library model The secure function call framework
+ MMIO Memory Mapped I/O
+ PSA Platform Security Architecture
+ RoT Root of Trust
+ SID RoT Service ID
+ SP Secure Partition
+ SPM Secure Partition Manager
+ TF-M Trusted firmware M
+ ================== ==================================
+
+************
+Introduction
+************
+Secure Partition is an execution environment that provides the following
+functions to Root of Trust (RoT) Services:
+
+- Access to resources, protection of its own code and data.
+- Mechanisms to interact with other components in the system.
+
+Each Secure Partition is a single thread of execution and the smallest unit of
+isolation.
+
+This document mainly describes how to add a secure partition in TF-M and
+focuses on the configuration, manifest, implement rules. The actual
+source-level implementation is not included in this document.
+
+.. Note::
+ If not otherwise specified, the steps are identical for library and IPC
+ model.
+
+ The IPC model conforms the *PSA Firmware Framework (FF) v 1.0.0*. Refer to
+ `PSA Firmware Framework specification`_ for details.
+
+*******
+Process
+*******
+The main steps to add a secure partition are as follows:
+
+- `Add source folder`_
+- `Add manifest`_
+- `Add configuration`_
+- `Generate files`_
+- `Implement the RoT services`_
+
+Add source folder
+=================
+Add a source folder under ``<TF-M base folder>/secure_fw/partitions`` for the new
+secure partition (Let's take EXAMPLE as the folder name):
+
+This folder should include those parts:
+
+- Manifest file: EXAMPLE.yaml
+- CMake configuration files
+- Source code files
+
+Add manifest
+============
+Each Secure Partition must have resource requirements declared in a manifest
+file. The Secure Partition Manager (SPM) uses the manifest file to assemble and
+allocate resources within the SPE. The manifest includes the following:
+
+- A Secure Partition name.
+- A list of implemented RoT Services.
+- Access to other RoT Services.
+- Memory requirements.
+- Scheduling hints.
+- Peripheral memory-mapped I/O regions and interrupts.
+
+.. Note::
+ The current manifest format in TF-M is "yaml" which is different from the
+ requirement of PSA FF.
+
+Here is a manifest reference example for the IPC model, please refer to
+`Library model support`_ for the library extend:
+
+.. code-block:: yaml
+
+ {
+ "psa_framework_version": 1.0,
+ "name": "TFM_SP_EXAMPLE",
+ "type": "PSA-ROT",
+ "priority": "HIGH",
+ "entry_point": "EXAMPLE_main",
+ "stack_size": "0x0200",
+ "services" : [
+ {
+ "name": "ROT_A",
+ "sid": "0x0000F000",
+ "non_secure_clients": true,
+ "version": 1,
+ "version_policy": "STRICT"
+ }
+ ],
+ "mmio_regions": [
+ {
+ "name": "TFM_PERIPHERAL_A",
+ "permission": "READ-WRITE"
+ }
+ ],
+ "irqs": [
+ {
+ "source": "TFM_A_IRQ",
+ "signal": "SPM_CORE_A_IRQ",
+ "tfm_irq_priority": 64,
+ }
+ ],
+ "linker_pattern": {
+ "object_list": [
+ "*EXAMPLE.*"
+ ]
+ }
+ }
+
+Secure Partition ID Distribution
+--------------------------------
+Every Secure Partition has an identifier (ID). TF-M will generate a header file
+that includes definitions of the Secure Partition IDs. The header file is
+``<TF-M base folder>/interface/include/psa_manifest/pid.h``. Each definition
+uses the ``name`` attribute in the manifest as its name and the value is
+allocated by SPM.
+
+.. code-block:: c
+
+ #define name id-value
+
+Here is the Secure Partition ID table used in TF-M.
+
+.. table:: PID table
+ :widths: auto
+
+ =============================== =================
+ **Partition name** **Partition ID**
+ =============================== =================
+ Reserved 0-255
+ TFM_SP_PS 256
+ TFM_SP_ITS 257
+ TFM_SP_AUDIT_LOG 258
+ TFM_SP_CRYPTO 259
+ TFM_SP_PLATFORM 260
+ TFM_SP_INITIAL_ATTESTATION 261
+ TFM_SP_CORE_TEST 262
+ TFM_SP_CORE_TEST_2 263
+ TFM_SP_SECURE_TEST_PARTITION 264
+ TFM_SP_IPC_SERVICE_TEST 265
+ TFM_SP_IPC_CLIENT_TEST 266
+ TFM_IRQ_TEST_1 267
+ TFM_SP_PS_TEST 268
+ =============================== =================
+
+About where to add the definition, please refer to the chapter `Add
+configuration`_.
+
+RoT Service ID (SID) Distribution
+---------------------------------
+An RoT Service is identified by its RoT Service ID (SID). A SID is a 32-bit
+number that is associated with a symbolic name in the Secure Partition
+manifest. The bits [31:12] uniquely identify the vendor of the RoT Service.
+The remaining bits [11:0] can be used at the discretion of the vendor.
+
+Here is the RoT Service ID table used in TF-M.
+
+.. table:: SID table
+ :widths: auto
+
+ =========================== ====================== ========================
+ **Services** **Vendor ID(20 bits)** **Function ID(12 bits)**
+ =========================== ====================== ========================
+ audit_logging 0x00000 0x000-0x01F
+ initial_attestation 0x00000 0x020-0x03F
+ platform 0x00000 0x040-0x05F
+ protected_storage 0x00000 0x060-0x07F
+ crypto 0x00000 0x080-0x09F
+ internal_trusted_storage 0x00000 0x0A0-0x0BF
+ test_secure_service 0x0000F 0x000-0x01F
+ core_test 0x0000F 0x020-0x03F
+ core_test_2 0x0000F 0x040-0x05F
+ tfm_ipc_client 0x0000F 0x060-0x07F
+ tfm_ipc_service 0x0000F 0x080-0x09F
+ tfm_irq_test_service_1 0x0000F 0x0A0-0x0BF
+ tfm_ps_test_service 0x0000F 0x0C0-0x0DF
+ =========================== ====================== ========================
+
+mmio_regions
+------------
+This attribute is a list of MMIO region objects which the Secure Partition
+needs access to. TF-M only supports the ``named_region`` current. Please refer
+to PSA FF for more details about it. The user needs to provide a name macro to
+indicate the variable of the memory region.
+
+TF-M uses the below structure to indicate a peripheral memory.
+
+.. code-block:: c
+
+ struct tfm_spm_partition_platform_data_t {
+ uint32_t periph_start;
+ uint32_t periph_limit;
+ int16_t periph_ppc_bank;
+ int16_t periph_ppc_loc;
+ };
+
+.. Note::
+ This structure is not expected by TF-M, it's only that the current
+ implementations are using. Other peripherals that need different information
+ to create isolation need to define a different structure with the same name.
+
+Here is a example for it:
+
+.. code-block:: c
+
+ struct tfm_spm_partition_platform_data_t tfm_peripheral_A;
+ #define TFM_PERIPHERAL_A (&tfm_peripheral_A)
+
+linker_pattern
+--------------
+``linker_pattern`` is a legacy region which contains the minimum information
+required to link a Secure Partition’s compiled static objects. Now, it is
+required as 'IMPLEMENTATION DEFINED' in PSA FF 1.0.0.
+
+Library model support
+---------------------
+For the library model, the user needs to add a ``secure_functions`` item. The
+main difference between ``secure_function`` and ``services`` is the extra
+``signal`` key for secure function entry.
+
+The ``signal`` must be the upper case of the secure function name.
+
+.. code-block:: yaml
+
+ "secure_functions": [
+ {
+ "name": "TFM_EXAMPLE_A",
+ "signal": "EXAMPLE_A_FUNC",
+ "sid": "0x00000000",
+ "non_secure_clients": true,
+ "version": 1,
+ "version_policy": "STRICT"
+ },
+
+Add configuration
+=================
+The following configuration tasks are required for the newly added secure
+partition:
+
+Add CMake configure files
+-------------------------
+Two CMake configure files need to be added:
+
+- CMakeLists.inc, which is used to add the definition of what files are needed
+ to build.
+- CMakeLists.txt, which is the compilation configuration for this module.
+
+.. Note::
+ The CMakeLists.inc is not mandatory, the user can put everything in
+ CMakeLists.txt.
+
+Please refer to the source code of TF-M for more detail.
+
+Update manifest list
+--------------------
+The ``<TF-M base folder>/tools/tfm_manifest_list.yaml`` is used to collect
+necessary information of secure partition.
+
+- ``name``: The name string of the secure partition.
+- ``short_name``: should be the same as the ``name`` in the secure partition
+ manifest file.
+- ``manifest``: the relative path of the manifest file to TF-M root.
+- ``tfm_partition_ipc``: indicate if this partition is compatible with the IPC
+ model.
+- ``conditional``: Optional. Configure control macro for this partition.
+- ``version_major``: major version the partition manifest.
+- ``version_minor``: minor version the partition manifest.
+- ``pid``: Secure Partition ID value distributed in chapter `Secure Partition
+ ID Distribution`_.
+
+Reference configuration example:
+
+.. code-block:: yaml
+
+ {
+ "name": "Example Service",
+ "short_name": "TFM_SP_EXAMPLE",
+ "manifest": "secure_fw/partitions/EXAMPLE/tfm_example.yaml",
+ "tfm_extensions": true,
+ "tfm_partition_ipc": true,
+ "conditional": "TFM_PARTITION_EXAMPLE_ENABLE",
+ "version_major": 0,
+ "version_minor": 1,
+ "pid": 256
+ }
+
+Generate files
+==============
+After finishing the configuration works, the user needs to generate necessary
+files from manifest by using TF-M tools.
+
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cd trusted-firmware-m
+ python ./tools/tfm_parse_manifest_list.py
+
+Implement the RoT services
+==========================
+The following not-binding rules, as currently implemented, can be used as
+guidelines:
+
+- In the IPC model, Use PSA FF proposed memory accessing mechanism. SPM
+ provides APIs and checking between isolation boundaries, a free accessing
+ of memory can cause program panic.
+- In the IPC model, the memory checking inside partition runtime is
+ unnecessary. SPM handles the checking while memory accessing APIs are
+ called.
+- In the IPC model, the client ID had been included in the message structure
+ and secure partition can get it when calling psa_get() function. The secure
+ partition does not need to call ``tfm_core_get_caller_client_id()`` to get
+ the caller client ID anymore.
+- In the IPC model, SPM will check the security policy and partition
+ dependence between client and service. So the service does not need to
+ validate the secure caller anymore.
+
+*********
+Reference
+*********
+
+| `PSA Firmware Framework specification`_
+
+.. _PSA Firmware Framework specification: https://pages.arm.com/psa-
+ resources-ff.html?_ga=2.156169596.61580709.1542617040-1290528876.1541647333
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*