logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

tee.h (13433B)


  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. #ifndef __TEE_H
  28. #define __TEE_H
  29. #include <linux/ioctl.h>
  30. #include <linux/types.h>
  31. /*
  32. * This file describes the API provided by a TEE driver to user space.
  33. *
  34. * Each TEE driver defines a TEE specific protocol which is used for the
  35. * data passed back and forth using TEE_IOC_CMD.
  36. */
  37. /* Helpers to make the ioctl defines */
  38. #define TEE_IOC_MAGIC 0xa4
  39. #define TEE_IOC_BASE 0
  40. #define TEE_MAX_ARG_SIZE 1024
  41. #define TEE_GEN_CAP_GP (1 << 0)/* GlobalPlatform compliant TEE */
  42. #define TEE_GEN_CAP_PRIVILEGED (1 << 1)/* Privileged device (for supplicant) */
  43. #define TEE_GEN_CAP_REG_MEM (1 << 2)/* Supports registering shared memory */
  44. #define TEE_GEN_CAP_MEMREF_NULL (1 << 3)/* NULL MemRef support */
  45. #define TEE_MEMREF_NULL (__u64)(-1) /* NULL MemRef Buffer */
  46. /*
  47. * TEE Implementation ID
  48. */
  49. #define TEE_IMPL_ID_OPTEE 1
  50. #define TEE_IMPL_ID_AMDTEE 2
  51. #define TEE_IMPL_ID_TSTEE 3
  52. /*
  53. * OP-TEE specific capabilities
  54. */
  55. #define TEE_OPTEE_CAP_TZ (1 << 0)
  56. /**
  57. * struct tee_ioctl_version_data - TEE version
  58. * @impl_id: [out] TEE implementation id
  59. * @impl_caps: [out] Implementation specific capabilities
  60. * @gen_caps: [out] Generic capabilities, defined by TEE_GEN_CAPS_* above
  61. *
  62. * Identifies the TEE implementation, @impl_id is one of TEE_IMPL_ID_* above.
  63. * @impl_caps is implementation specific, for example TEE_OPTEE_CAP_*
  64. * is valid when @impl_id == TEE_IMPL_ID_OPTEE.
  65. */
  66. struct tee_ioctl_version_data {
  67. __u32 impl_id;
  68. __u32 impl_caps;
  69. __u32 gen_caps;
  70. };
  71. /**
  72. * TEE_IOC_VERSION - query version of TEE
  73. *
  74. * Takes a tee_ioctl_version_data struct and returns with the TEE version
  75. * data filled in.
  76. */
  77. #define TEE_IOC_VERSION _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 0, \
  78. struct tee_ioctl_version_data)
  79. /**
  80. * struct tee_ioctl_shm_alloc_data - Shared memory allocate argument
  81. * @size: [in/out] Size of shared memory to allocate
  82. * @flags: [in/out] Flags to/from allocation.
  83. * @id: [out] Identifier of the shared memory
  84. *
  85. * The flags field should currently be zero as input. Updated by the call
  86. * with actual flags as defined by TEE_IOCTL_SHM_* above.
  87. * This structure is used as argument for TEE_IOC_SHM_ALLOC below.
  88. */
  89. struct tee_ioctl_shm_alloc_data {
  90. __u64 size;
  91. __u32 flags;
  92. __s32 id;
  93. };
  94. /**
  95. * TEE_IOC_SHM_ALLOC - allocate shared memory
  96. *
  97. * Allocates shared memory between the user space process and secure OS.
  98. *
  99. * Returns a file descriptor on success or < 0 on failure
  100. *
  101. * The returned file descriptor is used to map the shared memory into user
  102. * space. The shared memory is freed when the descriptor is closed and the
  103. * memory is unmapped.
  104. */
  105. #define TEE_IOC_SHM_ALLOC _IOWR(TEE_IOC_MAGIC, TEE_IOC_BASE + 1, \
  106. struct tee_ioctl_shm_alloc_data)
  107. /**
  108. * struct tee_ioctl_buf_data - Variable sized buffer
  109. * @buf_ptr: [in] A pointer to a buffer
  110. * @buf_len: [in] Length of the buffer above
  111. *
  112. * Used as argument for TEE_IOC_OPEN_SESSION, TEE_IOC_INVOKE,
  113. * TEE_IOC_SUPPL_RECV, and TEE_IOC_SUPPL_SEND below.
  114. */
  115. struct tee_ioctl_buf_data {
  116. __u64 buf_ptr;
  117. __u64 buf_len;
  118. };
  119. /*
  120. * Attributes for struct tee_ioctl_param, selects field in the union
  121. */
  122. #define TEE_IOCTL_PARAM_ATTR_TYPE_NONE 0 /* parameter not used */
  123. /*
  124. * These defines value parameters (struct tee_ioctl_param_value)
  125. */
  126. #define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_INPUT 1
  127. #define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_OUTPUT 2
  128. #define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_INOUT 3 /* input and output */
  129. /*
  130. * These defines shared memory reference parameters (struct
  131. * tee_ioctl_param_memref)
  132. */
  133. #define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INPUT 5
  134. #define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_OUTPUT 6
  135. #define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INOUT 7 /* input and output */
  136. /*
  137. * Mask for the type part of the attribute, leaves room for more types
  138. */
  139. #define TEE_IOCTL_PARAM_ATTR_TYPE_MASK 0xff
  140. /* Meta parameter carrying extra information about the message. */
  141. #define TEE_IOCTL_PARAM_ATTR_META 0x100
  142. /* Mask of all known attr bits */
  143. #define TEE_IOCTL_PARAM_ATTR_MASK \
  144. (TEE_IOCTL_PARAM_ATTR_TYPE_MASK | TEE_IOCTL_PARAM_ATTR_META)
  145. /*
  146. * Matches TEEC_LOGIN_* in GP TEE Client API
  147. * Are only defined for GP compliant TEEs
  148. */
  149. #define TEE_IOCTL_LOGIN_PUBLIC 0
  150. #define TEE_IOCTL_LOGIN_USER 1
  151. #define TEE_IOCTL_LOGIN_GROUP 2
  152. #define TEE_IOCTL_LOGIN_APPLICATION 4
  153. #define TEE_IOCTL_LOGIN_USER_APPLICATION 5
  154. #define TEE_IOCTL_LOGIN_GROUP_APPLICATION 6
  155. /*
  156. * Disallow user-space to use GP implementation specific login
  157. * method range (0x80000000 - 0xBFFFFFFF). This range is rather
  158. * being reserved for REE kernel clients or TEE implementation.
  159. */
  160. #define TEE_IOCTL_LOGIN_REE_KERNEL_MIN 0x80000000
  161. #define TEE_IOCTL_LOGIN_REE_KERNEL_MAX 0xBFFFFFFF
  162. /* Private login method for REE kernel clients */
  163. #define TEE_IOCTL_LOGIN_REE_KERNEL 0x80000000
  164. /**
  165. * struct tee_ioctl_param - parameter
  166. * @attr: attributes
  167. * @a: if a memref, offset into the shared memory object, else a value parameter
  168. * @b: if a memref, size of the buffer, else a value parameter
  169. * @c: if a memref, shared memory identifier, else a value parameter
  170. *
  171. * @attr & TEE_PARAM_ATTR_TYPE_MASK indicates if memref or value is used in
  172. * the union. TEE_PARAM_ATTR_TYPE_VALUE_* indicates value and
  173. * TEE_PARAM_ATTR_TYPE_MEMREF_* indicates memref. TEE_PARAM_ATTR_TYPE_NONE
  174. * indicates that none of the members are used.
  175. *
  176. * Shared memory is allocated with TEE_IOC_SHM_ALLOC which returns an
  177. * identifier representing the shared memory object. A memref can reference
  178. * a part of a shared memory by specifying an offset (@a) and size (@b) of
  179. * the object. To supply the entire shared memory object set the offset
  180. * (@a) to 0 and size (@b) to the previously returned size of the object.
  181. *
  182. * A client may need to present a NULL pointer in the argument
  183. * passed to a trusted application in the TEE.
  184. * This is also a requirement in GlobalPlatform Client API v1.0c
  185. * (section 3.2.5 memory references), which can be found at
  186. * http://www.globalplatform.org/specificationsdevice.asp
  187. *
  188. * If a NULL pointer is passed to a TA in the TEE, the (@c)
  189. * IOCTL parameters value must be set to TEE_MEMREF_NULL indicating a NULL
  190. * memory reference.
  191. */
  192. struct tee_ioctl_param {
  193. __u64 attr;
  194. __u64 a;
  195. __u64 b;
  196. __u64 c;
  197. };
  198. #define TEE_IOCTL_UUID_LEN 16
  199. /**
  200. * struct tee_ioctl_open_session_arg - Open session argument
  201. * @uuid: [in] UUID of the Trusted Application
  202. * @clnt_uuid: [in] UUID of client
  203. * @clnt_login: [in] Login class of client, TEE_IOCTL_LOGIN_* above
  204. * @cancel_id: [in] Cancellation id, a unique value to identify this request
  205. * @session: [out] Session id
  206. * @ret: [out] return value
  207. * @ret_origin [out] origin of the return value
  208. * @num_params [in] number of parameters following this struct
  209. */
  210. struct tee_ioctl_open_session_arg {
  211. __u8 uuid[TEE_IOCTL_UUID_LEN];
  212. __u8 clnt_uuid[TEE_IOCTL_UUID_LEN];
  213. __u32 clnt_login;
  214. __u32 cancel_id;
  215. __u32 session;
  216. __u32 ret;
  217. __u32 ret_origin;
  218. __u32 num_params;
  219. /* num_params tells the actual number of element in params */
  220. struct tee_ioctl_param params[];
  221. };
  222. /**
  223. * TEE_IOC_OPEN_SESSION - opens a session to a Trusted Application
  224. *
  225. * Takes a struct tee_ioctl_buf_data which contains a struct
  226. * tee_ioctl_open_session_arg followed by any array of struct
  227. * tee_ioctl_param
  228. */
  229. #define TEE_IOC_OPEN_SESSION _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 2, \
  230. struct tee_ioctl_buf_data)
  231. /**
  232. * struct tee_ioctl_invoke_func_arg - Invokes a function in a Trusted
  233. * Application
  234. * @func: [in] Trusted Application function, specific to the TA
  235. * @session: [in] Session id
  236. * @cancel_id: [in] Cancellation id, a unique value to identify this request
  237. * @ret: [out] return value
  238. * @ret_origin [out] origin of the return value
  239. * @num_params [in] number of parameters following this struct
  240. */
  241. struct tee_ioctl_invoke_arg {
  242. __u32 func;
  243. __u32 session;
  244. __u32 cancel_id;
  245. __u32 ret;
  246. __u32 ret_origin;
  247. __u32 num_params;
  248. /* num_params tells the actual number of element in params */
  249. struct tee_ioctl_param params[];
  250. };
  251. /**
  252. * TEE_IOC_INVOKE - Invokes a function in a Trusted Application
  253. *
  254. * Takes a struct tee_ioctl_buf_data which contains a struct
  255. * tee_invoke_func_arg followed by any array of struct tee_param
  256. */
  257. #define TEE_IOC_INVOKE _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 3, \
  258. struct tee_ioctl_buf_data)
  259. /**
  260. * struct tee_ioctl_cancel_arg - Cancels an open session or invoke ioctl
  261. * @cancel_id: [in] Cancellation id, a unique value to identify this request
  262. * @session: [in] Session id, if the session is opened, else set to 0
  263. */
  264. struct tee_ioctl_cancel_arg {
  265. __u32 cancel_id;
  266. __u32 session;
  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. * struct tee_ioctl_close_session_arg - Closes an open session
  275. * @session: [in] Session id
  276. */
  277. struct tee_ioctl_close_session_arg {
  278. __u32 session;
  279. };
  280. /**
  281. * TEE_IOC_CLOSE_SESSION - Closes a session
  282. */
  283. #define TEE_IOC_CLOSE_SESSION _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 5, \
  284. struct tee_ioctl_close_session_arg)
  285. /**
  286. * struct tee_iocl_supp_recv_arg - Receive a request for a supplicant function
  287. * @func: [in] supplicant function
  288. * @num_params [in/out] number of parameters following this struct
  289. *
  290. * @num_params is the number of params that tee-supplicant has room to
  291. * receive when input, @num_params is the number of actual params
  292. * tee-supplicant receives when output.
  293. */
  294. struct tee_iocl_supp_recv_arg {
  295. __u32 func;
  296. __u32 num_params;
  297. /* num_params tells the actual number of element in params */
  298. struct tee_ioctl_param params[];
  299. };
  300. /**
  301. * TEE_IOC_SUPPL_RECV - Receive a request for a supplicant function
  302. *
  303. * Takes a struct tee_ioctl_buf_data which contains a struct
  304. * tee_iocl_supp_recv_arg followed by any array of struct tee_param
  305. */
  306. #define TEE_IOC_SUPPL_RECV _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 6, \
  307. struct tee_ioctl_buf_data)
  308. /**
  309. * struct tee_iocl_supp_send_arg - Send a response to a received request
  310. * @ret: [out] return value
  311. * @num_params [in] number of parameters following this struct
  312. */
  313. struct tee_iocl_supp_send_arg {
  314. __u32 ret;
  315. __u32 num_params;
  316. /* num_params tells the actual number of element in params */
  317. struct tee_ioctl_param params[];
  318. };
  319. /**
  320. * TEE_IOC_SUPPL_SEND - Send a response to a received request
  321. *
  322. * Takes a struct tee_ioctl_buf_data which contains a struct
  323. * tee_iocl_supp_send_arg followed by any array of struct tee_param
  324. */
  325. #define TEE_IOC_SUPPL_SEND _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 7, \
  326. struct tee_ioctl_buf_data)
  327. /**
  328. * struct tee_ioctl_shm_register_data - Shared memory register argument
  329. * @addr: [in] Start address of shared memory to register
  330. * @length: [in/out] Length of shared memory to register
  331. * @flags: [in/out] Flags to/from registration.
  332. * @id: [out] Identifier of the shared memory
  333. *
  334. * The flags field should currently be zero as input. Updated by the call
  335. * with actual flags as defined by TEE_IOCTL_SHM_* above.
  336. * This structure is used as argument for TEE_IOC_SHM_REGISTER below.
  337. */
  338. struct tee_ioctl_shm_register_data {
  339. __u64 addr;
  340. __u64 length;
  341. __u32 flags;
  342. __s32 id;
  343. };
  344. /**
  345. * TEE_IOC_SHM_REGISTER - Register shared memory argument
  346. *
  347. * Registers shared memory between the user space process and secure OS.
  348. *
  349. * Returns a file descriptor on success or < 0 on failure
  350. *
  351. * The shared memory is unregisterred when the descriptor is closed.
  352. */
  353. #define TEE_IOC_SHM_REGISTER _IOWR(TEE_IOC_MAGIC, TEE_IOC_BASE + 9, \
  354. struct tee_ioctl_shm_register_data)
  355. /*
  356. * Five syscalls are used when communicating with the TEE driver.
  357. * open(): opens the device associated with the driver
  358. * ioctl(): as described above operating on the file descriptor from open()
  359. * close(): two cases
  360. * - closes the device file descriptor
  361. * - closes a file descriptor connected to allocated shared memory
  362. * mmap(): maps shared memory into user space using information from struct
  363. * tee_ioctl_shm_alloc_data
  364. * munmap(): unmaps previously shared memory
  365. */
  366. #endif /*__TEE_H*/