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_EXT_API_H 14 #define TEE_CLIENT_EXT_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_ext_api.h 27 * 28 * @brief Defines extend 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 "tee_client_type.h" 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @brief CA register an agent for TA communicate with CA. 48 * 49 * 50 * @param agentId [IN] user defined, do not conflict with other agent. 51 * @param devFd [OUT] TEE driver fd. 52 * @param buffer [OUT] shared memory between CA&TA, size is 4K. 53 * 54 * @return Returns {@code TEEC_SUCCESS} if the CA is successfully register an agent for TA communicate with CA. 55 * Returns {@code TEEC_ERROR_GENERIC} if error happened. 56 * @since 8 57 */ 58 TEEC_Result TEEC_EXT_RegisterAgent(uint32_t agentId, int *devFd, void **buffer); 59 60 /** 61 * @brief CA wait event from TA. 62 * 63 * when call this interface, CA thread will block until TA send a msg. 64 * 65 * @param agentId [IN] user registered agent 66 * @param devFd [IN] TEE driver fd 67 * 68 * @return Returns {@code TEEC_SUCCESS} if the CA receive msg from TA success. 69 * Returns {@code TEEC_ERROR_GENERIC} if error happened. 70 * @since 8 71 */ 72 TEEC_Result TEEC_EXT_WaitEvent(uint32_t agentId, int devFd); 73 74 /** 75 * @brief CA send response to TA. 76 * 77 * @param agentId [IN] user registered agent 78 * @param devFd [IN] TEE driver fd 79 * 80 * @return Returns {@code TEEC_SUCCESS} if the CA send cmd success. 81 * Returns {@code TEEC_ERROR_GENERIC} if error happened. 82 * @since 8 83 */ 84 TEEC_Result TEEC_EXT_SendEventResponse(uint32_t agentId, int devFd); 85 86 /** 87 * @brief CA unregister an agent. 88 * 89 * @param agentId [IN] user registered agent 90 * @param devFd [IN] TEE driver fd 91 * @param buffer [IN] shared mem between CA&TA, TEE will release this buffer and set it to NULL 92 * 93 * @return Returns {@code TEEC_SUCCESS} if the CA send cmd success. 94 * Returns {@code TEEC_ERROR_GENERIC} if error happened. 95 * Returns {@code TEEC_ERROR_BAD_PARAMETERS} if input parameter is invalid. 96 * @since 8 97 */ 98 TEEC_Result TEEC_EXT_UnregisterAgent(uint32_t agentId, int devFd, void **buffer); 99 100 /** 101 * @brief CA sends a secfile to TEE 102 * 103 * @param path [IN] path of the secfile 104 * @param session [IN] session beturn CA&TA 105 * 106 * @return Returns {@code TEEC_SUCCESS} if the CA send the secfile success. 107 * Returns {@code TEEC_ERROR_GENERIC} if error happened. 108 * Returns {@code TEEC_ERROR_BAD_PARAMETERS} if input parameter is invalid. 109 * @since 8 110 */ 111 TEEC_Result TEEC_SendSecfile(const char *path, TEEC_Session *session); 112 113 /** 114 * @brief Get the tee version. 115 * 116 * @return Returns {@code 0} if get the tee version failed. 117 * Returns {@code > 0} if get the version success. 118 * @since 8 119 */ 120 uint32_t TEEC_GetTEEVersion(void); 121 122 #ifdef __cplusplus 123 } 124 #endif 125 126 #endif 127