History

Merge tag 'armsoc-tee' of git://git.kernel.org/pub/scm/linux/kernel/git/arm/arm-soc

Pull TEE driver infrastructure and OP-TEE drivers from Arnd Bergmann: "This introduces a generic TEE framework in the kernel, to handle trusted environemtns (security coprocessor or software implementations such as OP-TEE/TrustZone). I'm sending it separately from the other arm-soc driver changes to give it a little more visibility, once the subsystem is merged, we will likely keep this in the arm₋soc drivers branch or have the maintainers submit pull requests directly, depending on the patch volume. I have reviewed earlier versions in the past, and have reviewed the latest version in person during Linaro Connect BUD17. Here is my overall assessment of the subsystem: - There is clearly demand for this, both for the generic infrastructure and the specific OP-TEE implementation. - The code has gone through a large number of reviews, and the review comments have all been addressed, but the reviews were not coming up with serious issues any more and nobody volunteered to vouch for the quality. - The user space ioctl interface is sufficient to work with the OP-TEE driver, and it should in principle work with other TEE implementations that follow the GlobalPlatform[1] standards, but it might need to be extended in minor ways depending on specific requirements of future TEE implementations - The main downside of the API to me is how the user space is tied to the TEE implementation in hardware or firmware, but uses a generic way to communicate with it. This seems to be an inherent problem with what it is trying to do, and I could not come up with any better solution than what is implemented here. For a detailed history of the patch series, see https://lkml.org/lkml/2017/3/10/1277" * tag 'armsoc-tee' of git://git.kernel.org/pub/scm/linux/kernel/git/arm/arm-soc: arm64: dt: hikey: Add optee node Documentation: tee subsystem and op-tee driver tee: add OP-TEE driver tee: generic TEE subsystem dt/bindings: add bindings for optee

Linus Torvalds committed 9 years ago

Commit a2d92142 parents de4d195 414d06a26 files · +5156 −0Browse files

Showing the changes to include/uapi/linux (1 of 26 files). Show all

Unified · Split

