upstream-layers/meta-arm/documentation/trusted-services.md - openbmc - Git at Google

 # The Trusted Services: framework for developing root-of-trust services

 meta-arm layer includes recipes for [Trusted Services][^1] Secure Partitions and Normal World applications
 in `meta-arm/recipes-security/trusted-services`

 ## Secure Partitions recipes

 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 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          |
 | 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 |

 Other steps depend on your machine/platform definition:

 1. For communications between Secure and Normal Words Linux kernel option `CONFIG_ARM_FFA_TRANSPORT=y`
    is required. If your platform doesn't include it already you can add `arm-ffa` into MACHINE_FEATURES.
    (Please see ` meta-arm/recipes-kernel/arm-tstee`.)

    For running the `uefi-test` or the `xtest -t ffa_spmc` tests under Linux the `arm-ffa-user` drivel is required. This is
    enabled if the `ts-smm-gateway` and/or the `optee-spmc-test` machine features are enabled.
    (Please see ` meta-arm/recipes-kernel/arm-ffa-user`.)

 2. optee-os might require platform specific OP-TEE build parameters (for example what SEL the SPM Core is implemented at).
    You can find examples in `meta-arm/recipes-security/optee/optee-os_%.bbappend` for qemuarm64-secureboot machine
    and in `meta-arm-bsp/recipes-security/optee/optee-os-corstone1000-common.inc` for the Corstone1000 platform.

 3. trusted-firmware-a might require platform specific TF-A build parameters (SPD and SPMC details on the platform).
    See `meta-arm/recipes-bsp/trusted-firmware-a/trusted-firmware-a_%.bbappend` for qemuarm64-secureboot machine
    and in `meta-arm-bsp/recipes-bsp/trusted-firmware-a/trusted-firmware-a-corstone1000.inc` for theCorstone1000 platform.

 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

 Optionally for testing purposes you can add `packagegroup-ts-tests` into your image. It includes
 [Trusted Services test and demo tools][^3] and [xtest][^4] configured to include the `ffa_spmc` tests.

 ## OEQA Trusted Services tests

 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

 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

 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

 [^2]: https://trusted-services.readthedocs.io/en/integration/deployments/secure-partitions.html

 [^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
	# The Trusted Services: framework for developing root-of-trust services

	meta-arm layer includes recipes for [Trusted Services][^1] Secure Partitions and Normal World applications
	in `meta-arm/recipes-security/trusted-services`

	## Secure Partitions recipes

	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 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 \|
	\| 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 \|

	Other steps depend on your machine/platform definition:

	1. For communications between Secure and Normal Words Linux kernel option `CONFIG_ARM_FFA_TRANSPORT=y`
	is required. If your platform doesn't include it already you can add `arm-ffa` into MACHINE_FEATURES.
	(Please see ` meta-arm/recipes-kernel/arm-tstee`.)

	For running the `uefi-test` or the `xtest -t ffa_spmc` tests under Linux the `arm-ffa-user` drivel is required. This is
	enabled if the `ts-smm-gateway` and/or the `optee-spmc-test` machine features are enabled.
	(Please see ` meta-arm/recipes-kernel/arm-ffa-user`.)

	2. optee-os might require platform specific OP-TEE build parameters (for example what SEL the SPM Core is implemented at).
	You can find examples in `meta-arm/recipes-security/optee/optee-os_%.bbappend` for qemuarm64-secureboot machine
	and in `meta-arm-bsp/recipes-security/optee/optee-os-corstone1000-common.inc` for the Corstone1000 platform.

	3. trusted-firmware-a might require platform specific TF-A build parameters (SPD and SPMC details on the platform).
	See `meta-arm/recipes-bsp/trusted-firmware-a/trusted-firmware-a_%.bbappend` for qemuarm64-secureboot machine
	and in `meta-arm-bsp/recipes-bsp/trusted-firmware-a/trusted-firmware-a-corstone1000.inc` for theCorstone1000 platform.

	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

	Optionally for testing purposes you can add `packagegroup-ts-tests` into your image. It includes
	[Trusted Services test and demo tools][^3] and [xtest][^4] configured to include the `ffa_spmc` tests.

	## OEQA Trusted Services tests

	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

	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

	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

	[^2]: https://trusted-services.readthedocs.io/en/integration/deployments/secure-partitions.html

	[^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