@@ -5,26 +5,31 @@ in `meta-arm/recipes-security/trusted-services`
## Secure Partitions recipes
-We define dedicated recipes for all supported Trusted Services (TS) Secure Partitions.
-These recipes produce ELF and DTB files for SPs.
-These files are automatically included into optee-os image accordingly to defined MACHINE_FEATURES.
+We define dedicated recipes for all supported Trusted Services (TS) Secure Partitions, which produce executables and
+manifest binaries (DT files) for SPs.
+
+The Secure Partitions are compatible with any SPMC implementation that complies with the FF-A specification. Meta-arm
+currently supports OP-TEE SPMC, and when enabled, the Secure Partition binaries are automatically included in the
+optee-os image based on the defined MACHINE_FEATURES. For more details bout OP-TEE SPMC please refer to the
+[OP-TEE documentation][^6].
### How to include TS SPs
-To include TS SPs into optee-os image you need to add into MACHINE_FEATURES
-features for each [Secure Partition][^2] you would like to include:
+To include TS SPs into the firmware image add the corresponding feature flags to the MACHINE_FEATURES variable for each
+[Secure Partition][^2] you would like to include :
| Secure Partition | MACHINE_FEATURE |
| ----------------- | --------------- |
| Attestation | ts-attesation |
| Crypto | ts-crypto |
-| Firmware Update | ts-fwu
+| Firmware Update | ts-fwu |
+| fTPM | ts-ftpm |
| Internal Storage | ts-its |
+| Logging | ts-logging |
| Protected Storage | ts-storage |
| se-proxy | ts-se-proxy |
| smm-gateway | ts-smm-gateway |
| spm-test[1-4] | optee-spmc-test |
-| Logging | ts-logging |
Other steps depend on your machine/platform definition:
@@ -47,6 +52,15 @@ Other steps depend on your machine/platform definition:
4. Trusted Services supports an SPMC agonistic binary format. To build SPs to this format the `TS_ENV` variable is to be
set to `sp`. The resulting SP binaries should be able to boot under any FF-A v1.1 compliant SPMC implementation.
+### Example configurations
+
+The `meta-arm/ci` directory contains various TS focused [KAS][^7] configuration files:
+
+| File name | Description |
+|-----------|-------------|
+| ci/fvp-base-ts-ftpm.yml |Enabling the fTPM SP on the fvp-base machine|
+| ci/fvp-base-ts.yml |TS config for the fvp-base machine|
+| ci/qemuarm64-secureboot-ts.yml |TS config for quemuarm64-secureboot machine|
## Normal World applications
@@ -55,7 +69,7 @@ Optionally for testing purposes you can add `packagegroup-ts-tests` into your im
## OEQA Trusted Services tests
- meta-arm also includes Trusted Service OEQA tests which can be used for automated testing.
+meta-arm also includes Trusted Service OEQA tests which can be used for automated testing.
See `ci/trusted-services.yml` for an example how to include them into an image.
## Configuration options
@@ -63,13 +77,59 @@ See `ci/trusted-services.yml` for an example how to include them into an image.
Some TS recipes support yocto variables to set build configuration. These variables can be set in .conf files (machine
specific or local.conf), or .bbappend files.
-SmmGW SP recipe supports the following configuration variables
+### SmmGW SP
+
+The recipe supports the following configuration variables
| Variable name | Type | Description |
|-----------------------|------|--------------------------------------------------------------------------------------------------------|
| SMMGW_AUTH_VAR | Bool | Enable Authenticated variable support |
| SMMGW_INTERNAL_CRYPTO | Bool | Use MbedTLS build into SmmGW for authentication related crypto operations. Depends on SMMGW_AUTH_VAR=1 |
+fTPM tests are supported by OEQA but are disabled by default due to their lengthy execution time. To enable them, set the RUN_TPM2_TESTS
+variable e.g. in local.conf.
+
+The list of supported test cases can be found in the `tests` array in the `meta-arm/recipes-tpm/tpm2-tools/files/tpm2-test-all` script.
+These can be ran one-by-one, but currently running all of them by calling `tpm2-test-all` results in a failure of the `tpm2-abmrd` tool.
+
+The tests not supported are listed in the same script under the `Failing tests:` line.
+
+This script was created to meet the needs of the Trusted Services project, but in the future it should be updated to be configurable to
+support generic usage. The aforementioned issue shall also be solved, so the supported tests could run together.
+
+### fTPM SP
+
+The fTPM SP is an experimental feature. Please refer to the [TS documentation][^5] for details on limitations.
+
+The current integration enables the fTPM Secure Partition and supports running tpm2-tools tests to verify correct
+functionality. Secure Boot and other features that leverage TPM capabilities are not enabled currently.
+
+Configuration variables of the recipe:
+
+| Variable name | Type | Description |
+|-----------------------|------|--------------------------------------------------------------------------------------------------------|
+| RUN_TPM2_TESTS | Bool | Enable automatic execution of TPM tests from OEQA to verify the TS fTPM SP |
+
+The current integration targeting the fvp-base machine enables fTPM SP and allows running the tests. To reproduce the
+build please use `ci/fvp-base-ts-ftpm.yml`. This configuration:
+
+ - deploys the SP in the SWd
+ - amends the Linux kernel configuration:
+ - enables the tpm-crb driver
+ - add a patch to allow DTB based discovery
+ - deploys user-space components (tpm2-tss, tpm2-abrmd, tmp2-tools)
+ - configures the initialization system to start tpm2-abrmd.
+
+The configuration leverages tpm2 components form meta-secure-core layer.
+
+Validation can be performed by running the script located at `meta-arm/recipes-tpm/tpm2-tools/files/tpm2-test-all`. This
+script runs a subset of tpm2 tests. While all tpm2 test pass when executed individually, executing the entire test suite
+in a sequence leads to a failure of the `tpm2-abmrd` tool. As a workaround some test cases are disabled in the script.
+You can find the list of disabled tests marked under the `Failing tests` section of the script.
+
+Note: tpm2 tests was designed to validate the tpm2 reference stack. Its use for verifying the fTPM SP is not fully
+aligned with this intent. As such, the current validation approach is considered “best effort” and is suitable for
+development purposes. A more appropriate and comprehensive test suite should be selected for future validation.
------
[^1]: https://trusted-services.readthedocs.io/en/integration/overview/index.html
@@ -79,3 +139,9 @@ SmmGW SP recipe supports the following configuration variables
[^3]: https://trusted-services.readthedocs.io/en/integration/deployments/test-executables.html
[^4]: https://optee.readthedocs.io/en/latest/building/gits/optee_test.html
+
+[^5]: https://trusted-services.readthedocs.io/en/integration/services/tpm-service-description.html
+
+[^6]: https://optee.readthedocs.io/en/latest/architecture/spmc.html
+
+[^7]: https://kas.readthedocs.io
Change the layout to enhance readability and add TS fTPM related information. Signed-off-by: Gyorgy Szing <gyorgy.szing@arm.com> --- documentation/trusted-services.md | 84 +++++++++++++++++++++++++++---- 1 file changed, 75 insertions(+), 9 deletions(-)