1 /* 2 * Copyright (c) 2013-2019 Huawei Technologies Co., Ltd. All rights reserved. 3 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without modification, 6 * are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, this list of 9 * conditions and the following disclaimer. 10 * 11 * 2. Redistributions in binary form must reproduce the above copyright notice, this list 12 * of conditions and the following disclaimer in the documentation and/or other materials 13 * provided with the distribution. 14 * 15 * 3. Neither the name of the copyright holder nor the names of its contributors may be used 16 * to endorse or promote products derived from this software without specific prior written 17 * permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 21 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 23 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 24 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 25 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 26 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 27 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 28 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 29 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 /* @defgroup TEEC_API client(REE) interface 33 * @defgroup TEEC_BASIC_FUNC common interface 34 * @ingroup TEEC_API 35 */ 36 37 #ifndef _TEEK_CLIENT_API_H_ 38 #define _TEEK_CLIENT_API_H_ 39 #include "teek_client_type.h" 40 #include "teek_ns_client.h" 41 42 /* 43 * @ingroup TEEC_BASIC_FUNC 44 * Calculate the values of the transfer parameters between REE and TEE 45 */ 46 #define TEEC_PARAM_TYPES(param0_type, param1_type, param2_type, param3_type) \ 47 (((param3_type) << 12) | ((param2_type) << 8) | \ 48 ((param1_type) << 4) | (param0_type)) 49 50 /* 51 * @ingroup TEEC_BASIC_FUNC 52 * Get the index value in parmaTypes 53 */ 54 #define TEEC_PARAM_TYPE_GET(paramTypes, index) \ 55 (((paramTypes) >> ((index) << 2)) & 0x0F) 56 57 /* 58 * @ingroup TEEC_BASIC_FUNC 59 * When the parameter type is #teec_value, if the member variable a or b is not assigned, 60 * you need to assign this value to it, indicates that this member variable is not used. 61 */ 62 #define TEEC_VALUE_UNDEF 0xFFFFFFFF 63 64 /* 65 * Function: TeekIsAgentAlive 66 * Description: This function check if the special agent is launched. 67 * Used For HDCP key. 68 * e.g. If sfs agent is not alive, 69 * you can not do HDCP key write to SRAM. 70 * Parameters: agentId. 71 * Return: 1:agent is alive 72 * 0:agent not exsit. 73 */ 74 int TeekIsAgentAlive(unsigned int agentId); 75 76 /* 77 * @ingroup TEEC_BASIC_FUNC 78 * @brief Initialize the TEE context 79 * 80 * @par Description 81 * Initialize the TEE context whose path is 'name'. The 'name' can be left empty, 82 * TEE initialization is the basis for opening a session and sending a command, 83 * after the initialization is successful, a connection is set up between the CA and the TEE. 84 * 85 * @param name [IN] Tee context path 86 * @param context [IN/OUT] context pointer，secure world environment handle 87 * 88 * @retval #TEEC_SUCCESS TEE context is successfully initialized 89 * @retval #TEEC_ERROR_BAD_PARAMETERS Parameter is incorrect, 'name' is incorrect or context is empty 90 * @retval #TEEC_ERROR_GENERIC System resources are insufficient 91 */ 92 TeecResult TeekInitializeContext(const char *name, TeecContext *context); 93 94 /* 95 * @ingroup TEEC_BASIC_FUNC 96 * @brief Close the tee context 97 * 98 * @par Description 99 * Close the TEE context to which the 'context' points, and disconnect the client application from the TEE environment. 100 * 101 * @param context [IN/OUT] The TEE context that has been successfully initialized 102 * 103 */ 104 void TeekFinalizeContext(TeecContext *context); 105 106 /* 107 * @ingroup TEEC_BASIC_FUNC 108 * @brief Open session 109 * 110 * @par Description 111 * Create a session which is from CA to the 'destination' UUID TA, 112 * the connection method is 'connectionMethod', and the link data is 'connectionData', 113 * The transferred data is contained in the 'opetation'. 114 * After a session is opened successfully, the output parameter 'session' is a description of the link. 115 * If the session fails to be opened, 'returnOrigin' is the error source. 116 * 117 * @param context [IN/OUT] The TEE context that has been successfully initialized 118 * @param session [OUT] Pointed to the session, the value cannot be empty 119 * @param destination [IN] UUID of a security service, a security service has a unique UUID. 120 * @param connectionMethod [IN] Connection mode. The value range is #TEEC_LoginMethod. 121 * @param connectionData [IN] Connection data corresponding to the connection mode 122 * If connection mode is #TEEC_LOGIN_PUBLIC, #TEEC_LOGIN_USE, 123 * #TEEC_LOGIN_USER_APPLICATION, #TEEC_LOGIN_GROUP_APPLICATION, connection data must be empty. 124 * If connection mode is #TEEC_LOGIN_GROUP、#TEEC_LOGIN_GROUP_APPLICATION， 125 * the connection data must point to data of type uint32_t, 126 * which represents the user group that the client application expects to connect to. 127 * @param operation [IN/OUT] Data transferred between CAs and TAs 128 * @param returnOrigin [IN/OUT] Error source. The value range is #TEEC_ReturnCodeOrigin. 129 * 130 * @retval #TEEC_SUCCESS Open successfully. 131 * @retval #TEEC_ERROR_BAD_PARAMETERS The parameter is incorrect. 132 * @retval #TEEC_ERROR_ACCESS_DENIED Failed to access the system call permission. 133 * @retval #TEEC_ERROR_OUT_OF_MEMORY Insufficient system resources. 134 * @retval #TEEC_ERROR_TRUSTED_APP_LOAD_ERROR Failed to load the security service. 135 * @retval Other return values, see. #TEEC_ReturnCode 136 */ 137 TeecResult TeekOpenSession(TeecContext *context, 138 TeecSession *session, 139 const TeecUuid *destination, 140 uint32_t connectionMethod, 141 const void *connectionData, 142 const TeecOperation *operation, 143 uint32_t *returnOrigin); 144 145 /** 146 * @ingroup TEEC_BASIC_FUNC 147 * @brief Close session 148 * 149 * @par Description 150 * Close the session to which the 'session' points, and disconnect the client application from the security service. 151 * 152 * @param session [IN/OUT] Point to a session that has been opened successfully 153 */ 154 void TeekCloseSession(TeecSession *session); 155 156 /** 157 * @ingroup TEEC_BASIC_FUNC 158 * @brief Send a command. 159 * 160 * @par Description 161 * In a specified 'session', the CA sends the 'commandID' command to the TA. 162 * The sent data is 'operation'. 163 * If the command fails to be sent, the 'returnOrigin' indicate the error source. 164 * 165 * @param session [IN/OUT] Pointing to a session that has been successfully opened 166 * @param commandID [IN] Command ID supported by the security service, which is defined by the security service. 167 * @param operation [IN/OUT] Contains the data sent from the CA to the TA. 168 * @param returnOrigin [IN/OUT] Error source. The value range is #TEEC_ReturnCodeOrigin. 169 * 170 * @retval #TEEC_SUCCESS Command sent successfully. 171 * @retval #TEEC_ERROR_BAD_PARAMETERS The parameter is incorrect, 172 * the session parameter is empty or the operation parameter is in an incorrect format. 173 * @retval #TEEC_ERROR_ACCESS_DENIED Failed to access the system call permission. 174 * @retval #TEEC_ERROR_OUT_OF_MEMORY Insufficient system resources. 175 * @retval other return values, see. #TEEC_ReturnCode 176 */ 177 TeecResult TeekInvokeCommand(TeecSession *session, 178 uint32_t commandID, 179 TeecOperation *operation, 180 uint32_t *returnOrigin); 181 182 /** 183 * @ingroup TEEC_BASIC_FUNC 184 * @brief Register the Shared Memory 185 * 186 * @par Description 187 * Registers the shared memory 'sharedMem' in the specified TEE 'context'， 188 * the operating system needs to support zero copy to obtain the shared memory through registration, 189 * in the current implementation, zero copy cannot be implemented in this mode. 190 * 191 * @attention If the size field of the input parameter 'sharedMem' is set to 0, 192 * the function returns a success message, but this field cannot be used.Shared memory, 193 * because this memory has no size 194 * @param context [IN/OUT] TEE environment that has been successfully initialized 195 * @param sharedMem [IN/OUT] Pointer to the shared memory, the memory cannot be null or 0. 196 * 197 * @retval #TEEC_SUCCESS Command sent successfully. 198 * @retval #TEEC_ERROR_BAD_PARAMETERS The parameter is incorrect. The context or sharedMem parameter is empty， 199 * or the memory to which the shared memory points is empty. 200 */ 201 TeecResult TeekRegisterSharedMemory(TeecContext *context, 202 TeecSharedMemory *sharedMem); 203 204 /** 205 * @ingroup TEEC_BASIC_FUNC 206 * @brief Apply for Shared Memory 207 * 208 * @par Description 209 * Apply for the shared memory 'sharedMem' in the specified TEE 'context', 210 * The shared memory can implement zero copy when data is transferred 211 * between the non-secure world and the secure world. 212 * 213 * @attention If the size field of the input parameter 'sharedMem' is set to 0, 214 * the function returns a success message, but this Shared memory field cannot be used, 215 * because this memory has neither address nor size. 216 * @param context [IN/OUT] TEE environment that has been successfully initialized 217 * @param sharedMem [IN/OUT] Pointer to the shared memory. The size of the shared memory cannot be 0. 218 * 219 * @retval #TEEC_SUCCESS Command sent successfully. 220 * @retval #TEEC_ERROR_BAD_PARAMETERS The parameter is incorrect. The context or sharedMem parameter is empty. 221 * @retval #TEEC_ERROR_OUT_OF_MEMORY Allocation failed due to insufficient system resources. 222 */ 223 TeecResult TeekAllocateSharedMemory(TeecContext *context, 224 TeecSharedMemory *sharedMem); 225 226 /** 227 * @ingroup TEEC_BASIC_FUNC 228 * @brief Release the shared memory. 229 * 230 * @par Description 231 * Releases the shared memory that has been registered or applied for. 232 * 233 * @attention If the shared memory is obtained in #TEEK_AllocateSharedMemory mode, When the memory is released, 234 * the memory is reclaimed. If the #TEEK_RegisterSharedMemory method is used, 235 * The local memory to which the shared memory points is not reclaimed when the shared memory is released. 236 * @param sharedMem [IN/OUT] Point to the shared memory that has been registered or applied for successfully 237 */ 238 void TeekReleaseSharedMemory(TeecSharedMemory *sharedMem); 239 240 /** 241 * @ingroup TEEC_BASIC_FUNC 242 * @brief cancel API 243 * 244 * @par Description 245 * Cancel a running open session or an invoke command. 246 * Send a cancel signal and return immediately. 247 * 248 * @attention This operation only sends a cancel message, 249 * whether to perform the cancel operation is determined by the TEE or TA. 250 * @param operation [IN/OUT] Contains the data sent from the CA to the TA. 251 */ 252 void TeekRequestCancellation(TeecOperation *operation); 253 254 #endif 255