1 /* SPDX-License-Identifier: BSD-2-Clause */ 2 /* 3 * Copyright (c) 2014, STMicroelectronics International N.V. 4 */ 5 6 /* Based on GP TEE Internal API Specification Version 0.22 */ 7 #ifndef TEE_TA_API_H 8 #define TEE_TA_API_H 9 10 #include <tee_api_defines.h> 11 #include <tee_api_types.h> 12 13 /* This is a null define in STE TEE environment */ 14 #define TA_EXPORT 15 16 /* 17 * TA Interface 18 * 19 * Each Trusted Application must provide the Implementation with a number 20 * of functions, collectively called the “TA interface”. These functions 21 * are the entry points called by the Trusted Core Framework to create the 22 * instance, notify the instance that a new client is connecting, notify 23 * the instance when the client invokes a command, etc. 24 * 25 * Trusted Application Entry Points: 26 */ 27 28 /* 29 * The function TA_CreateEntryPoint is the Trusted Application's 30 * constructor, which the Framework calls when it creates a new instance of 31 * the Trusted Application. To register instance data, the implementation 32 * of this constructor can use either global variables or the function 33 * TEE_InstanceSetData. 34 * 35 * Return Value: 36 * - TEE_SUCCESS: if the instance is successfully created, the function 37 * must return TEE_SUCCESS. 38 * - Any other value: if any other code is returned the instance is not 39 * created, and no other entry points of this instance will be called. 40 * The Framework MUST reclaim all resources and dereference all objects 41 * related to the creation of the instance. 42 * 43 * If this entry point was called as a result of a client opening a 44 * session, the error code is returned to the client and the session is 45 * not opened. 46 */ 47 TEE_Result TA_EXPORT TA_CreateEntryPoint(void); 48 49 /* 50 * The function TA_DestroyEntryPoint is the Trusted Application‟s 51 * destructor, which the Framework calls when the instance is being 52 * destroyed. 53 * 54 * When the function TA_DestroyEntryPoint is called, the Framework 55 * guarantees that no client session is currently open. Once the call to 56 * TA_DestroyEntryPoint has been completed, no other entry point of this 57 * instance will ever be called. 58 * 59 * Note that when this function is called, all resources opened by the 60 * instance are still available. It is only after the function returns that 61 * the Implementation MUST start automatically reclaiming resources left 62 * opened. 63 * 64 * Return Value: 65 * This function can return no success or error code. After this function 66 * returns the Implementation MUST consider the instance destroyed and 67 * reclaims all resources left open by the instance. 68 */ 69 void TA_EXPORT TA_DestroyEntryPoint(void); 70 71 /* 72 * The Framework calls the function TA_OpenSessionEntryPoint when a client 73 * requests to open a session with the Trusted Application. The open 74 * session request may result in a new Trusted Application instance being 75 * created as defined in section 4.5. 76 * 77 * The client can specify parameters in an open operation which are passed 78 * to the Trusted Application instance in the arguments paramTypes and 79 * params. These arguments can also be used by the Trusted Application 80 * instance to transfer response data back to the client. See section 4.3.6 81 * for a specification of how to handle the operation parameters. 82 * 83 * If this function returns TEE_SUCCESS, the client is connected to a 84 * Trusted Application instance and can invoke Trusted Application 85 * commands. When the client disconnects, the Framework will eventually 86 * call the TA_CloseSessionEntryPoint entry point. 87 * 88 * If the function returns any error, the Framework rejects the connection 89 * and returns the error code and the current content of the parameters the 90 * client. The return origin is then set to TEE_ORIGIN_TRUSTED_APP. 91 * 92 * The Trusted Application instance can register a session data pointer by 93 * setting *psessionContext. The value of this pointer is not interpreted 94 * by the Framework, and is simply passed back to other TA_ functions 95 * within this session. Note that *sessionContext may be set with a pointer 96 * to a memory allocated by the Trusted Application instance or with 97 * anything else, like an integer, a handle etc. The Framework will not 98 * automatically free *sessionContext when the session is closed; the 99 * Trusted Application instance is responsible for freeing memory if 100 * required. 101 * 102 * During the call to TA_OpenSessionEntryPoint the client may request to 103 * cancel the operation. See section 4.10 for more details on 104 * cancellations. If the call to TA_OpenSessionEntryPoint returns 105 * TEE_SUCCESS, the client must consider the session as successfully opened 106 * and explicitly close it if necessary. 107 * 108 * Parameters: 109 * - paramTypes: the types of the four parameters. 110 * - params: a pointer to an array of four parameters. 111 * - sessionContext: A pointer to a variable that can be filled by the 112 * Trusted Application instance with an opaque void* data pointer 113 * 114 * Return Value: 115 * - TEE_SUCCESS if the session is successfully opened. 116 * - Any other value if the session could not be open. 117 * o The error code may be one of the pre-defined codes, or may be a new 118 * error code defined by the Trusted Application implementation itself. 119 */ 120 TEE_Result TA_EXPORT TA_OpenSessionEntryPoint(uint32_t paramTypes, 121 TEE_Param params[TEE_NUM_PARAMS], 122 void **sessionContext); 123 124 /* 125 * The Framework calls this function to close a client session. During the 126 * call to this function the implementation can use any session functions. 127 * 128 * The Trusted Application implementation is responsible for freeing any 129 * resources consumed by the session being closed. Note that the Trusted 130 * Application cannot refuse to close a session, but can hold the closing 131 * until it returns from TA_CloseSessionEntryPoint. This is why this 132 * function cannot return an error code. 133 * 134 * Parameters: 135 * - sessionContext: The value of the void* opaque data pointer set by the 136 * Trusted Application in the function TA_OpenSessionEntryPoint for this 137 * session. 138 */ 139 void TA_EXPORT TA_CloseSessionEntryPoint(void *sessionContext); 140 141 /* 142 * The Framework calls this function when the client invokes a command 143 * within the given session. 144 * 145 * The Trusted Application can access the parameters sent by the client 146 * through the paramTypes and params arguments. It can also use these 147 * arguments to transfer response data back to the client. 148 * 149 * During the call to TA_InvokeCommandEntryPoint the client may request to 150 * cancel the operation. 151 * 152 * A command is always invoked within the context of a client session. 153 * Thus, any session function can be called by the command implementation. 154 * 155 * Parameter: 156 * - sessionContext: The value of the void* opaque data pointer set by the 157 * Trusted Application in the function TA_OpenSessionEntryPoint. 158 * - commandID: A Trusted Application-specific code that identifies the 159 * command to be invoked. 160 * - paramTypes: the types of the four parameters. 161 * - params: a pointer to an array of four parameters. 162 * 163 * Return Value: 164 * - TEE_SUCCESS: if the command is successfully executed, the function 165 * must return this value. 166 * - Any other value: if the invocation of the command fails for any 167 * reason. 168 * o The error code may be one of the pre-defined codes, or may be a new 169 * error code defined by the Trusted Application implementation itself. 170 */ 171 172 TEE_Result TA_EXPORT TA_InvokeCommandEntryPoint(void *sessionContext, 173 uint32_t commandID, 174 uint32_t paramTypes, 175 TEE_Param params[TEE_NUM_PARAMS]); 176 177 /* 178 * Correspondance Client Functions <--> TA Functions 179 * 180 * TEE_OpenSession or TEE_OpenTASession: 181 * If a new Trusted Application instance is needed to handle the session, 182 * TA_CreateEntryPoint is called. 183 * Then, TA_OpenSessionEntryPoint is called. 184 * 185 * 186 * TEE_InvokeCommand or TEE_InvokeTACommand: 187 * TA_InvokeCommandEntryPoint is called. 188 * 189 * 190 * TEE_CloseSession or TEE_CloseTASession: 191 * TA_CloseSessionEntryPoint is called. 192 * For a multi-instance TA or for a single-instance, non keep-alive TA, if 193 * the session closed was the last session on the instance, then 194 * TA_DestroyEntryPoint is called. Otherwise, the instance is kept until 195 * the TEE shuts down. 196 * 197 */ 198 199 #endif 200