Commit | Line | Data |
---|---|---|
50709576 SG |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ==================================================== | |
4 | OP-TEE (Open Portable Trusted Execution Environment) | |
5 | ==================================================== | |
6 | ||
7 | The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM | |
8 | TrustZone based OP-TEE solution that is supported. | |
9 | ||
10 | Lowest level of communication with OP-TEE builds on ARM SMC Calling | |
11 | Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface | |
12 | [3] used internally by the driver. Stacked on top of that is OP-TEE Message | |
13 | Protocol [4]. | |
14 | ||
15 | OP-TEE SMC interface provides the basic functions required by SMCCC and some | |
16 | additional functions specific for OP-TEE. The most interesting functions are: | |
17 | ||
18 | - OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information | |
19 | which is then returned by TEE_IOC_VERSION | |
20 | ||
21 | - OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used | |
22 | to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a | |
23 | separate secure co-processor. | |
24 | ||
25 | - OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol | |
26 | ||
27 | - OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory | |
28 | range to used for shared memory between Linux and OP-TEE. | |
29 | ||
30 | The GlobalPlatform TEE Client API [5] is implemented on top of the generic | |
31 | TEE API. | |
32 | ||
33 | Picture of the relationship between the different components in the | |
34 | OP-TEE architecture:: | |
35 | ||
36 | User space Kernel Secure world | |
37 | ~~~~~~~~~~ ~~~~~~ ~~~~~~~~~~~~ | |
38 | +--------+ +-------------+ | |
39 | | Client | | Trusted | | |
40 | +--------+ | Application | | |
41 | /\ +-------------+ | |
42 | || +----------+ /\ | |
43 | || |tee- | || | |
44 | || |supplicant| \/ | |
45 | || +----------+ +-------------+ | |
46 | \/ /\ | TEE Internal| | |
47 | +-------+ || | API | | |
48 | + TEE | || +--------+--------+ +-------------+ | |
49 | | Client| || | TEE | OP-TEE | | OP-TEE | | |
50 | | API | \/ | subsys | driver | | Trusted OS | | |
51 | +-------+----------------+----+-------+----+-----------+-------------+ | |
52 | | Generic TEE API | | OP-TEE MSG | | |
53 | | IOCTL (TEE_IOC_*) | | SMCCC (OPTEE_SMC_CALL_*) | | |
54 | +-----------------------------+ +------------------------------+ | |
55 | ||
56 | RPC (Remote Procedure Call) are requests from secure world to kernel driver | |
57 | or tee-supplicant. An RPC is identified by a special range of SMCCC return | |
58 | values from OPTEE_SMC_CALL_WITH_ARG. RPC messages which are intended for the | |
59 | kernel are handled by the kernel driver. Other RPC messages will be forwarded to | |
60 | tee-supplicant without further involvement of the driver, except switching | |
61 | shared memory buffer representation. | |
62 | ||
63 | OP-TEE device enumeration | |
64 | ------------------------- | |
65 | ||
66 | OP-TEE provides a pseudo Trusted Application: drivers/tee/optee/device.c in | |
67 | order to support device enumeration. In other words, OP-TEE driver invokes this | |
68 | application to retrieve a list of Trusted Applications which can be registered | |
69 | as devices on the TEE bus. | |
70 | ||
71 | OP-TEE notifications | |
72 | -------------------- | |
73 | ||
74 | There are two kinds of notifications that secure world can use to make | |
75 | normal world aware of some event. | |
76 | ||
77 | 1. Synchronous notifications delivered with ``OPTEE_RPC_CMD_NOTIFICATION`` | |
78 | using the ``OPTEE_RPC_NOTIFICATION_SEND`` parameter. | |
79 | 2. Asynchronous notifications delivered with a combination of a non-secure | |
80 | edge-triggered interrupt and a fast call from the non-secure interrupt | |
81 | handler. | |
82 | ||
83 | Synchronous notifications are limited by depending on RPC for delivery, | |
84 | this is only usable when secure world is entered with a yielding call via | |
85 | ``OPTEE_SMC_CALL_WITH_ARG``. This excludes such notifications from secure | |
86 | world interrupt handlers. | |
87 | ||
88 | An asynchronous notification is delivered via a non-secure edge-triggered | |
89 | interrupt to an interrupt handler registered in the OP-TEE driver. The | |
90 | actual notification value are retrieved with the fast call | |
91 | ``OPTEE_SMC_GET_ASYNC_NOTIF_VALUE``. Note that one interrupt can represent | |
92 | multiple notifications. | |
93 | ||
94 | One notification value ``OPTEE_SMC_ASYNC_NOTIF_VALUE_DO_BOTTOM_HALF`` has a | |
95 | special meaning. When this value is received it means that normal world is | |
96 | supposed to make a yielding call ``OPTEE_MSG_CMD_DO_BOTTOM_HALF``. This | |
97 | call is done from the thread assisting the interrupt handler. This is a | |
98 | building block for OP-TEE OS in secure world to implement the top half and | |
99 | bottom half style of device drivers. | |
100 | ||
101 | OPTEE_INSECURE_LOAD_IMAGE Kconfig option | |
102 | ---------------------------------------- | |
103 | ||
104 | The OPTEE_INSECURE_LOAD_IMAGE Kconfig option enables the ability to load the | |
105 | BL32 OP-TEE image from the kernel after the kernel boots, rather than loading | |
106 | it from the firmware before the kernel boots. This also requires enabling the | |
107 | corresponding option in Trusted Firmware for Arm. The Trusted Firmware for Arm | |
108 | documentation [6] explains the security threat associated with enabling this as | |
109 | well as mitigations at the firmware and platform level. | |
110 | ||
111 | There are additional attack vectors/mitigations for the kernel that should be | |
112 | addressed when using this option. | |
113 | ||
114 | 1. Boot chain security. | |
115 | ||
116 | * Attack vector: Replace the OP-TEE OS image in the rootfs to gain control of | |
117 | the system. | |
118 | ||
119 | * Mitigation: There must be boot chain security that verifies the kernel and | |
120 | rootfs, otherwise an attacker can modify the loaded OP-TEE binary by | |
121 | modifying it in the rootfs. | |
122 | ||
123 | 2. Alternate boot modes. | |
124 | ||
125 | * Attack vector: Using an alternate boot mode (i.e. recovery mode), the | |
126 | OP-TEE driver isn't loaded, leaving the SMC hole open. | |
127 | ||
128 | * Mitigation: If there are alternate methods of booting the device, such as a | |
129 | recovery mode, it should be ensured that the same mitigations are applied | |
130 | in that mode. | |
131 | ||
132 | 3. Attacks prior to SMC invocation. | |
133 | ||
134 | * Attack vector: Code that is executed prior to issuing the SMC call to load | |
135 | OP-TEE can be exploited to then load an alternate OS image. | |
136 | ||
137 | * Mitigation: The OP-TEE driver must be loaded before any potential attack | |
138 | vectors are opened up. This should include mounting of any modifiable | |
139 | filesystems, opening of network ports or communicating with external | |
140 | devices (e.g. USB). | |
141 | ||
142 | 4. Blocking SMC call to load OP-TEE. | |
143 | ||
144 | * Attack vector: Prevent the driver from being probed, so the SMC call to | |
145 | load OP-TEE isn't executed when desired, leaving it open to being executed | |
146 | later and loading a modified OS. | |
147 | ||
148 | * Mitigation: It is recommended to build the OP-TEE driver as builtin driver | |
149 | rather than as a module to prevent exploits that may cause the module to | |
150 | not be loaded. | |
151 | ||
152 | References | |
153 | ========== | |
154 | ||
155 | [1] https://github.com/OP-TEE/optee_os | |
156 | ||
157 | [2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html | |
158 | ||
159 | [3] drivers/tee/optee/optee_smc.h | |
160 | ||
161 | [4] drivers/tee/optee/optee_msg.h | |
162 | ||
163 | [5] http://www.globalplatform.org/specificationsdevice.asp look for | |
164 | "TEE Client API Specification v1.0" and click download. | |
165 | ||
166 | [6] https://trustedfirmware-a.readthedocs.io/en/latest/threat_model/threat_model.html |