DOC: update documentation.
Add documentation covering:
- developer information about architecture
- project structure and building
- project overview and service descriptions
- the portability model for supporting hardware
Signed-off-by: Julian Hall <julian.hall@arm.com>
Co-Authored-By: Gyorgy Szing <gyorgy.szing@gmail.com>
Change-Id: I8bf9c01a66350719d82a7ca2bc1c78a8ab17978d
diff --git a/docs/overview/goals.rst b/docs/overview/goals.rst
new file mode 100644
index 0000000..0e63122
--- /dev/null
+++ b/docs/overview/goals.rst
@@ -0,0 +1,43 @@
+Project Goals
+=============
+
+The trusted services project aims to make it easy to write new trusted services that can be deployed in different secure
+processing environments without having to rewrite lots of code. The aim is to make component reuse as painless as possible by
+keeping software components free of unnecessary dependencies on anything environment or platform specific.
+
+The project structure has been designed to help meet the following goals:
+
+ - **Support multiple deployments** - allow for different deployments where common service code can be built to run in
+ different environments.
+ - **Support multiple processing environments** - allow support for new processing environments to be easily added.
+ - **Support multiple hardware platforms** - provide a portability model for different hardware.
+ - **Avoid the need for duplicated code** - by encouraging code sharing, code duplication can be minimized.
+ - **Avoid cross-talk between builds** - allow images for different deployments to be built independently without any nasty
+ cross dependencies.
+ - **Support and promote automated testing** - writing and running test cases that operate on individual components,
+ component assemblies or complete service deployments should be easy and accessible.
+ - **Support component sharing with deployment specific configuration** - where necessary, a deployment specific build
+ configuration may need to be applied to a shared component.
+ - **Control which versions of external components are used** - where external components such as libraries are used, it
+ should be possible to peg to a specific version.
+
+Enhancing Security through Reuse and Testing
+--------------------------------------------
+
+Reuse of common framework and service components across multiple deployments will help to shake out bugs that may present
+security vulnerabilities. Repeated reuse of a piece of software in different contexts and by different people can help harden
+the code through progressive improvements and bug fixes. Reuse of a common framework also creates opportunities for standard
+solutions to security problems such as service discovery, client identification, authentication and access control.
+
+The confidence to reuse components needs to be underpinned by testing. A project structure that makes it easy to add tests, run
+tests and live with an increasing suite of test cases is fundamentally important in meeting security goals. Although trusted
+service code will be deployed in execution environments where test and debug can be somewhat awkward, a large amount of the code
+can be tested effectively in a native PC environment. Where code can be tested on a PC, it should be. It should be easy for
+anyone to build and run tests to give confidence that a component passes all tests before changes are made and that code changes
+haven't broken anything.
+
+----------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/overview/index.rst b/docs/overview/index.rst
new file mode 100644
index 0000000..4706034
--- /dev/null
+++ b/docs/overview/index.rst
@@ -0,0 +1,15 @@
+About trusted services
+======================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents:
+
+ introduction
+ goals
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/overview/introduction.rst b/docs/overview/introduction.rst
new file mode 100644
index 0000000..674e0b5
--- /dev/null
+++ b/docs/overview/introduction.rst
@@ -0,0 +1,69 @@
+What are trusted services?
+==========================
+
+The term 'trusted service' is used as a general name for a class of application that runs in an isolated
+processing environment. Other applications rely on trusted services to perform security related operations in
+a way that avoids exposing secret data beyond the isolation boundary of the environment. The word 'trusted'
+does not imply anything inherently trustworthy about a service application but rather that other applications
+put trust in the service. Meeting those trust obligations relies on a range of hardware and firmware
+implemented security measures.
+
+The Arm architecture, in combination with standard firmware, provides a range of isolated processing environments
+that offer hardware-backed protection against various classes of attack. Because of their strong security
+properties, these environments are suitable for running applications that have access to valuable assets
+such as keys or sensitive user data. The goal of the Trusted Services project is to provide a framework in
+which security related services may be developed, tested and easily deployed to run in any of the supported
+environments. A core set of trusted services are implemented to provide basic device security functions such
+as cryptography and secure storage.
+
+Example isolated processing environments are:
+
+ - **Secure partitions** - secure world VMs managed by a secure partition manager
+ - **Trusted applications** - application environments managed by a TEE
+ - **Integrated microcontroller** - a secondary MCU used as a secure enclave
+
+Typical problems solved by trusted services
+-------------------------------------------
+
+The following are examples of how trusted services can solve common device security problems.
+
+
+Protecting IoT device identity
+''''''''''''''''''''''''''''''
+
+During the provisioning process, an IoT device is assigned a secure identity that consists of a public/private
+key pair and a CA signed certificate that includes the public key. The device is also provisioned with the
+public key corresponding to the cloud service that it will operate with. The provisioned material is used
+whenever a device connects to the cloud during the authentication process. To prevent the possibility
+of device cloning or unauthorized transfer to a different cloud service, all provisioned material must be
+held in secure storage and access to the private key must be prevented. To achieve this, the certificate
+verification and nonce signing performed during the TLS handshake is performed by the Crypto trusted service
+that performs the operations without exposing the private key.
+
+
+Protecting Software Updates
+'''''''''''''''''''''''''''
+
+To ensure that software updates applied to a device originate from a legitimate source, update packages are
+signed. A signed package will include a signature block that includes a hash of the package contents within
+the signed data. During the update process, a device will verify the signature using a provisioned public key
+that corresponds to the signing key used by the update originator. By holding the public key in secure storage
+and performing the signature verification using the Crypto service, unauthorized modification of the update
+source is prevented.
+
+
+Secure Logging
+''''''''''''''
+
+A managed IoT device will often be configured by an installation engineer who has physical access to the
+device. To allow a cloud operator to audit configuration changes, it is necessary to keep a log of
+configuration steps performed by the installation engineer. To avoid the possibility of fraudulent
+modification of the audit log, a device signs log data using a device unique key-pair. The public key
+corresponding to the signing private key may be retrieved by the cloud operator to allow the log to
+be verified. To protect the signing key, the Crypto service is used for signing log records.
+
+--------------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause