Commit | Line | Data |
---|---|---|
4297739f | 1 | ============= |
6a6e7700 | 2 | TEE subsystem |
4297739f MCC |
3 | ============= |
4 | ||
6a6e7700 JW |
5 | This document describes the TEE subsystem in Linux. |
6 | ||
7 | A TEE (Trusted Execution Environment) is a trusted OS running in some | |
8 | secure environment, for example, TrustZone on ARM CPUs, or a separate | |
9 | secure co-processor etc. A TEE driver handles the details needed to | |
10 | communicate with the TEE. | |
11 | ||
12 | This subsystem deals with: | |
13 | ||
14 | - Registration of TEE drivers | |
15 | ||
16 | - Managing shared memory between Linux and the TEE | |
17 | ||
18 | - Providing a generic API to the TEE | |
19 | ||
20 | The TEE interface | |
21 | ================= | |
22 | ||
23 | include/uapi/linux/tee.h defines the generic interface to a TEE. | |
24 | ||
25 | User space (the client) connects to the driver by opening /dev/tee[0-9]* or | |
26 | /dev/teepriv[0-9]*. | |
27 | ||
28 | - TEE_IOC_SHM_ALLOC allocates shared memory and returns a file descriptor | |
29 | which user space can mmap. When user space doesn't need the file | |
30 | descriptor any more, it should be closed. When shared memory isn't needed | |
31 | any longer it should be unmapped with munmap() to allow the reuse of | |
32 | memory. | |
33 | ||
34 | - TEE_IOC_VERSION lets user space know which TEE this driver handles and | |
e47cf0c9 | 35 | its capabilities. |
6a6e7700 JW |
36 | |
37 | - TEE_IOC_OPEN_SESSION opens a new session to a Trusted Application. | |
38 | ||
39 | - TEE_IOC_INVOKE invokes a function in a Trusted Application. | |
40 | ||
41 | - TEE_IOC_CANCEL may cancel an ongoing TEE_IOC_OPEN_SESSION or TEE_IOC_INVOKE. | |
42 | ||
43 | - TEE_IOC_CLOSE_SESSION closes a session to a Trusted Application. | |
44 | ||
45 | There are two classes of clients, normal clients and supplicants. The latter is | |
46 | a helper process for the TEE to access resources in Linux, for example file | |
47 | system access. A normal client opens /dev/tee[0-9]* and a supplicant opens | |
48 | /dev/teepriv[0-9]. | |
49 | ||
50 | Much of the communication between clients and the TEE is opaque to the | |
51 | driver. The main job for the driver is to receive requests from the | |
52 | clients, forward them to the TEE and send back the results. In the case of | |
53 | supplicants the communication goes in the other direction, the TEE sends | |
54 | requests to the supplicant which then sends back the result. | |
55 | ||
56 | OP-TEE driver | |
57 | ============= | |
58 | ||
59 | The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM | |
60 | TrustZone based OP-TEE solution that is supported. | |
61 | ||
62 | Lowest level of communication with OP-TEE builds on ARM SMC Calling | |
63 | Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface | |
64 | [3] used internally by the driver. Stacked on top of that is OP-TEE Message | |
65 | Protocol [4]. | |
66 | ||
67 | OP-TEE SMC interface provides the basic functions required by SMCCC and some | |
68 | additional functions specific for OP-TEE. The most interesting functions are: | |
69 | ||
70 | - OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information | |
71 | which is then returned by TEE_IOC_VERSION | |
72 | ||
73 | - OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used | |
74 | to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a | |
75 | separate secure co-processor. | |
76 | ||
77 | - OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol | |
78 | ||
79 | - OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory | |
80 | range to used for shared memory between Linux and OP-TEE. | |
81 | ||
82 | The GlobalPlatform TEE Client API [5] is implemented on top of the generic | |
83 | TEE API. | |
84 | ||
85 | Picture of the relationship between the different components in the | |
4297739f MCC |
86 | OP-TEE architecture:: |
87 | ||
88 | User space Kernel Secure world | |
89 | ~~~~~~~~~~ ~~~~~~ ~~~~~~~~~~~~ | |
90 | +--------+ +-------------+ | |
91 | | Client | | Trusted | | |
92 | +--------+ | Application | | |
93 | /\ +-------------+ | |
94 | || +----------+ /\ | |
95 | || |tee- | || | |
96 | || |supplicant| \/ | |
97 | || +----------+ +-------------+ | |
98 | \/ /\ | TEE Internal| | |
99 | +-------+ || | API | | |
100 | + TEE | || +--------+--------+ +-------------+ | |
101 | | Client| || | TEE | OP-TEE | | OP-TEE | | |
102 | | API | \/ | subsys | driver | | Trusted OS | | |
103 | +-------+----------------+----+-------+----+-----------+-------------+ | |
104 | | Generic TEE API | | OP-TEE MSG | | |
105 | | IOCTL (TEE_IOC_*) | | SMCCC (OPTEE_SMC_CALL_*) | | |
106 | +-----------------------------+ +------------------------------+ | |
6a6e7700 JW |
107 | |
108 | RPC (Remote Procedure Call) are requests from secure world to kernel driver | |
109 | or tee-supplicant. An RPC is identified by a special range of SMCCC return | |
110 | values from OPTEE_SMC_CALL_WITH_ARG. RPC messages which are intended for the | |
111 | kernel are handled by the kernel driver. Other RPC messages will be forwarded to | |
112 | tee-supplicant without further involvement of the driver, except switching | |
113 | shared memory buffer representation. | |
114 | ||
79bfa4e7 RT |
115 | AMD-TEE driver |
116 | ============== | |
117 | ||
118 | The AMD-TEE driver handles the communication with AMD's TEE environment. The | |
119 | TEE environment is provided by AMD Secure Processor. | |
120 | ||
121 | The AMD Secure Processor (formerly called Platform Security Processor or PSP) | |
122 | is a dedicated processor that features ARM TrustZone technology, along with a | |
123 | software-based Trusted Execution Environment (TEE) designed to enable | |
124 | third-party Trusted Applications. This feature is currently enabled only for | |
125 | APUs. | |
126 | ||
127 | The following picture shows a high level overview of AMD-TEE:: | |
128 | ||
129 | | | |
130 | x86 | | |
131 | | | |
132 | User space (Kernel space) | AMD Secure Processor (PSP) | |
133 | ~~~~~~~~~~ ~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
134 | | | |
135 | +--------+ | +-------------+ | |
136 | | Client | | | Trusted | | |
137 | +--------+ | | Application | | |
138 | /\ | +-------------+ | |
139 | || | /\ | |
140 | || | || | |
141 | || | \/ | |
142 | || | +----------+ | |
143 | || | | TEE | | |
144 | || | | Internal | | |
145 | \/ | | API | | |
146 | +---------+ +-----------+---------+ +----------+ | |
147 | | TEE | | TEE | AMD-TEE | | AMD-TEE | | |
148 | | Client | | subsystem | driver | | Trusted | | |
149 | | API | | | | | OS | | |
150 | +---------+-----------+----+------+---------+---------+----------+ | |
151 | | Generic TEE API | | ASP | Mailbox | | |
152 | | IOCTL (TEE_IOC_*) | | driver | Register Protocol | | |
153 | +--------------------------+ +---------+--------------------+ | |
154 | ||
155 | At the lowest level (in x86), the AMD Secure Processor (ASP) driver uses the | |
156 | CPU to PSP mailbox regsister to submit commands to the PSP. The format of the | |
157 | command buffer is opaque to the ASP driver. It's role is to submit commands to | |
158 | the secure processor and return results to AMD-TEE driver. The interface | |
159 | between AMD-TEE driver and AMD Secure Processor driver can be found in [6]. | |
160 | ||
161 | The AMD-TEE driver packages the command buffer payload for processing in TEE. | |
162 | The command buffer format for the different TEE commands can be found in [7]. | |
163 | ||
164 | The TEE commands supported by AMD-TEE Trusted OS are: | |
165 | * TEE_CMD_ID_LOAD_TA - loads a Trusted Application (TA) binary into | |
166 | TEE environment. | |
167 | * TEE_CMD_ID_UNLOAD_TA - unloads TA binary from TEE environment. | |
168 | * TEE_CMD_ID_OPEN_SESSION - opens a session with a loaded TA. | |
169 | * TEE_CMD_ID_CLOSE_SESSION - closes session with loaded TA | |
170 | * TEE_CMD_ID_INVOKE_CMD - invokes a command with loaded TA | |
171 | * TEE_CMD_ID_MAP_SHARED_MEM - maps shared memory | |
172 | * TEE_CMD_ID_UNMAP_SHARED_MEM - unmaps shared memory | |
173 | ||
174 | AMD-TEE Trusted OS is the firmware running on AMD Secure Processor. | |
175 | ||
176 | The AMD-TEE driver registers itself with TEE subsystem and implements the | |
177 | following driver function callbacks: | |
178 | ||
179 | * get_version - returns the driver implementation id and capability. | |
180 | * open - sets up the driver context data structure. | |
181 | * release - frees up driver resources. | |
182 | * open_session - loads the TA binary and opens session with loaded TA. | |
183 | * close_session - closes session with loaded TA and unloads it. | |
184 | * invoke_func - invokes a command with loaded TA. | |
185 | ||
186 | cancel_req driver callback is not supported by AMD-TEE. | |
187 | ||
188 | The GlobalPlatform TEE Client API [5] can be used by the user space (client) to | |
189 | talk to AMD's TEE. AMD's TEE provides a secure environment for loading, opening | |
190 | a session, invoking commands and clossing session with TA. | |
191 | ||
4297739f MCC |
192 | References |
193 | ========== | |
194 | ||
6a6e7700 | 195 | [1] https://github.com/OP-TEE/optee_os |
4297739f | 196 | |
6a6e7700 | 197 | [2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html |
4297739f | 198 | |
6a6e7700 | 199 | [3] drivers/tee/optee/optee_smc.h |
4297739f | 200 | |
6a6e7700 | 201 | [4] drivers/tee/optee/optee_msg.h |
4297739f | 202 | |
6a6e7700 JW |
203 | [5] http://www.globalplatform.org/specificationsdevice.asp look for |
204 | "TEE Client API Specification v1.0" and click download. | |
79bfa4e7 RT |
205 | |
206 | [6] include/linux/psp-tee.h | |
207 | ||
208 | [7] drivers/tee/amdtee/amdtee_if.h |