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