]>
Commit | Line | Data |
---|---|---|
6a6e7700 JW |
1 | TEE subsystem |
2 | This document describes the TEE subsystem in Linux. | |
3 | ||
4 | A TEE (Trusted Execution Environment) is a trusted OS running in some | |
5 | secure environment, for example, TrustZone on ARM CPUs, or a separate | |
6 | secure co-processor etc. A TEE driver handles the details needed to | |
7 | communicate with the TEE. | |
8 | ||
9 | This subsystem deals with: | |
10 | ||
11 | - Registration of TEE drivers | |
12 | ||
13 | - Managing shared memory between Linux and the TEE | |
14 | ||
15 | - Providing a generic API to the TEE | |
16 | ||
17 | The TEE interface | |
18 | ================= | |
19 | ||
20 | include/uapi/linux/tee.h defines the generic interface to a TEE. | |
21 | ||
22 | User space (the client) connects to the driver by opening /dev/tee[0-9]* or | |
23 | /dev/teepriv[0-9]*. | |
24 | ||
25 | - TEE_IOC_SHM_ALLOC allocates shared memory and returns a file descriptor | |
26 | which user space can mmap. When user space doesn't need the file | |
27 | descriptor any more, it should be closed. When shared memory isn't needed | |
28 | any longer it should be unmapped with munmap() to allow the reuse of | |
29 | memory. | |
30 | ||
31 | - TEE_IOC_VERSION lets user space know which TEE this driver handles and | |
32 | the its capabilities. | |
33 | ||
34 | - TEE_IOC_OPEN_SESSION opens a new session to a Trusted Application. | |
35 | ||
36 | - TEE_IOC_INVOKE invokes a function in a Trusted Application. | |
37 | ||
38 | - TEE_IOC_CANCEL may cancel an ongoing TEE_IOC_OPEN_SESSION or TEE_IOC_INVOKE. | |
39 | ||
40 | - TEE_IOC_CLOSE_SESSION closes a session to a Trusted Application. | |
41 | ||
42 | There are two classes of clients, normal clients and supplicants. The latter is | |
43 | a helper process for the TEE to access resources in Linux, for example file | |
44 | system access. A normal client opens /dev/tee[0-9]* and a supplicant opens | |
45 | /dev/teepriv[0-9]. | |
46 | ||
47 | Much of the communication between clients and the TEE is opaque to the | |
48 | driver. The main job for the driver is to receive requests from the | |
49 | clients, forward them to the TEE and send back the results. In the case of | |
50 | supplicants the communication goes in the other direction, the TEE sends | |
51 | requests to the supplicant which then sends back the result. | |
52 | ||
53 | OP-TEE driver | |
54 | ============= | |
55 | ||
56 | The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM | |
57 | TrustZone based OP-TEE solution that is supported. | |
58 | ||
59 | Lowest level of communication with OP-TEE builds on ARM SMC Calling | |
60 | Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface | |
61 | [3] used internally by the driver. Stacked on top of that is OP-TEE Message | |
62 | Protocol [4]. | |
63 | ||
64 | OP-TEE SMC interface provides the basic functions required by SMCCC and some | |
65 | additional functions specific for OP-TEE. The most interesting functions are: | |
66 | ||
67 | - OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information | |
68 | which is then returned by TEE_IOC_VERSION | |
69 | ||
70 | - OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used | |
71 | to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a | |
72 | separate secure co-processor. | |
73 | ||
74 | - OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol | |
75 | ||
76 | - OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory | |
77 | range to used for shared memory between Linux and OP-TEE. | |
78 | ||
79 | The GlobalPlatform TEE Client API [5] is implemented on top of the generic | |
80 | TEE API. | |
81 | ||
82 | Picture of the relationship between the different components in the | |
83 | OP-TEE architecture. | |
84 | ||
85 | User space Kernel Secure world | |
86 | ~~~~~~~~~~ ~~~~~~ ~~~~~~~~~~~~ | |
87 | +--------+ +-------------+ | |
88 | | Client | | Trusted | | |
89 | +--------+ | Application | | |
90 | /\ +-------------+ | |
91 | || +----------+ /\ | |
92 | || |tee- | || | |
93 | || |supplicant| \/ | |
94 | || +----------+ +-------------+ | |
95 | \/ /\ | TEE Internal| | |
96 | +-------+ || | API | | |
97 | + TEE | || +--------+--------+ +-------------+ | |
98 | | Client| || | TEE | OP-TEE | | OP-TEE | | |
99 | | API | \/ | subsys | driver | | Trusted OS | | |
100 | +-------+----------------+----+-------+----+-----------+-------------+ | |
101 | | Generic TEE API | | OP-TEE MSG | | |
102 | | IOCTL (TEE_IOC_*) | | SMCCC (OPTEE_SMC_CALL_*) | | |
103 | +-----------------------------+ +------------------------------+ | |
104 | ||
105 | RPC (Remote Procedure Call) are requests from secure world to kernel driver | |
106 | or tee-supplicant. An RPC is identified by a special range of SMCCC return | |
107 | values from OPTEE_SMC_CALL_WITH_ARG. RPC messages which are intended for the | |
108 | kernel are handled by the kernel driver. Other RPC messages will be forwarded to | |
109 | tee-supplicant without further involvement of the driver, except switching | |
110 | shared memory buffer representation. | |
111 | ||
112 | References: | |
113 | [1] https://github.com/OP-TEE/optee_os | |
114 | [2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html | |
115 | [3] drivers/tee/optee/optee_smc.h | |
116 | [4] drivers/tee/optee/optee_msg.h | |
117 | [5] http://www.globalplatform.org/specificationsdevice.asp look for | |
118 | "TEE Client API Specification v1.0" and click download. |