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