Docs: Refresh the Crypto service integration guide
The TF-M Crypto service integration guide needs to be
refreshed to reflect newer changes that have been
merged over time. Also, introduce some useful references,
cross-referencing when needed, plus add support in conf.py
for newer versions of Sphinx.
Signed-off-by: Antonio de Angelis <antonio.deangelis@arm.com>
Change-Id: I2bcbc38e5940f042b516ab44355a7ad2354dac5f
diff --git a/docs/conf.py b/docs/conf.py
index 2a8deb5..931d39d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -49,7 +49,7 @@
'sphinx.ext.autosectionlabel', #Make sphinx generate a label for each section
'sphinxcontrib.plantuml', #Add support for PlantUML drawings
'sphinxcontrib.rsvgconverter', #Add support for SVG to PDF
- 'sphinx_tabs.tabs' #Enable tab extension in Sphinx
+ 'sphinx_tabs.tabs', #Enable tab extension in Sphinx
]
# PlantUML
@@ -157,3 +157,4 @@
author, 'manual'),
]
+language = 'en'
diff --git a/docs/design_docs/services/index.rst b/docs/design_docs/services/index.rst
index 5024f88..ada4e74 100644
--- a/docs/design_docs/services/index.rst
+++ b/docs/design_docs/services/index.rst
@@ -12,7 +12,7 @@
Service Signing <tfm_uniform_secure_service_signature.rst>
Crypto <tfm_crypto_design.rst>
Initial Attestation <symmetric_initial_attest.rst>
- Internal Storage <tfm_its_service.rst>
+ Internal Trusted Storage <tfm_its_service.rst>
Firmware Update <tfm_fwu_service.rst>
PS Key Management <ps_key_management.rst>
diff --git a/docs/design_docs/tfm_builtin_keys.rst b/docs/design_docs/tfm_builtin_keys.rst
index d68f51f..19a7d94 100644
--- a/docs/design_docs/tfm_builtin_keys.rst
+++ b/docs/design_docs/tfm_builtin_keys.rst
@@ -6,6 +6,8 @@
:Organization: Arm Limited
:Contact: raef.coles@arm.com
+.. _tfm-builtin-keys-label:
+
************
Introduction
************
diff --git a/docs/integration_guide/index.rst b/docs/integration_guide/index.rst
index 821d894..75fbbac 100644
--- a/docs/integration_guide/index.rst
+++ b/docs/integration_guide/index.rst
@@ -35,7 +35,7 @@
How to add a new platform
*************************
-:doc:`Porting TF-M to a New Hardware </integration_guide/platform/porting_TFM_to_a_new_hardware>`
+:doc:`Porting TF-M to a New Hardware </integration_guide/platform/porting_tfm_to_a_new_hardware>`
contains guidance on how to add a new platform.
***************************
diff --git a/docs/integration_guide/platform/index.rst b/docs/integration_guide/platform/index.rst
index ff3ed0b..79fe484 100644
--- a/docs/integration_guide/platform/index.rst
+++ b/docs/integration_guide/platform/index.rst
@@ -7,7 +7,7 @@
.. toctree::
:maxdepth: 1
- porting_TFM_to_a_new_hardware
+ porting_tfm_to_a_new_hardware
documenting_platform.rst
platform_deprecation.rst
diff --git a/docs/integration_guide/platform/porting_TFM_to_a_new_hardware.rst b/docs/integration_guide/platform/porting_tfm_to_a_new_hardware.rst
similarity index 100%
rename from docs/integration_guide/platform/porting_TFM_to_a_new_hardware.rst
rename to docs/integration_guide/platform/porting_tfm_to_a_new_hardware.rst
diff --git a/docs/integration_guide/services/index.rst b/docs/integration_guide/services/index.rst
index a534d6d..d92f6bf 100644
--- a/docs/integration_guide/services/index.rst
+++ b/docs/integration_guide/services/index.rst
@@ -7,11 +7,11 @@
Initial Attestation <tfm_attestation_integration_guide>
Crypto <tfm_crypto_integration_guide>
- Internal Storage <tfm_its_integration_guide>
+ Internal Trusted Storage <tfm_its_integration_guide>
Platform <tfm_platform_integration_guide>
Protected Storage <tfm_ps_integration_guide>
Adding a New Service <tfm_secure_partition_addition>
- The manifest tool <tfm_manifest_tool_user_guide>
+ Manifest Tool <tfm_manifest_tool_user_guide>
--------------
diff --git a/docs/integration_guide/services/tfm_crypto_integration_guide.rst b/docs/integration_guide/services/tfm_crypto_integration_guide.rst
index da0123e..1218bfb 100644
--- a/docs/integration_guide/services/tfm_crypto_integration_guide.rst
+++ b/docs/integration_guide/services/tfm_crypto_integration_guide.rst
@@ -5,18 +5,55 @@
************
Introduction
************
-TF-M Crypto service allows application to use cryptography primitives such as
-symmetric and asymmetric ciphers, hash, message authentication codes (MACs) and
-authenticated encryption with associated data (AEAD).
+The TF-M Crypto service allows Non Secure world applications and Secure
+services to use cryptographic functionalities such as symmetric ciphering,
+message signing and verification, asymmetric encryption and decryption,
+cryptographic hashes, message authentication codes (MACs), key derivation and
+agreement, authenticated encryption with associated data (AEAD). It exposes the
+PSA Crypto APIs [1]_.
+
+.. _components-label:
+
+The secure service resides in the Crypto partition as a single entry point and
+is made of different components:
+
+ - An interface layer that exposes the PSA Crypto API to either NS or S entities
+ and is implemented in ``interface/src/tfm_crypto_api.c``. The interface is
+ based on the Uniform Secure Service Signature and communicates with the
+ Secure Partition Manager available in TF-M
+ - An init module ``secure_fw/partitions/crypto/crypto_init.c`` that implements
+ functionalities requested by TF-M during the initialisation phase, and an API
+ dispatcher that at runtime receives the requests from the interface and
+ dispatches them to the component that processes that particular API request
+ - A set of components that process cryptographic API requests, each component
+ dispatching to a subset of functionalities, i.e. AEAD, Asymmetric, Ciphering,
+ Hashing, Key derivation, Key management, MACs, and Random Number Generation
+ - An alloc module ``secure_fw/partitions/crypto/crypto_alloc.c`` that manages
+ the partition secure memory, storing multipart application contexts, input /
+ outputs of the APIs being requested, inaccessible from NS or other secure
+ partitions
+ - A library abstraction module ``secure_fw/partitions/crypto/crypto_library.c``
+ which is used to abstract the details of the cryptographic library used by
+ the service *backend* to provide the actual implementation of the crypto
+ functionalities. The backend library must expose the PSA Crypto APIs, and
+ must provide support to encode *key ownership* into key identifiers. This is
+ not standardized by the PSA Crypto APIs so it must be provided as an
+ extension to the APIs. The backend library also needs to provide the
+ subsystem for key storage and retrieval, and, in case, the interface to the
+ cryptographic accelerator of the underlying platform, using the PSA
+ cryptoprocessor driver interface specification [2]_. For this reason, it must
+ provide a mechanism to access platform *builtin* keys, and permanent key
+ slots using the
+ :ref:`TF-M Internal Trusted Storage (ITS) service <its-introduction-label>`,
+ if available.
**************
Code structure
**************
The PSA interfaces for the Crypto service are located in ``interface/include``.
The only header to be included by applications that want to use functions from
-the PSA API is ``psa/crypto.h``.
-The TF-M Crypto service source files are located in
-``secure_fw/partitions/crypto``.
+the PSA API is ``psa/crypto.h``. The TF-M Crypto service source files are
+located in ``secure_fw/partitions/crypto``.
PSA interfaces
==============
@@ -28,54 +65,62 @@
Service source files
====================
-- ``crypto_cipher.c`` : This module handles requests for symmetric cipher
- operations
-- ``crypto_hash.c`` : This module handles requests for hashing operations
-- ``crypto_mac.c`` : This module handles requests for MAC operations
-- ``crypto_aead.c`` : This module handles requests for AEAD operations
-- ``crypto_key_derivation.c`` : This module handles requests for key derivation
- related operations
-- ``crypto_key_management.c`` : This module handles requests for key management
- related operations
-- ``crypto_key.c`` : This module handles requests for key backend operations,
- including key attributes switch between caller and service.
-- ``crypto_asymmetric.c`` : This module handles requests for asymmetric
- cryptographic operations
-- ``crypto_init.c`` : This module provides basic functions to initialise the
- secure service during TF-M boot. When the service is built for IPC model
- compatibility, this layer handles as well the connection requests and the
- proper dispatching of requests to the corresponding functions, and it holds
- the internal buffer used to allocate temporarily the IOVECs needed. The size
- of this buffer is controlled by the ``CRYPTO_IOVEC_BUFFER_SIZE`` define.
- This module also provides a static buffer which is used by the Mbed Crypto
- library for its own allocations. The size of this buffer is controlled by
- the ``CRYPTO_ENGINE_BUF_SIZE`` define
-- ``crypto_alloc.c`` : This module is required for the allocation and release of
- crypto operation contexts in the SPE. The ``CRYPTO_CONC_OPER_NUM``,
- defined in this file, determines how many concurrent contexts are supported
- for multipart operations (8 for the current implementation). For multipart
- cipher/hash/MAC/generator operations, a context is associated to the handle
- provided during the setup phase, and is explicitly cleared only following a
- termination or an abort
-- ``tfm_crypto_api.c`` : This module implements the PSA Crypto API
- client interface exposed to users.
-- ``tfm_crypto_api.c`` : This module is contained in ``interface/src`` and
- implements the PSA Crypto API client interface exposed to the Non-Secure
- Processing Environment.
-- ``tfm_mbedcrypto_alt.c`` : This module contains alternative implementations of
- Mbed Crypto functions. Decryption code is skipped in AES CCM mode in Profile
- Small by default.
+A brief description of what is implemented by each source file is as below:
-****************************
-Crypto Backend configuration
-****************************
+ - ``crypto_cipher.c`` : Dispatcher for symmetric crypto operations
+ - ``crypto_hash.c`` : Dispatcher for hash operations
+ - ``crypto_mac.c`` : Dispatcher for MAC operations
+ - ``crypto_aead.c`` : dispatcher for AEAD operations
+ - ``crypto_key_derivation.c`` : Dispatcher for key derivation and key agreement
+ operations
+ - ``crypto_key_management.c`` : Dispatcher for key management operations
+ towards the key slot management system provided by the backend library
+ - ``crypto_rng.c`` : Dispatcher for the random number generation requests
+ - ``crypto_asymmetric.c`` : Dispatcher for message signature/verification and
+ encryption/decryption using asymmetric crypto
+ - ``crypto_init.c`` : Init module for the service. The modules stores also the
+ internal buffer used to allocate temporarily the IOVECs needed, which is not
+ required in case of SFN model. The size of this buffer is controlled by the
+ ``CRYPTO_IOVEC_BUFFER_SIZE`` config define
+ - ``crypto_library.c`` : Library abstractions to interface the dispatchers
+ towards the underlying library providing *backend* crypto functions.
+ Currently this only supports the mbed TLS library. In particular, the mbed
+ TLS library requires to provide a static buffer to be used as heap for its
+ internal allocation. The size of this buffer is controlled by the
+ ``CRYPTO_ENGINE_BUF_SIZE`` config define
+ - ``crypto_alloc.c`` : Takes care of storing multipart operation contexts in a
+ secure memory not visible outside of the crypto service. The
+ ``CRYPTO_CONC_OPER_NUM`` config define determines how many concurrent
+ contexts are supported at once. In a multipart operation, the client view of
+ the contexts is much simpler (i.e. just an handle), and the Alloc module
+ keeps track of the association between handles and contexts
+ - ``tfm_crypto_api.c`` : This module is contained in ``interface/src`` and
+ implements the PSA Crypto API client interface exposed to both S/NS clients
+ - ``tfm_mbedcrypto_alt.c`` : This module is specific to the mbed TLS [3]_
+ library integration and provides some alternative implementation of mbed TLS
+ APIs that can be used when a optimised profile is chosen. Through the
+ ``_ALT`` mechanism it is possible to replace at link time default
+ implementations available in mbed TLS with the ones available in this file
-The Crypto service can use either a hardware crypto accelerator backend like
-CC-312 or a software crypto library which by default is MbedTLS.
+ .. Note::
+ The ``_ALT`` mechanism will be deprecated in future releases of the mbed
+ TLS library
-If using MbedTLS as backend, then the library configuration is supplied using
-the ``TFM_MBEDCRYPTO_CONFIG_PATH`` and ``TFM_MBEDCRYPTO_PSA_CRYPTO_CONFIG_PATH``
-cmake option.
+***************************************
+Considerations on service configuration
+***************************************
+
+Crypto *backend* library configuration
+======================================
+The TF-M Crypto service relies on a cryptographic library to provide the
+functionalities specific by the PSA Crypto API spec and the PSA cryptoprocessor
+driver interface spec. At the moment, the only supported library is mbed
+TLS [3]_.
+
+The configuration of the backend library is supplied using the
+``TFM_MBEDCRYPTO_CONFIG_PATH`` and ``TFM_MBEDCRYPTO_PSA_CRYPTO_CONFIG_PATH``
+config option that point to configuration headers following the legacy mbed TLS
+configuration scheme or the new PSA based configuration scheme.
Platforms can specify an extra config file by setting the
``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` variable (which is a wrapper
@@ -86,43 +131,51 @@
.. Note::
- The default entropy source configured for MbedTLS is
- MBEDTLS_ENTROPY_NV_SEED with unique seed. For production devices,
- it can also select a hardware entropy source via
- MBEDTLS_ENTROPY_HARDWARE_ALT
+ The default entropy source configured for mbed TLS is
+ ``MBEDTLS_ENTROPY_NV_SEED`` with a unique seed. For production devices, an
+ alternative hardware entropy source can be specified using the config option
+ ``MBEDTLS_ENTROPY_HARDWARE_ALT``
-**************************************
-Other Crypto Service Build Definitions
-**************************************
-- ``CRYPTO_STACK_SIZE``- Defines the stack size of the Crypto Secure Partition. This
- value mainly depends on other crypto service configurations, the build type(debug,
- release and minisizerel) and compiler.
+.. Note::
+ Starting from mbed TLS 3.3.0, the Python package ``jsonschema`` must be
+ available when building as it is required by the autogen framework for the
+ driver integrations into the PSA Crypto core and driver wrapper modules
-**************************
-Crypto service integration
-**************************
-In this section, a brief description of the required flow of operation for the
-functionalities exported by the PSA Crypto interface is given, with particular
-focus on the TF-M Crypto service specific operations. For the details of the
-generic PSA Crypto interface operations, please refer directly to the header
-``psa/crypto.h``.
+Crypto service build time options
+=================================
-Most of the PSA Crypto multipart APIs require an operation context to be
-allocated by the application and then to be passed as a pointer during the
-following API calls. These operation contexts are of four main types described
-below:
+ - ``CRYPTO_STACK_SIZE`` : Defines the stack size of the Crypto Secure
+ Partition. This value might depend on several parameters such as the build
+ type, the compiler being used, the cryptographic functionalities that are
+ enabled at build time
+ - ``CRYPTO_<COMPONENT>_MODULE_ENABLED`` : A series of defines, one per each
+ ``<COMPONENT>`` that processes cryptographic operations, that are used to
+ disable modules at build time. Each define corresponds to a component as
+ described in :ref:`the components list <components-label>`.
-- ``psa_key_derivation_operation_t`` - Operation context for key derivation
-- ``psa_hash_operation_t`` - Operation context for multipart hash operations
-- ``psa_mac_operation_t`` - Operation context for multipart MAC operations
-- ``psa_cipher_operation_t`` - Operation context for multipart cipher operations
-The user applications are not allowed to make any assumption about the original
-types behind these typedefs, which are defined inside ``psa/crypto.h``.
-In the scope of the TF-M Crypto service, these types are regarded as handles to
-the corresponding implementation defined structures which are stored in the
-Secure world.
+Crypto service *builtin* keys integration
+=========================================
+A detailed description of how the service interacts with *builtin* keys is
+available in the ``tfm_builtin_key_loader``
+:ref:`design document <tfm-builtin-keys-label>`.
+
+.. Note::
+
+ The crypto service integration with builtin keys relies on implementation
+ details of mbed TLS that are not standardized in the spec and might change
+ between releases due to ongoing work [4]_
+
+
+References
+----------
+
+.. [1] PSA Crypto APIs: \ https://armmbed.github.io/mbed-crypto/html/
+.. [2] PSA cryptoprocessor driver interface: \ https://github.com/Mbed-TLS/mbedtls/blob/development/docs/proposed/psa-driver-interface.md
+.. [3] mbed TLS library: \ https://www.trustedfirmware.org/projects/mbed-tls/
+.. [4] Interface for platform keys: \ https://github.com/ARM-software/psa-crypto-api/issues/550
+
--------------
-*Copyright (c) 2018-2022, Arm Limited. All rights reserved.*
+*Copyright (c) 2018-2023, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_its_integration_guide.rst b/docs/integration_guide/services/tfm_its_integration_guide.rst
index d8c1f31..d0102c3 100644
--- a/docs/integration_guide/services/tfm_its_integration_guide.rst
+++ b/docs/integration_guide/services/tfm_its_integration_guide.rst
@@ -2,6 +2,8 @@
TF-M Internal Trusted Storage Service Integration Guide
#######################################################
+.. _its-introduction-label:
+
************
Introduction
************
@@ -313,7 +315,7 @@
filesystem is lost in the case of an asynchronous power failure.
- ``ITS_STACK_SIZE``- Defines the stack size of the Internal Trusted Storage
Secure Partition. This value mainly depends on the platform specific flash
- drivers, the build type(debug, release and minisizerel) and compiler.
+ drivers, the build type (Debug, Release and MinSizeRel) and compiler.
--------------