| .. SPDX-License-Identifier: GPL-2.0 | |
| ==================================================== | |
| OP-TEE (Open Portable Trusted Execution Environment) | |
| ==================================================== | |
| The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM | |
| TrustZone based OP-TEE solution that is supported. | |
| Lowest level of communication with OP-TEE builds on ARM SMC Calling | |
| Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface | |
| [3] used internally by the driver. Stacked on top of that is OP-TEE Message | |
| Protocol [4]. | |
| OP-TEE SMC interface provides the basic functions required by SMCCC and some | |
| additional functions specific for OP-TEE. The most interesting functions are: | |
| - OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information | |
| which is then returned by TEE_IOC_VERSION | |
| - OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used | |
| to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a | |
| separate secure co-processor. | |
| - OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol | |
| - OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory | |
| range to used for shared memory between Linux and OP-TEE. | |
| The GlobalPlatform TEE Client API [5] is implemented on top of the generic | |
| TEE API. | |
| Picture of the relationship between the different components in the | |
| OP-TEE architecture:: | |
| User space Kernel Secure world | |
| ~~~~~~~~~~ ~~~~~~ ~~~~~~~~~~~~ | |
| +--------+ +-------------+ | |
| | Client | | Trusted | | |
| +--------+ | Application | | |
| /\ +-------------+ | |
| || +----------+ /\ | |
| || |tee- | || | |
| || |supplicant| \/ | |
| || +----------+ +-------------+ | |
| \/ /\ | TEE Internal| | |
| +-------+ || | API | | |
| + TEE | || +--------+--------+ +-------------+ | |
| | Client| || | TEE | OP-TEE | | OP-TEE | | |
| | API | \/ | subsys | driver | | Trusted OS | | |
| +-------+----------------+----+-------+----+-----------+-------------+ | |
| | Generic TEE API | | OP-TEE MSG | | |
| | IOCTL (TEE_IOC_*) | | SMCCC (OPTEE_SMC_CALL_*) | | |
| +-----------------------------+ +------------------------------+ | |
| RPC (Remote Procedure Call) are requests from secure world to kernel driver | |
| or tee-supplicant. An RPC is identified by a special range of SMCCC return | |
| values from OPTEE_SMC_CALL_WITH_ARG. RPC messages which are intended for the | |
| kernel are handled by the kernel driver. Other RPC messages will be forwarded to | |
| tee-supplicant without further involvement of the driver, except switching | |
| shared memory buffer representation. | |
| OP-TEE device enumeration | |
| ------------------------- | |
| OP-TEE provides a pseudo Trusted Application: drivers/tee/optee/device.c in | |
| order to support device enumeration. In other words, OP-TEE driver invokes this | |
| application to retrieve a list of Trusted Applications which can be registered | |
| as devices on the TEE bus. | |
| OP-TEE notifications | |
| -------------------- | |
| There are two kinds of notifications that secure world can use to make | |
| normal world aware of some event. | |
| 1. Synchronous notifications delivered with ``OPTEE_RPC_CMD_NOTIFICATION`` | |
| using the ``OPTEE_RPC_NOTIFICATION_SEND`` parameter. | |
| 2. Asynchronous notifications delivered with a combination of a non-secure | |
| edge-triggered interrupt and a fast call from the non-secure interrupt | |
| handler. | |
| Synchronous notifications are limited by depending on RPC for delivery, | |
| this is only usable when secure world is entered with a yielding call via | |
| ``OPTEE_SMC_CALL_WITH_ARG``. This excludes such notifications from secure | |
| world interrupt handlers. | |
| An asynchronous notification is delivered via a non-secure edge-triggered | |
| interrupt to an interrupt handler registered in the OP-TEE driver. The | |
| actual notification value are retrieved with the fast call | |
| ``OPTEE_SMC_GET_ASYNC_NOTIF_VALUE``. Note that one interrupt can represent | |
| multiple notifications. | |
| One notification value ``OPTEE_SMC_ASYNC_NOTIF_VALUE_DO_BOTTOM_HALF`` has a | |
| special meaning. When this value is received it means that normal world is | |
| supposed to make a yielding call ``OPTEE_MSG_CMD_DO_BOTTOM_HALF``. This | |
| call is done from the thread assisting the interrupt handler. This is a | |
| building block for OP-TEE OS in secure world to implement the top half and | |
| bottom half style of device drivers. | |
| OPTEE_INSECURE_LOAD_IMAGE Kconfig option | |
| ---------------------------------------- | |
| The OPTEE_INSECURE_LOAD_IMAGE Kconfig option enables the ability to load the | |
| BL32 OP-TEE image from the kernel after the kernel boots, rather than loading | |
| it from the firmware before the kernel boots. This also requires enabling the | |
| corresponding option in Trusted Firmware for Arm. The Trusted Firmware for Arm | |
| documentation [6] explains the security threat associated with enabling this as | |
| well as mitigations at the firmware and platform level. | |
| There are additional attack vectors/mitigations for the kernel that should be | |
| addressed when using this option. | |
| 1. Boot chain security. | |
| * Attack vector: Replace the OP-TEE OS image in the rootfs to gain control of | |
| the system. | |
| * Mitigation: There must be boot chain security that verifies the kernel and | |
| rootfs, otherwise an attacker can modify the loaded OP-TEE binary by | |
| modifying it in the rootfs. | |
| 2. Alternate boot modes. | |
| * Attack vector: Using an alternate boot mode (i.e. recovery mode), the | |
| OP-TEE driver isn't loaded, leaving the SMC hole open. | |
| * Mitigation: If there are alternate methods of booting the device, such as a | |
| recovery mode, it should be ensured that the same mitigations are applied | |
| in that mode. | |
| 3. Attacks prior to SMC invocation. | |
| * Attack vector: Code that is executed prior to issuing the SMC call to load | |
| OP-TEE can be exploited to then load an alternate OS image. | |
| * Mitigation: The OP-TEE driver must be loaded before any potential attack | |
| vectors are opened up. This should include mounting of any modifiable | |
| filesystems, opening of network ports or communicating with external | |
| devices (e.g. USB). | |
| 4. Blocking SMC call to load OP-TEE. | |
| * Attack vector: Prevent the driver from being probed, so the SMC call to | |
| load OP-TEE isn't executed when desired, leaving it open to being executed | |
| later and loading a modified OS. | |
| * Mitigation: It is recommended to build the OP-TEE driver as builtin driver | |
| rather than as a module to prevent exploits that may cause the module to | |
| not be loaded. | |
| References | |
| ========== | |
| [1] https://github.com/OP-TEE/optee_os | |
| [2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html | |
| [3] drivers/tee/optee/optee_smc.h | |
| [4] drivers/tee/optee/optee_msg.h | |
| [5] http://www.globalplatform.org/specificationsdevice.asp look for | |
| "TEE Client API Specification v1.0" and click download. | |
| [6] https://trustedfirmware-a.readthedocs.io/en/latest/threat_model/threat_model.html |