2 * Copyright (c) 2014, STMicroelectronics International N.V.
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
8 * 1. Redistributions of source code must retain the above copyright notice,
9 * this list of conditions and the following disclaimer.
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.
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.
27 #ifndef TEE_CLIENT_API_H
28 #define TEE_CLIENT_API_H
33 #endif /* __KERNEL__ */
36 * Defines the number of available memory references in an open session or
37 * invoke command operation payload.
39 #define TEEC_CONFIG_PAYLOAD_REF_COUNT 4
42 * Defines the maximum size of a single shared memory block, in bytes, of both
43 * API allocated and API registered memory. The size is currently set to
44 * 512 * kB (512 * 1024).
46 #define TEEC_CONFIG_SHAREDMEM_MAX_SIZE 0x8000
49 * Flag constants indicating the type of parameters encoded inside the
50 * operation payload (TEEC_Operation), Type is uint32_t.
52 * TEEC_NONE The Parameter is not used
54 * TEEC_VALUE_INPUT The Parameter is a TEEC_Value tagged as input.
56 * TEEC_VALUE_OUTPUT The Parameter is a TEEC_Value tagged as output.
58 * TEEC_VALUE_INOUT The Parameter is a TEEC_Value tagged as both as
59 * input and output, i.e., for which both the
60 * behaviors of TEEC_VALUE_INPUT and
61 * TEEC_VALUE_OUTPUT apply.
63 * TEEC_MEMREF_TEMP_INPUT The Parameter is a TEEC_TempMemoryReference
64 * describing a region of memory which needs to be
65 * temporarily registered for the duration of the
66 * Operation and is tagged as input.
68 * TEEC_MEMREF_TEMP_OUTPUT Same as TEEC_MEMREF_TEMP_INPUT, but the Memory
69 * Reference is tagged as output. The
70 * Implementation may update the size field to
71 * reflect the required output size in some use
74 * TEEC_MEMREF_TEMP_INOUT A Temporary Memory Reference tagged as both
75 * input and output, i.e., for which both the
76 * behaviors of TEEC_MEMREF_TEMP_INPUT and
77 * TEEC_MEMREF_TEMP_OUTPUT apply.
79 * TEEC_MEMREF_WHOLE The Parameter is a Registered Memory Reference
80 * that refers to the entirety of its parent Shared
81 * Memory block. The parameter structure is a
82 * TEEC_MemoryReference. In this structure, the
83 * Implementation MUST read only the parent field
84 * and MAY update the size field when the operation
87 * TEEC_MEMREF_PARTIAL_INPUT A Registered Memory Reference structure that
88 * refers to a partial region of its parent Shared
89 * Memory block and is tagged as input.
91 * TEEC_MEMREF_PARTIAL_OUTPUT Registered Memory Reference structure that
92 * refers to a partial region of its parent Shared
93 * Memory block and is tagged as output.
95 * TEEC_MEMREF_PARTIAL_INOUT The Registered Memory Reference structure that
96 * refers to a partial region of its parent Shared
97 * Memory block and is tagged as both input and
98 * output, i.e., for which both the behaviors of
99 * TEEC_MEMREF_PARTIAL_INPUT and
100 * TEEC_MEMREF_PARTIAL_OUTPUT apply.
102 #define TEEC_NONE 0x00000000
103 #define TEEC_VALUE_INPUT 0x00000001
104 #define TEEC_VALUE_OUTPUT 0x00000002
105 #define TEEC_VALUE_INOUT 0x00000003
106 #define TEEC_MEMREF_TEMP_INPUT 0x00000005
107 #define TEEC_MEMREF_TEMP_OUTPUT 0x00000006
108 #define TEEC_MEMREF_TEMP_INOUT 0x00000007
109 #define TEEC_MEMREF_WHOLE 0x0000000C
110 #define TEEC_MEMREF_PARTIAL_INPUT 0x0000000D
111 #define TEEC_MEMREF_PARTIAL_OUTPUT 0x0000000E
112 #define TEEC_MEMREF_PARTIAL_INOUT 0x0000000F
115 * Flag constants indicating the data transfer direction of memory in
116 * TEEC_Parameter. TEEC_MEM_INPUT signifies data transfer direction from the
117 * client application to the TEE. TEEC_MEM_OUTPUT signifies data transfer
118 * direction from the TEE to the client application. Type is uint32_t.
120 * TEEC_MEM_INPUT The Shared Memory can carry data from the client
121 * application to the Trusted Application.
122 * TEEC_MEM_OUTPUT The Shared Memory can carry data from the Trusted
123 * Application to the client application.
124 * TEEC_MEM_DMABUF The Shared Memory is allocated with the dma buf api and
125 * not necessarly user mapped.
126 * Handle of the memory pass to drivers is the implementation
127 * fd field instead of the buffer field.
128 * TEEC_MEM_KAPI Shared memory is required from another linux module.
129 * Dma buf file descriptor is not created.
131 #define TEEC_MEM_INPUT 0x00000001
132 #define TEEC_MEM_OUTPUT 0x00000002
133 #define TEEC_MEM_DMABUF 0x00010000
134 #define TEEC_MEM_KAPI 0x00020000
137 * Return values. Type is TEEC_Result
139 * TEEC_SUCCESS The operation was successful.
140 * TEEC_ERROR_GENERIC Non-specific cause.
141 * TEEC_ERROR_ACCESS_DENIED Access privileges are not sufficient.
142 * TEEC_ERROR_CANCEL The operation was canceled.
143 * TEEC_ERROR_ACCESS_CONFLICT Concurrent accesses caused conflict.
144 * TEEC_ERROR_EXCESS_DATA Too much data for the requested operation was
146 * TEEC_ERROR_BAD_FORMAT Input data was of invalid format.
147 * TEEC_ERROR_BAD_PARAMETERS Input parameters were invalid.
148 * TEEC_ERROR_BAD_STATE Operation is not valid in the current state.
149 * TEEC_ERROR_ITEM_NOT_FOUND The requested data item is not found.
150 * TEEC_ERROR_NOT_IMPLEMENTED The requested operation should exist but is not
152 * TEEC_ERROR_NOT_SUPPORTED The requested operation is valid but is not
153 * supported in this implementation.
154 * TEEC_ERROR_NO_DATA Expected data was missing.
155 * TEEC_ERROR_OUT_OF_MEMORY System ran out of resources.
156 * TEEC_ERROR_BUSY The system is busy working on something else.
157 * TEEC_ERROR_COMMUNICATION Communication with a remote party failed.
158 * TEEC_ERROR_SECURITY A security fault was detected.
159 * TEEC_ERROR_SHORT_BUFFER The supplied buffer is too short for the
161 * TEEC_ERROR_TARGET_DEAD Trusted Application has panicked
162 * during the operation.
166 * Standard defined error codes.
168 #define TEEC_SUCCESS 0x00000000
169 #define TEEC_ERROR_GENERIC 0xFFFF0000
170 #define TEEC_ERROR_ACCESS_DENIED 0xFFFF0001
171 #define TEEC_ERROR_CANCEL 0xFFFF0002
172 #define TEEC_ERROR_ACCESS_CONFLICT 0xFFFF0003
173 #define TEEC_ERROR_EXCESS_DATA 0xFFFF0004
174 #define TEEC_ERROR_BAD_FORMAT 0xFFFF0005
175 #define TEEC_ERROR_BAD_PARAMETERS 0xFFFF0006
176 #define TEEC_ERROR_BAD_STATE 0xFFFF0007
177 #define TEEC_ERROR_ITEM_NOT_FOUND 0xFFFF0008
178 #define TEEC_ERROR_NOT_IMPLEMENTED 0xFFFF0009
179 #define TEEC_ERROR_NOT_SUPPORTED 0xFFFF000A
180 #define TEEC_ERROR_NO_DATA 0xFFFF000B
181 #define TEEC_ERROR_OUT_OF_MEMORY 0xFFFF000C
182 #define TEEC_ERROR_BUSY 0xFFFF000D
183 #define TEEC_ERROR_COMMUNICATION 0xFFFF000E
184 #define TEEC_ERROR_SECURITY 0xFFFF000F
185 #define TEEC_ERROR_SHORT_BUFFER 0xFFFF0010
186 #define TEEC_ERROR_TARGET_DEAD 0xFFFF3024
189 * Function error origins, of type TEEC_ErrorOrigin. These indicate where in
190 * the software stack a particular return value originates from.
192 * TEEC_ORIGIN_API The error originated within the TEE Client API
194 * TEEC_ORIGIN_COMMS The error originated within the underlying
195 * communications stack linking the rich OS with
197 * TEEC_ORIGIN_TEE The error originated within the common TEE code.
198 * TEEC_ORIGIN_TRUSTED_APP The error originated within the Trusted Application
201 #define TEEC_ORIGIN_API 0x00000001
202 #define TEEC_ORIGIN_COMMS 0x00000002
203 #define TEEC_ORIGIN_TEE 0x00000003
204 #define TEEC_ORIGIN_TRUSTED_APP 0x00000004
207 * Session login methods, for use in TEEC_OpenSession() as parameter
208 * connectionMethod. Type is uint32_t.
210 * TEEC_LOGIN_PUBLIC No login data is provided.
211 * TEEC_LOGIN_USER Login data about the user running the Client
212 * Application process is provided.
213 * TEEC_LOGIN_GROUP Login data about the group running the Client
214 * Application process is provided.
215 * TEEC_LOGIN_APPLICATION Login data about the running Client Application
216 * itself is provided.
218 #define TEEC_LOGIN_PUBLIC 0x00000000
219 #define TEEC_LOGIN_USER 0x00000001
220 #define TEEC_LOGIN_GROUP 0x00000002
221 #define TEEC_LOGIN_APPLICATION 0x00000004
224 * Encode the paramTypes according to the supplied types.
226 * @param p0 The first param type.
227 * @param p1 The second param type.
228 * @param p2 The third param type.
229 * @param p3 The fourth param type.
231 #define TEEC_PARAM_TYPES(p0, p1, p2, p3) \
232 ((p0) | ((p1) << 4) | ((p2) << 8) | ((p3) << 12))
235 * Get the i_th param type from the paramType.
237 * @param p The paramType.
238 * @param i The i-th parameter to get the type for.
240 #define TEEC_PARAM_TYPE_GET(p, i) (((p) >> (i * 4)) & 0xF)
242 typedef uint32_t TEEC_Result;
245 * struct TEEC_Context - Represents a connection between a client application
248 * Context identifier can be a handle (when opened from user land)
249 * or a structure pointer (when opened from kernel land).
250 * Identifier is defined as an union to match type sizes on all architectures.
255 struct tee_context *ctx;
261 * This type contains a Universally Unique Resource Identifier (UUID) type as
262 * defined in RFC4122. These UUID values are used to identify Trusted
268 uint16_t timeHiAndVersion;
269 uint8_t clockSeqAndNode[8];
273 * struct TEEC_SharedMemory - Memory to transfer data between a client
274 * application and trusted code.
276 * @param buffer The memory buffer which is to be, or has been, shared
278 * @param size The size, in bytes, of the memory buffer.
279 * @param flags Bit-vector which holds properties of buffer.
280 * The bit-vector can contain either or both of the
281 * TEEC_MEM_INPUT and TEEC_MEM_OUTPUT flags.
283 * A shared memory block is a region of memory allocated in the context of the
284 * client application memory space that can be used to transfer data between
285 * that client application and a trusted application. The user of this struct
286 * is responsible to populate the buffer pointer.
293 * identifier can store a handle (int) or a structure pointer (void *).
294 * define this union to match case where sizeof(int)!=sizeof(void *).
304 * struct TEEC_TempMemoryReference - Temporary memory to transfer data between
305 * a client application and trusted code, only used for the duration of the
308 * @param buffer The memory buffer which is to be, or has been shared with
310 * @param size The size, in bytes, of the memory buffer.
312 * A memory buffer that is registered temporarily for the duration of the
313 * operation to be called.
318 } TEEC_TempMemoryReference;
321 * struct TEEC_RegisteredMemoryReference - use a pre-registered or
322 * pre-allocated shared memory block of memory to transfer data between
323 * a client application and trusted code.
325 * @param parent Points to a shared memory structure. The memory reference
326 * may utilize the whole shared memory or only a part of it.
329 * @param size The size, in bytes, of the memory buffer.
331 * @param offset The offset, in bytes, of the referenced memory region from
332 * the start of the shared memory block.
336 TEEC_SharedMemory *parent;
339 } TEEC_RegisteredMemoryReference;
342 * struct TEEC_Value - Small raw data container
344 * Instead of allocating a shared memory buffer this structure can be used
345 * to pass small raw data between a client application and trusted code.
347 * @param a The first integer value.
349 * @param b The second second value.
357 * union TEEC_Parameter - Memory container to be used when passing data between
358 * client application and trusted code.
360 * Either the client uses a shared memory reference, parts of it or a small raw
363 * @param tmpref A temporary memory reference only valid for the duration
366 * @param memref The entire shared memory or parts of it.
368 * @param value The small raw data container to use
371 TEEC_TempMemoryReference tmpref;
372 TEEC_RegisteredMemoryReference memref;
377 * struct TEEC_Session - Represents a connection between a client application
378 * and a trusted application.
385 * struct TEEC_Operation - Holds information and memory references used in
386 * TEEC_InvokeCommand().
388 * @param started Client must initialize to zero if it needs to cancel
389 * an operation about to be performed.
390 * @param paramTypes Type of data passed. Use TEEC_PARAMS_TYPE macro to
391 * create the correct flags.
392 * 0 means TEEC_NONE is passed for all params.
393 * @param params Array of parameters of type TEEC_Parameter.
394 * @param session Internal pointer to the last session used by
395 * TEEC_InvokeCommand with this operation.
401 TEEC_Parameter params[TEEC_CONFIG_PAYLOAD_REF_COUNT];
402 /* Implementation-Defined */
403 TEEC_Session *session;
404 TEEC_SharedMemory memRefs[TEEC_CONFIG_PAYLOAD_REF_COUNT];
409 * TEEC_InitializeContext() - Initializes a context holding connection
410 * information on the specific TEE, designated by the name string.
412 * @param name A zero-terminated string identifying the TEE to connect to.
413 * If name is set to NULL, the default TEE is connected to. NULL
414 * is the only supported value in this version of the API
417 * @param context The context structure which is to be initialized.
419 * @return TEEC_SUCCESS The initialization was successful.
420 * @return TEEC_Result Something failed.
422 TEEC_Result TEEC_InitializeContext(const char *name, TEEC_Context *context);
425 * TEEC_FinalizeContext() - Destroys a context holding connection information
426 * on the specific TEE.
428 * This function destroys an initialized TEE context, closing the connection
429 * between the client application and the TEE. This function must only be
430 * called when all sessions related to this TEE context have been closed and
431 * all shared memory blocks have been released.
433 * @param context The context to be destroyed.
435 void TEEC_FinalizeContext(TEEC_Context *context);
438 * TEEC_OpenSession() - Opens a new session with the specified trusted
441 * @param context The initialized TEE context structure in which
442 * scope to open the session.
443 * @param session The session to initialize.
444 * @param destination A structure identifying the trusted application
445 * with which to open a session.
447 * @param connectionMethod The connection method to use.
448 * @param connectionData Any data necessary to connect with the chosen
449 * connection method. Not supported, should be set to
451 * @param operation An operation structure to use in the session. May
452 * be set to NULL to signify no operation structure
455 * @param returnOrigin A parameter which will hold the error origin if
456 * this function returns any value other than
459 * @return TEEC_SUCCESS OpenSession successfully opened a new session.
460 * @return TEEC_Result Something failed.
463 TEEC_Result TEEC_OpenSession(TEEC_Context *context,
464 TEEC_Session *session,
465 const TEEC_UUID *destination,
466 uint32_t connectionMethod,
467 const void *connectionData,
468 TEEC_Operation *operation,
469 uint32_t *returnOrigin);
472 * TEEC_CloseSession() - Closes the session which has been opened with the
473 * specific trusted application.
475 * @param session The opened session to close.
477 void TEEC_CloseSession(TEEC_Session *session);
480 * TEEC_InvokeCommand() - Executes a command in the specified trusted
483 * @param session A handle to an open connection to the trusted
485 * @param commandID Identifier of the command in the trusted application
487 * @param operation An operation structure to use in the invoke command.
488 * May be set to NULL to signify no operation structure
490 * @param returnOrigin A parameter which will hold the error origin if this
491 * function returns any value other than TEEC_SUCCESS.
493 * @return TEEC_SUCCESS OpenSession successfully opened a new session.
494 * @return TEEC_Result Something failed.
496 TEEC_Result TEEC_InvokeCommand(TEEC_Session *session,
498 TEEC_Operation *operation,
499 uint32_t *returnOrigin);
502 * TEEC_RegisterSharedMemory() - Register a block of existing memory as a
503 * shared block within the scope of the specified context.
505 * @param context The initialized TEE context structure in which scope to
507 * @param sharedMem pointer to the shared memory structure to register.
509 * @return TEEC_SUCCESS The registration was successful.
510 * @return TEEC_ERROR_OUT_OF_MEMORY Memory exhaustion.
511 * @return TEEC_Result Something failed.
513 TEEC_Result TEEC_RegisterSharedMemory(TEEC_Context *context,
514 TEEC_SharedMemory *sharedMem);
517 * TEEC_AllocateSharedMemory() - Allocate shared memory for TEE.
519 * @param context The initialized TEE context structure in which scope to
521 * @param sharedMem Pointer to the allocated shared memory.
523 * @return TEEC_SUCCESS The registration was successful.
524 * @return TEEC_ERROR_OUT_OF_MEMORY Memory exhaustion.
525 * @return TEEC_Result Something failed.
527 TEEC_Result TEEC_AllocateSharedMemory(TEEC_Context *context,
528 TEEC_SharedMemory *sharedMem);
531 * TEEC_ReleaseSharedMemory() - Free or deregister the shared memory.
533 * @param sharedMem Pointer to the shared memory to be freed.
535 void TEEC_ReleaseSharedMemory(TEEC_SharedMemory *sharedMemory);
538 * TEEC_RequestCancellation() - Request the cancellation of a pending open
539 * session or command invocation.
541 * @param operation Pointer to an operation previously passed to open session
544 void TEEC_RequestCancellation(TEEC_Operation *operation);
547 * Register a pre-allocated Trusted Application This is mainly intended for
548 * OS-FREE contexts or when a filesystem is not available.
550 * @param ta Pointer to the trusted application binary
551 * @param size The size of the TA binary
553 * @return TEEC_SUCCESS if successful.
554 * @return TEEC_Result something failed.
556 TEEC_Result TEEC_RegisterTA(const void *ta, const size_t size);
559 * Unregister a pre-allocated Trusted Application This is mainly intended for
560 * OS-FREE contexts or when a filesystem is not available.
562 * @param ta Pointer to the trusted application binary
564 void TEEC_UnregisterTA(const void *ta);