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