1 .. SPDX-License-Identifier: GPL-2.0
2
3 ==============================================
4 OP-TEE (Open Portable Trusted Execution Enviro
5 ==============================================
6
7 The OP-TEE driver handles OP-TEE [1] based TEE
8 TrustZone based OP-TEE solution that is suppor
9
10 Lowest level of communication with OP-TEE buil
11 Convention (SMCCC) [2], which is the foundatio
12 [3] used internally by the driver. Stacked on
13 Protocol [4].
14
15 OP-TEE SMC interface provides the basic functi
16 additional functions specific for OP-TEE. The
17
18 - OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) r
19 which is then returned by TEE_IOC_VERSION
20
21 - OPTEE_SMC_CALL_GET_OS_UUID returns the parti
22 to tell, for instance, a TrustZone OP-TEE ap
23 separate secure co-processor.
24
25 - OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE me
26
27 - OPTEE_SMC_GET_SHM_CONFIG lets the driver and
28 range to used for shared memory between Linu
29
30 The GlobalPlatform TEE Client API [5] is imple
31 TEE API.
32
33 Picture of the relationship between the differ
34 OP-TEE architecture::
35
36 User space Kernel
37 ~~~~~~~~~~ ~~~~~~
38 +--------+
39 | Client |
40 +--------+
41 /\
42 || +----------+
43 || |tee- |
44 || |supplicant|
45 || +----------+
46 \/ /\
47 +-------+ ||
48 + TEE | || +--------+--------
49 | Client| || | TEE | OP-TEE
50 | API | \/ | subsys | driver
51 +-------+----------------+----+-------+----
52 | Generic TEE API | |
53 | IOCTL (TEE_IOC_*) | |
54 +-----------------------------+ +----
55
56 RPC (Remote Procedure Call) are requests from
57 or tee-supplicant. An RPC is identified by a s
58 values from OPTEE_SMC_CALL_WITH_ARG. RPC messa
59 kernel are handled by the kernel driver. Other
60 tee-supplicant without further involvement of
61 shared memory buffer representation.
62
63 OP-TEE device enumeration
64 -------------------------
65
66 OP-TEE provides a pseudo Trusted Application:
67 order to support device enumeration. In other
68 application to retrieve a list of Trusted Appl
69 as devices on the TEE bus.
70
71 OP-TEE notifications
72 --------------------
73
74 There are two kinds of notifications that secu
75 normal world aware of some event.
76
77 1. Synchronous notifications delivered with ``
78 using the ``OPTEE_RPC_NOTIFICATION_SEND`` p
79 2. Asynchronous notifications delivered with a
80 edge-triggered interrupt and a fast call fr
81 handler.
82
83 Synchronous notifications are limited by depen
84 this is only usable when secure world is enter
85 ``OPTEE_SMC_CALL_WITH_ARG``. This excludes suc
86 world interrupt handlers.
87
88 An asynchronous notification is delivered via
89 interrupt to an interrupt handler registered i
90 actual notification value are retrieved with t
91 ``OPTEE_SMC_GET_ASYNC_NOTIF_VALUE``. Note that
92 multiple notifications.
93
94 One notification value ``OPTEE_SMC_ASYNC_NOTIF
95 special meaning. When this value is received i
96 supposed to make a yielding call ``OPTEE_MSG_C
97 call is done from the thread assisting the int
98 building block for OP-TEE OS in secure world t
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 e
105 BL32 OP-TEE image from the kernel after the ke
106 it from the firmware before the kernel boots.
107 corresponding option in Trusted Firmware for A
108 documentation [6] explains the security threat
109 well as mitigations at the firmware and platfo
110
111 There are additional attack vectors/mitigation
112 addressed when using this option.
113
114 1. Boot chain security.
115
116 * Attack vector: Replace the OP-TEE OS imag
117 the system.
118
119 * Mitigation: There must be boot chain secu
120 rootfs, otherwise an attacker can modify
121 modifying it in the rootfs.
122
123 2. Alternate boot modes.
124
125 * Attack vector: Using an alternate boot mo
126 OP-TEE driver isn't loaded, leaving the S
127
128 * Mitigation: If there are alternate method
129 recovery mode, it should be ensured that
130 in that mode.
131
132 3. Attacks prior to SMC invocation.
133
134 * Attack vector: Code that is executed prio
135 OP-TEE can be exploited to then load an a
136
137 * Mitigation: The OP-TEE driver must be loa
138 vectors are opened up. This should includ
139 filesystems, opening of network ports or
140 devices (e.g. USB).
141
142 4. Blocking SMC call to load OP-TEE.
143
144 * Attack vector: Prevent the driver from be
145 load OP-TEE isn't executed when desired,
146 later and loading a modified OS.
147
148 * Mitigation: It is recommended to build th
149 rather than as a module to prevent exploi
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.a
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/specificatio
164 "TEE Client API Specification v1.0" and cl
165
166 [6] https://trustedfirmware-a.readthedocs.io/e
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.