tee.h

  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*/