1 /* 2 * Copyright (C) 2022 Huawei Technologies Co., Ltd. 3 * Licensed under the Mulan PSL v2. 4 * You can use this software according to the terms and conditions of the Mulan PSL v2. 5 * You may obtain a copy of Mulan PSL v2 at: 6 * http://license.coscl.org.cn/MulanPSL2 7 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR 8 * IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR 9 * PURPOSE. 10 * See the Mulan PSL v2 for more details. 11 */ 12 13 #ifndef TEE_CLIENT_API_H 14 #define TEE_CLIENT_API_H 15 /** 16 * @addtogroup TeeClient 17 * @{ 18 * 19 * @brief Provides APIs for the client applications (CAs) in the Rich Execution Environment (normal mode) to 20 * access the trusted applications (TAs) in a Trusted Execution Environment (TEE). 21 * 22 * @syscap SystemCapability.Tee.TeeClient 23 * @since 9 24 * @version 1.0 25 */ 26 27 /** 28 * @file tee_client_api.h 29 * 30 * @brief Defines APIs for CAs to access TAs. 31 * 32 * <p> Example: 33 * <p>1. Initialize a TEE: Call <b>TEEC_InitializeContext</b> to initialize the TEE. 34 * <p>2. Open a session: Call <b>TEEC_OpenSession</b> with the Universal Unique Identifier (UUID) of the TA. 35 * <p>3. Send a command: Call <b>TEEC_InvokeCommand</b> to send a command to the TA. 36 * <p>4. Close the session: Call <b>TEEC_CloseSession</b> to close the session. 37 * <p>5. Close the TEE: Call <b>TEEC_FinalizeContext</b> to close the TEE. 38 * 39 * @since 9 40 * @version 1.0 41 */ 42 43 #include <string.h> 44 #include "tee_client_type.h" 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** 51 * @brief Defines the values of the parameters transmitted between the REE and TEE. 52 * 53 * @since 9 54 * @version 1.0 55 */ 56 #define TEEC_PARAM_TYPES(param0Type, param1Type, param2Type, param3Type) \ 57 ((param3Type) << 12 | (param2Type) << 8 | (param1Type) << 4 | (param0Type)) 58 59 /** 60 * @brief Defines the value of the parameter specified by <b>paramTypes</b> and <b>index</b>. 61 * 62 * @since 9 63 * @version 1.0 64 */ 65 #define TEEC_PARAM_TYPE_GET(paramTypes, index) \ 66 (((paramTypes) >> (4*(index))) & 0x0F) 67 68 /** 69 * @brief Initializes a TEE. 70 * 71 * The TEE must be initialized before a session is open or commands are sent. 72 * After the initialization, a connection is set up between the CA and the TEE. 73 * 74 * @param name [IN] Indicates the pointer to the TEE path. 75 * @param context [IN/OUT] Indicates the context pointer, which is the handle of the TEE. 76 * 77 * @return Returns {@code TEEC_SUCCESS} if the TEE is successfully initialized. 78 * Returns {@code TEEC_ERROR_BAD_PARAMETERS} if <b>name</b> is incorrect or <b>context</b> is null. 79 * Returns {@code TEEC_ERROR_GENERIC} if the available system resources are insufficient. 80 * 81 * @since 9 82 * @version 1.0 83 */ 84 TEEC_Result TEEC_InitializeContext(const char *name, TEEC_Context *context); 85 86 /** 87 * @brief Closes the TEE. 88 * 89 * After the TEE is closed, the CA is disconnected from the TEE. 90 * 91 * @param context [IN/OUT] Indicates the pointer to the TEE that is successfully initialized. 92 * 93 * @since 9 94 * @version 1.0 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 context. 102 * 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 by the CA. 115 * @param operation [IN/OUT] Indicates the pointer to the data to be transmitted between the CA and TA. 116 * @param returnOrigin [IN/OUT] Indicates the pointer to the error source. For details, see {@code TEEC_ReturnCodeOrigin}. 117 * 118 * @return Returns {@code TEEC_SUCCESS} if the session is open successfully. 119 * Returns {@code TEEC_ERROR_BAD_PARAMETERS} if <b>context</b>, <b>session</b>, or <b>destination</b> is null. 120 * Returns {@code TEEC_ERROR_ACCESS_DENIED} if the access request is denied. 121 * Returns {@code TEEC_ERROR_OUT_OF_MEMORY} if the available system resources are insufficient. 122 * Returns {@code TEEC_ERROR_TRUSTED_APP_LOAD_ERROR} if the TA failed to be loaded. 123 * For details about other return values, see {@code TEEC_ReturnCode}. 124 * 125 * @since 9 126 * @version 1.0 127 */ 128 TEEC_Result TEEC_OpenSession(TEEC_Context *context, TEEC_Session *session, const TEEC_UUID *destination, 129 uint32_t connectionMethod, const void *connectionData, TEEC_Operation *operation, uint32_t *returnOrigin); 130 131 /** 132 * @brief Closes a session. 133 * 134 * After the session is closed, the CA is disconnected from the TA. 135 * 136 * @param session [IN/OUT] Indicates the pointer to the session to close. 137 * 138 * @since 9 139 * @version 1.0 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. For details, see {@code TEEC_ReturnCodeOrigin}. 152 * 153 * @return Returns {@code TEEC_SUCCESS} if the command is sent successfully. 154 * Returns {@code TEEC_ERROR_BAD_PARAMETERS} if <b>session</b> is null or <b>operation</b> is in incorrect format. 155 * Returns {@code TEEC_ERROR_ACCESS_DENIED} if the access request is denied. 156 * Returns {@code TEEC_ERROR_OUT_OF_MEMORY} if the available system resources are insufficient. 157 * For details about other return values, see {@code TEEC_ReturnCode}. 158 * 159 * @since 9 160 * @version 1.0 161 */ 162 TEEC_Result TEEC_InvokeCommand(TEEC_Session *session, uint32_t commandID, 163 TEEC_Operation *operation, uint32_t *returnOrigin); 164 165 /** 166 * @brief Registers shared memory in the specified TEE context. 167 * 168 * The registered shared memory can implement zero-copy. 169 * The zero-copy function, however, also requires support by the operating system. 170 * At present, zero-copy cannot be implemented in this manner. 171 * 172 * @param context [IN/OUT] Indicates the pointer to the TEE that is successfully initialized. 173 * @param sharedMem [IN/OUT] Indicates the pointer to the shared memory. The pointed shared memory cannot be null and the size cannot be 0. 174 * 175 * @return Returns {@code TEEC_SUCCESS} if the operation is successful. 176 * Returns {@code TEEC_ERROR_BAD_PARAMETERS} if <b>context</b> or <b>sharedMem</b> is null or the pointed memory is empty. 177 * 178 * @since 9 179 * @version 1.0 180 */ 181 TEEC_Result TEEC_RegisterSharedMemory(TEEC_Context *context, TEEC_SharedMemory *sharedMem); 182 183 /** 184 * @brief Requests shared memory in the specified TEE context. 185 * 186 * The shared memory can be used to implement zero-copy during data transmission between the REE and TEE. 187 * The zero-copy function, however, also requires support by the operating system. 188 * At present, zero-copy cannot be implemented in this manner. 189 * 190 * @attention If the <b>size</b> field of the input parameter <b>sharedMem</b> is set to <b>0</b>, <b>TEEC_SUCCESS</b> will be returned but 191 * the shared memory cannot be used because this memory has neither an address nor size. 192 * @param context [IN/OUT] Indicates the pointer to the TEE that is successfully initialized. 193 * @param sharedMem [IN/OUT] Indicates the pointer to the shared memory. The size of the shared memory cannot be 0. 194 * 195 * @return Returns {@code TEEC_SUCCESS} if the operation is successful. 196 * Returns {@code TEEC_ERROR_BAD_PARAMETERS} if <b>context</b> or <b>sharedMem</b> is null. 197 * Returns {@code TEEC_ERROR_OUT_OF_MEMORY} if the available system resources are insufficient. 198 * 199 * @since 9 200 * @version 1.0 201 */ 202 TEEC_Result TEEC_AllocateSharedMemory(TEEC_Context *context, TEEC_SharedMemory *sharedMem); 203 204 /** 205 * @brief Releases the shared memory registered or acquired. 206 * 207 * @attention If the shared memory is acquired by using {@code TEEC_AllocateSharedMemory}, 208 * the memory released will be reclaimed. If the shared memory is acquired by using {@code TEEC_RegisterSharedMemory}, 209 * the local memory released will not be reclaimed. 210 * @param sharedMem [IN/OUT] Indicates the pointer to the shared memory to release. 211 * 212 * @since 9 213 * @version 1.0 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 determined by the TEE or TA. At present, the cancel operation does not take effect. 221 * @param operation [IN/OUT] Indicates the pointer to the data to be sent from the CA to the TA. 222 * 223 * @since 9 224 * @version 1.0 225 */ 226 void TEEC_RequestCancellation(TEEC_Operation *operation); 227 228 #ifdef __cplusplus 229 } 230 #endif 231 /** @} */ 232 #endif 233