blob: 56ea85ffebf24545dccb0d4c467c0400d3b7ff90
1 | ============= |
2 | TEE subsystem |
3 | ============= |
4 | |
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 |
35 | the 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 | |
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 |
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 | +-----------------------------+ +------------------------------+ |
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 | |
115 | References |
116 | ========== |
117 | |
118 | [1] https://github.com/OP-TEE/optee_os |
119 | |
120 | [2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html |
121 | |
122 | [3] drivers/tee/optee/optee_smc.h |
123 | |
124 | [4] drivers/tee/optee/optee_msg.h |
125 | |
126 | [5] http://www.globalplatform.org/specificationsdevice.asp look for |
127 | "TEE Client API Specification v1.0" and click download. |
128 |