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