1============= 2TEE subsystem 3============= 4 5This document describes the TEE subsystem in Linux. 6 7A TEE (Trusted Execution Environment) is a trusted OS running in some 8secure environment, for example, TrustZone on ARM CPUs, or a separate 9secure co-processor etc. A TEE driver handles the details needed to 10communicate with the TEE. 11 12This 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 20The TEE interface 21================= 22 23include/uapi/linux/tee.h defines the generic interface to a TEE. 24 25User 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 35 its capabilities. 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 45There are two classes of clients, normal clients and supplicants. The latter is 46a helper process for the TEE to access resources in Linux, for example file 47system access. A normal client opens /dev/tee[0-9]* and a supplicant opens 48/dev/teepriv[0-9]. 49 50Much of the communication between clients and the TEE is opaque to the 51driver. The main job for the driver is to receive requests from the 52clients, forward them to the TEE and send back the results. In the case of 53supplicants the communication goes in the other direction, the TEE sends 54requests to the supplicant which then sends back the result. 55 56The TEE kernel interface 57======================== 58 59Kernel provides a TEE bus infrastructure where a Trusted Application is 60represented as a device identified via Universally Unique Identifier (UUID) and 61client drivers register a table of supported device UUIDs. 62 63TEE bus infrastructure registers following APIs: 64- match(): iterates over the client driver UUID table to find a corresponding 65 match for device UUID. If a match is found, then this particular device is 66 probed via corresponding probe API registered by the client driver. This 67 process happens whenever a device or a client driver is registered with TEE 68 bus. 69- uevent(): notifies user-space (udev) whenever a new device is registered on 70 TEE bus for auto-loading of modularized client drivers. 71 72TEE bus device enumeration is specific to underlying TEE implementation, so it 73is left open for TEE drivers to provide corresponding implementation. 74 75Then TEE client driver can talk to a matched Trusted Application using APIs 76listed in include/linux/tee_drv.h. 77 78TEE client driver example 79------------------------- 80 81Suppose a TEE client driver needs to communicate with a Trusted Application 82having UUID: ``ac6a4085-0e82-4c33-bf98-8eb8e118b6c2``, so driver registration 83snippet would look like:: 84 85 static const struct tee_client_device_id client_id_table[] = { 86 {UUID_INIT(0xac6a4085, 0x0e82, 0x4c33, 87 0xbf, 0x98, 0x8e, 0xb8, 0xe1, 0x18, 0xb6, 0xc2)}, 88 {} 89 }; 90 91 MODULE_DEVICE_TABLE(tee, client_id_table); 92 93 static struct tee_client_driver client_driver = { 94 .id_table = client_id_table, 95 .driver = { 96 .name = DRIVER_NAME, 97 .bus = &tee_bus_type, 98 .probe = client_probe, 99 .remove = client_remove, 100 }, 101 }; 102 103 static int __init client_init(void) 104 { 105 return driver_register(&client_driver.driver); 106 } 107 108 static void __exit client_exit(void) 109 { 110 driver_unregister(&client_driver.driver); 111 } 112 113 module_init(client_init); 114 module_exit(client_exit); 115 116OP-TEE driver 117============= 118 119The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM 120TrustZone based OP-TEE solution that is supported. 121 122Lowest level of communication with OP-TEE builds on ARM SMC Calling 123Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface 124[3] used internally by the driver. Stacked on top of that is OP-TEE Message 125Protocol [4]. 126 127OP-TEE SMC interface provides the basic functions required by SMCCC and some 128additional functions specific for OP-TEE. The most interesting functions are: 129 130- OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information 131 which is then returned by TEE_IOC_VERSION 132 133- OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used 134 to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a 135 separate secure co-processor. 136 137- OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol 138 139- OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory 140 range to used for shared memory between Linux and OP-TEE. 141 142The GlobalPlatform TEE Client API [5] is implemented on top of the generic 143TEE API. 144 145Picture of the relationship between the different components in the 146OP-TEE architecture:: 147 148 User space Kernel Secure world 149 ~~~~~~~~~~ ~~~~~~ ~~~~~~~~~~~~ 150 +--------+ +-------------+ 151 | Client | | Trusted | 152 +--------+ | Application | 153 /\ +-------------+ 154 || +----------+ /\ 155 || |tee- | || 156 || |supplicant| \/ 157 || +----------+ +-------------+ 158 \/ /\ | TEE Internal| 159 +-------+ || | API | 160 + TEE | || +--------+--------+ +-------------+ 161 | Client| || | TEE | OP-TEE | | OP-TEE | 162 | API | \/ | subsys | driver | | Trusted OS | 163 +-------+----------------+----+-------+----+-----------+-------------+ 164 | Generic TEE API | | OP-TEE MSG | 165 | IOCTL (TEE_IOC_*) | | SMCCC (OPTEE_SMC_CALL_*) | 166 +-----------------------------+ +------------------------------+ 167 168RPC (Remote Procedure Call) are requests from secure world to kernel driver 169or tee-supplicant. An RPC is identified by a special range of SMCCC return 170values from OPTEE_SMC_CALL_WITH_ARG. RPC messages which are intended for the 171kernel are handled by the kernel driver. Other RPC messages will be forwarded to 172tee-supplicant without further involvement of the driver, except switching 173shared memory buffer representation. 174 175OP-TEE device enumeration 176------------------------- 177 178OP-TEE provides a pseudo Trusted Application: drivers/tee/optee/device.c in 179order to support device enumeration. In other words, OP-TEE driver invokes this 180application to retrieve a list of Trusted Applications which can be registered 181as devices on the TEE bus. 182 183AMD-TEE driver 184============== 185 186The AMD-TEE driver handles the communication with AMD's TEE environment. The 187TEE environment is provided by AMD Secure Processor. 188 189The AMD Secure Processor (formerly called Platform Security Processor or PSP) 190is a dedicated processor that features ARM TrustZone technology, along with a 191software-based Trusted Execution Environment (TEE) designed to enable 192third-party Trusted Applications. This feature is currently enabled only for 193APUs. 194 195The following picture shows a high level overview of AMD-TEE:: 196 197 | 198 x86 | 199 | 200 User space (Kernel space) | AMD Secure Processor (PSP) 201 ~~~~~~~~~~ ~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 202 | 203 +--------+ | +-------------+ 204 | Client | | | Trusted | 205 +--------+ | | Application | 206 /\ | +-------------+ 207 || | /\ 208 || | || 209 || | \/ 210 || | +----------+ 211 || | | TEE | 212 || | | Internal | 213 \/ | | API | 214 +---------+ +-----------+---------+ +----------+ 215 | TEE | | TEE | AMD-TEE | | AMD-TEE | 216 | Client | | subsystem | driver | | Trusted | 217 | API | | | | | OS | 218 +---------+-----------+----+------+---------+---------+----------+ 219 | Generic TEE API | | ASP | Mailbox | 220 | IOCTL (TEE_IOC_*) | | driver | Register Protocol | 221 +--------------------------+ +---------+--------------------+ 222 223At the lowest level (in x86), the AMD Secure Processor (ASP) driver uses the 224CPU to PSP mailbox regsister to submit commands to the PSP. The format of the 225command buffer is opaque to the ASP driver. It's role is to submit commands to 226the secure processor and return results to AMD-TEE driver. The interface 227between AMD-TEE driver and AMD Secure Processor driver can be found in [6]. 228 229The AMD-TEE driver packages the command buffer payload for processing in TEE. 230The command buffer format for the different TEE commands can be found in [7]. 231 232The TEE commands supported by AMD-TEE Trusted OS are: 233 234* TEE_CMD_ID_LOAD_TA - loads a Trusted Application (TA) binary into 235 TEE environment. 236* TEE_CMD_ID_UNLOAD_TA - unloads TA binary from TEE environment. 237* TEE_CMD_ID_OPEN_SESSION - opens a session with a loaded TA. 238* TEE_CMD_ID_CLOSE_SESSION - closes session with loaded TA 239* TEE_CMD_ID_INVOKE_CMD - invokes a command with loaded TA 240* TEE_CMD_ID_MAP_SHARED_MEM - maps shared memory 241* TEE_CMD_ID_UNMAP_SHARED_MEM - unmaps shared memory 242 243AMD-TEE Trusted OS is the firmware running on AMD Secure Processor. 244 245The AMD-TEE driver registers itself with TEE subsystem and implements the 246following driver function callbacks: 247 248* get_version - returns the driver implementation id and capability. 249* open - sets up the driver context data structure. 250* release - frees up driver resources. 251* open_session - loads the TA binary and opens session with loaded TA. 252* close_session - closes session with loaded TA and unloads it. 253* invoke_func - invokes a command with loaded TA. 254 255cancel_req driver callback is not supported by AMD-TEE. 256 257The GlobalPlatform TEE Client API [5] can be used by the user space (client) to 258talk to AMD's TEE. AMD's TEE provides a secure environment for loading, opening 259a session, invoking commands and clossing session with TA. 260 261References 262========== 263 264[1] https://github.com/OP-TEE/optee_os 265 266[2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html 267 268[3] drivers/tee/optee/optee_smc.h 269 270[4] drivers/tee/optee/optee_msg.h 271 272[5] http://www.globalplatform.org/specificationsdevice.asp look for 273 "TEE Client API Specification v1.0" and click download. 274 275[6] include/linux/psp-tee.h 276 277[7] drivers/tee/amdtee/amdtee_if.h 278