[go: up one dir, main page]
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#define TEE_MAX_ARG_SIZE 4096
46
47#define TEE_GEN_CAP_GP (1 << 0)/* GlobalPlatform compliant TEE */
48#define TEE_GEN_CAP_PRIVILEGED (1 << 1)/* Privileged device (for supplicant) */
49#define TEE_GEN_CAP_REG_MEM (1 << 2)/* Supports registering shared memory */
50#define TEE_GEN_CAP_MEMREF_NULL (1 << 3)/* NULL MemRef support */
51#define TEE_GEN_CAP_OBJREF (1 << 4)/* Supports generic object reference */
52
53#define TEE_MEMREF_NULL ((__u64)(-1)) /* NULL MemRef Buffer */
54#define TEE_OBJREF_NULL ((__u64)(-1)) /* NULL ObjRef Object */
55
56/*
57 * TEE Implementation ID
58 */
59#define TEE_IMPL_ID_OPTEE 1
60#define TEE_IMPL_ID_AMDTEE 2
61#define TEE_IMPL_ID_TSTEE 3
62#define TEE_IMPL_ID_QTEE 4
63
64/*
65 * OP-TEE specific capabilities
66 */
67#define TEE_OPTEE_CAP_TZ (1 << 0)
68
69/**
70 * struct tee_ioctl_version_data - TEE version
71 * @impl_id: [out] TEE implementation id
72 * @impl_caps: [out] Implementation specific capabilities
73 * @gen_caps: [out] Generic capabilities, defined by TEE_GEN_CAPS_* above
74 *
75 * Identifies the TEE implementation, @impl_id is one of TEE_IMPL_ID_* above.
76 * @impl_caps is implementation specific, for example TEE_OPTEE_CAP_*
77 * is valid when @impl_id == TEE_IMPL_ID_OPTEE.
78 */
79struct tee_ioctl_version_data {
80 __u32 impl_id;
81 __u32 impl_caps;
82 __u32 gen_caps;
83};
84
85/**
86 * TEE_IOC_VERSION - query version of TEE
87 *
88 * Takes a tee_ioctl_version_data struct and returns with the TEE version
89 * data filled in.
90 */
91#define TEE_IOC_VERSION _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 0, \
92 struct tee_ioctl_version_data)
93
94/**
95 * struct tee_ioctl_shm_alloc_data - Shared memory allocate argument
96 * @size: [in/out] Size of shared memory to allocate
97 * @flags: [in/out] Flags to/from allocation.
98 * @id: [out] Identifier of the shared memory
99 *
100 * The flags field should currently be zero as input. Updated by the call
101 * with actual flags as defined by TEE_IOCTL_SHM_* above.
102 * This structure is used as argument for TEE_IOC_SHM_ALLOC below.
103 */
104struct tee_ioctl_shm_alloc_data {
105 __u64 size;
106 __u32 flags;
107 __s32 id;
108};
109
110/**
111 * TEE_IOC_SHM_ALLOC - allocate shared memory
112 *
113 * Allocates shared memory between the user space process and secure OS.
114 *
115 * Returns a file descriptor on success or < 0 on failure
116 *
117 * The returned file descriptor is used to map the shared memory into user
118 * space. The shared memory is freed when the descriptor is closed and the
119 * memory is unmapped.
120 */
121#define TEE_IOC_SHM_ALLOC _IOWR(TEE_IOC_MAGIC, TEE_IOC_BASE + 1, \
122 struct tee_ioctl_shm_alloc_data)
123
124/**
125 * struct tee_ioctl_buf_data - Variable sized buffer
126 * @buf_ptr: [in] A __user pointer to a buffer
127 * @buf_len: [in] Length of the buffer above
128 *
129 * Used as argument for TEE_IOC_OPEN_SESSION, TEE_IOC_INVOKE,
130 * TEE_IOC_SUPPL_RECV, and TEE_IOC_SUPPL_SEND below.
131 */
132struct tee_ioctl_buf_data {
133 __u64 buf_ptr;
134 __u64 buf_len;
135};
136
137/*
138 * Attributes for struct tee_ioctl_param, selects field in the union
139 */
140#define TEE_IOCTL_PARAM_ATTR_TYPE_NONE 0 /* parameter not used */
141
142/*
143 * These defines value parameters (struct tee_ioctl_param_value)
144 */
145#define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_INPUT 1
146#define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_OUTPUT 2
147#define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_INOUT 3 /* input and output */
148
149/*
150 * These defines shared memory reference parameters (struct
151 * tee_ioctl_param_memref)
152 */
153#define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INPUT 5
154#define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_OUTPUT 6
155#define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INOUT 7 /* input and output */
156
157/*
158 * These defines userspace buffer parameters.
159 */
160#define TEE_IOCTL_PARAM_ATTR_TYPE_UBUF_INPUT 8
161#define TEE_IOCTL_PARAM_ATTR_TYPE_UBUF_OUTPUT 9
162#define TEE_IOCTL_PARAM_ATTR_TYPE_UBUF_INOUT 10 /* input and output */
163
164/*
165 * These defines object reference parameters.
166 */
167#define TEE_IOCTL_PARAM_ATTR_TYPE_OBJREF_INPUT 11
168#define TEE_IOCTL_PARAM_ATTR_TYPE_OBJREF_OUTPUT 12
169#define TEE_IOCTL_PARAM_ATTR_TYPE_OBJREF_INOUT 13
170
171/*
172 * Mask for the type part of the attribute, leaves room for more types
173 */
174#define TEE_IOCTL_PARAM_ATTR_TYPE_MASK 0xff
175
176/* Meta parameter carrying extra information about the message. */
177#define TEE_IOCTL_PARAM_ATTR_META 0x100
178
179/* Mask of all known attr bits */
180#define TEE_IOCTL_PARAM_ATTR_MASK \
181 (TEE_IOCTL_PARAM_ATTR_TYPE_MASK | TEE_IOCTL_PARAM_ATTR_META)
182
183/*
184 * Matches TEEC_LOGIN_* in GP TEE Client API
185 * Are only defined for GP compliant TEEs
186 */
187#define TEE_IOCTL_LOGIN_PUBLIC 0
188#define TEE_IOCTL_LOGIN_USER 1
189#define TEE_IOCTL_LOGIN_GROUP 2
190#define TEE_IOCTL_LOGIN_APPLICATION 4
191#define TEE_IOCTL_LOGIN_USER_APPLICATION 5
192#define TEE_IOCTL_LOGIN_GROUP_APPLICATION 6
193/*
194 * Disallow user-space to use GP implementation specific login
195 * method range (0x80000000 - 0xBFFFFFFF). This range is rather
196 * being reserved for REE kernel clients or TEE implementation.
197 */
198#define TEE_IOCTL_LOGIN_REE_KERNEL_MIN 0x80000000
199#define TEE_IOCTL_LOGIN_REE_KERNEL_MAX 0xBFFFFFFF
200/* Private login method for REE kernel clients */
201#define TEE_IOCTL_LOGIN_REE_KERNEL 0x80000000
202
203/**
204 * struct tee_ioctl_param - parameter
205 * @attr: attributes
206 * @a: if a memref, offset into the shared memory object,
207 * else if a ubuf, address of the user buffer,
208 * else if an objref, object identifier, else a value parameter
209 * @b: if a memref or ubuf, size of the buffer,
210 * else if objref, flags for the object, else a value parameter
211 * @c: if a memref, shared memory identifier, else a value parameter
212 *
213 * @attr & TEE_PARAM_ATTR_TYPE_MASK indicates if memref, ubuf, or value is
214 * used in the union. TEE_PARAM_ATTR_TYPE_VALUE_* indicates value,
215 * TEE_PARAM_ATTR_TYPE_MEMREF_* indicates memref, TEE_PARAM_ATTR_TYPE_UBUF_*
216 * indicates ubuf, and TEE_PARAM_ATTR_TYPE_OBJREF_* indicates objref.
217 * TEE_PARAM_ATTR_TYPE_NONE indicates that none of the members are used.
218 *
219 * Shared memory is allocated with TEE_IOC_SHM_ALLOC which returns an
220 * identifier representing the shared memory object. A memref can reference
221 * a part of a shared memory by specifying an offset (@a) and size (@b) of
222 * the object. To supply the entire shared memory object set the offset
223 * (@a) to 0 and size (@b) to the previously returned size of the object.
224 *
225 * A client may need to present a NULL pointer in the argument
226 * passed to a trusted application in the TEE.
227 * This is also a requirement in GlobalPlatform Client API v1.0c
228 * (section 3.2.5 memory references), which can be found at
229 * http://www.globalplatform.org/specificationsdevice.asp
230 *
231 * If a NULL pointer is passed to a TA in the TEE, the (@c)
232 * IOCTL parameters value must be set to TEE_MEMREF_NULL indicating a NULL
233 * memory reference.
234 */
235struct tee_ioctl_param {
236 __u64 attr;
237 __u64 a;
238 __u64 b;
239 __u64 c;
240};
241
242#define TEE_IOCTL_UUID_LEN 16
243
244/**
245 * struct tee_ioctl_open_session_arg - Open session argument
246 * @uuid: [in] UUID of the Trusted Application
247 * @clnt_uuid: [in] UUID of client
248 * @clnt_login: [in] Login class of client, TEE_IOCTL_LOGIN_* above
249 * @cancel_id: [in] Cancellation id, a unique value to identify this request
250 * @session: [out] Session id
251 * @ret: [out] return value
252 * @ret_origin: [out] origin of the return value
253 * @num_params: [in] number of &struct tee_ioctl_param entries in @params
254 * @params: array of ioctl parameters
255 */
256struct tee_ioctl_open_session_arg {
257 __u8 uuid[TEE_IOCTL_UUID_LEN];
258 __u8 clnt_uuid[TEE_IOCTL_UUID_LEN];
259 __u32 clnt_login;
260 __u32 cancel_id;
261 __u32 session;
262 __u32 ret;
263 __u32 ret_origin;
264 __u32 num_params;
265 /* num_params tells the actual number of element in params */
266 struct tee_ioctl_param params[];
267};
268
269/**
270 * TEE_IOC_OPEN_SESSION - opens a session to a Trusted Application
271 *
272 * Takes a struct tee_ioctl_buf_data which contains a struct
273 * tee_ioctl_open_session_arg followed by any array of struct
274 * tee_ioctl_param
275 */
276#define TEE_IOC_OPEN_SESSION _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 2, \
277 struct tee_ioctl_buf_data)
278
279/**
280 * struct tee_ioctl_invoke_arg - Invokes a function in a Trusted Application
281 * @func: [in] Trusted Application function, specific to the TA
282 * @session: [in] Session id
283 * @cancel_id: [in] Cancellation id, a unique value to identify this request
284 * @ret: [out] return value
285 * @ret_origin: [out] origin of the return value
286 * @num_params: [in] number of parameters following this struct
287 * @params: array of ioctl parameters
288 */
289struct tee_ioctl_invoke_arg {
290 __u32 func;
291 __u32 session;
292 __u32 cancel_id;
293 __u32 ret;
294 __u32 ret_origin;
295 __u32 num_params;
296 /* num_params tells the actual number of element in params */
297 struct tee_ioctl_param params[];
298};
299
300/**
301 * TEE_IOC_INVOKE - Invokes a function in a Trusted Application
302 *
303 * Takes a struct tee_ioctl_buf_data which contains a struct
304 * tee_invoke_func_arg followed by any array of struct tee_param
305 */
306#define TEE_IOC_INVOKE _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 3, \
307 struct tee_ioctl_buf_data)
308
309/**
310 * struct tee_ioctl_cancel_arg - Cancels an open session or invoke ioctl
311 * @cancel_id: [in] Cancellation id, a unique value to identify this request
312 * @session: [in] Session id, if the session is opened, else set to 0
313 */
314struct tee_ioctl_cancel_arg {
315 __u32 cancel_id;
316 __u32 session;
317};
318
319/**
320 * TEE_IOC_CANCEL - Cancels an open session or invoke
321 */
322#define TEE_IOC_CANCEL _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 4, \
323 struct tee_ioctl_cancel_arg)
324
325/**
326 * struct tee_ioctl_close_session_arg - Closes an open session
327 * @session: [in] Session id
328 */
329struct tee_ioctl_close_session_arg {
330 __u32 session;
331};
332
333/**
334 * TEE_IOC_CLOSE_SESSION - Closes a session
335 */
336#define TEE_IOC_CLOSE_SESSION _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 5, \
337 struct tee_ioctl_close_session_arg)
338
339/**
340 * struct tee_iocl_supp_recv_arg - Receive a request for a supplicant function
341 * @func: [in] supplicant function
342 * @num_params: [in/out] number of &struct tee_ioctl_param entries in @params
343 * @params: array of ioctl parameters
344 *
345 * @num_params is the number of params that tee-supplicant has room to
346 * receive when input, @num_params is the number of actual params
347 * tee-supplicant receives when output.
348 */
349struct tee_iocl_supp_recv_arg {
350 __u32 func;
351 __u32 num_params;
352 /* num_params tells the actual number of element in params */
353 struct tee_ioctl_param params[];
354};
355
356/**
357 * TEE_IOC_SUPPL_RECV - Receive a request for a supplicant function
358 *
359 * Takes a struct tee_ioctl_buf_data which contains a struct
360 * tee_iocl_supp_recv_arg followed by any array of struct tee_param
361 */
362#define TEE_IOC_SUPPL_RECV _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 6, \
363 struct tee_ioctl_buf_data)
364
365/**
366 * struct tee_iocl_supp_send_arg - Send a response to a received request
367 * @ret: [out] return value
368 * @num_params: [in] number of &struct tee_ioctl_param entries in @params
369 * @params: array of ioctl parameters
370 */
371struct tee_iocl_supp_send_arg {
372 __u32 ret;
373 __u32 num_params;
374 /* num_params tells the actual number of element in params */
375 struct tee_ioctl_param params[];
376};
377
378/**
379 * TEE_IOC_SUPPL_SEND - Send a response to a received request
380 *
381 * Takes a struct tee_ioctl_buf_data which contains a struct
382 * tee_iocl_supp_send_arg followed by any array of struct tee_param
383 */
384#define TEE_IOC_SUPPL_SEND _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 7, \
385 struct tee_ioctl_buf_data)
386
387/**
388 * struct tee_ioctl_shm_register_data - Shared memory register argument
389 * @addr: [in] Start address of shared memory to register
390 * @length: [in/out] Length of shared memory to register
391 * @flags: [in/out] Flags to/from registration.
392 * @id: [out] Identifier of the shared memory
393 *
394 * The flags field should currently be zero as input. Updated by the call
395 * with actual flags as defined by TEE_IOCTL_SHM_* above.
396 * This structure is used as argument for TEE_IOC_SHM_REGISTER below.
397 */
398struct tee_ioctl_shm_register_data {
399 __u64 addr;
400 __u64 length;
401 __u32 flags;
402 __s32 id;
403};
404
405/**
406 * struct tee_ioctl_shm_register_fd_data - Shared memory registering argument
407 * @fd: [in] File descriptor identifying dmabuf reference
408 * @size: [out] Size of referenced memory
409 * @flags: [in] Flags to/from allocation.
410 * @id: [out] Identifier of the shared memory
411 *
412 * The flags field should currently be zero as input. Updated by the call
413 * with actual flags as defined by TEE_IOCTL_SHM_* above.
414 * This structure is used as argument for TEE_IOC_SHM_REGISTER_FD below.
415 */
416struct tee_ioctl_shm_register_fd_data {
417 __s64 fd;
418 __u64 size;
419 __u32 flags;
420 __s32 id;
421};
422
423/**
424 * TEE_IOC_SHM_REGISTER_FD - register a shared memory from a file descriptor
425 *
426 * Returns a file descriptor on success or < 0 on failure
427 *
428 * The returned file descriptor refers to the shared memory object in the
429 * kernel. The supplied file deccriptor can be closed if it's not needed
430 * for other purposes. The shared memory is freed when the descriptor is
431 * closed.
432 */
433#define TEE_IOC_SHM_REGISTER_FD _IOWR(TEE_IOC_MAGIC, TEE_IOC_BASE + 8, \
434 struct tee_ioctl_shm_register_fd_data)
435
436/**
437 * TEE_IOC_SHM_REGISTER - Register shared memory argument
438 *
439 * Registers shared memory between the user space process and secure OS.
440 *
441 * Returns a file descriptor on success or < 0 on failure
442 *
443 * The shared memory is unregisterred when the descriptor is closed.
444 */
445#define TEE_IOC_SHM_REGISTER _IOWR(TEE_IOC_MAGIC, TEE_IOC_BASE + 9, \
446 struct tee_ioctl_shm_register_data)
447/*
448 * Five syscalls are used when communicating with the TEE driver.
449 * open(): opens the device associated with the driver
450 * ioctl(): as described above operating on the file descriptor from open()
451 * close(): two cases
452 * - closes the device file descriptor
453 * - closes a file descriptor connected to allocated shared memory
454 * mmap(): maps shared memory into user space using information from struct
455 * tee_ioctl_shm_alloc_data
456 * munmap(): unmaps previously shared memory
457 */
458
459/**
460 * struct tee_ioctl_object_invoke_arg - Invokes an object in a
461 * Trusted Application
462 * @id: [in] Object id
463 * @op: [in] Object operation, specific to the object
464 * @ret: [out] return value
465 * @num_params: [in] number of parameters following this struct
466 * @params: array of ioctl parameters
467 */
468struct tee_ioctl_object_invoke_arg {
469 __u64 id;
470 __u32 op;
471 __u32 ret;
472 __u32 num_params;
473 /* num_params tells the actual number of element in params */
474 struct tee_ioctl_param params[];
475};
476
477#define TEE_IOC_OBJECT_INVOKE _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 10, \
478 struct tee_ioctl_buf_data)
479
480#endif /*__TEE_H*/
481

source code of linux/include/uapi/linux/tee.h