1 // Copyright 2018 The Fuchsia Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #pragma once 6 7 #include <stddef.h> 8 #include <stdint.h> 9 10 #include <zircon/compiler.h> 11 12 #include <tee-client-api/tee-client-impl.h> 13 14 __BEGIN_CDECLS 15 16 /* 17 * Global Platform TEE Client API 18 * 19 * https://globalplatform.org/specs-library/tee-client-api-specification/ 20 * 21 * This header contains Fuchsia's implementation of the constants and data structures that are 22 * defined by the Global Platform TEE Client API V1.0_c and its associated Errata (V2.0). 23 */ 24 25 /************* 26 * Constants * 27 *************/ 28 29 /* Configuration Settings 30 * 31 * Shared Memory Maximum Size 32 * The maximum size of a single Shared Memory block, in bytes, of both API allocated and API 33 * registered memory. This version of the standard requires that this maximum size is greater 34 * than or equal to 512kB. In systems where there is no limit imposed by the Implementation 35 * then this definition should be defined to be the size of the address space. 36 */ 37 #define TEEC_CONFIG_SHAREDMEM_MAX_SIZE UINT64_MAX 38 39 /* Return Codes 40 * 41 * TEEC_SUCCESS The operation was successful. 42 * TEEC_ERROR_GENERIC Non-specific cause. 43 * TEEC_ERROR_ACCESS_DENIED Access privileges are not sufficient. 44 * TEEC_ERROR_CANCEL The operation was cancelled. 45 * TEEC_ERROR_ACCESS_CONFLICT Concurrent accesses caused conflict. 46 * TEEC_ERROR_EXCESS_DATA Too much data for the requested operation was passed. 47 * TEEC_ERROR_BAD_FORMAT Input data was of invalid format. 48 * TEEC_ERROR_BAD_PARAMETERS Input parameters were invalid. 49 * TEEC_ERROR_BAD_STATE Operation is not valid in the current state. 50 * TEEC_ERROR_ITEM_NOT_FOUND The requested data item is not found. 51 * TEEC_ERROR_NOT_IMPLEMENTED The requested operation should exist but is not yet implemented. 52 * TEEC_ERROR_NOT_SUPPORTED The requested operation is valid but is not supported in this 53 * Implementation. 54 * TEEC_ERROR_NO_DATA Expected data was missing. 55 * TEEC_ERROR_OUT_OF_MEMORY System ran out of resources. 56 * TEEC_ERROR_BUSY The system is busy working on something else. 57 * TEEC_ERROR_COMMUNICATION Communication with a remote party failed. 58 * TEEC_ERROR_SECURITY A security fault was detected. 59 * TEEC_ERROR_SHORT_BUFFER The supplied buffer is too short for the generated output. 60 * TEE_ERROR_EXTERNAL_CANCEL An external event has caused a User Interface operation to be 61 * aborted. 62 * TEE_ERROR_OVERFLOW Internal TEE error. 63 * TEE_ERROR_TARGET_DEAD The Trusted Application has terminated. 64 * TEEC_ERROR_TARGET_DEAD The Trusted Application has terminated. 65 * TEE_ERROR_STORAGE_NO_SPACE Internal TEE error. 66 */ 67 #define TEEC_SUCCESS 0x00000000 68 #define TEEC_ERROR_GENERIC 0xFFFF0000 69 #define TEEC_ERROR_ACCESS_DENIED 0xFFFF0001 70 #define TEEC_ERROR_CANCEL 0xFFFF0002 71 #define TEEC_ERROR_ACCESS_CONFLICT 0xFFFF0003 72 #define TEEC_ERROR_EXCESS_DATA 0xFFFF0004 73 #define TEEC_ERROR_BAD_FORMAT 0xFFFF0005 74 #define TEEC_ERROR_BAD_PARAMETERS 0xFFFF0006 75 #define TEEC_ERROR_BAD_STATE 0xFFFF0007 76 #define TEEC_ERROR_ITEM_NOT_FOUND 0xFFFF0008 77 #define TEEC_ERROR_NOT_IMPLEMENTED 0xFFFF0009 78 #define TEEC_ERROR_NOT_SUPPORTED 0xFFFF000A 79 #define TEEC_ERROR_NO_DATA 0xFFFF000B 80 #define TEEC_ERROR_OUT_OF_MEMORY 0xFFFF000C 81 #define TEEC_ERROR_BUSY 0xFFFF000D 82 #define TEEC_ERROR_COMMUNICATION 0xFFFF000E 83 #define TEEC_ERROR_SECURITY 0xFFFF000F 84 #define TEEC_ERROR_SHORT_BUFFER 0xFFFF0010 85 #define TEE_ERROR_EXTERNAL_CANCEL 0xFFFF0011 86 #define TEE_ERROR_OVERFLOW 0xFFFF300F 87 #define TEE_ERROR_TARGET_DEAD 0xFFFF3024 88 #define TEEC_ERROR_TARGET_DEAD 0xFFFF3024 89 #define TEE_ERROR_STORAGE_NO_SPACE 0xFFFF3041 90 91 /* Return Code Origins 92 * 93 * These indicate where in the software stack the return code was generated for an open session 94 * operation or an invoke-command operation. 95 * 96 * TEEC_ORIGIN_API The return code is an error that originated within the TEE Client API 97 * implementation. 98 * TEEC_ORIGIN_COMMS The return code is an error that originated within the underlying 99 * communications stack linking the rich OS with the TEE. 100 * TEEC_ORIGIN_TEE The return code is an error that originated within the common TEE code. 101 * TEEC_ORIGIN_TRUSTED_APP The return code originated within the Trusted Application code. This 102 * includes the case where the return code is a success. 103 */ 104 #define TEEC_ORIGIN_API 0x00000001 105 #define TEEC_ORIGIN_COMMS 0x00000002 106 #define TEEC_ORIGIN_TEE 0x00000003 107 #define TEEC_ORIGIN_TRUSTED_APP 0x00000004 108 109 /* Shared Memory Control - TEEC_MEM_* 110 * 111 * These are used to indicate the current status and synchronization requirements of Shared Memory 112 * blocks. 113 * 114 * TEEC_MEM_INPUT The Shared Memory can carry data from the Client Application to the Trusted 115 * Application. 116 * TEEC_MEM_OUTPUT The Shared Memory can carry data from the Trusted Application to the Client 117 * Application. 118 */ 119 #define TEEC_MEM_INPUT 0x00000001 120 #define TEEC_MEM_OUTPUT 0x00000002 121 122 /* Shared Memory Control - TEEC_VALUE_* 123 * 124 * These are used to indicate the type of Parameter encoded inside the operation structure. 125 * 126 * TEEC_NONE The Parameter is not used. 127 * TEEC_VALUE_INPUT The Parameter is a TEEC_Value tagged as input. 128 * TEEC_VALUE_OUTPUT The Parameter is a TEEC_Value tagged as output. 129 * TEEC_VALUE_INOUT The Parameter is a TEEC_Value tagged as both as input and output, 130 * i.e., for which both the behaviors of TEEC_VALUE_INPUT and 131 * TEEC_VALUE_OUTPUT apply. 132 * TEEC_MEMREF_TEMP_INPUT The Parameter is a TEEC_TemporaryMemoryReference describing a region 133 * of memory which needs to be temporarily registered for the duration 134 * of the Operation and is tagged as input. 135 * TEEC_MEMREF_TEMP_OUTPUT Same as TEEC_MEMREF_TEMP_INPUT, but the Memory Reference is tagged 136 * as output. The Implementation may update the size field to reflect 137 * the required output size in some use cases. 138 * TEEC_MEMREF_TEMP_INOUT A Temporary Memory Reference tagged as both input and output, i.e., 139 * for which both the behaviors of TEEC_MEMREF_TEMP_INPUT and 140 * TEEC_MEMREF_TEMP_OUTPUT apply. 141 * TEEC_MEMREF_WHOLE The Parameter is a Registered Memory Reference that refers to the 142 * entirety of its parent Shared Memory block. The parameter structure 143 * is a TEEC_RegisteredMemoryReference. In this structure, the 144 * Implemetnation must read only the parent field and may update the 145 * size field when the operation completes. 146 * TEEC_MEMREF_PARTIAL_INPUT A Registered Memory Reference structure that refers to a partial 147 * region of its parent Shared Memory block and is tagged as input. 148 * TEEC_MEMREF_PARTIAL_OUTPUT A Registered Memory Reference structure that refers to a partial 149 * region of its parent Shared Memory block and is tagged as output. 150 * TEEC_MEMREF_PARTIAL_INOUT The Registered Memory Reference structure that refers to a partial 151 * region of its parent Shared Memory block and is tagged as both 152 * input and output, i.e., for which both the behaviors of 153 * TEEC_MEMREF_PARTIAL_INPUT and TEEC_MEMREF_PARTIAL_OUTPUT apply. 154 */ 155 #define TEEC_NONE 0x00000000 156 #define TEEC_VALUE_INPUT 0x00000001 157 #define TEEC_VALUE_OUTPUT 0x00000002 158 #define TEEC_VALUE_INOUT 0x00000003 159 #define TEEC_MEMREF_TEMP_INPUT 0x00000005 160 #define TEEC_MEMREF_TEMP_OUTPUT 0x00000006 161 #define TEEC_MEMREF_TEMP_INOUT 0x00000007 162 #define TEEC_MEMREF_WHOLE 0x0000000C 163 #define TEEC_MEMREF_PARTIAL_INPUT 0x0000000D 164 #define TEEC_MEMREF_PARTIAL_OUTPUT 0x0000000E 165 #define TEEC_MEMREF_PARTIAL_INOUT 0x0000000F 166 167 /* Session Login Methods 168 * 169 * These are used to indicate what identity credentials about the Client Application are used by 170 * the Implementation to determine access control permissions to functionality provided by, or data 171 * stored by, the Trusted Application. 172 * 173 * Login types are designed to be orthogonal from reach other, in accordance with the identity 174 * token(s) defined for each constant. For example, the credentials generated for 175 * TEEC_LOGIN_APPLICATION must only depend on the identity of the application program, and not the 176 * user running it. If two users use the same program, the Implementation must assign the same 177 * login identity to both users so that they can access the same assets held inside the TEE. These 178 * identity tokens must also be persistent within one Implementation, across multiple invocations of 179 * the application and across power cycles, enabling them to be used to disambiguate persistent 180 * storage. Note that this specification does not guarantee separation based on use of different 181 * login types - in many embedded platforms there is no notion of "group" or "user" so these login 182 * types may fall back to TEEC_LOGIN_PUBLIC - these details of generating the credential for each 183 * login type are implementation-defined. 184 * 185 * TEEC_LOGIN_PUBLIC No login data is provided. 186 * TEEC_LOGIN_USER Login data about the user running the Client Application process is 187 * provided. 188 * TEEC_LOGIN_GROUP Login data about the group running the Client Application process is 189 * provided. 190 * TEEC_LOGIN_APPLICATION Login data about the running Client Application itself is provided. 191 * TEEC_LOGIN_USER_APPLICATION Login data about the user running the Client Application and about 192 * the Client Application itself is provided. 193 * TEEC_LOGIN_GROUP_APPLICATION Login data about the group running the Client Application and about 194 * the Client Application itself is provided. 195 */ 196 #define TEEC_LOGIN_PUBLIC 0x00000000 197 #define TEEC_LOGIN_USER 0x00000001 198 #define TEEC_LOGIN_GROUP 0x00000002 199 #define TEEC_LOGIN_APPLICATION 0x00000004 200 #define TEEC_LOGIN_USER_APPLICATION 0x00000005 201 #define TEEC_LOGIN_GROUP_APPLICATION 0x00000006 202 203 /********** 204 * Macros * 205 **********/ 206 207 /* TEEC_PARAM_TYPES 208 * 209 * This function-like macro builds a constant containing four Parameter types for use in the 210 * paramTypes field of a TEEC_Operation structure. 211 */ 212 #define TEEC_PARAM_TYPES(param0Type, param1Type, param2Type, param3Type) \ 213 (((param0Type & 0xF) << 0) | ((param1Type & 0xF) << 4) | \ 214 ((param2Type & 0xF) << 8) | ((param3Type & 0xF) << 12)) 215 216 /************** 217 * Data Types * 218 **************/ 219 220 // TODO(godtamit): may want to mark structs as packed or aligned in some manner 221 222 /* TEEC_Result 223 * 224 * This type is used to contain return codes which are the results of invoking TEE Client API 225 * functions. 226 */ 227 typedef uint32_t TEEC_Result; 228 229 /* TEEC_UUID 230 * 231 * This type contains a Universally Unique Resource Identifier (UUID) type as defined in RFC4122. 232 * These UUID values are used to identify Trusted Applications. 233 */ 234 typedef struct { 235 uint32_t timeLow; 236 uint16_t timeMid; 237 uint16_t timeHiAndVersion; 238 uint8_t clockSeqAndNode[8]; 239 } TEEC_UUID; 240 241 /* TEEC_Context 242 * 243 * This type denotes a TEE Context, the main logical container linking a Client Application with a 244 * particular TEE. Its content is entirely implementation-defined. 245 */ 246 typedef struct { 247 teec_context_impl_t imp; 248 } TEEC_Context; 249 250 /* TEEC_Session 251 * 252 * This type denotes a TEE Session, the logical container linking a Client Application with a 253 * particular Trusted Application. Its content is entirely implementation-defined. 254 */ 255 typedef struct { 256 teec_session_impl_t imp; 257 } TEEC_Session; 258 259 /* TEEC_SharedMemory 260 * 261 * This type denotes a Shared Memory block which has either been registered with the Implementation 262 * or allocated by it. 263 * 264 * Fields: 265 * buffer A pointer to the memory buffer shared with the TEE. 266 * 267 * size The size of the memory buffer, in bytes. 268 * 269 * flags A bit-vector which can contain the following flags: 270 * TEEC_MEM_INPUT: The memory can be used to transfer data from the Client Application 271 * to the TEE. 272 * TEEC_MEM_OUTPUT: The memory can be used to transfer data from the TEE to the Client 273 * Application. 274 * All other bits in this field should be set to zero, and are reserved for future use. 275 * 276 * imp Contains any additional implementation-defined data attached to the Shared Memory 277 * structure. 278 */ 279 typedef struct { 280 void* buffer; 281 size_t size; 282 uint32_t flags; 283 teec_shared_memory_impl_t imp; 284 } TEEC_SharedMemory; 285 286 /* TEEC_TempMemoryReference 287 * 288 * This type defines a Temporary Memory Reference. It is used as a TEEC_Operation parameter when 289 * the corresponding parameter type is one of TEEC_MEMREF_TEMP_INPUT, TEEC_MEMREF_TEMP_OUTPUT, or 290 * TEEC_MEMREF_TEMP_INOUT. 291 * 292 * Fields: 293 * buffer A pointer to the first byte of a region of memory which needs to be temporarily 294 * registered for the duration of the Operation. This field can be NULL to specify a null 295 * Memory Reference. 296 * 297 * size The size of the referenced memory region, in bytes. 298 */ 299 typedef struct { 300 void* buffer; 301 size_t size; 302 } TEEC_TempMemoryReference; 303 304 /* TEEC_RegisteredMemoryReference 305 * 306 * This type defines a Registered Memory Reference, i.e., that uses a pre-registered or 307 * pre-allocated Shared Memory block. It is used as a TEEC_Operation parameter when the 308 * corresponding parameter type is one of TEEC_MEMREF_WHOLE, TEEC_MEMREF_PARTIAL_INPUT, 309 * TEEC_MEMREF_PARTIAL_OUTPUT, or TEEC_MEMREF_PARTIAL_INOUT. 310 * 311 * Fields: 312 * parent A pointer to a TEEC_SharedMemory structure. The memory reference refers either to the 313 * whole Shared Memory or to a partial region within the Shared Memory block, depending on 314 * the parameter type. The data flow direction of the memory reference must be consistent 315 * with the flags defined in the parent Shared Memory Block. Note that the parent field 316 * must not be NULL. To encode a null Memory Reference, the Client Application must use a 317 * Temporary Memory Reference with the buffer field set to NULL. 318 * 319 * size The size of the referenced memory region, in bytes. 320 * 321 * offset The offset, in bytes, of the referenced memory region from the start of the Shared 322 * Memory block. 323 */ 324 typedef struct { 325 TEEC_SharedMemory* parent; 326 size_t size; 327 size_t offset; 328 } TEEC_RegisteredMemoryReference; 329 330 /* TEEC_Value 331 * 332 * This type defines a parameter that is not referencing shared memory, but carries instead small 333 * raw data passed by value. It is used as a TEEC_Operation parameter when the corresponding 334 * parameter type is one of TEEC_VALUE_INPUT, TEEC_VALUE_OUTPUT, or TEEC_VALUE_INOUT. 335 * 336 * The two fields of this structure do not have a particular meaning. It is up to the protocol 337 * between the Client Application and the Trusted Application to assign a semantic to those two 338 * integers. 339 */ 340 typedef struct { 341 uint32_t a; 342 uint32_t b; 343 } TEEC_Value; 344 345 /* TEEC_Parameter 346 * 347 * This type defines a Parameter of a TEEC_Operation. It can be a Temporary Memory Reference, a 348 * Registered Memory Reference or a Value Parameter. The field to select in this union depends on 349 * the type of the parameter specified in the paramTypes field of the TEEC_Operation structure. 350 */ 351 typedef union { 352 TEEC_TempMemoryReference tmpref; 353 TEEC_RegisteredMemoryReference memref; 354 TEEC_Value value; 355 } TEEC_Parameter; 356 357 /* TEEC_Operation 358 * 359 * This type defines the payload of either an open Session operation or an invoke Command operation. 360 * It is also used for cancellation of operations, which may be desirable even if no payload is 361 * passed. 362 * 363 * Fields: 364 * started A field which must be initialized to zero by the Client Application before each use 365 * in an operation if the Client Application may need to cancel the operation about to 366 * be performed. 367 * 368 * paramTypes Encodes the type of each of the Parameters in the operation. The layout of these 369 * types within a 32-bit integer is implementation-defined and the Client Application 370 * must use the macro TEEC_PARAM_TYPES to construct a constant value for this field. As 371 * a special case, if the Client Application sets paramTypes to 0, then the 372 * Implementation must interpret it as a meaning that the type of each Parameter is set 373 * to TEEC_NONE. 374 * 375 * params An array of four parameters. For each parameter, one of the memref, tmpref or value 376 * fields must be used depending on the corresponding parameter type passed in 377 * paramTypes as described in the specification of TEEC_Parameter. 378 * 379 * imp Contains any additional implementation-defined data attached to the operation 380 * structure. 381 */ 382 typedef struct { 383 uint32_t started; 384 uint32_t paramTypes; 385 TEEC_Parameter params[TEEC_NUM_PARAMS_MAX]; 386 teec_operation_impl_t imp; 387 } TEEC_Operation; 388 389 __END_CDECLS 390