include/uapi/linux/tee.h+346−0
@@ -0,0 +1,346 @@
1+/*
2+ * Copyright (c) 2015-2016, Linaro Limited
3+ * All rights reserved.
4+ *
5+ * Redistribution and use in source and binary forms, with or without
6+ * modification, are permitted provided that the following conditions are met:
7+ *
8+ * 1. Redistributions of source code must retain the above copyright notice,
9+ * this list of conditions and the following disclaimer.
10+ *
11+ * 2. Redistributions in binary form must reproduce the above copyright notice,
12+ * this list of conditions and the following disclaimer in the documentation
13+ * and/or other materials provided with the distribution.
14+ *
15+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
19+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
20+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
21+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
22+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
23+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
24+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
25+ * POSSIBILITY OF SUCH DAMAGE.
26+ */
27+
28+#ifndef __TEE_H
29+#define __TEE_H
30+
31+#include <linux/ioctl.h>
32+#include <linux/types.h>
33+
34+/*
35+ * This file describes the API provided by a TEE driver to user space.
36+ *
37+ * Each TEE driver defines a TEE specific protocol which is used for the
38+ * data passed back and forth using TEE_IOC_CMD.
39+ */
40+
41+/* Helpers to make the ioctl defines */
42+#define TEE_IOC_MAGIC 0xa4
43+#define TEE_IOC_BASE 0
44+
45+/* Flags relating to shared memory */
46+#define TEE_IOCTL_SHM_MAPPED 0x1 /* memory mapped in normal world */
47+#define TEE_IOCTL_SHM_DMA_BUF 0x2 /* dma-buf handle on shared memory */
48+
49+#define TEE_MAX_ARG_SIZE 1024
50+
51+#define TEE_GEN_CAP_GP (1 << 0)/* GlobalPlatform compliant TEE */
52+
53+/*
54+ * TEE Implementation ID
55+ */
56+#define TEE_IMPL_ID_OPTEE 1
57+
58+/*
59+ * OP-TEE specific capabilities
60+ */
61+#define TEE_OPTEE_CAP_TZ (1 << 0)
62+
63+/**
64+ * struct tee_ioctl_version_data - TEE version
65+ * @impl_id: [out] TEE implementation id
66+ * @impl_caps: [out] Implementation specific capabilities
67+ * @gen_caps: [out] Generic capabilities, defined by TEE_GEN_CAPS_* above
68+ *
69+ * Identifies the TEE implementation, @impl_id is one of TEE_IMPL_ID_* above.
70+ * @impl_caps is implementation specific, for example TEE_OPTEE_CAP_*
71+ * is valid when @impl_id == TEE_IMPL_ID_OPTEE.
72+ */
73+struct tee_ioctl_version_data {
74+ __u32 impl_id;
75+ __u32 impl_caps;
76+ __u32 gen_caps;
77+};
78+
79+/**
80+ * TEE_IOC_VERSION - query version of TEE
81+ *
82+ * Takes a tee_ioctl_version_data struct and returns with the TEE version
83+ * data filled in.
84+ */
85+#define TEE_IOC_VERSION _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 0, \
86+ struct tee_ioctl_version_data)
87+
88+/**
89+ * struct tee_ioctl_shm_alloc_data - Shared memory allocate argument
90+ * @size: [in/out] Size of shared memory to allocate
91+ * @flags: [in/out] Flags to/from allocation.
92+ * @id: [out] Identifier of the shared memory
93+ *
94+ * The flags field should currently be zero as input. Updated by the call
95+ * with actual flags as defined by TEE_IOCTL_SHM_* above.
96+ * This structure is used as argument for TEE_IOC_SHM_ALLOC below.
97+ */
98+struct tee_ioctl_shm_alloc_data {
99+ __u64 size;
100+ __u32 flags;
101+ __s32 id;
102+};
103+
104+/**
105+ * TEE_IOC_SHM_ALLOC - allocate shared memory
106+ *
107+ * Allocates shared memory between the user space process and secure OS.
108+ *
109+ * Returns a file descriptor on success or < 0 on failure
110+ *
111+ * The returned file descriptor is used to map the shared memory into user
112+ * space. The shared memory is freed when the descriptor is closed and the
113+ * memory is unmapped.
114+ */
115+#define TEE_IOC_SHM_ALLOC _IOWR(TEE_IOC_MAGIC, TEE_IOC_BASE + 1, \
116+ struct tee_ioctl_shm_alloc_data)
117+
118+/**
119+ * struct tee_ioctl_buf_data - Variable sized buffer
120+ * @buf_ptr: [in] A __user pointer to a buffer
121+ * @buf_len: [in] Length of the buffer above
122+ *
123+ * Used as argument for TEE_IOC_OPEN_SESSION, TEE_IOC_INVOKE,
124+ * TEE_IOC_SUPPL_RECV, and TEE_IOC_SUPPL_SEND below.
125+ */
126+struct tee_ioctl_buf_data {
127+ __u64 buf_ptr;
128+ __u64 buf_len;
129+};
130+
131+/*
132+ * Attributes for struct tee_ioctl_param, selects field in the union
133+ */
134+#define TEE_IOCTL_PARAM_ATTR_TYPE_NONE 0 /* parameter not used */
135+
136+/*
137+ * These defines value parameters (struct tee_ioctl_param_value)
138+ */
139+#define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_INPUT 1
140+#define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_OUTPUT 2
141+#define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_INOUT 3 /* input and output */
142+
143+/*
144+ * These defines shared memory reference parameters (struct
145+ * tee_ioctl_param_memref)
146+ */
147+#define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INPUT 5
148+#define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_OUTPUT 6
149+#define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INOUT 7 /* input and output */
150+
151+/*
152+ * Mask for the type part of the attribute, leaves room for more types
153+ */
154+#define TEE_IOCTL_PARAM_ATTR_TYPE_MASK 0xff
155+
156+/*
157+ * Matches TEEC_LOGIN_* in GP TEE Client API
158+ * Are only defined for GP compliant TEEs
159+ */
160+#define TEE_IOCTL_LOGIN_PUBLIC 0
161+#define TEE_IOCTL_LOGIN_USER 1
162+#define TEE_IOCTL_LOGIN_GROUP 2
163+#define TEE_IOCTL_LOGIN_APPLICATION 4
164+#define TEE_IOCTL_LOGIN_USER_APPLICATION 5
165+#define TEE_IOCTL_LOGIN_GROUP_APPLICATION 6
166+
167+/**
168+ * struct tee_ioctl_param - parameter
169+ * @attr: attributes
170+ * @a: if a memref, offset into the shared memory object, else a value parameter
171+ * @b: if a memref, size of the buffer, else a value parameter
172+ * @c: if a memref, shared memory identifier, else a value parameter
173+ *
174+ * @attr & TEE_PARAM_ATTR_TYPE_MASK indicates if memref or value is used in
175+ * the union. TEE_PARAM_ATTR_TYPE_VALUE_* indicates value and
176+ * TEE_PARAM_ATTR_TYPE_MEMREF_* indicates memref. TEE_PARAM_ATTR_TYPE_NONE
177+ * indicates that none of the members are used.
178+ *
179+ * Shared memory is allocated with TEE_IOC_SHM_ALLOC which returns an
180+ * identifier representing the shared memory object. A memref can reference
181+ * a part of a shared memory by specifying an offset (@a) and size (@b) of
182+ * the object. To supply the entire shared memory object set the offset
183+ * (@a) to 0 and size (@b) to the previously returned size of the object.
184+ */
185+struct tee_ioctl_param {
186+ __u64 attr;
187+ __u64 a;
188+ __u64 b;
189+ __u64 c;
190+};
191+
192+#define TEE_IOCTL_UUID_LEN 16
193+
194+/**
195+ * struct tee_ioctl_open_session_arg - Open session argument
196+ * @uuid: [in] UUID of the Trusted Application
197+ * @clnt_uuid: [in] UUID of client
198+ * @clnt_login: [in] Login class of client, TEE_IOCTL_LOGIN_* above
199+ * @cancel_id: [in] Cancellation id, a unique value to identify this request
200+ * @session: [out] Session id
201+ * @ret: [out] return value
202+ * @ret_origin [out] origin of the return value
203+ * @num_params [in] number of parameters following this struct
204+ */
205+struct tee_ioctl_open_session_arg {
206+ __u8 uuid[TEE_IOCTL_UUID_LEN];
207+ __u8 clnt_uuid[TEE_IOCTL_UUID_LEN];
208+ __u32 clnt_login;
209+ __u32 cancel_id;
210+ __u32 session;
211+ __u32 ret;
212+ __u32 ret_origin;
213+ __u32 num_params;
214+ /* num_params tells the actual number of element in params */
215+ struct tee_ioctl_param params[];
216+};
217+
218+/**
219+ * TEE_IOC_OPEN_SESSION - opens a session to a Trusted Application
220+ *
221+ * Takes a struct tee_ioctl_buf_data which contains a struct
222+ * tee_ioctl_open_session_arg followed by any array of struct
223+ * tee_ioctl_param
224+ */
225+#define TEE_IOC_OPEN_SESSION _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 2, \
226+ struct tee_ioctl_buf_data)
227+
228+/**
229+ * struct tee_ioctl_invoke_func_arg - Invokes a function in a Trusted
230+ * Application
231+ * @func: [in] Trusted Application function, specific to the TA
232+ * @session: [in] Session id
233+ * @cancel_id: [in] Cancellation id, a unique value to identify this request
234+ * @ret: [out] return value
235+ * @ret_origin [out] origin of the return value
236+ * @num_params [in] number of parameters following this struct
237+ */
238+struct tee_ioctl_invoke_arg {
239+ __u32 func;
240+ __u32 session;
241+ __u32 cancel_id;
242+ __u32 ret;
243+ __u32 ret_origin;
244+ __u32 num_params;
245+ /* num_params tells the actual number of element in params */
246+ struct tee_ioctl_param params[];
247+};
248+
249+/**
250+ * TEE_IOC_INVOKE - Invokes a function in a Trusted Application
251+ *
252+ * Takes a struct tee_ioctl_buf_data which contains a struct
253+ * tee_invoke_func_arg followed by any array of struct tee_param
254+ */
255+#define TEE_IOC_INVOKE _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 3, \
256+ struct tee_ioctl_buf_data)
257+
258+/**
259+ * struct tee_ioctl_cancel_arg - Cancels an open session or invoke ioctl
260+ * @cancel_id: [in] Cancellation id, a unique value to identify this request
261+ * @session: [in] Session id, if the session is opened, else set to 0
262+ */
263+struct tee_ioctl_cancel_arg {
264+ __u32 cancel_id;
265+ __u32 session;
266+};
267+
268+/**
269+ * TEE_IOC_CANCEL - Cancels an open session or invoke
270+ */
271+#define TEE_IOC_CANCEL _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 4, \
272+ struct tee_ioctl_cancel_arg)
273+
274+/**
275+ * struct tee_ioctl_close_session_arg - Closes an open session
276+ * @session: [in] Session id
277+ */
278+struct tee_ioctl_close_session_arg {
279+ __u32 session;
280+};
281+
282+/**
283+ * TEE_IOC_CLOSE_SESSION - Closes a session
284+ */
285+#define TEE_IOC_CLOSE_SESSION _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 5, \
286+ struct tee_ioctl_close_session_arg)
287+
288+/**
289+ * struct tee_iocl_supp_recv_arg - Receive a request for a supplicant function
290+ * @func: [in] supplicant function
291+ * @num_params [in/out] number of parameters following this struct
292+ *
293+ * @num_params is the number of params that tee-supplicant has room to
294+ * receive when input, @num_params is the number of actual params
295+ * tee-supplicant receives when output.
296+ */
297+struct tee_iocl_supp_recv_arg {
298+ __u32 func;
299+ __u32 num_params;
300+ /* num_params tells the actual number of element in params */
301+ struct tee_ioctl_param params[];
302+};
303+
304+/**
305+ * TEE_IOC_SUPPL_RECV - Receive a request for a supplicant function
306+ *
307+ * Takes a struct tee_ioctl_buf_data which contains a struct
308+ * tee_iocl_supp_recv_arg followed by any array of struct tee_param
309+ */
310+#define TEE_IOC_SUPPL_RECV _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 6, \
311+ struct tee_ioctl_buf_data)
312+
313+/**
314+ * struct tee_iocl_supp_send_arg - Send a response to a received request
315+ * @ret: [out] return value
316+ * @num_params [in] number of parameters following this struct
317+ */
318+struct tee_iocl_supp_send_arg {
319+ __u32 ret;
320+ __u32 num_params;
321+ /* num_params tells the actual number of element in params */
322+ struct tee_ioctl_param params[];
323+};
324+
325+/**
326+ * TEE_IOC_SUPPL_SEND - Receive a request for a supplicant function
327+ *
328+ * Takes a struct tee_ioctl_buf_data which contains a struct
329+ * tee_iocl_supp_send_arg followed by any array of struct tee_param
330+ */
331+#define TEE_IOC_SUPPL_SEND _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 7, \
332+ struct tee_ioctl_buf_data)
333+
334+/*
335+ * Five syscalls are used when communicating with the TEE driver.
336+ * open(): opens the device associated with the driver
337+ * ioctl(): as described above operating on the file descriptor from open()
338+ * close(): two cases
339+ * - closes the device file descriptor
340+ * - closes a file descriptor connected to allocated shared memory
341+ * mmap(): maps shared memory into user space using information from struct
342+ * tee_ioctl_shm_alloc_data
343+ * munmap(): unmaps previously shared memory
344+ */
345+
346+#endif /*__TEE_H*/