1 /* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef TEE_CLIENT_API_H 17 #define TEE_CLIENT_API_H 18 /** 19 * @addtogroup TeeClient 20 * @{ 21 * 22 * @brief Provides APIs for the client applications (CAs) in the Rich Execution Environment (normal mode) to 23 * access the trusted applications (TAs) in a Trusted Execution Environment (TEE). 24 * 25 * @since 12 26 * @version 1.0 27 */ 28 29 /** 30 * @file tee_client_api.h 31 * 32 * @brief Defines APIs for CAs to access TAs. 33 * 34 * <p> Example: 35 * <p>1. Initialize a TEE: Call <b>TEEC_InitializeContext</b> to initialize the TEE. 36 * <p>2. Open a session: Call <b>TEEC_OpenSession</b> with the Universal Unique Identifier (UUID) of the TA. 37 * <p>3. Send a command: Call <b>TEEC_InvokeCommand</b> to send a command to the TA. 38 * <p>4. Close the session: Call <b>TEEC_CloseSession</b> to close the session. 39 * <p>5. Close the TEE: Call <b>TEEC_FinalizeContext</b> to close the TEE. 40 * 41 * @library libteec.so 42 * @kit TEE Kit 43 * @syscap SystemCapability.Tee.TeeClient 44 * @since 12 45 * @version 1.0 46 */ 47 48 #include <string.h> 49 #include "tee_client_type.h" 50 51 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 55 /** 56 * @brief Defines the values of the parameters transmitted between the REE and TEE. 57 * 58 * @since 12 59 * @version 1.0 60 */ 61 #define TEEC_PARAM_TYPES(param0Type, param1Type, param2Type, param3Type) \ 62 ((param3Type) << 12 | (param2Type) << 8 | (param1Type) << 4 | (param0Type)) 63 64 /** 65 * @brief Defines the value of the parameter specified by <b>paramTypes</b> and <b>index</b>. 66 * 67 * @since 12 68 * @version 1.0 69 */ 70 #define TEEC_PARAM_TYPE_GET(paramTypes, index) \ 71 (((paramTypes) >> (4*(index))) & 0x0F) 72 73 /** 74 * @brief Initializes a TEE. 75 * 76 * The TEE must be initialized before a session is open or commands are sent. 77 * After the initialization, a connection is set up between the CA and the TEE. 78 * 79 * @param name [IN] Indicates the pointer to the TEE path. 80 * @param context [IN/OUT] Indicates the context pointer, which is the handle of the TEE. 81 * 82 * @return Returns {@code TEEC_SUCCESS} if the TEE is successfully initialized. 83 * Returns {@code TEEC_ERROR_BAD_PARAMETERS} if <b>name</b> is incorrect or <b>context</b> is null. 84 * Returns {@code TEEC_ERROR_GENERIC} if the available system resources are insufficient. 85 * 86 * @since 12 87 * @version 1.0 88 */ 89 TEEC_Result TEEC_InitializeContext(const char *name, TEEC_Context *context); 90 91 /** 92 * @brief Closes the TEE. 93 * 94 * After the TEE is closed, the CA is disconnected from the TEE. 95 * 96 * @param context [IN/OUT] Indicates the pointer to the TEE that is successfully initialized. 97 * 98 * @since 12 99 * @version 1.0 100 */ 101 void TEEC_FinalizeContext(TEEC_Context *context); 102 103 /** 104 * @brief Opens a session. 105 * 106 * This function is used to set up a connection between the CA and the TA of the specified UUID in the specified TEE 107 * context. The data to be transferred is contained in <b>operation</b>. 108 * If a session is opened successfully, <b>session</b> is returned providing a description of the connection. 109 * If the session fails to open, <b>returnOrigin</b> is returned indicating the cause of the failure. 110 * 111 * @param context [IN/OUT] Indicates the pointer to the TEE that is successfully initialized. 112 * @param session [OUT] Indicates the pointer to the session. The value cannot be null. 113 * @param destination [IN] Indicates the pointer to the UUID of the target TA. Each TA has a unique UUID. 114 * @param connectionMethod [IN] Indicates the connection method. For details, see {@link TEEC_LoginMethod}. 115 * @param connectionData [IN] Indicates the pointer to the connection data, which varies with the connection mode. 116 * If the connection mode is {@code TEEC_LOGIN_PUBLIC}, {@code TEEC_LOGIN_USER}, 117 * {@code TEEC_LOGIN_USER_APPLICATION}, or {@code TEEC_LOGIN_GROUP_APPLICATION}, the connection data must be null. 118 * If the connection mode is {@code TEEC_LOGIN_GROUP} or {@code TEEC_LOGIN_GROUP_APPLICATION}, 119 * the connection data must point to data of the uint32_t type, which indicates the target group user to be connected 120 * by the CA. 121 * @param operation [IN/OUT] Indicates the pointer to the data to be transmitted between the CA and TA. 122 * @param returnOrigin [IN/OUT] Indicates the pointer to the error source. 123 * For details, see {@code TEEC_ReturnCodeOrigin}. 124 * 125 * @return Returns {@code TEEC_SUCCESS} if the session is open successfully. 126 * Returns {@code TEEC_ERROR_BAD_PARAMETERS} if <b>context</b>, <b>session</b>, or <b>destination</b> is null. 127 * Returns {@code TEEC_ERROR_ACCESS_DENIED} if the access request is denied. 128 * Returns {@code TEEC_ERROR_OUT_OF_MEMORY} if the available system resources are insufficient. 129 * Returns {@code TEEC_ERROR_TRUSTED_APP_LOAD_ERROR} if the TA failed to be loaded. 130 * For details about other return values, see {@code TEEC_ReturnCode}. 131 * 132 * @since 12 133 * @version 1.0 134 */ 135 TEEC_Result TEEC_OpenSession(TEEC_Context *context, TEEC_Session *session, const TEEC_UUID *destination, 136 uint32_t connectionMethod, const void *connectionData, TEEC_Operation *operation, uint32_t *returnOrigin); 137 138 /** 139 * @brief Closes a session. 140 * 141 * After the session is closed, the CA is disconnected from the TA. 142 * 143 * @param session [IN/OUT] Indicates the pointer to the session to close. 144 * 145 * @since 12 146 * @version 1.0 147 */ 148 void TEEC_CloseSession(TEEC_Session *session); 149 150 /** 151 * @brief Sends a command to a TA. 152 * 153 * The CA sends the command ID to the TA through the specified session. 154 * 155 * @param session [IN/OUT] Indicates the pointer to the session opened. 156 * @param commandID [IN] Indicates the command ID supported by the TA. It is defined by the TA. 157 * @param operation [IN/OUT] Indicates the pointer to the data to be sent from the CA to the TA. 158 * @param returnOrigin [IN/OUT] Indicates the pointer to the error source. 159 * For details, see {@code TEEC_ReturnCodeOrigin}. 160 * 161 * @return Returns {@code TEEC_SUCCESS} if the command is sent successfully. 162 * Returns {@code TEEC_ERROR_BAD_PARAMETERS} if <b>session</b> is null or 163 * <b>operation</b> is in incorrect format. 164 * Returns {@code TEEC_ERROR_ACCESS_DENIED} if the access request is denied. 165 * Returns {@code TEEC_ERROR_OUT_OF_MEMORY} if the available system resources are insufficient. 166 * For details about other return values, see {@code TEEC_ReturnCode}. 167 * 168 * @since 12 169 * @version 1.0 170 */ 171 TEEC_Result TEEC_InvokeCommand(TEEC_Session *session, uint32_t commandID, 172 TEEC_Operation *operation, uint32_t *returnOrigin); 173 174 /** 175 * @brief Registers shared memory in the specified TEE context. 176 * 177 * The registered shared memory can implement zero-copy. 178 * The zero-copy function, however, also requires support by the operating system. 179 * At present, zero-copy cannot be implemented in this manner. 180 * 181 * @param context [IN/OUT] Indicates the pointer to the TEE that is successfully initialized. 182 * @param sharedMem [IN/OUT] Indicates the pointer to the shared memory. 183 * The pointed shared memory cannot be null and the size cannot be 0. 184 * 185 * @return Returns {@code TEEC_SUCCESS} if the operation is successful. 186 * Returns {@code TEEC_ERROR_BAD_PARAMETERS} if <b>context</b> or <b>sharedMem</b> is null or 187 * the pointed memory is empty. 188 * 189 * @since 12 190 * @version 1.0 191 */ 192 TEEC_Result TEEC_RegisterSharedMemory(TEEC_Context *context, TEEC_SharedMemory *sharedMem); 193 194 /** 195 * @brief Requests shared memory in the specified TEE context. 196 * 197 * The shared memory can be used to implement zero-copy during data transmission between the REE and TEE. 198 * The zero-copy function, however, also requires support by the operating system. 199 * At present, zero-copy cannot be implemented in this manner. 200 * 201 * @attention If the <b>size</b> field of the input parameter <b>sharedMem</b> is set to <b>0</b>, <b>TEEC_SUCCESS</b> 202 * will be returned but the shared memory cannot be used because this memory has neither an address nor size. 203 * @param context [IN/OUT] Indicates the pointer to the TEE that is successfully initialized. 204 * @param sharedMem [IN/OUT] Indicates the pointer to the shared memory. The size of the shared memory cannot be 0. 205 * 206 * @return Returns {@code TEEC_SUCCESS} if the operation is successful. 207 * Returns {@code TEEC_ERROR_BAD_PARAMETERS} if <b>context</b> or <b>sharedMem</b> is null. 208 * Returns {@code TEEC_ERROR_OUT_OF_MEMORY} if the available system resources are insufficient. 209 * 210 * @since 12 211 * @version 1.0 212 */ 213 TEEC_Result TEEC_AllocateSharedMemory(TEEC_Context *context, TEEC_SharedMemory *sharedMem); 214 215 /** 216 * @brief Releases the shared memory registered or acquired. 217 * 218 * @attention If the shared memory is acquired by using {@code TEEC_AllocateSharedMemory}, 219 * the memory released will be reclaimed. If the shared memory is acquired by using {@code TEEC_RegisterSharedMemory}, 220 * the local memory released will not be reclaimed. 221 * @param sharedMem [IN/OUT] Indicates the pointer to the shared memory to release. 222 * 223 * @since 12 224 * @version 1.0 225 */ 226 void TEEC_ReleaseSharedMemory(TEEC_SharedMemory *sharedMem); 227 228 /** 229 * @brief Cancels an operation. 230 * 231 * @attention This operation is only used to send a cancel message. Whether to perform the cancel operation is 232 * determined by the TEE or TA. 233 * At present, the cancel operation does not take effect. 234 * @param operation [IN/OUT] Indicates the pointer to the data to be sent from the CA to the TA. 235 * 236 * @since 12 237 * @version 1.0 238 */ 239 void TEEC_RequestCancellation(TEEC_Operation *operation); 240 241 #ifdef __cplusplus 242 } 243 #endif 244 /** @} */ 245 #endif 246