Docs: Update crypto service related documentation
This patch updates the relevant documentation in the
docs folder following the migration of the TF-M Crypto
service to use Mbed Crypto and associated activities.
Change-Id: Ifb1baf870bb702a68cf25832cc2e2cdf62834b9d
Signed-off-by: Antonio de Angelis <antonio.deangelis@arm.com>
Co-authored-by: Jamie Fox <jamie.fox@arm.com>
diff --git a/docs/user_guides/services/tfm_crypto_integration_guide.rst b/docs/user_guides/services/tfm_crypto_integration_guide.rst
index 82faea9..7fcac0e 100644
--- a/docs/user_guides/services/tfm_crypto_integration_guide.rst
+++ b/docs/user_guides/services/tfm_crypto_integration_guide.rst
@@ -21,62 +21,60 @@
PSA interfaces
==============
The TF-M Crypto service exposes the PSA interfaces detailed in the header
-``psa_crypto.h``. There are two additional header files, named
-``psa_crypto_extra.h`` and ``psa_crypto_platform.h``, which are meant to be
-included only by the ``psa_crypto.h`` header itself, that specify, respectively,
-extensions to the API that are vendor specific, and provide definitions and
-types which are platform specific. For a detailed description of the PSA API
-interface, please refer to the comments in the ``psa_crypto.h`` header itself.
+``psa_crypto.h``. This header, in turn, includes several other headers which
+are not meant to be included directly by user applications. For a detailed
+description of the PSA API interface, please refer to the comments in the
+``psa_crypto.h`` header itself.
Service source files
====================
-- ``crypto_cipher.c`` : This file implements functionalities related to the
- ciphering module
-- ``crypto_hash.c`` : This file implements functionalities related to
- the hashing module
-- ``crypto_init.c`` : This file provides basic functions to initialise
- the secure service during TF-M boot;
-- ``crypto_key.c`` : This file implements functionalities related to
- the key management module. The ``TFM_CRYPTO_KEY_STORAGE_NUM`` determines how
- many key stores are available, while the ``TFM_CRYPTO_MAX_KEY_LENGTH`` defines
- the maximum allowed key length in bytes supported in a key storage. These
- two items can be modfied at the build configuration step by defining the
- following variables, ``-DCRYPTO_KEY_STORAGE_NUM=<value>`` and the
- ``-DCRYPTO_KEY_MAX_KEY_LENGTH=<value>``
-- ``crypto_alloc.c`` : This file implements extensions to the PSA interface
- which are specifically required by the TF-M Crypto service, in particular
- related to the allocation and deallocation of crypto operation contexts in
- the secure world. The ``TFM_CRYPTO_CONC_OPER_NUM``, defined in this file,
- determines how many concurrent contexts are supported (8 for the current
- implementation). For multipart cipher/hash/MAC operations, a context is
- associated to the handle provided during the setup phase, and is explicitly
- cleared only following a successful termination or an abort
-- ``crypto_engine.c`` : This file implements the layer which the other
- modules use to interact with the cryptography primitives available (in SW or
- HW). The ``TFM_CRYPTO_ENGINE_BUF_SIZE`` determines the size in bytes of the
- static scratch buffer used by this layer for its internal allocations. This
- item can be modified at the build configuration step by defining
- ``-DCRYPTO_ENGINE_BUF_SIZE=<value>``. The current implementation provides only
- SW primitives based on Mbed TLS functions
-- ``crypto_mac.c`` : This file implements functionalities related to the
- MAC (Message Authentication Code) module
-- ``crypto_aead.c`` : This file implements functionalities related to the AEAD
- (Authenticated Encryption with Associated Data) module.
+- ``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_generator.c`` : This module handles requests for generator related
+ operations
+- ``crypto_key.c`` : This module handles requests for key related operations
+- ``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 mode
+ 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 ``TFM_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 ``TFM_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 ``TFM_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_secure_api.c`` : This module implements the PSA Crypto API
+ client interface exposed to the Secure Processing Environment
+ - ``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.
********************************
Crypto service integration guide
********************************
-n this section, a brief description of the required flow of operation for the
+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``.
-Most of the PSA Crypto 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 describes below:
+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:
-- ``psa_key_policy_t`` - Operation context to be used when setting key policies
+- ``psa_crypto_generator_t`` - Operation context for generator operations
- ``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
diff --git a/docs/user_guides/services/tfm_sst_integration_guide.rst b/docs/user_guides/services/tfm_sst_integration_guide.rst
index 87cf3ce..5fd2a31 100644
--- a/docs/user_guides/services/tfm_sst_integration_guide.rst
+++ b/docs/user_guides/services/tfm_sst_integration_guide.rst
@@ -24,21 +24,21 @@
- **Confidentiality** - Resistance to unauthorised accesses through
hardware/software attacks.
-
+
- **Access Authentication** - Mechanism to establish requester's identity (a
non-secure entity, secure entity, or a remote server).
-
+
- **Integrity** - Resistant to tampering by either the normal users of a product,
package, or system or others with physical access to it. If the content of the
secure storage is changed maliciously, the service is able to detect it.
-
+
- **Reliability** - Resistant to power failure scenarios and incomplete write
cycles.
-
+
- **Configurability** - High level configurability to scale up/down memory
footprint to cater for a variety of devices with varying security
requirements.
-
+
- **Performance** - Optimized to be used for resource constrained devices with
very small silicon footprint, the PPA (power, performance, area) should be
optimal.
@@ -54,19 +54,19 @@
A delete operation implicitly moves all the assets towards the top of the block
to avoid fragmentation within block. However, this may also result in
unutilized space at the end of each block.
-
+
- **Asset size limitation** - An asset is stored in a contiguous space in a
block/sector. Hence, the maximum asset size can be up-to the size of the
data block/sector. Detailed information about the maximum asset size can be
found in the section `Maximum asset size` below.
-
+
- **Non-hierarchical storage model** - The current design uses a
non-hierarchical storage model, as a filesystem, where all the assets are
managed by a linearly indexed list of metadata. This model locates the
metadata in blocks which are always stored in the same flash location. That
increases the number of writes in a specific flash location as every change in
the storage area requires a metadata update.
-
+
- **PSA internal trusted storage API** - In the current design, the service does
not use the PSA Internal Trusted Storage API to write the rollback protection
values stored in the internal storage. The PSA Internal Trusted Storage API is
@@ -191,13 +191,11 @@
Cryptographic Interface
=======================
--``crypto/sst_crypto_interface.h`` - Abstracts the cryptographic
- operations for the secure storage service.
+- ``crypto/sst_crypto_interface.h`` - Abstracts the cryptographic operations for
+ the secure storage service.
-- ``crypto/sst_crypto_interface.c`` - Currently, it implements the SST
- service cryptographic operations using Mbed TLS library. The system integrator
- **may** replace this implementation with calls to another service, crypto
- library or hardware crypto unit.
+- ``crypto/sst_crypto_interface.c`` - Implements the SST service cryptographic
+ operations with calls to the TF-M Crypto service.
Non-volatile (NV) Counters Interface
====================================
@@ -319,9 +317,9 @@
required cryptographic interface in
``secure_fw/services/secure_storage/crypto/sst_crypto_interface.h``
-Currently, the SST service cryptographic operations are implemented in
-``secure_fw/services/secure_storage/crypto/sst_crypto_interface.c``, using
-Mbed TLS library.
+The SST service cryptographic operations are implemented in
+``secure_fw/services/secure_storage/crypto/sst_crypto_interface.c``, using calls
+to the TF-M Crypto service.
SST Service Features Flags
==========================
diff --git a/docs/user_guides/tfm_build_instruction.rst b/docs/user_guides/tfm_build_instruction.rst
index 4c180c9..2b8c557 100644
--- a/docs/user_guides/tfm_build_instruction.rst
+++ b/docs/user_guides/tfm_build_instruction.rst
@@ -15,16 +15,16 @@
* - -DPROJ_CONFIG=<file>
- Specifies the way the application is built.
-
+
| <file> is the absolute path to configurations file
named as ``Config<APP_NAME>.cmake``.
| i.e. On Linux:
``-DPROJ_CONFIG=`readlink -f ../ConfigRegression.cmake```
-
+
* - -DTARGET_PLATFORM=<target platform name>
- Specifies the target platform.
Supported platforms:
-
+
- Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
``-DTARGET_PLATFORM=AN521``
- Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
@@ -33,24 +33,24 @@
``-DTARGET_PLATFORM=MUSCA_A``
- Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
``-DTARGET_PLATFORM=MUSCA_B1``
-
+
* - -DCOMPILER=<compiler name>
- Specifies the compiler toolchain
The possible values are:
-
+
- ``ARMCLANG``
- ``GNUARM``
* - -DCMAKE_BUILD_TYPE=<build type>
- Configures debugging support.
The possible values are:
-
+
- ``Debug``
- ``Release``
- ``Relwithdebinfo``
- ``Minsizerel``
* - -DMBEDTLS_DEBUG=<ON|OFF>
- - To enables debug symbols for the Mbed TLS library.
-
+ - Enables debug symbols for the Mbed TLS and Mbed Crypto libraries.
+
.. Note::
Follow :doc:`secure boot <./tfm_secure_boot>` to build the binaries with or
without BL2 bootloader.
@@ -59,7 +59,7 @@
External dependency
*******************
- CMSIS_5 is used to import RTX for the example non-secure app
-- Mbed TLS is used as a crypto library on the secure side
+- Mbed TLS and Mbed Crypto are used as crypto libraries on the secure side
****************
TF-M build steps
@@ -79,6 +79,7 @@
cd <TF-M base folder>
git clone https://git.trustedfirmware.org/trusted-firmware-m.git
git clone https://github.com/ARMmbed/mbedtls.git -b mbedtls-2.7.9
+ git clone https://github.com/ARMmbed/mbed-crypto.git -b mbedcrypto-1.0.0
git clone https://github.com/ARM-software/CMSIS_5.git -b 5.2.0
Build steps for the AN521 target platform: