diff options
author | Julian Hall <julian.hall@arm.com> | 2020-11-25 03:07:21 +0100 |
---|---|---|
committer | György Szing <gyorgy.szing@arm.com> | 2021-01-28 00:06:35 +0000 |
commit | e76ade88c741bd1c052624082a869a60eebd420f (patch) | |
tree | 9547270318c9ae5539b40d8d9003e946d278e152 | |
parent | 3924b1b22e28014e0905ce80cd4c4dae10a6bca5 (diff) | |
download | trusted-services-e76ade88c741bd1c052624082a869a60eebd420f.tar.gz |
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
51 files changed, 2973 insertions, 15 deletions
diff --git a/docs/conf.py b/docs/conf.py index f9ccb6fca..e35a28ed1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- # -- Metadata about this file ------------------------------------------------ -__copyright__ = "Copyright (c) 2020 Arm Limited" +__copyright__ = "Copyright (c) 2020-2021 Arm Limited and Contributors." __license__ = "SPDX-License-Identifier: BSD-3-Clause" # Configuration file for the Sphinx documentation builder. @@ -102,8 +102,7 @@ autosectionlabel_maxdepth = 1 # -- Options for plantuml ---------------------------------------------------- plantuml_output_format = 'svg_img' - # -- Options for todo extension ---------------------------------------------- # Display todos -todo_include_todos = True +todo_include_todos = False diff --git a/docs/developer/arch-overview.rst b/docs/developer/arch-overview.rst new file mode 100644 index 000000000..d2f8c4d17 --- /dev/null +++ b/docs/developer/arch-overview.rst @@ -0,0 +1,79 @@ +Architecture Overview +===================== + +The Trusted Services project provides a framework for developing applications that can be built and deployed in +different secure processing environments and on different hardware platforms. The structure and conventions adopted +are designed to maximize opportunities for component reuse. The project adopts a portability model based on the +*ports and adapters* architectural pattern, which promotes loose coupling between an application +and its environment. The model allows applications to be deployed in a diverse range of environments from full +featured trusted OSs, such as OP-TEE, to bare metal secure partitions. + +For a more in-depth description of how the ports and adapters pattern is applied, see: +:ref:`Portability Model` + +Service Model +------------- + +Trusted services conform to a client/server model where service specific operations are invoked using an RPC mechanism. +The realization of the RPC layer and any underlying messaging layer may vary between deployments but the service layer +should be identical for every deployment of a particular service. The following diagram illustrates the common layered +model and where standardization on layer interfaces and protocols will be aimed for. + +.. image:: image/TrustedServicesLayers.svg + +The layered service model is reflected in the project source tree where software components are organized by layer and role. +Because components that perform the same role are inter-changeable, there is much flexibility to meet the needs of +different deployments. For example: + + - An instance of the secure storage service could be accessed by different types of client, each presenting + different upper edge APIs to suite the needs of different applications. Some different secure storage clients + could be: + + - A filesystem driver that presents a filesystem mount for user-space access to stored objects. + - A client that presents the PSA Protected Storage API. + + - Different types of secure storage provider are possible, each accessed using a common protocol. Some different + secure storage providers could be: + + - A secure storage provider that uses an external RPMB serial flash device for storage. + - A secure storage provider that encrypts objects before passing them to a normal world agent to access + file-backed storage. + + - Different RPC layers may be used to access services deployed in different secure processing environments. + +Service Deployments +------------------- + +The ability to deploy trusted services over a range of secure processing environments allows a consistent view of +services to be presented to clients, independent of the back-end implementation. For a particular service deployment, a +concrete set of build-time and run-time dependencies and configurations must be defined. Representing each deployment +in the project structure allows multiple deployments to be supported, each reusing a subset of shared components. +The following diagram illustrates the dependencies and configurations that must be defined for a fully specified +deployment. + +.. uml:: uml/ServiceDeployment.puml + +Currently supported deployments are listed here: +:ref:`Deployments` + +Service Access Protocols +------------------------ + +As mentioned in the section on layering, trusted services are accessed by clients via an RPC layer. Independent of the +mechanics of the RPC layer, a service access protocol is defined by: + + - A supported set of operations, each qualified by an opcode. + - A set of request and response message parameter definitions, one for each operation. + +The main documentation page for service access protocols is here: :ref:`Service Access Protocols`. + +The trusted service framework can accommodate the use of arbitrary serializations for message parameters. So far, +message protocols using Google Protocol Buffers and packed C structures have been defined. + +.. image:: image/ServiceAccessProto.svg + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/developer/b-test.rst b/docs/developer/b-test.rst new file mode 100644 index 000000000..4ef53c012 --- /dev/null +++ b/docs/developer/b-test.rst @@ -0,0 +1,6 @@ +.. include:: ../../tools/b-test/Readme.rst + +.. + *Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + + SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/developer/build-instructions.rst b/docs/developer/build-instructions.rst new file mode 100644 index 000000000..5fe6c634a --- /dev/null +++ b/docs/developer/build-instructions.rst @@ -0,0 +1,140 @@ +Build Instructions +================== +All trusted service builds use CMake to create native build files for building and installing service binaries +and other build products. Details about the tools needed for building are specified here: +:ref:`Software Requirements`. + +All top-level build files are located beneath the 'deployments' parent directory under a sub-directory +for each deployment. For more information about the project directory structure, see: +:ref:`Project Structure`. + +Build Flow +---------- +All deployment builds follow a common flow that results in the creation of executable binaries or libraries +and the installation of files into an output directory. Deploying the contents of the output directory into +the target environment is handled in an environment specific way and is not part of the common build +flow. The build flow conforms to the conventional CMake process where building takes place in to following +two stages: + + 1. Native build files, such as makefiles, are generated from CMake configuration files. + 2. Native build tools, such as make, are used to build and install items, ready for deployment. + +The following activity diagram illustrates the common deployment build flow. The green activity states +lie outside of the common build flow. Environment specific instructions are provided for deploying into +different environments: + +.. uml:: uml/BuildFlow.puml + +Building and Installing +----------------------- +When building from a clean environment where no generated build files exist, it is necessary to run +the CMake command, specifying the source directory, the build directory and optionally, the install +directory where build output is installed. + +To illustrate the steps involved, we will build the 'component-test' executable to run in the +'linux-pc' environment. The built executable is a standalone program that uses the CppUTest +framework to run a set of component level tests on components from within the project. For this +example, it is assumed that we are building under Linux and 'make' is used as the native build tool. + +The described steps may be used for any of the deployments under the top-level *deployments* directory. + +Starting from the project root directory, change directory to the relevant deployment directory:: + + cd deployments/component-test/linux-pc + +Build file generation is performed using the CMake command. If no CMAKE_INSTALL_PREFIX path is +specified, build output will be installed in the default location (*build/install*). To generate +build files that install to the default location, use:: + + cmake -S . -B build + +To generate build files that install to an alternative location, use:: + + cmake -S . -B build -DCMAKE_INSTALL_PREFIX=<install_dir> + +Having successfully generated build files, the native build tool may be run to build and install +files using:: + + cd build + make install + +In the above example, all build output is written to a sub-directory called 'build'. You +are free to choose any location for build output. + +Dependencies on external components and in-tree built objects, such as libraries, +are handled automatically by the build system during the *generating* phase. External components +are fetched from the relevant source repository and built as part of the build context for the +deployment binary being built. This allows deployment specific configuration and compiler options +to be applied to the external component without impacting other builds. Dependencies on in-tree +built libraries are handled in a similar manner. + +For information on running tests, see: +:ref:`Running Tests`. + +For more information on deployments, see: +:ref:`Deployments`. + +Installed build output files +---------------------------- +On successfully completing the *building* phase of the build flow, a set of build output files are +installed to the directory specified by CMAKE_INSTALL_PREFIX. The set of installed files will +depend on the type of build and the environment in which the files will be deployed. The following +table summarizes what files are installed for different typed of build during the *installing* phase +of the build flow: + +.. list-table:: Example build output files + :header-rows: 1 + + * - Deployment type + - Environment + - Files installed + * - Binary executable + - linux-pc, arm-linux + - | *bin/* - program binary + * - Shared library + - linux-pc, arm-linux + - | *include/* - public header files + | *lib/* - shared library + | *lib/cmake/* - cmake target import file + * - SP image + - opteesp + - | *bin/* - stripped elf file for SP + | *lib/make* - OP-TEE helper makefile + * - SP collection + - opteesp + - | *bin/* - set of stripped elf files + | *lib/make/* - set of OP-TEE helper makefiles + + +Deploying installed files +------------------------- +Having built and installed build output files to a known directory, further steps may be needed to +deploy the files into the target processing environment. The nature of these steps will be different +for different environments. + +To avoid overly complicating the common Trusted Services build system, details of how installed files +are deployed into the target execution environment are handled separately and may rely on environment +specific tools. + +Some example deployment methods are: + + * A filesystem share exists between a build machine and the target machine. Files installed into the shared directory are + directly accessible by the target. + * Installed files are incorporated into a third-party build process e.g. OP-TEE. + +The following guides provide instructions on deploying to different environments: + +* :ref:`Deploying trusted services in S-EL0 Secure Partitions under OP-TEE` +* :ref:`Deploying Programs on FVP` + +Batch Building +-------------- +To support batching building of a set of deployments, a tool called b-test is included. For +more information, see +:doc:`b-test page <./b-test>` + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/developer/deployments.rst b/docs/developer/deployments.rst new file mode 100644 index 000000000..74fdeb3d1 --- /dev/null +++ b/docs/developer/deployments.rst @@ -0,0 +1,49 @@ +Deployments +=========== +In the context of the Trusted Services project, a deployment represents a unit of functionality +that is built for a specific environment. You can find out more about deployments here +:ref:`Project Structure`. + +The following table lists currently supported deployments: + +.. list-table:: Supported deployments + :header-rows: 1 + + * - Deployment Name + - Environments + - Provides + - Used for + * - component-test + - linux-pc, arm-linux + - Standalone tests for components and integrations + - Test driven development and regression testing + * - ts-service-test + - linux-pc, arm-linux + - Service API level tests + - Tests services from perspective of client application + * - ts-demo + - linux-pc, arm-linux + - Demonstration client application + - Example user-space client application + * - libts + - linux-pc, arm-linux + - Provides standard client interface for locating services and establishing RPC sessions + - Client application development + * - crypto + - opteesp + - Crypto trusted service + - Production deployments + * - secure-storage + - opteesp + - Secure storage trusted service + - Production deployments + * - libsp + - opteesp + - FF-A interface library + - FF-A library used in secure partition environments + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/developer/docs-build.rst b/docs/developer/docs-build.rst new file mode 100644 index 000000000..3ae422434 --- /dev/null +++ b/docs/developer/docs-build.rst @@ -0,0 +1,77 @@ +Building Documentation +====================== + +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 +pages. + +If you are building the documentation for the first time then you will need to +check that you have the required software packages, as described in the +*Prerequisites* section that follows. + +Prerequisites +------------- + +For building a local copy of the |TS| documentation you will need, at minimum: + +- GNUMake +- Python 3 (3.5 or later) +- PlantUML (1.2017.15 or later) + +You must also install the Python modules that are specified in the +``requirements.txt`` file in the root of the ``docs`` directory. These modules +can be installed using ``pip3`` (the Python Package Installer). Passing this +requirements file as an argument to ``pip3`` automatically installs the specific +module versions required. + +Example environment +------------------- + +An example set of installation commands for Linux with the following assumptions: + #. OS and version: Ubuntu 18.04 LTS + #. `virtualenv` is used to separate the python dependencies + #. pip is used for python dependency management + #. `bash` is used as the shell. + +.. code:: shell + + sudo apt install make python3 python3-pip virtualenv python3-virtualenv plantuml + virtualenv -p python3 ~/sphinx-venv + . ~/sphinx-venv/bin/activate + pip3 install -r requirements.txt + deactivate + +.. note:: + More advanced usage instructions for *pip* are beyond the scope of this + document but you can refer to the `pip homepage`_ for detailed guides. + +.. note:: + For more information on Virtualenv please refer to the `Virtualenv documentation`_ + +Building rendered documentation +------------------------------- + +From the ``docs`` directory of the project, run the following commands. + +.. code:: shell + + . ~/sphinx-venv/bin/activate + make clean + make SPHINXOPTS=-W html + deactivate + +Output from the build process will be placed in: + +:: + + <tf-a CMF root>/docs/_build/html/ + +-------------- + +.. _Sphinx: http://www.sphinx-doc.org/en/master/ +.. _pip homepage: https://pip.pypa.io/en/stable/ +.. _`Virtualenv documentation`: https://virtualenv.pypa.io/en/latest/ + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/developer/image/ServiceAccessProto.svg b/docs/developer/image/ServiceAccessProto.svg new file mode 100644 index 000000000..aa7f9117a --- /dev/null +++ b/docs/developer/image/ServiceAccessProto.svg @@ -0,0 +1,3 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg xmlns="http://www.w3.org/2000/svg" style="background-color: rgb(255, 255, 255);" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="681px" height="331px" viewBox="-0.5 -0.5 681 331" content="<mxfile host="confluence.arm.com" modified="2020-10-05T19:50:28.353Z" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:81.0) Gecko/20100101 Firefox/81.0" etag="Bzz9yr5hRQzs9jvCqYym" version="12.7.1.1" type="atlas"><mxAtlasLibraries/><diagram id="Yb5y5pyupjcRv4pKJqIq" name="Page-1">7VjZbuM2FP0aA+1DDEqyJPsxXibTogOkcNt0ngpaupLYUKRA0Vu/vqRE7coKZ9wCozyEPNzPPZe81xNnlZ7uBM6SLzwEOrFReJo464ltWzN7rv5p5FwiC98AsSCh6dQAW/IPGBAZdE9CyDsdJedUkqwLBpwxCGQHw0LwY7dbxGl31QzHZkXUANsAUxh0eyChTEp07rZ6fwYSJ9XKFjItKa46GyBPcMiPLcjZTJyV4FyWpfS0AqrJq3gpx316orXemAAmXzPgTPh8c/f7WsLjr7cPm+TIf97d2OUsB0z35sD3gksecJqbXctzRYU6QKaLmkMQE2cZcSa3pt1S9TzDAWHxbzzTAFKIxLuKtZmp12xZsxK45zmRhDMFUYhUyzKRKTVTUrwD2uoRqMMWax9ASKLM9Euvw45LyVPVAVMSj464NQ1Sb3MZEUpXnHJRnNGJXP2nzyIFf4RWi1d85tQtvPwUPrSHMZFeGE4tyNjnDngKUpxVF9PqGKkYX7mxfAMcG+nVekraspsbEBu5x/XcjSJUwYjiDQJxBgLJQRxIAH8RzWuEA5hmWjIT26PaeDuhSrEu/VBIabePtPtDRFhpI+WEhMKPA3kJvmch6L1opRwTImGrBKVbj+pu6eriAmR7bo9sNCTbckfI9j6K69mA623JtQJXlOijXpu0Gxt1NTrK2phEP4w19xnWlAIPRF9W1+bN8f5rtHkD2gYkAQtv9ROqajwD1iVFcSHOfxoCi8pXXZm6VXV9ajeuz1XtRGQxbGq7pvq11dSM0pV6EAs/EX2+ohbiPCls96xxcr4XAbzsbhKLGOTLVyCEVaTwhKlbphy7NipMAMWSHLrxxZh5zQr3nGjHbzxw3pOS1ZNIeXAzrB0QDGbqvTd9rZXMDCZSmsDnVrdMd8if2XH9jFVXrd+JVFShnLIRc83q+/XtX0rf1nv17V9Z3+7/U989sVjOO+VtuW5vIvdD5D1zr6Du+cvqbmm5Tj066kKviZJTEoZ6xmUV/aenWGd60zK5sqd/79PsJ2b8aFmkeZYWfpECOnO9hm77DFiv6S2mRbCsIkNsIvYFGgnDEXYQHgvDl2sfITQMw6Piu8xjbc/saS849P0K6USHNdp2BBvV8MVf7cXA7q0g+wvkuU5nbbRhAQ9VKnYtUcgjf8DnjijQ1KtV4Q4tHgTgFvYbWNzxnIUTXih87b+dI2HYbPYtw7Dq8W5Z9A4YCCyhOGzwqKbds7KAlFU1THQWtRoYV5HQS5+7ZDLOoMe8gSqLmwT8SXuPBcrdUPrNCXs99yUc17d0VNm2sDMSZ6MRA/dfmcsZeJhBf7+qy6s6oiT746Uw5w3OXSdQ1a09HzH+t7+zrWFe/0oXZ2UgpUCT/SOKWbwv7vjvvv/81T7m+GMJ9jscX1Wbn23LiK758dvZ/As=</diagram></mxfile>"><defs/><g><path d="M 230 0 L 270 0 L 270 14 L 450 14 L 450 180 L 230 180 L 230 14 Z" fill="#f5f5f5" stroke="#666666" stroke-miterlimit="10" pointer-events="all"/><path d="M 230 14 L 270 14" fill="none" stroke="#666666" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 197px; margin-left: 340px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #333333; line-height: 1.2; pointer-events: all; font-weight: bold; white-space: nowrap; ">Protocols</div></div></div></foreignObject><text x="340" y="209" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle" font-weight="bold">Protocols</text></switch></g><rect x="265" y="70" width="150" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 148px; height: 1px; padding-top: 100px; margin-left: 266px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">service_interface.proto<br />(Protobuf definition file)</div></div></div></foreignObject><text x="340" y="104" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">service_interface.proto...</text></switch></g><rect x="0" y="270" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 300px; margin-left: 1px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Service Client</div></div></div></foreignObject><text x="60" y="304" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Service Client</text></switch></g><rect x="560" y="270" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 300px; margin-left: 561px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Service Provider</div></div></div></foreignObject><text x="620" y="304" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Service Provider</text></switch></g><path d="M 30 270 L 30 110 Q 30 100 40 100 L 262.76 100" fill="none" stroke="#000000" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke"/><path d="M 256.88 103.5 L 263.88 100 L 256.88 96.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 650 270 L 650 110 Q 650 100 640 100 L 417.24 100" fill="none" stroke="#000000" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke"/><path d="M 423.12 96.5 L 416.12 100 L 423.12 103.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 562 92.5 L 600 127.16 L 562 161.83 L 562 142.16 C 496 142.17 442.5 212.83 442.5 300 C 442.5 196.26 496 112.17 562 112.16 Z" fill="#f0a30a" stroke="#bd7000" stroke-miterlimit="10" transform="rotate(90,521.25,196.25)" pointer-events="all"/><path d="M 155 288 L 525 288 L 525 270 L 560 300 L 525 330 L 525 312 L 155 312 L 155 330 L 120 300 L 155 270 Z" fill="#cce5ff" stroke="#36393d" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 300px; margin-left: 340px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: nowrap; ">Protobuf Message Encoding</div></div></div></foreignObject><text x="340" y="304" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Protobuf Message Encoding</text></switch></g><rect x="471.25" y="200" width="100" height="30" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 98px; height: 1px; padding-top: 215px; margin-left: 473px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Generate pack/unpack code in C</div></div></div></foreignObject><text x="473" y="219" fill="#000000" font-family="Helvetica" font-size="12px">Generate pack/un...</text></switch></g><path d="M 199.5 90 L 237.5 124.66 L 199.5 159.33 L 199.5 139.66 C 133.5 139.67 80 210.33 80 297.5 C 80 193.76 133.5 109.67 199.5 109.66 Z" fill="#f0a30a" stroke="#bd7000" stroke-miterlimit="10" transform="translate(0,193.75)scale(1,-1)translate(0,-193.75)rotate(-90,158.75,193.75)" pointer-events="all"/><rect x="120" y="200" width="120" height="30" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 118px; height: 1px; padding-top: 215px; margin-left: 122px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Generate pack/unpack code in native client language</div></div></div></foreignObject><text x="122" y="219" fill="#000000" font-family="Helvetica" font-size="12px">Generate pack/unpack...</text></switch></g></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://desk.draw.io/support/solutions/articles/16000042487" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Viewer does not support full SVG 1.1</text></a></switch></svg>
\ No newline at end of file diff --git a/docs/developer/image/TSportabilityModel.svg b/docs/developer/image/TSportabilityModel.svg new file mode 100644 index 000000000..e0635c552 --- /dev/null +++ b/docs/developer/image/TSportabilityModel.svg @@ -0,0 +1,3 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg xmlns="http://www.w3.org/2000/svg" style="background-color: rgb(255, 255, 255);" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="471px" height="371px" viewBox="-0.5 -0.5 471 371" content="<mxfile host="confluence.arm.com" modified="2021-01-21T15:49:55.792Z" agent="Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:84.0) Gecko/20100101 Firefox/84.0" etag="T4OmEHaxOAbJXEuewn-x" version="12.7.1.1" type="atlas"><mxAtlasLibraries/><diagram id="Fh55IqWZiI4TxFe46PeK" name="Page-1">7Zpbc5s4FIB/jWe2D+4YZMf2Y25tZrbddSftNN2XjAwyaAuICvlCf/1KRsIg4ZikxgRv8xLpoAv6zjnSOTI9cB1u3lMY+x+Ji4KePXA3PXDTs21rZA35PyFJpQRYk0ziUexK2U5wj38iKRxI6RK7KCk1ZIQEDMdloUOiCDmsJIOUknW52YIE5Vlj6MkZBzvBvQMDZDT7il3mZ9LJqND6DmHPVzNbA/kkhKqxFCQ+dMm6IAK3PXBNCWFZKdxco0DQU1yyfu/2PM1fjKKI1elAfvzzJ/2azsm3VTL8Mr999B/Tvp2NsoLBUi74M10mDLlceI/oCjuIl2aUrLgaaM++CPhcV3NR8kTpDxjHAXYgwyR6I9fJUgWPLzkWRR9toEci3j5GFIeI8aFy6UyJOJGrtY8Zuo+hI7qtuU1xmc/CgNcsXnQx5UrGYqibhCwF4SuTg0SzQpShTUEkubxHhM9HU95EPgVSRdJIh7K63incmkiZX1B2bqRQGpmXj7zTAy9IVTxDLSNDLe2wXeAguCYBEUNGJELHwd0flnn3wcgADuwK4GDcFPALA/httMKURKFYps6er5OV4SWMku9IQ1VBDwbYE4AdPqxQ1JWgxv0nuJQPQuy6YppKbVGyjFwk1jE4jiby3Upqwh6bpj+ssvym9DA29ABdGAtUug7KLA7YdjN2nGNINZoFeqNT0pt0ml7FtntSetNO05u0TE+dhd3A1wevzHUtq9P42vZdywxku4SvdecFBr5ZANmC0NDgdzbBj32hhaF2y8GPSpafCvv5MDz13ceoecu1NNOdmqF7leWCxpjVSJVQ5F6KqwBhegFMEuyUUaENZg+F8jdhY29HsnazkSa3raSqEvG3fyhWCr1EdddtW1P99uqAp1zUQTWsg0HqIVbjJEauutrYo9MDOlMyivhWgFflC5EqRcoZZgSLnGmvyQwHmjFkS5fdijcY+kiT8kBgpA2UoTEG2hpWvu5fsDUzSzze6dKzwWL7d6TNTY9vTD+tyrAbu9GwzNykM+yGbbMzM5POsJu0zE5N1g12rw2emZR0B17bXqtYdRJe28eFbSYkBrwDuGASZz8ILfBGIG6SH88/NYBVV9qnjIvtOrnEWcTFylQOx8VyxN9x8ZHjYrtODvaSvPXYu5wGPN++DjhpYwm/XSOhaNRJrVM56bSmjypTOjsfHWo+ahjVHh/luodpoVksGiT73xhY2kE0HTz5Xnp77SsCXsje4Lgbhvkzn2H31CfhfJm0umH0tVPdrgiLTnuq18gE1YcBThrgyN3esx4gOM+i0A/zXACd7942Nv17yfgoqHnUQEM9td/WC0FVoHV01qBG/H4eEdS47uY8PdPNue0ACtTIds7DrS3Qvl//bzKjSU2/Vub3269f7tfj9Mt0Pftr/u8D++xfkk8f7+5oxdeVL7a0wTMs7eUWowKzV2sJ+oVTbUvQf3GfNhN+6xZnfJR7oL0Wrj83/ObV3QfFWfPdd9ng9j8=</diagram></mxfile>"><defs/><g><path d="M 197.5 90 L 302.5 90 L 355 180 L 302.5 270 L 197.5 270 L 145 180 Z" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" transform="rotate(90,250,180)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 178px; height: 1px; padding-top: 180px; margin-left: 161px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Trusted Service Provider<br />(application)</div></div></div></foreignObject><text x="250" y="184" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Trusted Service Provider...</text></switch></g><path d="M 157.5 25 L 342.5 25 L 435 185 L 342.5 345 L 157.5 345 L 65 185 Z" fill="none" stroke="#000000" stroke-miterlimit="10" transform="rotate(90,250,185)" pointer-events="all"/><rect x="230" y="305" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 315px; margin-left: 231px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Environment</div></div></div></foreignObject><text x="250" y="319" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Enviro...</text></switch></g><rect x="350" y="135" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 145px; margin-left: 351px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="375" y="149" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="350" y="175" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 185px; margin-left: 351px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="375" y="189" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="350" y="215" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 225px; margin-left: 351px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="375" y="229" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="100" y="135" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 145px; margin-left: 101px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="125" y="149" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="100" y="175" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 185px; margin-left: 101px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="125" y="189" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="100" y="215" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 225px; margin-left: 101px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="125" y="229" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="390" y="15" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 25px; margin-left: 391px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Platform</div></div></div></foreignObject><text x="410" y="29" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Platfo...</text></switch></g><ellipse cx="25" cy="145" rx="25" ry="15" fill="transparent" stroke="#000000" pointer-events="all"/><path d="M 50 145 L 93.63 145" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 98.88 145 L 91.88 148.5 L 93.63 145 L 91.88 141.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="150" y="140" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="150" y="180" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="150" y="220" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="330" y="220" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="330" y="180" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="330" y="140" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="10" y="170" width="30" height="30" fill="#ffffff" stroke="#000000" pointer-events="all"/><path d="M 40 185 L 93.63 185" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 98.88 185 L 91.88 188.5 L 93.63 185 L 91.88 181.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><ellipse cx="375" cy="255" rx="15" ry="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><path d="M 400 225 L 430 225 Q 440 225 440 235 L 440 245 Q 440 255 430 255 L 396.37 255" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 391.12 255 L 398.12 251.5 L 396.37 255 L 398.12 258.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 125 240 L 140 255 L 125 270 L 110 255 Z" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 134.5 C 450 125.17 470 125.17 470 134.5 L 470 155.5 C 470 164.83 450 164.83 450 155.5 Z" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 134.5 C 450 141.5 470 141.5 470 134.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 400 145 L 443.63 145" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 448.88 145 L 441.88 148.5 L 443.63 145 L 441.88 141.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 174.5 C 450 165.17 470 165.17 470 174.5 L 470 195.5 C 470 204.83 450 204.83 450 195.5 Z" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 174.5 C 450 181.5 470 181.5 470 174.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 400 185 L 443.63 185" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 448.88 185 L 441.88 188.5 L 443.63 185 L 441.88 181.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 110 255 L 60 255 Q 50 255 50 245 L 50 235 Q 50 225 60 225 L 93.63 225" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 98.88 225 L 91.88 228.5 L 93.63 225 L 91.88 221.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://desk.draw.io/support/solutions/articles/16000042487" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Viewer does not support full SVG 1.1</text></a></switch></svg>
\ No newline at end of file diff --git a/docs/developer/image/TrustedServicesLayers.svg b/docs/developer/image/TrustedServicesLayers.svg new file mode 100644 index 000000000..b57a65c69 --- /dev/null +++ b/docs/developer/image/TrustedServicesLayers.svg @@ -0,0 +1,3 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg xmlns="http://www.w3.org/2000/svg" style="background-color: rgb(255, 255, 255);" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="1083px" height="379px" viewBox="-0.5 -0.5 1083 379" content="<mxfile host="confluence.arm.com" modified="2020-10-12T14:32:15.581Z" agent="Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:81.0) Gecko/20100101 Firefox/81.0" etag="NMyOFHADfPI-JQlNiOb1" version="12.7.1.1" type="atlas"><mxAtlasLibraries/><diagram id="wNY_4wXUTk2zhrBGsPOK" name="Page-1">5Vpbd6I6FP41rnXOg7O4COpj8dJ22q5jaz22fYsQMTOBsELEy6+fBAMiYHV1vM2IDyU7N/J9e3/shFb0lje/pSCYPBEH4oqmOPOK3q5omto0Nf5HWBbSoqnmyuJS5Ejb2tBHSyiNirROkQPDjYaMEMxQsGm0ie9Dm23YAKVkttlsTPDmrAFw5YzK2tC3AYaFZkPksMnK2jAyre8gcifJzKoiazyQNJaGcAIcMsuY9E5Fb1FC2OrOm7cgFugluKz6dbfUpg9Goc/26UDu3/S+A+e2oVYHdwNj/r+nV+UoEcBTueAWRmJATelRYsMwRL7LCx0/QpT4XlwVr4YtEogomfoOFLOoFd2aTRCD/QDYonbGvYLbJszDsnqMMG4RTGjcV++Y4sftIaPkJ8zU1HStbdR5DQYjiHskRAwRn9fZ/Bkgb2RFkDLEmXrMNWBEzAkwckub38iKEWGMeOKRiM8yEyvxlT5SwrrOLUXIE/z42HCeMUkKbiHxIKML3kTWVrWG9AcZEdXUY2Zr/9ITp5lkfEs3pRFIn3bT0de08xvJfLkXzG4Gr8Fy5D18OB9jv3sTfuisWit4QR/aUwo/9QLln36v8++JvMHSJCl/lzeozT2cwVSP5QzLD/f5MUJGU3/oBt7351bTj0ok4ZVOQ8Yp1ZQ+pBGyhV8kMrGVfWU3+wcJJ3MTQa2IXxpxWfyOBp9WgO+l1xKAAYy5510cYI1zA6YXAHviggPcleQ8gsUloqbWTghb+8mcvfhDN2zMfgzf3eipsezsGaZcviOeQJ0fwTSh2x6nRv2U+G2L047vBARdgLTlETtloJYi9icEah6088dpvYBaASToOzdiqyLyEwx4smXH+QagrGjOwMVRoos3CW1ceBeFb0ZSbM+zle1FUpoj9paMwe8zvXhp3UkUkj5bqQnJlNpw9/uQr8aFbHc8QifZj20hOisYJTwmNgoxYCja3MWVkStn6K1ifi34eb2q5xxktfBeKhXdbSOp+QxFy420gqYwUuxt6cK/7oCNggOKVIRb7v2I2CBOk/MeyaONbTrbzgTaQ44julsUhmgJRvFQwnViNY2XalgVo53k8Bawf7qxPGSy7XF8lfrbp8GV14f0PEA+RyW75S59wSvftFr9IK6THHCsU/rNEch4HMKjMN28cqlRL0pCcvv8WpOv+0sKkpei4khHVpBk/o3zgSTD/C8I/1j5SALmouSjcQL5KD0FKu4orks+9EuWD9U8mH6UDHU4ASn1rOJeK7NzuHzt+DRark472MtoOgiUZzS1qoHx0MWtea3sOwLxPJFZ8jSTszYWe77f2hzmjorHhviVHRWb8VU8yV1dBzoPUnPhWS9uM9WyM/x87v+VbWYpAcUj/OsiQNXPzYBxXQxozQuLAPO68T9/ABRPuhICTCxe6SPK71xx16OEEZvg4s6BT4OCEO7mwgHhJP3KePyPghnmfeLDw1Bo5Bjck8D0o+HvMHhnWjXz4X5Ib9/d0atyOwlai5K3uEiVeNJfSb8pFCk79RGvsce5eNmXBPUQjm8N6s1h1LYYdX3w4N936GMZbH+18hiny314cf0PMqtcdf1/RnrnFw==</diagram></mxfile>"><defs/><g><rect x="1" y="17" width="320" height="360" rx="48" ry="48" fill="#e6e6e6" stroke="#432d57" stroke-width="3" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-end; justify-content: unsafe center; width: 318px; height: 1px; padding-top: 14px; margin-left: 2px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Client Processing Environment</div></div></div></foreignObject><text x="161" y="14" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Client Processing Environment</text></switch></g><rect x="471" y="17" width="610" height="360" rx="54" ry="54" fill="#e6e6e6" stroke="#b20000" stroke-width="3" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-end; justify-content: unsafe center; width: 608px; height: 1px; padding-top: 14px; margin-left: 472px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Secure Processing Environment (SPE)</div></div></div></foreignObject><text x="776" y="14" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Secure Processing Environment (SPE)</text></switch></g><rect x="21" y="137" width="280" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 278px; height: 1px; padding-top: 167px; margin-left: 22px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Trusted Service Client</div></div></div></foreignObject><text x="161" y="171" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Trusted Service Client</text></switch></g><rect x="21" y="197" width="280" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 278px; height: 1px; padding-top: 227px; margin-left: 22px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">RPC Caller</div></div></div></foreignObject><text x="161" y="231" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">RPC Caller</text></switch></g><rect x="21" y="257" width="280" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 278px; height: 1px; padding-top: 287px; margin-left: 22px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Messaging Layer</div></div></div></foreignObject><text x="161" y="291" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Messaging Layer</text></switch></g><rect x="491" y="137" width="570" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 568px; height: 1px; padding-top: 167px; margin-left: 492px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Trusted Service Provider</div></div></div></foreignObject><text x="776" y="171" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Trusted Service Provider</text></switch></g><rect x="491" y="197" width="280" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 278px; height: 1px; padding-top: 227px; margin-left: 492px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">RPC Endpoint</div></div></div></foreignObject><text x="631" y="231" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">RPC Endpoint</text></switch></g><rect x="491" y="257" width="280" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 278px; height: 1px; padding-top: 287px; margin-left: 492px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Messaging Layer</div></div></div></foreignObject><text x="631" y="291" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Messaging Layer</text></switch></g><path d="M 307.37 227 L 484.63 227" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 302.12 227 L 309.12 223.5 L 307.37 227 L 309.12 230.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 489.88 227 L 482.88 230.5 L 484.63 227 L 482.88 223.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 218px; margin-left: 390px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Call Invocation</div></div></div></foreignObject><text x="390" y="221" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Call Invocation</text></switch></g><path d="M 307.37 166.98 L 484.63 166.52" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 302.12 167 L 309.11 163.48 L 307.37 166.98 L 309.13 170.48 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 489.88 166.5 L 482.89 170.02 L 484.63 166.52 L 482.87 163.02 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 157px; margin-left: 391px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Service Ops</div></div></div></foreignObject><text x="391" y="161" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Service Ops</text></switch></g><path d="M 307.37 286.98 L 484.63 286.52" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 302.12 287 L 309.11 283.48 L 307.37 286.98 L 309.13 290.48 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 489.88 286.5 L 482.89 290.02 L 484.63 286.52 L 482.87 283.02 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 277px; margin-left: 391px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Messaging</div></div></div></foreignObject><text x="391" y="281" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Messaging</text></switch></g><rect x="101" y="187" width="120" height="20" fill="#f5f5f5" stroke="#666666" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 197px; margin-left: 102px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #333333; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Common Interface</div></div></div></foreignObject><text x="161" y="201" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle">Common Interface</text></switch></g><rect x="101" y="247" width="120" height="20" fill="#f5f5f5" stroke="#666666" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 257px; margin-left: 102px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #333333; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Common Interface</div></div></div></foreignObject><text x="161" y="261" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle">Common Interface</text></switch></g><rect x="571" y="187" width="120" height="20" fill="#f5f5f5" stroke="#666666" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 197px; margin-left: 572px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #333333; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Common Interface</div></div></div></foreignObject><text x="631" y="201" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle">Common Interface</text></switch></g><rect x="571" y="247" width="120" height="20" fill="#f5f5f5" stroke="#666666" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 257px; margin-left: 572px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #333333; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Common Interface</div></div></div></foreignObject><text x="631" y="261" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle">Common Interface</text></switch></g><ellipse cx="391" cy="222" rx="60" ry="95" fill="transparent" stroke="#000000" stroke-dasharray="3 3" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-end; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 124px; margin-left: 332px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Common<br />Protocols</div></div></div></foreignObject><text x="391" y="124" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Common...</text></switch></g><rect x="791" y="197" width="270" height="120" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 268px; height: 1px; padding-top: 257px; margin-left: 792px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Backend Services</div></div></div></foreignObject><text x="926" y="261" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Backend Services</text></switch></g><rect x="861" y="187" width="120" height="20" fill="#f5f5f5" stroke="#666666" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 197px; margin-left: 862px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #333333; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Common Interface</div></div></div></foreignObject><text x="921" y="201" fill="#333333" font-family="Helvetica" font-size="12px" text-anchor="middle">Common Interface</text></switch></g></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://desk.draw.io/support/solutions/articles/16000042487" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Viewer does not support full SVG 1.1</text></a></switch></svg>
\ No newline at end of file diff --git a/docs/developer/index.rst b/docs/developer/index.rst new file mode 100644 index 000000000..33a03cc00 --- /dev/null +++ b/docs/developer/index.rst @@ -0,0 +1,26 @@ +Developer Docs +============== + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + arch-overview + project-structure + portability-model + service-access-protocols + service-locator + deployments + service-descriptions/index + software-requirements + build-instructions + running-tests + docs-build + writing-documentation + b-test + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/developer/portability-model.rst b/docs/developer/portability-model.rst new file mode 100644 index 000000000..8305cb237 --- /dev/null +++ b/docs/developer/portability-model.rst @@ -0,0 +1,211 @@ +Portability Model +================= + +Within the Trusted Services project, an environment represents the execution environment for an application such +as a trusted service provider. Some example environments are: + + - *opteesp* - Secure partition managed by OP-TEE. + - *opteeta* - TA running under OP-TEE with access to the Global Platform internal API. + - *hfsp* - Secure partition managed by Hafnium. + +An underlying TEE or SPM that manages a secure processing environment will have its own model for porting to different hardware. +For example, OP-TEE has its own driver model that allows for alternative hardware drivers. In some cases, a secure processing +environment will not provide native support for all hardware that an application depends on. To address this, the TS +portability model allows: + + - Application interfaces to be adapted to services natively provided by a secure processing environment if they are available. + - Adapting to platform provided drivers when no native environment support is available. + +Ports and Adapters Architecture +------------------------------- + +An application is decoupled from any particular environment via a set of interfaces that reflect the needs of the application. +This model conforms to the *ports and adapters* architectural pattern that aims to avoid tight coupling between application +components and any particular environment. This pattern, also known as the *hexagonal architecture*, is often illustrated as +a hexagonal cell with the application on the inside and the platform on the outside. + +The following diagram illustrates how ports and adapters is applied in the trusted services project to provide a model for +application portability. + +.. image:: image/TSportabilityModel.svg + +The portability model has the following characteristics: + + - The application is decoupled from the environment by a set of virtual interfaces (ports) that reflect the needs of the + application. + - Those interfaces are realized by a set of adapters that either use native environment services or platform provided + services. + - For a given environment, the set of adapters that realize interfaces used by an application will always be the same, + independent of the platform. + - A platform presents interfaces that conform to conventional driver and middleware abstractions such as block drivers and + filesystems. + - The set of platform interfaces that an application depends on is defined by the set of adapters used for a deployment of an + application in a particular environment. This can form the basis for a platform configuration. + +The need to use platform provided components will depend on the native features provided by an environment. For example, the +*opteeta* environment represents the TA environment provided by OP-TEE. In its role as a trusted OS, OP-TEE provides access to +an implementation of the Global Platform Internal Core API that provides services such as secure storage. Usage of any back-end +hardware is handled by OP-TEE and its own OS components so no additional provision is needed. Bare metal environments such as +secure partitions offer few native facilities so it may be necessary to map application interfaces to platform provided drivers. +Mapping application interfaces to platform drivers is a way of extending the native services provided by an environment. + +The portability model allows for an arbitrary partitioning of hardware-backed services between native environment services and +platform drivers. + +Portability Model Example +------------------------- + +To illustrate usage of the portability model, consider deployments of the following two trusted services: + + - fTPM based on the Microsoft TPM2.0 reference implementation. + - trustedfirmware.org Crypto service based on the Mbed TLS library. + +The Microsoft TPM2.0 reference and Mbed TLS both define their own platform interfaces to allow for platform specific +implementations of features such as roll-back protected storage and entropy. Although some interfaces are similar between the +two implementations, they are not the same. These interfaces are classed as ports within the ports and adapters architecture. +To simplify the example, just the entropy platform dependency is considered. Both fTPM and Crypto service providers need access +to a cryptographic grade RNG to support key generation. How the RNG is realized will depend on: + + - What facilities the environment natively provides. + - What other trusted services are available on the device. + - Whether the environment allows for platform specific access to hardware. + - Availability of a spare hardware TRNG instance. + +Adapters will be responsible for adapting both fTPM and Crypto views of an entropy source to a suitable realization. +Some example adapters: + +fTPM adapters that realize MS entropy interface (port) +'''''''''''''''''''''''''''''''''''''''''''''''''''''' + - *Adapts to crypto service* - Uses crypto service generate_random operation + - *Adapts to TEE API* - Uses native TEE OS + - *Adapts to TRNG* - Uses platform TRNG hardware + +Crypto adapters that realize Mbed TLS entropy source interface (port) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + - *Adapts to fTPM* - Uses TPM2 getrandom command + - *TEE API* - Uses native TEE OS + - *TRNG* - Uses platform TRNG hardware + +The above examples reveal that for a given environment, a port may be realized by more than one type of adapter. For example, an +fTPM deployed within a secure partition could source entropy from either TRNG hardware or from the Crypto service. This +ambiguity may be resolved by various strategies such as: + + 1. Allow a service profile to be applied at build time that defines a core set of mandatory trusted services. A build-time + selection of alternative adapters is made, based on available core services. + 2. A built image for a trusted service deployment to a particular environment includes the superset of adapters that could be + used. A runtime configuration is applied, that specifies which adapters to use. + +Providing Platform Firmware +--------------------------- + +A goal of the TS project is to reduce barriers to deploying trusted services on different hardware platforms. To this end, +build-time and run-time coupling between TS project and platform components should be minimized. Platform providers should be +free to make any of the following choices: + + - Reuse existing drivers and driver frameworks (e.g. from tf-a, an RTOS, CMSIS). + - Provide platform components as part of a BSP. + - Maintain platform components in separate repos. + - Operate independent test, bug reporting and release processes for platform components. + - Control the logical organization and naming of different platforms within the TS project. + - Maintain whatever platform configuration files that are needed within the provider's sub-tree within the TS project. + +The platform top-level directory within the TS project provides a structure that allows platform specific components to be +contributed by different providers. Different providers are represented beneath the platform/providers directory. The virtual +platform interfaces used by some adapters are defined under platform/interface. The directory structure beneath a platform +provider's parent is organized to reflect the provider's own naming scheme for different hardware. Supported platforms are each +represented by a leaf sub-directory within the provider's subtree. + +For Arm provided platforms, the structure will look something like this:: + + platform + |-- interface + |-- providers + |--arm + |-- corstone700 + |-- fvp + |-- fvp_base_aemva + |-- fvp_base_revc-2xaemv8a + |-- platform.cmake + +Under each platform leaf directory is a file called *platform.cmake*. This file implements the common configuration and build +interface that will be used during the deployment build process. How this interface is realized is entirely down to the +platform provider. An implementation will do things like setting configuration variables for SoC, board and driver selection. +Any additional files needed to support platform configuration and build may be included within the platform provider's sub-tree. + +For product developers who want to define and maintain their own private platforms, it should be possible to override the +default platform/providers directory path to allow an alternative sub-tree to be used. A product developer is free to organize +a private sub-tree in any way that suites their needs. + +Although the TS project structure doesn't mandate it, platform specific firmware is likely to live outside of the TS project. +The ability to reuse existing drivers and driver frameworks is important for promoting adoption across hardware from different +vendors. Board and silicon vendors may reuse existing CI and project infrastructure for platform components that they maintain. + +Some special platforms are provided by the TS project itself. These are represented beneath the *ts* provider. +Current TS platforms are: + +.. list-table:: + :header-rows: 1 + :widths: 10, 90 + + * - TS Platform + - Purpose + * - ts/vanilla + - | A platform that never provides any drivers. The ts/vanilla platform should be used when an environment provides its own + | device framework and no additional drivers need to be provided by the platform. An attempt to build a deployment with + | platform dependencies on the vanilla platform will result in a build-time error. The vanilla platform is selected by + | default at build-time if no explicit platform has been specified. + * - ts/mock + - | A platform that provides a complete set of drivers that may be selected when building any deployment. The platform uses + | mock drivers that don't offer functionality suitable for production builds. The mock platform is useful for CI build + | testing of deployments with platform dependencies. You should always expect a deployment with platform dependencies to + | build when TS_PLATFORM=ts/mock. + +Determining a Platform Configuration for a Deployment +----------------------------------------------------- + +The TS project supports building and installing an application image into different environments that could be hosted on +different hardware platforms. A platform is characterized by SoC and board-level hardware and possibly by OS type components +such as device drivers and middleware. To deploy an application that depends on platform drivers, you need to tie-down: + + - *Application name* - such as the name of the service e.g. crypto, secure-storage, attestation, tpm. + - *Environment* - the environment in which the application will run e.g. bare metal secure partition, Global Platform TEE, + Trusty TEE, microcontroller RTOS. + - *Platform* - the hardware platform that hosts the environment. + +The following example illustrates how these parameters are specified via the deployment build command line:: + + cd trusted-services/deployments/crypto/opteesp + cmake -S . -B build -DTS_PLATFORM=arm/fvp/fvp_base_revc-2xaemv8a + +The combination of <application name> + <environment> allows a set of build-time platform dependencies to be generated, based on +the set of adapter components used for the deployment. This information is passed via the platform build interface to the +platform.cmake file for the specified platform via a CMake target property called TS_PLATFORM_DRIVER_DEPENDENCIES. The +translation of the platform dependency information to a suitable build configuration is handled by the platform.cmake file for +the selected platform. This separation gives a platform provider the freedom to use their own configuration conventions when +reusing existing drivers. + +To allow for out-of-tree platform definitions, the root path for platform definitions may be modified by providing an +alternative value for TS_PLATFORM_ROOT. Both TS_PLATFORM and TS_PLATFORM_ROOT may be set via the CMake command line or using +environment variables. + +Adapters +-------- + +As described above, the role of an adapter conforms to the Ports and Adapters pattern. With reference to the hexagonal cell +representation, an adapter implements an application defined inside interface and adapts it to either an environment interface +or an outside platform interface. Within the TS project, adapters are treated like any other software component and may be +reused whenever appropriate. However, because an adapter implements an application defined interface, adapter implementations +will tend to be tied to a particular application or component. The complexity of adapter implementations can vary a lot and +will depend on how closely an inside interface matches either an outside interface or an environment interface. + +The collection of adapters used for a deployment is defined by the environment specific build file for a deployment. Deployment +of the same service into a different environment may result in a different set of adapters being used. As each adapter is +treated as a separate component, a separate component.cmake file exists for each adapter. When an adapter depends on one or +more platform interfaces, the dependency must be declared in the adapter's component.cmake file. This information forms the +basis for the platform build configuration. + +-------------- + +*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/developer/project-structure.rst b/docs/developer/project-structure.rst new file mode 100644 index 000000000..b070510d8 --- /dev/null +++ b/docs/developer/project-structure.rst @@ -0,0 +1,209 @@ +Project Structure +================= + +This page describes the directory and repository structure for the trusted services project. + +Top-Level Project Organization +------------------------------ +The project is organized under the following top-level directories:: + + project + |-- docs + |-- deployments + |-- environments + |-- platforms + |-- components + |-- external + |-- protocols + |-- tools + +Top-level directories are used to organize project files as follows: + +docs +'''' + +The home for project documentation source. + +deployments +''''''''''' + +A deployment represents the build instance of a service (or in fact any unit of functionality) for a particular +environment. For each deployment, there is a single deployable output, usually a binary executable. The +deployment is concerned with configuring and building a particular set of components to run in a particular +environment. For each supported deployment, there is a leaf sub-directory that lives under a parent. The +parent directory identifies what's being deployed while the leaf sub-directory identifies where it is being +deployed. The following example illustrates how the 'what' and 'where' are combined to form fully defined +deployments:: + + deployment-name = <descriptive-name>/<environment> + + deployments + |-- secure-storage/opteesp + |-- crypto/opteesp + |-- ts-demo/arm-linux + |-- component-test/posix-x86 + |-- ts-lib/posix-x86 + +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 +environment specific. Each deployment leaf directory also holds a source file that defines the main entry +point to allow a particular set of components to be initialized before entering the application that implements +the core functionality of software being deployed. + +The directory structure for deployments supports inheritance from the deployment parent to promote reuse of +common definitions and initialization code. For example, deployments of the secure-storage service for +different environments are likely to have similarities in terms of the set of components used and in subsystem +initialization code. To avoid duplication between deployments, common cmake and source files may be located +under the deployment parent. This is illustrated in the following:: + + deployments + |-- secure-storage + |-- common.cmake <-- Common cmake file + |-- service_init.c <-- Common initialization code + |-- opteesp + |-- CMakeLists.txt <-- Includes ../common.cmake to inherit common definitions + |-- opteesp_service_init.c + +environments +'''''''''''' + +An environment represents the execution context in which a built image runs. There are different environments +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 + +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 +following: + + - Environment specific libraries that have been externally built. + - Public header files for libraries. + - An install method that takes a deployment image and installs it in the environment. + - Compiler configuration + +A deployment will include an environment specific build file (see above) that defines the list of environment +specific components used for a deployment into a particular environment. + +platforms +''''''''' + +For some deployments, an environment may not provide access to all hardware backed services needed by an +application. Files under the platforms directory are concerned with configuring and building platform specific +code that extends the capabilities of an environment. Details of how this works are described in the: +:ref:`Portability Model` + +components +'''''''''' + +Source code lives under the components directory, organized as reusable groups of source files. A component +is the unit of reuse for code that may be combined with other components to realize the functionality needed +for a deployment. Creating a new deployment should be just a case of selecting the right set of components +to provide the required functionality for the target environment. Some components may depend on other +components and others may only make sense in a particular environment. + +The components sub-tree has an organization that reflects the layered model where service components are +kept separate from RPC components and so on. There is also a separation between client components and service +provider components. The following illustrates this:: + + components + |-- service + | |-- common + | | |-- test + | |-- secure-storage + | | |-- client + | | |-- provider + | | |-- test + | |-- crypto + | | |-- client + | | |- component.cmake + | | |-- provider + |-- rpc + | |-- common + | |-- ffarpc + | | |-- caller + | | |-- endpoint + +Each leaf directory under the components parent includes a cmake file called component.cmake. This is used to +define all files that make up the component and any special defines that are needed to build it. A deployment +CMakeLists.txt just needs to reference the required set of components. No details of the component internals +are reflected in the deployment CMakeLists.txt file. + +Test components +''''''''''''''' + +Test code is treated in exactly the same as any other source code and is organized into components to achieve +the same reuse goals. To create a deployment intended for testing, you select an appropriate set of components +where some happen to be test components. By convention, test components live in sub-directories called test. +Test directories are located at the point in the components sub-tree that reflects the scope of tests. In the +above example, two test sub-directories are illustrated. The locations of the test component directories imply +the following about the scope of the tests:: + + components + |-- service + | |-- common + | | |-- test <-- Tests for the common service component + | |-- secure-storage + | | |-- client + | | |-- provider + | | |-- 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 +for different classes of test. e.g:: + + components + |-- service + |-- common + |-- test + |-- unit + |-- fuzz + +external +'''''''' + +Code that originates from other open source projects that needs to be built as part of trusted service +deployments is represented by directories beneath the external top-level directory. External components +are generally fetched from the source repo during the CMake build process. During the build for a particular +deployment, a deployment specific configuration may be applied to an external component. A CMake file under +each external component directory is responsible for fetching and building the external component:: + + external + |-- CppUTest + | |-- CppUTest.cmake + | |-- cpputest-cmake-fix.patch + |-- mbed-crypto + |-- nanopb + +protocols +''''''''' + +The protocols directory holds protocol definition files to allow clients to use trusted services. Ideally, +the service access protocol should be formally defined using an interface description language (IDL) that +provides a programming language neutral definition of the service interface. The protocols directory +structure accommodates protocol definitions using different definition methods. Where a service access +protocol has been defined using an IDL with language compilation support, code may be generated from the +interface description to allow RPC request and response parameters to be serialized and deserialized in a +compatible way between service clients and providers. The protocols sub-tree is organized as follows:: + + protocols + |-- service + | |-- common + | |-- crypto + | | |-- packed-c <-- C structure based definitions + | | |-- protobuf <-- Protocol Buffers definitions + | |-- secure-storage + | |-- packed-c + +tools +''''' + +The project directory structure includes a tools directory for holding general purpose tools components +to support activities such as build and test. + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/developer/running-tests.rst b/docs/developer/running-tests.rst new file mode 100644 index 000000000..be0e82ab9 --- /dev/null +++ b/docs/developer/running-tests.rst @@ -0,0 +1,48 @@ +Running Tests +============= + + + +Running component tests +----------------------- +On successfully completing the steps above, a binary executable called 'component-test' +will have been created. Because this deployment targets the linux-pc environment, the +executable may be run as a native application. The application uses the stock CppUtest +command line test runner. + +To run component tests, use:: + + ./component-test -v + + Typical verbose output: + TEST(PackedCprotocolChecks, checkTsStatusCodes) - 0 ms + TEST(InternalTrustedStorageTests, storeNewItem) - 0 ms + TEST(E2EcryptoOpTests, generateRandomNumbers) - 2 ms + TEST(E2EcryptoOpTests, asymEncryptDecrypt) - 4 ms + TEST(E2EcryptoOpTests, signAndVerifyHash) - 40 ms + TEST(E2EcryptoOpTests, exportAndImportKeyPair) - 18 ms + TEST(E2EcryptoOpTests, exportPublicKey) - 7 ms + TEST(E2EcryptoOpTests, generatePersistentKeys) - 39 ms + TEST(E2EcryptoOpTests, generateVolatileKeys) - 20 ms + TEST(CryptoFaultTests, randomNumbersWithBrokenStorage) - 0 ms + TEST(CryptoFaultTests, persistentKeysWithBrokenStorage) - 9 ms + TEST(CryptoFaultTests, volatileKeyWithBrokenStorage) - 8 ms + TEST(PocCryptoOpTests, checkOpSequence) - 13 ms + TEST(CryptoMsgTests, SignHashOutMsgTest) - 0 ms + TEST(CryptoMsgTests, SignHashInMsgTest) - 0 ms + TEST(CryptoMsgTests, ExportPublicKeyOutMsgTest) - 1 ms + TEST(CryptoMsgTests, ExportPublicKeyInMsgTest) - 0 ms + TEST(CryptoMsgTests, GenerateKeyInMsgTest) - 0 ms + TEST(ServiceFrameworkTests, serviceWithOps) - 0 ms + TEST(ServiceFrameworkTests, serviceWithNoOps) - 0 ms + TEST(TsDemoTests, runTsDemo) - 71 ms + + OK (21 tests, 21 ran, 159 checks, 0 ignored, 0 filtered out, 233 ms) + + + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/developer/service-access-protocols.rst b/docs/developer/service-access-protocols.rst new file mode 100644 index 000000000..4161f0d15 --- /dev/null +++ b/docs/developer/service-access-protocols.rst @@ -0,0 +1,202 @@ +Service Access Protocols +======================== + +A trusted service is accessed by calling service-specific methods via an RPC mechanism. The set of callable methods forms the +public interface exposed by a service. This section is concerned with interface conventions and protocols used for serializing +method parameters and return values. It is anticipated that there will be a need to support different parameter serialization +schemes to suite different needs. The project accommodates this with the following: + + - The Protocols directory structure allows for different protocol definitions for the same service. + - Message serialization code is decoupled from service provider code using an abstract 'serializer' interface. Alternative + concrete serializers may provide implementations of the interface. + +RPC Session +----------- + +Before a client can call trusted service methods, an RPC session must be established where an association is made between an RPC +Caller and a call endpoint that corresponds to the required service provider instance. To establish the session, the client +must provide: + + - An identifier for the service provider instance. + - Any client credentials that allow RPC layer access control to be applied if needed. + +.. uml:: uml/RpcSessionClassDiagram.puml + +Once the RPC session is established, the client may call service methods via an abstract RPC Caller interface that takes the +following parameters: + + - The opcode that identifies the method to call. + - A buffer for the serialized method parameters. + - A buffer for the serialized return values. + +A deployment independent interface for locating services and establishing RPC sessions is described here: :ref:`Service Locator` + +Status Codes +------------ + +On returning from a request to invoke a service method, two status codes are returned as follows: + + - *RPC status* - A generic status code that corresponds to the RPC call transaction. RPC status codes are standardized across + all services. + - *Operation status* - a service specific status code. + +Separation of status codes by layer allows service specific status codes to be accommodated while keeping RPC status codes +common. + +A client should only check the returned operation status if the returned RPC status value is RPC_CALL_ACCEPTED. All other RPC +status values indicate that an error occurred in delivering the RPC request. An RPC status of RPC_CALL_ACCEPTED does not +indicate that the service operation was successful. It merely indicates that the request was delivered, a suitable handler was +identified and the request parameters were understood. + +Service Access Protocol Definition Conventions +---------------------------------------------- + +A service access protocol defines the following: + + - Opcodes used for identifying service methods. + - Request parameters for each method. + - Response parameters for method return values. + - Operation status code. + +Details of how public interface definition files for trusted services are organized, see: :ref:`Project Structure` + +It is possible that for certain deployments, it will be necessary to customize which parameter encoding scheme is used. Many +schemes are possible such as Protocol Buffers, CBOR, JSON, TLV, TPM commands or packed C structures. To make scheme +customization straight forward, serilize/deserialize operations should be encapsulated behind a common interface to decouple +service provider code from any particular serialization scheme. A section below describes a pattern for achieving this. + +Service Namespace +''''''''''''''''' + +Definitions that form a service access protocol should live within a namespace that is unique for the particular service. Using +a namespace for service definitions avoids possible clashes between similarly named definitions that belong to different +services. How the namespace is implemented depends on how the access protocol is defined. For example, the Protocol Buffers +definitions for the crypto service all live within the ts_crypto package. The recommended convention for forming a trusted +service namespace is as follows:: + + ts_<service_name> + + e.g. + ts_crypto + ts_secure_storage + +Language Independent Protocol Definitions +''''''''''''''''''''''''''''''''''''''''' + +By defining service access protocols using an interface description language (IDL) with good support for different programming +languages, it should be straight forward to access trusted services from clients written in a range of languages. On Arm +Cortex-A deployments, it is common for user applications to be implemented using a range of languages such as Go, Python or +Java. Rather than relying on a binding to a C client library, native client code may be generated from the formal protocol +definition files. Initial protocol definitions use Google Protocol Buffers as the IDL. The project structure allows for use of +alternative definition schemes and serializations. + +Opcode Definition +````````````````` + +Opcodes are integer values that identify methods implemented by a service endpoint. Opcodes only need to be unique within the +scope of a particular service. The mapping of opcode to method is an important part of a service interface definition and +should be readily available to clients written in a variety of programming languages. For a Protocol Buffers based definition, +opcodes are defined in a file called:: + + opcodes.proto + +For example, for the Crypto trusted service, the Protocol Buffers opcode definitions are in:: + + protocols/service/crypto/protobuf/opcodes.proto + +Alternative definitions for light-weight C clients using the packed-c scheme are in:: + + protocols/service/crypto/packed-c/opcodes.h + +Parameter Definition +```````````````````` + +The convention used for serializing method parameters and return values may be specific to a particular service. The definition +file will include message definitions for both request and response parameters. Common objects that are used for multiple +methods should be defined in separate files. When using Protobufs, the following naming convention for method parameter files +should be used:: + + <method_name>.proto + +For example, the Crypto export_public_key method is defined in a file called:: + + protocols/service/crypto/protobuf/export_public_key.proto + +RPC Status Codes +```````````````` + +Generic RPC status code definitions using different definition schemes are defined here:: + + protocols/rpc/common/protobuf/status.proto + protocols/rpc/common/packed-c/status.h + +Service Status Codes +```````````````````` + +Service specific status code definitions using different definition schemes are defined here (using crypto service as an +example):: + + protocols/service/crypto/protobuf/status.proto + protocols/service/crypto/packed-c/status.h + +Status code definitions may also be shared between services. For example, services that conform to PSA API conventions will use +standardized PSA status codes, defined here:: + + protocols/service/psa/protobuf/status.proto + protocols/service/psa/packed-c/status.h + +Use of Protocol Buffers +----------------------- + +When Protocol Buffers is used for protocol definition and parameter serialization, the following conventions have been adopted. + +.proto File Style Guide +''''''''''''''''''''''' + +The style of the .proto files should follow Google's Protocol Buffers Style Guide. + +Protocol Buffer Library for Trusted Services +'''''''''''''''''''''''''''''''''''''''''''' + +Protocol Buffers standardizes how service interfaces are defined and the on-wire encoding for messages. Because of this, service +clients and service providers are free to use any conformant implementation. However for trusted services that may be deployed +across a range of environments, some of which may be resource constrained, a lightweight library should be used for C/C++ code +that implement or use trusted services. For this purpose, Nanobp (https://github.com/nanopb/nanopb) should be used. + +Serialization Protocol Flexibility +---------------------------------- + +Many different serialization protocols exist for encoding and decoding message parameters. Hard-wiring a particular protocol +into a trusted service provider implementation isn't desirable for the following reasons: + + - Depending on the complexity of serialization operations, mixing serialization logic with protocol-independent code makes + trusted service provider code bigger and more difficult to maintain. + - Different protocols may be needed for different deployments. It should be possible to make a build-time or even a + run-time selection of which protocol to use. + - The number of supported serializations protocols is likely to grow. Adding a new protocol shouldn't require you to make + extensive code changes and definitely shouldn't break support for existing protocols. + +These problems can be avoided by implementing protocol specific operations behind a common interface. Serialize/deserialize +operations will have the following pattern:: + + int serialize_for_method(msg_buffer *buf, in args...); + int deserialize_for_method(const msg_buffer *buf, out args...); + +To extend a service provider to support a new serialization encoding, the following steps are required: + + 1. Define a new encoding identifier string if a suitable one doesn't exist. Currently used identifiers are protobuf and + packed-c. The identifier will be used as a directory name so it needs to be filename-friendly. Some likely candidate + identifiers could be cbor and json. + 2. Add a new RPC encoding ID to *protocols/rpc/common/packed-c/encoding.h*. This is used by a caller to identify the encoding + used for RPC parameters. This is analogous to the content-type header parameter used in HTTP. + 3. Under the protocols parent directory, add a new access protocol definition for the service that needs extending. This will + be a representation of existing service access protocols but using a definition notation compatible with the new encoding. + 4. Add a new serializer implementation under the service provider's serializer directory e.g. for the crypto service - + *components/service/crypto/provider/serializer*. + 5. Add registration of the new serializer to any deployment initialization code where the new encoding is needed. + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/developer/service-descriptions/crypto-service-description.rst b/docs/developer/service-descriptions/crypto-service-description.rst new file mode 100644 index 000000000..717c73b55 --- /dev/null +++ b/docs/developer/service-descriptions/crypto-service-description.rst @@ -0,0 +1,85 @@ +Crypto Service Description +========================== +Service Overview +---------------- +The Crypto service provides a rich set of cryptographic operations with the backing +of a private key store. Clients identify keys using opaque key handles, enabling +cryptographic operations to be performed without exposing key values beyond the +boundary of the service's secure processing environment. This pattern underpins +the security guarantees offered by the Crypto service. + +The set of supported operations is aligned to the PSA Crypto API. C API functions +are invoked by clients using the Crypto service access protocol. All types and values +defined by the PSA Crypto C API are projected by the Crypto access protocol. The +one-to-one mapping between the C API and Crypto access protocol allows developers +to use PSA Crypto documentation and examples to understand details of the protocol. + +Supported operations fall into the following categories: + + * Key lifetime management + * Message signing and signature verification + * Asymmetric encryption/decryption + * Random number generation + +Service Provider Implementation +------------------------------- +The default crypto service provider uses the Mbed Crypto library to implement backend +operations. The following diagram illustrates the component dependencies in the crypto +service provider implementation (note that there are many more handlers than +illustrated): + +.. uml:: uml/CryptoProviderClassDiagram.puml + +The packages illustrated reflect the partitioning of the code into separate directories. +Functionality is partitioned as follows: + +Crypto Provider +''''''''''''''' +Implements the set of handlers that map incoming RPC call requests to PSA Crypto API +function calls. A separate handler function exists for each operation supported by the +service. + +Crypto Serializer +''''''''''''''''' +Incoming call request parameters are de-serialized and response parameters serialized +by a serializer. The trusted services framework allows for the use of alternative +serializers to support different parameter encoding schemes. + +Mbed Crypto +''''''''''' +All cryptographic operations are handled by an instance of the Mbed Crypto library. +The library is built with a specific configuration that creates dependencies on the +following: + + * PSA ITS API for persistent key storage + * External entropy source + +Secure Storage +'''''''''''''' +Persistent storage of keys is handled by an instance of the Secure Storage service. +The service is accessed via a client that presents the PSA ITS API at its upper edge. +This is needed for compatibility with Mbed Crypto. As long as it meets security +requirements, any Secure Storage service provider may be used. An RPC session between +the Crypto and Secure Storage service providers is established during initialization +and is maintained for the lifetime of the Crypto service provider. + +Entropy Source +'''''''''''''' +Certain cryptographic operations, such as key generation, require use of a +cryptographically secure random number generator. To allow a hardware TRNG to be used, +the Mbed Crypto library is configured to use an externally provided entropy source. +Any deployment of the service provider must include an implementation of the following +function:: + + int mbedtls_hardware_poll(void *data, unsigned char *output, size_t len, size_t *olen) + +For production deployments, an implementation of this function should be provided that +obtains the requested bytes of entropy from a suitable source. To allow the Crypto +service to be used where no hardware backed implementation is available, a software +only implementation is provided. + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/developer/service-descriptions/index.rst b/docs/developer/service-descriptions/index.rst new file mode 100644 index 000000000..6f710a4d2 --- /dev/null +++ b/docs/developer/service-descriptions/index.rst @@ -0,0 +1,14 @@ +Service Descriptions +==================== + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + crypto-service-description + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/developer/service-descriptions/uml/CryptoProviderClassDiagram.puml b/docs/developer/service-descriptions/uml/CryptoProviderClassDiagram.puml new file mode 100644 index 000000000..65c6d83d1 --- /dev/null +++ b/docs/developer/service-descriptions/uml/CryptoProviderClassDiagram.puml @@ -0,0 +1,49 @@ +'------------------------------------------------------------------------------- +' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved. +' +' SPDX-License-Identifier: BSD-3-Clause +' +'------------------------------------------------------------------------------- + +@startuml +allow_mixing +left to right direction + + +package CryptoProvider +{ + class handler + class generate_key_handler + class import_key_handler + class sign_hash_handler + generate_key_handler --|> handler + import_key_handler --|> handler + sign_hash_handler --|> handler +} +package CryptoSerializer +{ + class crypto_serializer + class protobuf_crypto_serializer + class packed_c_crypto_serializer + protobuf_crypto_serializer --|> crypto_serializer + packed_c_crypto_serializer --|> crypto_serializer +} +package MbedCrypto +{ + class libmbedcrypto +} +package SecureStorage +{ + class its_client +} +package EntropySource +{ + class hw_entropy_source +} + +CryptoProvider ..> CryptoSerializer +CryptoProvider ..> MbedCrypto +MbedCrypto ..> SecureStorage +MbedCrypto ..> EntropySource + +@enduml
\ No newline at end of file diff --git a/docs/developer/service-locator.rst b/docs/developer/service-locator.rst new file mode 100644 index 000000000..80649139d --- /dev/null +++ b/docs/developer/service-locator.rst @@ -0,0 +1,169 @@ +Service Locator +=============== + +The service locator model provides clients of trusted services with a common interface for locating service instances and +establishing RPC sessions with service endpoints. By using the service locator, application code is decoupled from the details +of where services are deployed. Use of the service locator is entirely optional for client applications. Different deployments +of *libts* provide implementations of the service locator API that are suitable for different environments. The trusted +services project uses *libts* to decouple test code from the services under test. This enables tests to be reused for testing +on different platforms with different distributions of services. The same flexibility may be exploited when writing +applications that use trusted services. + +Service Locator Model +--------------------- + +The following class diagram illustrates the service locator model: + +.. uml:: uml/ServiceLocatorClassDiagram.puml + +The model takes inspiration from microservices architectures where there is a similar need to decouple clients from service +location. In the model, classes have the following roles: + +Class service_locator +''''''''''''''''''''' + +The service_locator is responsible for locating service provider instances and returning a service_context object to allow a +client to establish RPC sessions with the located service endpoint. A service instance is requested by a client using a service +name. The service name uniquely identifies a service instance, independent of where the service provider is located. The +service_locator is a singleton and forms the common interface for locating trusted services. + +Class service_context +''''''''''''''''''''' + +A service_context object represents a located service and enables a service client to establish RPC sessions with the service. +A concrete service_context will provide open and close methods that manage RPC session setup and teardown. + +Class rpc_caller +'''''''''''''''' + +An rpc_caller provides methods for making remote calls associated with a service endpoint. An rpc_caller object represents an +instance of an RPC session. + +Locating Service Instances +-------------------------- + +The location of service instances is likely to vary between deployments. Many factors influence where a service instance is +deployed and the method needed to locate it. e.g.: + + - The type of processing environment in which a service instance is deployed. e.g. service could be deployed in a secure + partition, as a TA or in a secure enclave. + - Whether a service instance is co-located with other services instances in the same processing environment or whether a + separate environment instance is used per service instance. + - For Linux user-space clients, the kernel driver model used for messaging influences how a service is located and the type + of messaging interface used for RPC requests. + +Because of the wide variability in service deployment options, the Trusted Services framework supports the following: + + - *Location independent service names* - a naming convention for identifying service instances, wherever they are located. + By using a location independent service name, a client is decoupled from the actual location of a service instance + (similar to a DNS names). A concrete service locator is responsible for resolving the location independent service name. + - *Service location strategies* - to accommodate the likely variability, an extensible framework for alternative service + location strategies is provided. + +Service Names +''''''''''''' + +Location Independent Service Names +`````````````````````````````````` + +Because of the potential variability in where service instances are deployed, a naming convention that allows a service instance +to be identified, independent of its location, is useful. By using a location independent service name, coupling between a +client application and any particular service deployment can be avoided. Use of the Service Locator API and location +independent service names allows client applications to be portable across different platforms. + +The service instance naming convention uses a URN type string to uniquely identify a particular instance of a class of service. +To provide extensibility, a naming authority is included in the name. This allows anyone with a domain name to define their own +unique service names. Core service names are defined under the *trustedfirmware.org* authority. The general structure of a +service name is as follows:: + + urn:sn:<authority>:<service>.<version>:<instance> + + The 'urn' prefix should be dropped when service names are used in context. + The version field is optional. + +The naming convention includes a version number, separated from the <service> field by a '.' character. Beyond the '.', any +version numbering scheme may be used. This will potentially be useful for delegating version compatibility decisions to a +service locator. It is preferable for a client to specify a service name that includes a version number as this will +potentially allow a service locator to: + + - Locate a compatible service instance. For example, a service provider may expose multiple RPC call endpoints to handle + different protocol versions. A service locator may resolve the name to the compatible RPC endpoint, based on the version + string requested by the client. + - Fail gracefully if no compatible version is found. + +Some example service names:: + + sn:trustedfirmware.org:crypto.1.0.4:0 + sn:trustedfirmware.org:secure-storage.1.3.11:1 + sn:trustedfirmware.org:tpm.2.0:0 + +Location Specific Service Names +``````````````````````````````` + +To enable a client to be able to specify location specific service names, it should also be possible to use names that express a +location specific identifier such as a partition UUID. While use of location specific services names creates a coupling between +the client and details of the service deployment, their use may be important in the following cases: + + - Where there is no well-known mapping between a location independent service name and a location specific identifier. + - Where the client needs to be specific e.g. for tests that target a specific service deployment. + +Location specific service names use the same structure as location independent services names but with a technology specific +authority field. The following is an example of a service name that identifies a service instance that is deployed in a secure +partition:: + + sn:ffa:d9df52d5-16a2-4bb2-9aa4-d26d3b84e8c0:0 + + The instance field qualified a particular SP instance from the discovered set. + +Service Location Strategies +''''''''''''''''''''''''''' + +The method used by the service locator to resolve a service name to a service instance will depend on the environment in which a +client is running and where service instances are located. Services will need to be located by any client of a trusted service. +There are typically two classes of trusted service client: + + - A user-space application. + - Another trusted service, running in a secure processing environment. + +Different methods for locating service instances in different environments are illustrated in the following examples: + +Locating a Service from Linux User-space +```````````````````````````````````````` + +Depending on the kernel driver model used, the example methods for locating service instances from Linux user-space are: + + 1. Service instances are represented by device nodes e.g. /dev/tpm0. The service locator will simply map the <service> + portion of the services name to the base device name and the <instance> to the device node instance. + 2. A service instance is hosted by a TEE as a TA. The TEE will provide a discovery mechanism that will allow a TA type and + instance to be identified. The service locator will need to map the service name to the TEE specific naming scheme. + 3. A special device that provides messaging provides a method for discovery. e.g. an FF-A driver supports partition + discovery. + 4. A device is used for remote messaging to a separate microcontroller. There is a well-known protocol for endpoint + discovery using the messaging layer. + +Locating a Service from another Trusted Service +``````````````````````````````````````````````` + +Where a trusted service uses another trusted service, it is likely that both service instances will be running in the same +security domain e.g. both running in secure partitions within the secure world. Where a single service instance is deployed per +secure partition, the client service will use the following strategy to locate the service provider: + + 1. The service name is mapped to the well known UUID for the class of SP that hosts the service provider. + 2. FF-A partition discovery is used to find all SPs that match the requested UUID. + 3. The service instance portion of the service name is used to match the partition ID when selecting the target SP from the + list of discovered SPs. + +Extending the Service Locator Model +``````````````````````````````````` + +To accommodate the need to support alternative location strategies, the Service Locator model can be extended to use a set of +concrete strategy objects to implement different methods of locating a service instance. The set of strategies used will be +different for different client environments. The following class diagram illustrates how the model can be extended. + +.. uml:: uml/ServiceLocationStrategyClassDiagram.puml + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/developer/software-requirements.rst b/docs/developer/software-requirements.rst new file mode 100644 index 000000000..ec6c2e406 --- /dev/null +++ b/docs/developer/software-requirements.rst @@ -0,0 +1,38 @@ +Software Requirements +===================== + +As of today the only available normal-world interface for Trusted Services is available trough linux. Building and end-to-end +firmware stack requires compiling the Linux Kernel and linux user space applications. This restricts the possible host +environments to Linux distributions. +While some TS components can be built under Windows this scenario is not mandated by this documentation. + +The preferred host environment is Ubuntu 18.04. + +The following tools are required: + + * CMake, version 3.18.4. (See the `CMake download page`_.) + * GNU Make v4.1 or higher. + * Git v2.17 or newer. + * Python3.6 and the modules listed in ``<project>/requirements.txt``. + * GCC supporting the deployment. + + * `opteesp` environment: a host to aarch64 cross-compiler is needed. Please use the compilers specified by the + `OP-TEE documentation`_. + * `arm-linux` environment: a host to aarch64 linux cross-compiler is needed. Please use the version `9.2-2019.12` of the + "aarch64-none-linux-gnu" compiler available from `arm Developer`_. + (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`. + +.. todo:: Add info on commit validation dependencies (checkpatch, uncrustify, etc...) + +-------------- + +.. _OP-TEE documentation: https://optee.readthedocs.io/en/latest/building/gits/build.html#step-4-get-the-toolchains +.. _arm Developer: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads +.. _CMake download page: https://cmake.org/files/v3.18/ + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/developer/uml/BuildFlow.puml b/docs/developer/uml/BuildFlow.puml new file mode 100644 index 000000000..0dc146862 --- /dev/null +++ b/docs/developer/uml/BuildFlow.puml @@ -0,0 +1,55 @@ +'------------------------------------------------------------------------------- +' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved. +' +' SPDX-License-Identifier: BSD-3-Clause +' +'------------------------------------------------------------------------------- + +@startuml + +(*) --> [cmake command] "Generating" +note right + Generate native build files from deployment + configuration files. External components are + fetched and built. Child deployments are + generated, built and installed. +end note + +If "success" + --> [false]"Generation Errors" #Red +else + --> [true]"Generated" +Endif + +--> [make install command] "Building" +note right + Compile and link to create build output. +end note + +If "success" + --> [false]"Build Errors" #Red +else + --> [true]"Built" +Endif + +--> "Installing" +note right + Copy build output files to installation + directory specified by CMAKE_INSTALL_PREFIX. +end note + +If "success" + --> [false]"Install Errors" #Red +else + --> [true]"Installed" +Endif + +--> "Deploying" #Green +note right + Perform environment specific + deployment steps. +end note + +--> "Deployed" #Green + +@enduml
\ No newline at end of file diff --git a/docs/developer/uml/RpcSessionClassDiagram.puml b/docs/developer/uml/RpcSessionClassDiagram.puml new file mode 100644 index 000000000..d2645605b --- /dev/null +++ b/docs/developer/uml/RpcSessionClassDiagram.puml @@ -0,0 +1,20 @@ +'------------------------------------------------------------------------------- +' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved. +' +' SPDX-License-Identifier: BSD-3-Clause +' +'------------------------------------------------------------------------------- + +@startuml + +class rpc_caller { + {abstract}int call(opcode, param_buf, result_buf) +} + +rpc_caller -> call_ep +note right on link +Association with call_ep is made when +RPC session is established. +end note + +@enduml
\ No newline at end of file diff --git a/docs/developer/uml/SecureServicesLayers.puml b/docs/developer/uml/SecureServicesLayers.puml new file mode 100644 index 000000000..114b2fbd5 --- /dev/null +++ b/docs/developer/uml/SecureServicesLayers.puml @@ -0,0 +1,46 @@ +'------------------------------------------------------------------------------- +' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved. +' +' SPDX-License-Identifier: BSD-3-Clause +' +'------------------------------------------------------------------------------- + +@startuml + +!include ../../uml/style-component.puml + +package "Client Processing Environment" COLOR_GREY1 { + NS_COMPONENT trusted_service_client as "Trusted Service client" + NS_IFC ns_rpc as "RPC" + NS_COMPONENT rpc_caller as "RPC Caller" + NS_IFC ns_messaging as "messaging" + NS_COMPONENT ns_messaging_layer as "Messaging Layer" +} +trusted_service_client --down-> ns_rpc +ns_rpc-down->rpc_caller +rpc_caller-down->ns_messaging +ns_messaging-down->ns_messaging_layer + +package "Secure Processing Environment" COLOR_BLUE2 { + S_COMPONENT trusted_service_provider as "Trusted Service Provider" + S_COMPONENT rpc_endpoint as "RPC endpoint" + S_COMPONENT s_messaging_layer as "Messaging Layer" + S_COMPONENT backend_service as "Backend Service" + S_IFC s_rpc as "RPC" + S_IFC s_messaging as "messaging" + S_IFC s_backend as "backend interface" +} + +trusted_service_provider --down-> s_rpc +s_rpc-down->rpc_endpoint +rpc_endpoint-down->s_messaging +s_messaging-down->s_messaging_layer + +trusted_service_provider-down->s_backend +s_backend-down->backend_service + +trusted_service_client<.>trusted_service_provider +rpc_caller<.>rpc_endpoint +ns_messaging_layer<.>s_messaging_layer + +@enduml
\ No newline at end of file diff --git a/docs/developer/uml/ServiceDeployment.puml b/docs/developer/uml/ServiceDeployment.puml new file mode 100644 index 000000000..8c6f9548a --- /dev/null +++ b/docs/developer/uml/ServiceDeployment.puml @@ -0,0 +1,84 @@ +'------------------------------------------------------------------------------- +' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved. +' +' SPDX-License-Identifier: BSD-3-Clause +' +'------------------------------------------------------------------------------- + +@startuml + +!include ../../uml/style-component.puml + +skinparam component { + BackgroundColor COLOR_BLUE2 +} + +skinparam package { + BackgroundColor COLOR_BLUE1 +} + +package "tools" { + component sw_qa as "Software QA Tools" + component compiler_toolchain as "Compiler Toolchain" +} + +package "protocols" { + component proto_protobuf as "Protobuf interface definition" + component proto_packed_c as "Packed-C interface definition" +} + +package "platform" { + component plat_interfaces as "Common driver interfaces" + component plat_providers as "Platform providers" +} + +package "deployments" { + component deploy_deploy as "Deployment" + component depoy_build_cfg as "Deployment specific build configuration" + component deploy_init as "Deployment specific service initialization" +} + +package "components" { + component comp_src as "Source files" + component comp_test_cases as "Test cases" + component comp_adapters as "Adapters" +} + +package "external" { + component ext_all as "External components/libraries" +} + +package "environments" { + component env_build_cfg as "Environment build configuration" + component env_libs as "Environment libraries" + component env_hdrs as "Environment header files" + component env_inst as "installation" + env_build_cfg-[hidden]->env_libs + env_build_cfg-[hidden]->env_hdrs +} + +deploy_deploy ...> depoy_build_cfg +deploy_deploy .up.> deploy_init + +deploy_deploy ..left..> proto_protobuf +deploy_deploy ..left..> proto_packed_c + +deploy_deploy ..right..> env_build_cfg +deploy_deploy ..right..> env_libs +deploy_deploy ..right..> env_hdrs +deploy_deploy ..right..> env_inst + +deploy_deploy ..up..> sw_qa +deploy_deploy ..up..> compiler_toolchain + +deploy_deploy ..> ext_all + +deploy_deploy ..down..> comp_src +deploy_deploy ..down..> comp_test_cases +deploy_deploy ..down..> comp_adapters + +deploy_init -[hidden]up-> proto_protobuf + +comp_adapters ...> plat_interfaces + +@enduml
\ No newline at end of file diff --git a/docs/developer/uml/ServiceLocationStrategyClassDiagram.puml b/docs/developer/uml/ServiceLocationStrategyClassDiagram.puml new file mode 100644 index 000000000..4ef2c52fd --- /dev/null +++ b/docs/developer/uml/ServiceLocationStrategyClassDiagram.puml @@ -0,0 +1,24 @@ +'------------------------------------------------------------------------------- +' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved. +' +' SPDX-License-Identifier: BSD-3-Clause +' +'------------------------------------------------------------------------------- + +@startuml + +class service_location_strategy +{ + {abstract} service_context query(service_name) +} + +class service_locator <<singleton>> +{ + void init() + void register_strategy(strategy) + service_context query(service_name) +} + +service_locator --> "0..*" service_location_strategy + +@enduml
\ No newline at end of file diff --git a/docs/developer/uml/ServiceLocatorClassDiagram.puml b/docs/developer/uml/ServiceLocatorClassDiagram.puml new file mode 100644 index 000000000..0519f41c3 --- /dev/null +++ b/docs/developer/uml/ServiceLocatorClassDiagram.puml @@ -0,0 +1,37 @@ +'------------------------------------------------------------------------------- +' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved. +' +' SPDX-License-Identifier: BSD-3-Clause +' +'------------------------------------------------------------------------------- + +@startuml + +class service_client + +class rpc_caller +{ + rpc_call_handle call_begin() + int call_invoke() + void call_end() +} + +abstract class service_context +{ + {abstract} rpc_caller open() + {abstract} void close(rpc_caller) +} + +class service_locator <<singleton>> +{ + service_context query(service_name) + void relinquish(service_context) +} + +service_locator ..> "finds" service_context +service_context ..> "opens session" rpc_caller +service_client ..> "queries" service_locator +service_client --> service_context +service_client --> rpc_caller + +@enduml
\ No newline at end of file diff --git a/docs/developer/writing-documentation.rst b/docs/developer/writing-documentation.rst new file mode 100644 index 000000000..850d9cd83 --- /dev/null +++ b/docs/developer/writing-documentation.rst @@ -0,0 +1,53 @@ +Writing documentation +===================== + +|TS| is documented using `Sphinx`_, which in turn uses Docutils and `Restructured Text`_ (|REST| hereafter). + +The source files for the documents are in the *docs* directory of the |TS_REPO|. + +The preferred output format is *HTML*, and other formats may or may not work. + + +Section Headings +---------------- + +In order to avoid problems if documents include each other, it is important to follow a consistent section heading +style. Please use at most five heading levels. Please use the following style:: + + First-Level Title + ================= + + Second-Level Title + ------------------ + + Third-Level Title + ''''''''''''''''' + + Forth-level Title + """"""""""""""""" + + Fifth-level Title + ~~~~~~~~~~~~~~~~~ + + +Inline documentation +-------------------- + +To get all information integrated into a single document the project uses Sphinx extensions to allow capturing inline +documentation into this manual. + + +CMake +''''' + +.. todo:: Add content about how to document cmake scripts. + + +-------------- + +.. _`Restructured Text`: https://docutils.sourceforge.io/rst.html +.. _`Sphinx`: https://www.sphinx-doc.org + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/environments/deployment-guides/fvp-deployment-guide.rst b/docs/environments/deployment-guides/fvp-deployment-guide.rst new file mode 100644 index 000000000..eeb90780f --- /dev/null +++ b/docs/environments/deployment-guides/fvp-deployment-guide.rst @@ -0,0 +1,86 @@ +Deploying Programs on FVP +========================= +This page explains how to load and run user space programs on a Linux image running in FVP simulation. +The loaded programs may use any trusted services that are available as part of the image firmware. + +To prepare and run an image that includes trusted services running in S-EL0 secure partitions under +OP-TEE. see: +:ref:`Deploying trusted services in S-EL0 Secure Partitions under OP-TEE` + +Shared directory +---------------- +The OP-TEE image built for the FVP virtual platform supports directory sharing between the running +OS and the host computer. This provides a convenient way to transfer files between the host and +the device simulation. When the FVP is run using the *run-only* target in *fvp.mk*, the shared +directory is set-up automatically. + +On the host, the shared directory is located here:: + + optee/shared + +On the simulated device, running under FVP, a mount is created here:: + + /mnt + +Deploying service level tests +----------------------------- +As an example of how to load and run programs, the *ts-service-test* binary executable is used. +The build file for the *arm-linux* deployment of *ts-service-test* lives under:: + + trusted-services/deployments/ts-service-test/arm-linux + +The executable includes service level test cases that exercise trusted services via their +standard interfaces. Test cases use *libts* for locating services and establishing RPC +sessions. *ts-service-test* provides a useful reference for understanding how *libts* may +be used for accessing trusted services. + +The build file for the *arm-linux* deployment of *libts* lives under:: + + trusted-services/deployments/libts/arm-linux + +Trusted service build instructions are here: +:ref:`Build Instructions` + +Having built *ts-service-test* and *libts* for the *arm-linux* environment, the steps +are required. + +Copy files to share directory +''''''''''''''''''''''''''''' +Assuming that the *OP-TEE* and *trusted-services* projects are located under a common +parent directory, the following files need to be copied from the host using:: + + cp trusted-services/deployments/libts/arm-linux/build/install/lib/libts.so optee/shared/. + cp trusted-services/deployments/ts-service-test/arm-linux/build/install/bin/ts-service-test optee/shared/. + +Installing libts.so +''''''''''''''''''' +Having copied *libts.so* to the shared directory, it needs to be copied to one of the standard +lib directories so that it is located when a dependent program is started. From the terminal +command prompt for the booted FVP, use:: + + cd /mnt + cp libts.so /usr/lib/. + +Running the program executable +'''''''''''''''''''''''''''''' +The *ts-service-test* program may be run directly from the */mnt* directory using:: + + ./ts-service-test -v + +If all is well, you should see something like:: + + TEST(E2EcryptoOpTests, generateRandomNumbers) - 3 ms + TEST(E2EcryptoOpTests, asymEncryptDecrypt) - 8 ms + TEST(E2EcryptoOpTests, signAndVerifyHash) - 29 ms + TEST(E2EcryptoOpTests, exportAndImportKeyPair) - 17 ms + TEST(E2EcryptoOpTests, exportPublicKey) - 10 ms + TEST(E2EcryptoOpTests, generatePersistentKeys) - 34 ms + TEST(E2EcryptoOpTests, generateVolatileKeys) - 16 ms + + OK (7 tests, 7 ran, 56 checks, 0 ignored, 0 filtered out, 117 ms) + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/environments/deployment-guides/opteesp-deployment-guide.rst b/docs/environments/deployment-guides/opteesp-deployment-guide.rst new file mode 100644 index 000000000..e71140fa8 --- /dev/null +++ b/docs/environments/deployment-guides/opteesp-deployment-guide.rst @@ -0,0 +1,97 @@ +Deploying trusted services in S-EL0 Secure Partitions under OP-TEE +================================================================== + +Trusted services built for the *opteesp* environment may be deployed to run within S-EL0 secure +partitions, managed by OP-TEE. Secure partitions are loaded and run by OP-TEE using the early-TA +feature where a set of TAs or SPs are loaded during OP-TEE initialization. This feature relies on +SP images being incorporated into the *OP-TEE OS* image at build time. It is therefore necessary to +have access to the OP-TEE build environment and tools in order to deploy SP images. + +Tool prerequisites and general build instruction for OP-TEE are described here: +`<https://optee.readthedocs.io/en/latest/building/gits/build.html>`_ + +Download page for Arm Fixed Virtual Platforms (FVP): +`<https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms>`_ + +Incorporating SP images into the *OP-TEE OS* image +-------------------------------------------------- + +The set of SP images to include in the built *OP-TEE OS* image are specified to the *OP-TEE OS* +build by the EARLY_TA_PATHS make variable. The EARLY_TA_PATHS variable should be assigned a string +containing a space separated list of file paths for each SP image file to include. SP images +that need to be deployed from the Trusted Services project will be located in the install directory, +specified when the SP images where built i.e.:: + + <CMAKE_INSTALL_PREFIX>/bin + +The following example illustrates a setting of the EARLY_TA_PATHS variable to deploy the Secure Storage +SP and Crypto SP:: + + EARLY_TA_PATHS="ts-install-dir/bin/dc1eef48-b17a-4ccf-ac8b-dfcff7711b14.stripped.elf \ + ts-install-dir/bin/d9df52d5-16a2-4bb2-9aa4-d26d3b84e8c0.stripped.elf" + +To help with integration with the OP-TEE build system, the installation step for a deployment to the +*opteesp* environment includes the generation of a simple makefile that extends the EARLY_TA_PATHS +variable for the particular deployment. For example, the generated makefile for the crypto SP +contains:: + + OPTEE_OS_COMMON_EXTRA_FLAGS+=EARLY_TA_PATHS+=${TS_INSTALL_PREFIX}/bin/d9df52d5-16a2-4bb2-9aa4-d26d3b84e8c0.stripped.elf + +The generated makefile is installed to:: + + <CMAKE_INSTALL_PREFIX>/lib/make + +Reference OP-TEE build with PSA RoT Services +-------------------------------------------- +To provide an example integration of OP-TEE with a set of trusted services, a makefile called *fvp_ffa.mk* +is included in the OP-TEE build repository that builds OP-TEE OS with a set of SP images that provide PSA +RoT services. SP images are built using the standard trusted services build flow and are automatically +injected into the *optee_os* build using the early TA feature described above. + +A bootable Linux image is created that is intended to run on the Arm FVP virtual platform. The built image +includes user space programs that may be used to test and demonstrate the deployed trusted services. + +Setting up the OP-TEE build environment +''''''''''''''''''''''''''''''''''''''' +To help setup the OP-TEE build environment, a manifest file called *psa-sp-fvp.xml* is included in OP-TEE +manifests repository. This may be used with the *repo* tool to manage the set of git repositories. Note +that this manifest relies on SSH access to *github.com* so ensure that you have installed a suitable public +key into your *github* account. + +Having created a new directory for the OP-TEE build environment, the required set of git repositories can +be cloned and fetched using:: + + repo init -u https://git.trustedfirmware.org/OP-TEE/manifest.git -b psa-development -m psa-sp-fvp.xml + repo sync + +Building the reference OP-TEE image +''''''''''''''''''''''''''''''''''' +To build the bootable image that includes OP-TEE and the set of secure partition images that hold the +PSA RoT services, use the following (from your OP-TEE root directory):: + + cd build + make -f fvp_ffa.mk all + +This will take many tens of minutes to complete. + +Running the reference OP-TEE image on FVP +''''''''''''''''''''''''''''''''''''''''' +The fvp makefile includes a *run* and *run-only* target which can be used to start the FVP model and +boot the built image. The example assumes that the FVP model has been installed in the following +directory relative to the OP-TEE build directory:: + + ../Foundation_Platformpkg/models/Linux64_GCC-6.4/ + +To boot the built image on FVP without building, use:: + + make run-only FVP_PATH=../Foundation_Platformpkg/models/Linux64_GCC-6.4/ + +For information on running user space programs on FVP, see: + +:ref:`Deploying Programs on FVP` + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/environments/ffa/libsp.rst b/docs/environments/ffa/libsp.rst new file mode 100644 index 000000000..ff1b55210 --- /dev/null +++ b/docs/environments/ffa/libsp.rst @@ -0,0 +1,132 @@ +libsp +===== + +libsp is intended to be used from S-EL0 secure partitions. It contains all +the necessary features for communicating with other components using the FF-A +interfaces. + +The implementation is split into multiple layers for easy maintainability and +usage. The structure and the short description of the components of the library +is described below. + +For detailed information about the FF-A interfaces please check the +`FF-A specification <https://developer.arm.com/documentation/den0077/a/>`_ + +The API reference documentation is included in the code. + +The components of the following diagram are illustrated as classes but as the +library is written in C they are not real classes. Their purpose is to describe +the interfaces and dependencies of the library's components. + +.. uml:: /uml/libsp_functions.puml + +SP layer +-------- + +The SP layer provides convenient high level interface for accessing FF-A +features. The layer has multiple components around the groups of the FF-A +interfaces. + +SP RXTX +''''''' + +The FF-A calls may utilize a pair or buffers called RXTX buffers for passing +data to the SPM that won't fit into registers. These buffers should be set up +during the initialization phase of the SP, then the FF-A calls can use these in +discovery or memory management calls. + +The SP RXTX component provides a high level interface for registering these +buffers. It also enables other components of the SP layer to use these buffers +during FF-A calls without the need of manually passing the buffers to the +functions. + +SP memory management +'''''''''''''''''''' + +The FF-A memory management interfaces involve multiple steps for setting up a +memory transaction. This component gives a set of functions to the user for +doing these transactions in a simple way. The supported memory transactions +follows below: + +* Donate + +* Lend + +* Share + +* Retrieve + +* Relinquish + +* Reclaim + +FF-A layer +---------- + +The FF-A layer provides functions and types for accessing FF-A features through +a C API. This low level API gives full control of the FF-A call parameters. + +FF-A API +'''''''' + +The FF-A API provides wrappers for the FF-A interfaces. These interfaces are +fitted into the following groups: + +* Setup and discovery interfaces + +* CPU cycle management interfaces + +* Messaging interfaces + +* Memory management interfaces + +The functions of this unit give raw control of all the parameters of the FF-A +calls beside providing basic validity checks for the parameters. + +Couple FF-A interfaces have the ability to receive a response which indicates +an interrupt that is meant to be handled by the SP. All these functions call a +common interrupt handler function which is defined in the FF-A API component. +This interrupt handler function should be implemented by the upper layers (in +fact it is implemented by the SP layer or libsp). + +FF-A memory descriptors +''''''''''''''''''''''' + +The FF-A defines memory descriptors to provide information to the SPM about the +referenced memory areas. These are used by memory transactions like sharing, +lending, etc. This information covers various details like instruction and data +access rights, the endpoints of the transaction, address and size of the area, +and so on. Building and parsing memory transaction structures can be quite +complex and this is what this component addresses. + +First of all it provides a type for describing buffers where the transaction +descriptors should be built. Using this type provides safety against buffer +overflows during the transaction build and parse processes. + +The transaction data consists of three main sections. + +1. A transaction descriptor should be added where the memory region attributes + are described. + +2. Multiple memory access descriptors should be added which specify access for + each receiver of the memory area. + +3. Addresses and sizes of the memory regions can be added. + +At this point the transaction data should be ready to passed to the SPM by +invoking the suitable FF-A call. + + +FF-A internal API +----------------- + +The lowest layer implemented in libsp is responsible for wrapping FF-A layer +calls into the SVC conduit. Practically this means an escalation of the +exception level and invoking the SVC handler of the SPM with the suitable +parameters passed in registers. + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/environments/index.rst b/docs/environments/index.rst new file mode 100644 index 000000000..a2448270a --- /dev/null +++ b/docs/environments/index.rst @@ -0,0 +1,16 @@ +Processing Environments +======================= + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + ffa/libsp + deployment-guides/fvp-deployment-guide.rst + deployment-guides/opteesp-deployment-guide.rst + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/global_substitutions.txt b/docs/global_substitutions.txt index 925a078d6..bc1625eff 100644 --- a/docs/global_substitutions.txt +++ b/docs/global_substitutions.txt @@ -8,13 +8,15 @@ .. |LCS| replace:: :term:`LCS` .. |ACLE| replace:: :term:`ACLE` .. |REST| replace:: reST +.. |SEMVER| replace:: `Semantic Versioning`_ .. _`TS Mailing List`: https://lists.trustedfirmware.org/mailman/listinfo/trusted-services -.. _`TS repository`: https://review.trustedfirmware.org/TS/trusted-services.git +.. _`TS repository`: https://review.trustedfirmware.org/admin/repos/TS/trusted-services +.. _`Semantic Versioning`: https://semver.org/spec/v2.0.0.html .. -------------- - *Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.* + *Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/index.rst b/docs/index.rst index 9a643c45c..cb44e2c3c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,16 +4,67 @@ The Trusted Services project provides a framework for developing and deploying d root-of-trust services across a range of secure processing environments such as those provided by OP-TEE and Hafnium. +.. raw:: html + + <ul class="grid"> + <li class="grid-item"> + <a href="overview/index.html"> + <img alt="" src="_static/images/tfm.png"/> + <h2>About trusted services</h2> + </a> + <p></p> + </li> + <li class="grid-item"> + <a href="project/index.html"> + <img alt="" src="_static/images/tfm.png"/> + <h2>About the project</h2> + </a> + <p></p> + </li> + <li class="grid-item"> + <a href="developer/index.html"> + <img alt="" src="_static/images/tfm.png"/> + <h2>Developer Docs</h2> + </a> + <p></p> + </li> + <li class="grid-item"> + <a href="environments/index.html"> + <img alt="" src="_static/images/tfm.png"/> + <h2>Processing Environments</h2> + </a> + <p></p> + </li> + <li class="grid-item"> + <a href="security/index.html"> + <img alt="" src="_static/images/tfm.png"/> + <h2>Security Model</h2> + </a> + <p></p> + </li> + <li class="grid-item"> + <a href="standards/index.html"> + <img alt="" src="_static/images/tfm.png"/> + <h2>Standards Compliance</h2> + </a> + <p></p> + </li> + </ul> + .. toctree:: :maxdepth: 1 :caption: Contents: :hidden: - project/license - project/maintainers + overview/index + project/index + developer/index + environments/index + security/index + standards/index -------------- -*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/overview/goals.rst b/docs/overview/goals.rst new file mode 100644 index 000000000..0e6312278 --- /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 000000000..4706034ea --- /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 000000000..674e0b50d --- /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 diff --git a/docs/project/change-log.rst b/docs/project/change-log.rst new file mode 100644 index 000000000..fbabfa42a --- /dev/null +++ b/docs/project/change-log.rst @@ -0,0 +1,30 @@ +Change Log & Release Notes +========================== + +This document contains a summary of the new features, changes, fixes and known +issues in each release of Trusted Services. + +Version 0.1.0 +------------- + +New Features +^^^^^^^^^^^^ +First release. + +Changes +^^^^^^^ +None. + +Resolved Issues +^^^^^^^^^^^^^^^ +None. + +Deprecations +^^^^^^^^^^^^ +None. + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/project/coding-guidelines.rst b/docs/project/coding-guidelines.rst new file mode 100644 index 000000000..3090aa489 --- /dev/null +++ b/docs/project/coding-guidelines.rst @@ -0,0 +1,73 @@ +Coding Style & Guidelines +========================= + +The following sections contain |TS| coding guidelines. They are continually evolving and should not be considered "set +in stone". Feel free to question them and provide feedback. + +The |TS| project uses multiple "domains" (textual content types, like programming languages) and each defines its own +rules. + +To help configuring text editors the project comes with "`EditorConfig`_" file(s). (:download:`../../.editorconfig`). + +Shared rules +------------ + +The following rules are common for all domains, except where noted otherwise: + +#. Files shall be **UTF-8** encoded. +#. Use **Unix** style line endings (``LF`` character) +#. The primary language of the project is English. All comments and documentation must be in this language. +#. Trailing whitespace is not welcome, please trim these. + +C Domain +-------- + +C source code rules are base on the *Linux Coding Style* (See: |LCS|). The following deviations apply: + +5. |TS| follows *ISO/IEC 9899:1999* standard with |ACLE| version *Q3 2020* extensions. +#. Line length shall not exceed 100 characters. +#. Use `snake_case`_ for function, variable and file names. +#. Each file shall be "self contained" and include header files with external dependencies. No file shall depend on + headers included by other files. +#. Include ordering: please include project specific headers first and then system includes. Please order the files + alphabetically in the above two groups. +#. All variables must be initialized. + +Boring stuff is not for smart people and the project uses the `Uncrustify`_ code beautifier to easy formatting the +source. (See :download:`../../.uncrustify.cfg`) + +CMake domain +------------ + +11. CMake file names use `CamelCase`_ style. +#. Indent with tabs and otherwise use spaces. Use 4 spaces for tab size. +#. Use LF as line end in CMake files. +#. Remove trailing whitespace. +#. Maximum line length is 128 characters. +#. When complicated functionality is needed prefer CMake scripting over other languages. +#. Prefix local variables with `_`. +#. Use functions to prevent global name-space pollution. +#. Use `snake_case`_ for function and variable names. +#. Use the ``include_guard()`` CMake function when creating new modules, to prevent multiple inclusion. +#. Use self contained modules, i.e. include direct dependencies of the module. +#. Use the Sphinx CMake domain for in-line documentation of CMake scripts. For details please refer to the + `CMake Documentation`_. + +.. todo:: Explain CMake return values and parent scope concept in more detail. + +Restructured Text Domain +------------------------ + +Please refer to :doc:`/developer/writing-documentation`. + +-------------- + +.. _`CamelCase`: https://hu.wikipedia.org/wiki/CamelCase +.. _`snake_case`: https://en.wikipedia.org/wiki/Snake_case +.. _`CMake Documentation`: https://github.com/Kitware/CMake/blob/master/Help/dev/documentation.rst +.. _`EditorConfig`: https://editorconfig.org/ +.. _`Uncrustify`: https://github.com/uncrustify/uncrustify + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/project/contributing.rst b/docs/project/contributing.rst new file mode 100644 index 000000000..d9760d9f1 --- /dev/null +++ b/docs/project/contributing.rst @@ -0,0 +1,88 @@ +Contributing +============ + + +Getting Started +--------------- + +- Make sure you have a GitHub account and you are logged on `developer.trustedfirmware.org`_. +- Send an email to the |TS_MAIL_LIST| about your work. This gives everyone + visibility of whether others are working on something similar. +- Clone the |TS_REPO| on your own machine. +- Create a local topic branch based on ``main`` branch of the |TS_REPO|. + +Making Changes +-------------- + +- Make commits of logical units. See these general `Git guidelines`_ for contributing to a project. +- Follow the :ref:`Coding Style & Guidelines`. +- Keep the commits on topic. If you need to fix another bug or make another enhancement, please create a separate + change. +- Avoid long commit series. If you do have a long series, consider whether some + commits should be squashed together or addressed in a separate topic. +- Make sure your commit messages are in the proper format. Please keel the 50/72 rule (for details see `Tim Popes blog entry`_.) +- Where appropriate, please update the documentation. + + - Consider whether the this document or other in-source documentation + needs updating. + - Ensure that each changed file has the correct copyright and license information. Files that entirely consist of + contributions to this project should have a copyright notice and BSD-3-Clause SPDX license identifier of the form + as shown in :ref:`license`. Files that contain changes to imported Third Party IP files should retain their + original copyright and license notices. For significant contributions you may add your own copyright notice in + following format:: + + Portions copyright (c) [XXXX-]YYYY, <OWNER>. All rights reserved. + + where XXXX is the year of first contribution (if different to YYYY) and YYYY is the year of most recent + contribution. *<OWNER>* is your name or your company name. + - If you are submitting new files that you intend to be the technical sub-maintainer for (for example, a new platform + port), then also update the :ref:`maintainers` file. + - For topics with multiple commits, you should make all documentation changes (and nothing else) in the last commit + of the series. Otherwise, include the documentation changes within the single commit. + +- Please test your changes. + +Submitting Changes +------------------ + +- Ensure that each commit in the series has at least one ``Signed-off-by:`` line, using your real name and email + address. The names in the ``Signed-off-by:`` and ``Author:`` lines must match. If anyone else contributes to the + commit, they must also add their own ``Signed-off-by:`` line. By adding this line the contributor certifies the + contribution is made under the terms of the :download:`Developer Certificate of Origin <../../dco.txt>`. + + More details may be found in the `Gerrit Signed-off-by Lines guidelines`_. + +- Ensure that each commit also has a unique ``Change-Id:`` line. If you have cloned the repository with the "`Clone with + commit-msg hook`" clone method, this should already be the case. + + More details may be found in the `Gerrit Change-Ids documentation`_. + +- Submit your changes for review at https://review.trustedfirmware.org targeting the ``integration`` branch. + + - The changes will then undergo further review and testing by the :ref:`maintainers`. Any review comments will be made + directly on your patch. This may require you to do some rework. + + Refer to the `Gerrit Uploading Changes documentation`_ for more details. + +- When the changes are accepted, the :ref:`maintainers` will integrate them. + + - Typically, the :ref:`maintainers` will merge the changes into the ``integration`` branch. + - If the changes are not based on a sufficiently-recent commit, or if they cannot be automatically rebased, then the + :ref:`maintainers` may rebase it on the ``main`` branch or ask you to do so. + - After final integration testing, the changes will make their way into the ``main`` branch. If a problem is found + during integration, the merge commit will be removed from the ``integration`` branch and the :ref:`maintainers` will + ask you to create a new patch set to resolve the problem. + +-------------- + +.. _developer.trustedfirmware.org: https://developer.trustedfirmware.org +.. _Git guidelines: http://git-scm.com/book/ch5-2.html +.. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html +.. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html +.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html +.. _`Tim Popes blog entry`: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html + + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/project/glossary.rst b/docs/project/glossary.rst new file mode 100644 index 000000000..da907b436 --- /dev/null +++ b/docs/project/glossary.rst @@ -0,0 +1,35 @@ +Glossary +======== + +This glossary provides definitions for terms and abbreviations used in the Trusted Services documentation. + +You can find additional definitions in the `Arm Glossary`_. + +.. glossary:: + :sorted: + + TF-A + Trusted Firmware-A + + TS + Trusted Services + + C identifier like string + A name which uses only alphanumeric characters and underscores and the first character is not a digit. + + LCS + `Linux Coding Style`_ + + ACLE + `Arm C language extensions`_ + + +-------------- + +.. _`Arm Glossary`: https://developer.arm.com/support/arm-glossary +.. _`Linux Coding Style`: https://www.kernel.org/doc/html/v4.10/process/coding-style.html +.. _`Arm C language extensions`: https://developer.arm.com/documentation/101028/0012/?lang=en + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/project/index.rst b/docs/project/index.rst new file mode 100644 index 000000000..21f1d0f57 --- /dev/null +++ b/docs/project/index.rst @@ -0,0 +1,21 @@ +About the project +================= + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + change-log + coding-guidelines + contributing + glossary + license + maintainers + versioning_policy + todo + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/project/license.rst b/docs/project/license.rst index 472bc6a12..fb63be6a8 100644 --- a/docs/project/license.rst +++ b/docs/project/license.rst @@ -1,7 +1,7 @@ License ======= -Copyright (c) 2020, Arm Limited and Contributors. All rights reserved. +Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: @@ -11,7 +11,7 @@ are permitted provided that the following conditions are met: - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. -- Neither the name of ARM nor the names of its contributors may be used to +- Neither the name of Arm nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. diff --git a/docs/project/maintainers.rst b/docs/project/maintainers.rst index 61d13c586..992d92695 100644 --- a/docs/project/maintainers.rst +++ b/docs/project/maintainers.rst @@ -1,9 +1,9 @@ Maintainers =========== -|TS| is a Trusted Firmware maintained project. All contributions are ultimately +|TS| is a trustedfirmware.org maintained project. All contributions are ultimately merged by the maintainers listed below. Technical ownership of some parts of the -codebase is delegated to the code owners listed below. An acknowledgement from +code-base is delegated to the code owners listed below. An acknowledgment from these code maintainers may be required before the maintainers merge a contribution. @@ -45,6 +45,6 @@ Code owners .. _`Linux Maintainers file`: https://github.com/torvalds/linux/blob/master/MAINTAINERS#L80 .. _Project Maintenance Process: https://developer.trustedfirmware.org/w/collaboration/project-maintenance-process/ -*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/project/todo.rst b/docs/project/todo.rst new file mode 100644 index 000000000..1739eabcd --- /dev/null +++ b/docs/project/todo.rst @@ -0,0 +1,22 @@ +TODO list +========= + +This file collects information on planned future changes and issues to be +addressed. For managing the TODO list below, the `Sphinx TODO extension`_ is +used. + +.. todo:: Find a solution to make the rendering of TODO entries less intrusive + at their original location. + +List of TODO entries in the project +----------------------------------- + +.. todolist:: + +-------------- + +.. _`Sphinx TODO extension`: https://www.sphinx-doc.org/en/master/usage/extensions/todo.html + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause
\ No newline at end of file diff --git a/docs/project/versioning_policy.rst b/docs/project/versioning_policy.rst new file mode 100644 index 000000000..d57057fbe --- /dev/null +++ b/docs/project/versioning_policy.rst @@ -0,0 +1,47 @@ +Versioning policy +================== + +This document captures information about the version identifier used by the +project. It tells the meaning of each part, where the version information is +captured and how it is managed. + +Summary +------- + +The version identifier identifies the feature set supported by a specific +release, and captures compatibility information to other releases. + +This project uses "Semantic Versioning", for details please refer to |SEMVER|. + +In general the version number is constructed from three numbers. The `MAJOR` +number is changed when incompatible API changes are introduced, the `MINOR` +version when you functionality is added in a backward compatible manner, and +the `PATCH` version when backwards compatible bug fixes are added. + +Each release will get a unique release id assigned. When a release is made, the +version number will get incremented in accordance with the compatibility rules +mentioned above. + +This project is only using the core version and will not use pre-release or +build specific metadata extension. + +Storage and format +------------------ + +The version number of each release will be stored at two locations: + #. In a tag of the version control system in the form of "vX.Y.Z" where X Y + and Z are the major, minor and patch version numbers. + #. In a file called version.txt. This file uses ASCII encoding and will + contain the version number as "X.Y.Z" where X Y and Z are the major, + minor and patch version numbers. + +.. note:: The version id is independent from version identifiers of the + versioning system used to store the |TS| (i.e. git). + +-------------- + +.. _`Semantic Versioning`: https://semver.org/spec/v2.0.0.html + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/security/index.rst b/docs/security/index.rst new file mode 100644 index 000000000..ac271be6f --- /dev/null +++ b/docs/security/index.rst @@ -0,0 +1,19 @@ +Security Model +============== + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + self + +TODO: +SDL +Threat Modell +etc.. + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/standards/index.rst b/docs/standards/index.rst new file mode 100644 index 000000000..486cac031 --- /dev/null +++ b/docs/standards/index.rst @@ -0,0 +1,14 @@ +Standards Compliance +==================== + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + psa_certification + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/standards/psa_certification.rst b/docs/standards/psa_certification.rst new file mode 100644 index 000000000..e9a888c91 --- /dev/null +++ b/docs/standards/psa_certification.rst @@ -0,0 +1,191 @@ +PSA Certification Requirements +============================== + +Trusted services contribute to meeting PSA security requirements. In the context of PSA certification, the scope and required +capabilities of supported trusted services are guided by: + + - The security primitives needed by system software for PSA level 1 checklist compliance. + - Test coverage of the certification test suite used for PSA Functional API certification. + +To determine what security primitives are needed, the 'system software' PSA scope has been used as a reference. The current PSA +level 1 questionnaire is highly Cortex-M specific so some interpretation is needed to map requirements to Cortex-A based designs +that use a rich-OS such as Linux. The following assessment is based on the assumption that the PSA system software scope +encompasses an entire Linux distribution. The reference system software for the assessment will include: + + - TF-A. + - Secure partition manager (OP-TEE with FF-A extensions performs this role). + - Set of trusted services, deployed in S-EL0 secure partitions that are built-in to the OP-TEE image to allow early loading. + - Normal-world boot loader. EDK2 with Grub used as reference. + - Linux kernel. + - Root filesystem that includes generic services, libraries and program binaries. + +Product developers will extend the base distribution to add application specific components. + +PSA System Software Questionnaire Analysis +------------------------------------------ + +The following table lists PSA level 1 assessment questions with an attempt to identify the back-end security primitives that are +needed to meet the requirement. The table is based on PSA Certified Level 1 Questionnaire Version 2.1. + +.. list-table:: PSA Questionnaire Analysis + :widths: 13 40 15 15 28 + :header-rows: 1 + + * - Requirement + - Summary + - Depends on + - TS used + - Comment + * - R1.1 + - | System software and application software update + | verification using immutable root-of-trust. + - Verify signed hash + - Crypto + - Depends on secure for persistent key storage. + * - R1.2 + - | System software and application software update + | anti-rollback protection. + - Increment only NV counter + - | Secure Storage (for protecting normal + | world components) + - | TF-A uses OTP fuses for early boot stages. This requirement is much more difficult to meet + | on Cortex-A compared to M as + | there are potentially many separately updatable components. + * - R2.1 + - Protected device ID + - Sign hash + - Crypto + - Depends on secure storage for persistent key storage. + * - R2.2 + - Secure storage + - Replay protected persistent storage, tied to device + - Secure storage + - | A filesystem mount that provided file storage with the required security properties would be + | the conventional interface for user-space processes. + * - R2.3 + - Crypto best practices + - TRNG for random number and key generation + - Crypto + - Crypto service will need an entropy source. + * - R3.1 + - Remote server authentication + - Verify signed hash + - Crypto + - Depends on secure storage for persistent key storage. + * - R3.2 + - Communication encryption + - Kernel encryption support + - None + - Not a use-case for trusted services. + * - R3.3 + - TLS authentication support + - Sign & verify hash + - Crypto + - TLS library such as Mbed TLS needs to use Crypto service. + * - R4.1 + - Provide attestation token for device life-cycle state + - Secure life-cycle state variable, Sign message. + - Attestation, Secure lifecycle, Crypto + - + * - R4.2 + - Unused functionality disabled + - Secure life-cycle state variable + - Secure Lifecycle + - | Although the PSA questionnaire doesn't state this, in practice, the minimal capabilities + | required will depend on the device lifecycle state. This will extend to all parts of the + | system software, including trusted service capabilities. + * - R4.3 + - Secure logging + - Sign hash for non-repudiable log. + - Crypto + - | PSA questionnaire isn't specific about non-repudiation but for security auditing purposes, + | this may be a requirement. For example, for industrial IoT applications where conformance + | to IEC 62443 is important, verifiable log data that can be reliably traced, back to the + | originating device is understood to be required. + * - R4.4 + - Restricted log file access + - File access control + - None + - File access using standard Linux DAC or MAC if used. + * - R4.5 + - Data on external interfaces checked defensively + - Good coding practices in application components + - + - | The same could be applied for messages crossing any security boundary e.g. trusted service + | interfaces. PSA only mentions external interfaces and critical APIs but for Cortex-A, this + | likely to be insufficient. + * - R4.6 + - Principle of least privileges + - Use of Linux isolation, access control and other containment methods. + - + - | No direct dependency on trusted services but access to TS held assets must be controlled + | according to principle of least privileges. + * - R5.1 + - Passwords not resettable + - Enforcing password policy + - + - + * - R5.2 + - Password best practices + - Enforcing password policy + - + - + * - R5.3 + - User authentication using critical security parameters + - Depends on auth method + - Crypto (possibly) + - | Requirement is not specific enough to determine if there is a trusted service dependency. + | Dependency may be indirect, say to authenticate an Oauth2 server. + * - R6.1 + - Externally applied configuration signed + - Verify signed hash + - Crypto + - Similar to firmware update verification requirement. + * - R7.1 + - Persistent storage of user data must support destructive erase + - Destructive erase secure Storage (possibly) + - Secure storage + - | File based storage with a filesystem mount with the required security properties would be the + | conventional way to provide persistent storage to user-space processes. + +Observations +------------ + +- All dependencies on the PSA Crypto service involve persistent keys. Volatile key support is not needed for compliance. +- Applying R4.2 to system software doesn't really make sense. The system software features that are needed are largely + determined by the application software that implements the device functionality. For a supplier of the base system software, + a super-set of required functionality is likely to be the right offering but with the facility to allow features to be + configured by device developers. The ability to apply a configuration that limits functionality would be a more useful goal. +- Although the PSA certification document doesn't mention this, available device capabilities need to be a function of device + life-cycle state. For example, some features used during manufacture should not be available when a device is delivered to + end users. +- It's hard to see anyone using the PSA Protected Storage API directly. However, enabling a filesystem mount with equivalent + security properties would be beneficial. For example, a protected storage filesystem driver that uses the Protected Storage + service as its back-end would be a good fit. The PSA Protected Storage API would never be used directly by user-space + applications. +- Logging with the guarantee of non-repudiation is really required to support audit use-cases. Without that guarantee, it's + just logging. + +PSA Functional API Tests +------------------------ + +Functional API tests suites are currently available for: + + - PSA Crypto + - PSA Attestation + - PSA Storage + +Running and passing API tests is not a requirement for PSA level 1 certification. However, incorporating the API tests into the +trusted service test process is obviously beneficial as a way of demonstrating a defined set of functionality. + +Functional API tests focus on valid behavior testing and are quite thorough in exercising all required functionality that can be +observed at each API. To pass all tests, the service implementation needs to be complete, at least from a functional +perspective. + +Test code depends on an implementation of the PSA C APIs for each service under test. + +-------------- + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause diff --git a/docs/uml/colors.puml b/docs/uml/colors.puml new file mode 100644 index 000000000..7b1238c52 --- /dev/null +++ b/docs/uml/colors.puml @@ -0,0 +1,30 @@ +'------------------------------------------------------------------------------- +' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved. +' +' SPDX-License-Identifier: BSD-3-Clause +' +'------------------------------------------------------------------------------- + +' Colors shared between various graphs + +!define COLOR_ARM_BLUE #0091BD +!define COLOR_LT_BLUE b3edff + +' The higher the number at the end of the name the darker the color is. +!define COLOR_BLUE1 #DCEEF3 +!define COLOR_BLUE2 #B9DDE7 +!define COLOR_BLUE3 #96CDDB +!define COLOR_GREEN1 #EBF1E0 +!define COLOR_GREEN2 #DEF2B8 +!define COLOR_GREY1 #D9D9D9 +!define COLOR_GREY2 #F2F2F2 +!define COLOR_RED1 #FF9C9C +!define COLOR_RED2 #FFD6D6 + +!define COLOR_PSA_NW COLOR_GREY1 +!define COLOR_PSA_S_APP_ROT COLOR_GREEN1 +!define COLOR_PSA_S_PSA_ROT COLOR_BLUE2 +!define COLOR_PSA_S_ROT_PERIPHERAL COLOR_BLUE1 +!define COLOR_PSA_NS_PE COLOR_NW +!define COLOR_PSA_FW_API COLOR_RED2 +!define COLOR_PSA_ROT_SERVICE_API COLOR_RED1 diff --git a/docs/uml/libsp_functions.puml b/docs/uml/libsp_functions.puml new file mode 100644 index 000000000..b46cc01ec --- /dev/null +++ b/docs/uml/libsp_functions.puml @@ -0,0 +1,118 @@ +'------------------------------------------------------------------------------- +' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved. +' +' SPDX-License-Identifier: BSD-3-Clause +' +'------------------------------------------------------------------------------- + +@startuml + +class ffa_internal_api { + .. SVC call .. + + ffa_svc() +} + +package "FF-A layer" { + class ffa_api { + .. Setup and discovery interfaces .. + + ffa_version() + + ffa_features() + + ffa_rx_release() + + ffa_rxtx_map() + + ffa_rxtx_unmap() + + ffa_partition_info_get() + + ffa_id_get() + + .. CPU cycle management interfaces .. + + ffa_msg_wait() + + .. Messaging interfaces .. + + ffa_msg_send_direct_req() + + ffa_msg_send_direct_resp() + + .. Memory management interfaces .. + + ffa_mem_donate() + + ffa_mem_donate_rxtx() + + ffa_mem_lend() + + ffa_mem_lend_rxtx() + + ffa_mem_share() + + ffa_mem_share_rxtx() + + ffa_mem_retrieve_req() + + ffa_mem_retrieve_req_rxtx() + + ffa_mem_relinquish() + + ffa_mem_reclaim() + + .. Interrupt handler definition .. + + ffa_interrupt_handler() + } + + class ffa_memory_descriptors { + .. Transaction buffer handling .. + + ffa_init_mem_transaction_buffer() + + .. Transaction descriptor .. + + ffa_init_mem_transaction_desc() + + ffa_get_mem_transaction_desc() + + .. Memory access descriptor .. + + ffa_reserve_mem_access_desc() + + ffa_add_mem_access_desc() + + ffa_get_mem_access_desc_count() + + ffa_get_mem_access_desc() + + .. Memory region .. + + ffa_add_memory_region() + + ffa_get_memory_region() + } +} + +package "SP layer" { + class sp_rxtx { + .. RXTX buffer handling .. + + sp_rxtx_buffer_map() + + sp_rxtx_buffer_unmap() + + sp_rxtx_buffer_alignment_boundary_get() + + sp_rxtx_buffer_rx_get() + + sp_rxtx_buffer_tx_get() + } + + class sp_memory_management { + .. Donate .. + + sp_memory_donate() + + sp_memory_donate_dynamic() + + sp_memory_donate_dynamic_is_supported() + + .. Lend .. + + sp_memory_lend() + + sp_memory_lend_dynamic() + + sp_memory_lend_dynamic_is_supported() + + .. Share .. + + sp_memory_share() + + sp_memory_share_dynamic() + + sp_memory_share_dynamic_is_supported() + + .. Retrieve .. + + sp_memory_retrieve() + + sp_memory_retrieve_dynamic() + + sp_memory_retrieve_dynamic_is_supported() + + .. Relinquish .. + + sp_memory_relinquish() + + .. Reclaim .. + + sp_memory_reclaim() + } +} + + +ffa_api -left-> ffa_internal_api + +ffa_api -[hidden]-> ffa_memory_descriptors + +sp_rxtx -left-> ffa_api +sp_memory_management --> ffa_api +sp_memory_management -left-> ffa_memory_descriptors +sp_memory_management -up-> sp_rxtx + +@enduml diff --git a/docs/uml/style-component.puml b/docs/uml/style-component.puml new file mode 100644 index 000000000..9400e93b6 --- /dev/null +++ b/docs/uml/style-component.puml @@ -0,0 +1,28 @@ +'------------------------------------------------------------------------------- +' Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved. +' +' SPDX-License-Identifier: BSD-3-Clause +' +'------------------------------------------------------------------------------- + +@startuml +!include colors.puml + +'Comonent diagram definitions +!define NS_COMPONENT component COLOR_GREY2 +!define NS_IFC interface COLOR_GREY2 +!define S_COMPONENT component COLOR_BLUE1 +!define S_IFC interface COLOR_BLUE1 + +skinparam component { + ArrowColor black + BorderColor black +} + +skinparam interface { + BorderColor black +} + +skinparam BackgroundColor COLOR_ARM_BLUE + +@enduml diff --git a/tools/b-test/Readme.rst b/tools/b-test/Readme.rst index 4100e9188..a4ec2c40e 100644 --- a/tools/b-test/Readme.rst +++ b/tools/b-test/Readme.rst @@ -96,8 +96,6 @@ Execute ``run.sh help`` to get further details. -------------- -*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.* - .. |yasha| replace:: `yasha`_ .. |jinja2| replace:: `Jinja2`_ .. |yaml| replace:: `yaml`_ @@ -105,3 +103,7 @@ Execute ``run.sh help`` to get further details. .. _Jinja2: https://palletsprojects.com/p/jinja .. _yasha: https://github.com/kblomqvist/yasha .. _yaml: https://yaml.org + +*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.* + +SPDX-License-Identifier: BSD-3-Clause
\ No newline at end of file |