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