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