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