aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJulian Hall <julian.hall@arm.com>2021-03-24 10:11:29 +0000
committerGyörgy Szing <gyorgy.szing@arm.com>2021-07-01 17:43:12 +0200
commit2075a217e87fe18f6be4a3be4f949253bdf6c5a2 (patch)
tree04fa7343917f47429c024c5ad0a06cfd172cc3dd
parent3a4207dc7d5be5a4723168b864e6957d526fa5e5 (diff)
downloadtrusted-services-2075a217e87fe18f6be4a3be4f949253bdf6c5a2.tar.gz
Add secure storage service docs
Adds a description of the secure storage service. Also updates and fixes a few other documentation niggles. Signed-off-by: Julian Hall <julian.hall@arm.com> Change-Id: Ie212cc12344f71a2ef2f9d683a967b0433acf866
-rw-r--r--docs/developer/docs-build.rst6
-rw-r--r--docs/developer/project-structure.rst22
-rw-r--r--docs/developer/service-descriptions/index.rst1
-rw-r--r--docs/developer/service-descriptions/secure-storage-service-description.rst172
-rw-r--r--docs/developer/service-descriptions/uml/InternalTrustedDeploymentDiagram.puml20
-rw-r--r--docs/developer/service-descriptions/uml/ProtectedProxyDeploymentDiagram.puml25
-rw-r--r--docs/developer/service-descriptions/uml/SecureStorageClassDiagram.puml28
-rw-r--r--docs/developer/software-requirements.rst2
-rw-r--r--docs/developer/writing-documentation.rst2
9 files changed, 263 insertions, 15 deletions
diff --git a/docs/developer/docs-build.rst b/docs/developer/docs-build.rst
index 3ae422434..9f36e649e 100644
--- a/docs/developer/docs-build.rst
+++ b/docs/developer/docs-build.rst
@@ -1,5 +1,5 @@
-Building Documentation
-======================
+Documentation Build Instructions
+================================
To create a rendered copy of this documentation locally you can use the
`Sphinx`_ tool to build and package the plain-text documents into HTML-formatted
@@ -57,7 +57,7 @@ From the ``docs`` directory of the project, run the following commands.
. ~/sphinx-venv/bin/activate
make clean
- make SPHINXOPTS=-W html
+ make
deactivate
Output from the build process will be placed in:
diff --git a/docs/developer/project-structure.rst b/docs/developer/project-structure.rst
index b070510d8..b69af9850 100644
--- a/docs/developer/project-structure.rst
+++ b/docs/developer/project-structure.rst
@@ -38,11 +38,11 @@ deployments::
deployment-name = <descriptive-name>/<environment>
deployments
- |-- secure-storage/opteesp
+ |-- protected-storage/opteesp
|-- crypto/opteesp
|-- ts-demo/arm-linux
- |-- component-test/posix-x86
- |-- ts-lib/posix-x86
+ |-- component-test/linux-pc
+ |-- libts/linux-pc
The trusted services project uses CMake to configure and generate build files. A CMakeLists.txt file exists
for each deployment to define the set of components, any deployment specific configuration and anything
@@ -71,9 +71,9 @@ An environment represents the execution context in which a built image runs. Th
represented in the project structure, one for each supported isolated execution context. Files related to a
particular environment live under a sub-directory whose name describes the environment. For example:
- - opteesp An S-EL0 secure partition hosted by OP-TEE
- - arm-linux Linux user-space, cross compiled for Arm.
- - linux-pc Native PC POSIX environment
+ - *opteesp* An S-EL0 secure partition hosted by OP-TEE
+ - *arm-linux* Linux user-space, cross compiled for Arm.
+ - *linux-pc* Native PC POSIX environment
Files related to an environment will tend to live outside of the project tree and will need to be imported
in some way. How this is handled will depend on the environment. An environment will generally provide the
@@ -113,8 +113,9 @@ provider components. The following illustrates this::
| |-- common
| | |-- test
| |-- secure-storage
- | | |-- client
- | | |-- provider
+ | | |-- frontend
+ | | |-- backend
+ | | |-- factory
| | |-- test
| |-- crypto
| | |-- client
@@ -146,8 +147,9 @@ the following about the scope of the tests::
| |-- common
| | |-- test <-- Tests for the common service component
| |-- secure-storage
- | | |-- client
- | | |-- provider
+ | | |-- frontend
+ | | |-- backend
+ | | |-- factory
| | |-- test <-- Service level tests for the secure-storage service
If it is necessary to componentize tests further, sub-directories under the test directory may be used, say
diff --git a/docs/developer/service-descriptions/index.rst b/docs/developer/service-descriptions/index.rst
index 6f710a4d2..6762238cb 100644
--- a/docs/developer/service-descriptions/index.rst
+++ b/docs/developer/service-descriptions/index.rst
@@ -6,6 +6,7 @@ Service Descriptions
:caption: Contents:
crypto-service-description
+ secure-storage-service-description
--------------
diff --git a/docs/developer/service-descriptions/secure-storage-service-description.rst b/docs/developer/service-descriptions/secure-storage-service-description.rst
new file mode 100644
index 000000000..defb2b5af
--- /dev/null
+++ b/docs/developer/service-descriptions/secure-storage-service-description.rst
@@ -0,0 +1,172 @@
+Secure Storage Service Description
+==================================
+Service Overview
+----------------
+The Secure Storage service provides a generic persistent object store for valuable
+assets such as cryptographic keys. The confidentiality and integrity of stored data
+is typically achieved using keys that are bound to the device. The backend object
+store can be implemented in different ways, depending on available hardware such as:
+
+ * On-SoC secure world peripherals such as NV counters.
+ * A hardware unique key stored in OTP.
+ * Internal flash (on-die or in package).
+ * On-SoC crypto island with persistent storage.
+ * RPMB partition in a an external eMMC chip.
+
+The secure storage service provider architecture offers flexibility to use alternative
+backend storage implementations to suite available hardware.
+
+Service Access Protocol
+-----------------------
+A client accesses any instance of the Secure Storage service using a common secure
+storage access protocol. Although multiple secure storage service instances may exist
+on a device, they are all accessed using the same access protocol. By standardizing on
+a common protocol, client applications maintain compatibility with any secure storage
+provider instance.
+
+The protocol definition lives here::
+
+ protocols/service/secure_storage
+
+PSA Storage Classes
+-------------------
+Backend storage implementations that rely on external components, such as a flash chip,
+will require security measures that are not necessarily needed when on-chip or in-package
+storage is used. The PSA Storage API specification introduces the storage classes
+*Protected* and *Internal Trusted* to distinguish between externally and internally provided
+storage. These storage class designations are used for naming secure storage service instances.
+For example, the secure storage deployment that uses an RPMB backend is referred to as
+Protected Storage. The two storage classes have the following characteristics. Both
+classes of storage are required to support the notion of data ownership and to implement
+access control based on policy set by the owner.
+
+Internal Trusted Storage
+''''''''''''''''''''''''
+Internal trusted storage uses isolated or shielded locations for storage. Example
+storage backends could be on-die or in package flash memory that is inherently secure.
+Alternatively, storage may be delegated to an on-die secure enclave that offers equivalent
+security properities. An external storage device may also be used, as long as there is a
+cryptographic binding between the owning secure partition and the stored data that prevents
+unauthorized access to the storage device.
+
+To provide a persisent store for fundamental objects such as device ID and trust anchor
+certificates, access control based on the secure lifecycle state should be possible to
+support access policies such as r/w during manufacture but read-only in all other lifecycle
+states.
+
+Protected Storage
+'''''''''''''''''
+Protected storage uses an external memory device for persistent storage. To meet PSA
+security goals, the following protection measures should exist:
+
+ * Privacy and integrity protection to prevent data access and modification by an
+ unauthorized agent.
+ * Replay protection to prevent the current set of stored data being replaced by an
+ old set.
+
+Common implementation options for a protected store are:
+
+ * RPMB partition in an eMMC device. Access to the device is brokered by a normal-world
+ agent such as tee-supplicant.
+ * Dedicated serial flash device with secure-world only access.
+ * Normal-world filesystem for backend storage. Data is encrypted and integrity protected
+ in the secure-world.
+
+PSA Storage C API
+-----------------
+For client application developers who wish to use the PSA Storage API to access secure
+storage, two storage frontends are available; one that implements the Protected Storage
+API and another that implements the Internal Trusted Storage API.
+
+Storage Frontend and Backend Separation
+---------------------------------------
+For flexibility, secure storage components are separated between frontend and backend.
+All storage backends implement a common public interface and may be used with any storage
+frontend. A storage frontend presents an interface that suites a particular type of consumer.
+The following class diagram illustrates how a storage frontend is decoupled from any concrete
+storage backend through the use of an abstract storage backend interface.
+
+.. uml:: uml/SecureStorageClassDiagram.puml
+
+Some example storage frontends:
+
+ * Secure storage service provider - provides access using the secure storage access protocol.
+ * ITS frontend - provides secure storage access via PSA Internal Trusted Storage C API
+ * PS frontend - provides secure storage access via PSA Protected Storage C API
+
+Some example storage backends:
+
+ * RPMB storage backend
+ * Secure enclave storage backend
+ * Normal-world filesystem backend
+ * Secure storage service client
+
+Components related to storage frontends and backends live under the following TS project directories::
+
+ components/service/secure_storage/frontend
+ components/service/secure_storage/backend
+
+Storage Frontend and Backend Responsibilities
+---------------------------------------------
+A storage frontend is responsible for presenting an interface that is suitable for a particular
+type of consumer. For example, the Mbed TLS library depends on the PSA Internal Trusted Storage C
+API for accessing persistent storage. The ITS frontend provides an implementation of this API at
+its upper edge. Where appropriate, a storage frontend will be responsible for sanitizing input
+parameters.
+
+A storage backend is responsible for:
+
+ * Realizing the common storage backend interface.
+ * Implementing per object access control based on the provided client ID. The client ID associated
+ with the creator of an object is treated as the object owner.
+ * Providing persistent storage with appropriate security and robustness properties.
+
+Storage Factory
+---------------
+To decouple generic code from environment and platform specific code, a storage factory
+interface is defined that provides a common interface for constructing storage backends.
+A concrete storage factory may use environment specific methods and configuration to construct
+a suitable storage backend. Allows new storage backends to be added without impacting service
+provider implementations. The factory method uses PSA storage classifications to allow a
+service provider to specify the security characteristics of the backend. How those security
+characteristics are realized will depend on the secure processing environment and platform.
+
+A concrete storage factory may exploit any of the following to influence how the storage
+backend is constructed:
+
+ * Environment and platform specific factory component used in deployment
+ * Runtime configuration e.g. from Device Tree
+ * The PSA storage classification specified by the SP initialization code.
+
+Concrete storage factory components live under the following TS project directory::
+
+ components/service/secure_storage/factory
+
+Storage Frontend/Backend Combinations
+-------------------------------------
+The following storage frontend/backend combinations are used in different deployments.
+
+Persistent Key Store for Crypto Service Provider
+''''''''''''''''''''''''''''''''''''''''''''''''
+The Crypto service provider uses the Mbed Crypto portion of Mbed TLS to implement crypto
+operations. Persistent keys are stored via the PSA Internal Trusted Storage C API.
+In the opteesp deployment of the Crypto service provider, a storage client backend is
+used that accesses a secure store provided by a separate secure partition. The following
+deployment diagram illustrates the storage frontend/backend combination used:
+
+.. uml:: uml/InternalTrustedDeploymentDiagram.puml
+
+Proxy for OP-TEE Provided Storage
+'''''''''''''''''''''''''''''''''
+When service providers are deployed in secure partitions running under OP-TEE, access
+to OP-TEE provided secure storage is possible via an S-EL1 SP that hosts a secure storage
+provider instance. The following deployment diagram illustrates how secure storage
+access is brokered by an S-EL0 proxy:
+
+.. uml:: uml/ProtectedProxyDeploymentDiagram.puml
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/service-descriptions/uml/InternalTrustedDeploymentDiagram.puml b/docs/developer/service-descriptions/uml/InternalTrustedDeploymentDiagram.puml
new file mode 100644
index 000000000..13d26b0e7
--- /dev/null
+++ b/docs/developer/service-descriptions/uml/InternalTrustedDeploymentDiagram.puml
@@ -0,0 +1,20 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+
+node crypto_sp {
+ [its_frontend] -> [secure_storage_client]
+}
+
+node internal_trusted_store_sp {
+ [secure_storage_provider] -> [secure_flash_store]
+}
+
+[secure_storage_client] -> [secure_storage_provider]
+
+@enduml \ No newline at end of file
diff --git a/docs/developer/service-descriptions/uml/ProtectedProxyDeploymentDiagram.puml b/docs/developer/service-descriptions/uml/ProtectedProxyDeploymentDiagram.puml
new file mode 100644
index 000000000..a6d5c1405
--- /dev/null
+++ b/docs/developer/service-descriptions/uml/ProtectedProxyDeploymentDiagram.puml
@@ -0,0 +1,25 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+
+node crypto_sp {
+ [its_frontend:0] -> [secure_storage_client:0]
+}
+
+node protected_store_sp {
+ [secure_storage_provider:1] -> [secure_storage_client:1]
+}
+
+node sel1_sp {
+ [secure_storage_provider:2] -> [optee_store:2]
+}
+
+[secure_storage_client:0] -> [secure_storage_provider:1]
+[secure_storage_client:1] -> [secure_storage_provider:2]
+
+@enduml \ No newline at end of file
diff --git a/docs/developer/service-descriptions/uml/SecureStorageClassDiagram.puml b/docs/developer/service-descriptions/uml/SecureStorageClassDiagram.puml
new file mode 100644
index 000000000..60177eb6c
--- /dev/null
+++ b/docs/developer/service-descriptions/uml/SecureStorageClassDiagram.puml
@@ -0,0 +1,28 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+
+interface storage_backend
+{
+ +{abstract} set()
+ +{abstract} get()
+ +{abstract} get_info()
+ +{abstract} remove()
+ +{abstract} create()
+ +{abstract} set_extended()
+}
+
+secure_flash_store -u--|> storage_backend
+secure_storage_client -u--|> storage_backend
+null_store -u--|> storage_backend
+
+secure_storage_provider -d--> storage_backend
+its_frontend -d--> storage_backend
+ps_frontend -d--> storage_backend
+
+@enduml \ No newline at end of file
diff --git a/docs/developer/software-requirements.rst b/docs/developer/software-requirements.rst
index ec6c2e406..700c32da6 100644
--- a/docs/developer/software-requirements.rst
+++ b/docs/developer/software-requirements.rst
@@ -23,7 +23,7 @@ The following tools are required:
(Note: the compiler part of the OP-TEE build environment works too.)
* For `linux-pc` environment use the native version of GCC available in your Linux distribution.
-To build the documentation, please refer to :ref:`Building Documentation`.
+To build the documentation, please refer to :ref:`Documentation Build Instructions`.
.. todo:: Add info on commit validation dependencies (checkpatch, uncrustify, etc...)
diff --git a/docs/developer/writing-documentation.rst b/docs/developer/writing-documentation.rst
index 850d9cd83..eb10449e3 100644
--- a/docs/developer/writing-documentation.rst
+++ b/docs/developer/writing-documentation.rst
@@ -1,4 +1,4 @@
-Writing documentation
+Writing Documentation
=====================
|TS| is documented using `Sphinx`_, which in turn uses Docutils and `Restructured Text`_ (|REST| hereafter).