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/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.*