diff options
Diffstat (limited to 'Documentation/tee/op-tee.rst')
| -rw-r--r-- | Documentation/tee/op-tee.rst | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/Documentation/tee/op-tee.rst b/Documentation/tee/op-tee.rst new file mode 100644 index 000000000000..b0ac097d5547 --- /dev/null +++ b/Documentation/tee/op-tee.rst @@ -0,0 +1,166 @@ +.. 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 |