1 /* 2 * Copyright (c) 2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"), 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup TeeClient 18 * @{ 19 * 20 * @brief Provides APIs for the client applications (CAs) in the Rich Execution Environment (normal mode) to 21 * access the trusted applications (TAs) in a Trusted Execution Environment (TEE). 22 * 23 * @since 20 24 */ 25 26 /** 27 * @file tee_client_type.h 28 * 29 * @brief Defines basic data types and data structures. 30 * 31 * @library libteec.so 32 * @kit TEEKit 33 * @syscap SystemCapability.Tee.TeeClient 34 * @since 20 35 */ 36 37 #ifndef TEE_CLIENT_TYPE_H 38 #define TEE_CLIENT_TYPE_H 39 40 #include <semaphore.h> 41 #include <stdbool.h> 42 #include <stddef.h> 43 #include <stdint.h> 44 #include <stdio.h> 45 #include "tee_client_constants.h" 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 /** 52 * @brief Defines the linked list type. 53 * 54 * @since 20 55 */ 56 struct ListNode { 57 /** Pointer to the next node in the list. */ 58 struct ListNode *next; 59 /** Pointer to the previous node in the list. */ 60 struct ListNode *prev; 61 }; 62 63 /** 64 * @brief Defines the return values. 65 * 66 * @since 20 67 */ 68 typedef enum TEEC_ReturnCode TEEC_Result; 69 70 /** 71 * @brief Defines the universally unique identifier (UUID) as defined in RFC4122 [2]. 72 * The UUIDs are used to identify TAs. 73 * 74 * @since 20 75 */ 76 typedef struct { 77 /** The low part of the time field. */ 78 uint32_t timeLow; 79 /** The middle part of the time field. */ 80 uint16_t timeMid; 81 /** The high part of the time field and version information. */ 82 uint16_t timeHiAndVersion; 83 /** The clock sequence and node field (8 bytes). */ 84 uint8_t clockSeqAndNode[8]; 85 } TEEC_UUID; 86 87 /** 88 * @brief Defines the context, a logical connection between a CA and a TEE. 89 * 90 * @since 20 91 */ 92 typedef struct { 93 /** File descriptor for the TA. */ 94 int32_t fd; 95 /** Path to the Trusted Application (TA). */ 96 uint8_t *ta_path; 97 /** Linked list of sessions associated with the context. */ 98 struct ListNode session_list; 99 /** Linked list of shared memory regions associated with the context. */ 100 struct ListNode shrd_mem_list; 101 /** 102 * @brief Union for either shared buffer or implementation data. 103 * 104 * @since 20 105 */ 106 union { 107 /** 108 * @brief Shared buffer used for data exchange and synchronization. 109 * 110 * @since 20 111 */ 112 struct { 113 /** Pointer to the shared buffer. */ 114 void *buffer; 115 /** Semaphore for synchronization of the shared buffer. */ 116 sem_t buffer_barrier; 117 } share_buffer; 118 /** Implementation-specific data. */ 119 uint64_t imp; 120 }; 121 } TEEC_Context; 122 123 /** 124 * @brief Defines the session between a CA and a TA. 125 * 126 * @since 20 127 */ 128 typedef struct { 129 /** Session ID for the session. */ 130 uint32_t session_id; 131 /** UUID representing the service associated with the session. */ 132 TEEC_UUID service_id; 133 /** The number of operations associated with the session. */ 134 uint32_t ops_cnt; 135 /** 136 * @brief Union for either a linked list head or implementation-specific data. 137 * 138 * @since 20 139 */ 140 union { 141 /** Linked list head for session-related data. */ 142 struct ListNode head; 143 /** Implementation-specific data. */ 144 uint64_t imp; 145 }; 146 /** Pointer to the TEEC context associated with the session. */ 147 TEEC_Context *context; 148 } TEEC_Session; 149 150 /** 151 * @brief Defines a shared memory block, which can be registered or allocated. 152 * 153 * @since 20 154 */ 155 typedef struct { 156 /** Pointer to the shared memory buffer. */ 157 void *buffer; 158 /** Size of the shared memory buffer. */ 159 uint32_t size; 160 /** Flags associated with the shared memory. */ 161 uint32_t flags; 162 /** The number of operations associated with the shared memory. */ 163 uint32_t ops_cnt; 164 /** Indicates whether the memory has been allocated. */ 165 bool is_allocated; 166 /** 167 * @brief Union for either a linked list head or implementation-specific data. 168 * 169 * @since 20 170 */ 171 union { 172 /** Linked list head for shared memory-related data. */ 173 struct ListNode head; 174 /** Implementation-specific data. */ 175 void* imp; 176 }; 177 /** Pointer to the TEEC context associated with the shared memory. */ 178 TEEC_Context *context; 179 } TEEC_SharedMemory; 180 181 /** 182 * @brief Defines a pointer to a temporary buffer. 183 * 184 * @since 20 185 */ 186 typedef struct { 187 /** Pointer to the temporary memory buffer. */ 188 void *buffer; 189 /** Size of the temporary memory buffer. */ 190 uint32_t size; 191 } TEEC_TempMemoryReference; 192 193 /** 194 * @brief Defines a pointer to the shared memory that is registered or allocated. 195 * 196 * @since 20 197 */ 198 typedef struct { 199 /** Pointer to the parent shared memory. */ 200 TEEC_SharedMemory *parent; 201 /** Size of the registered memory reference. */ 202 uint32_t size; 203 /** Offset within the parent shared memory. */ 204 uint32_t offset; 205 } TEEC_RegisteredMemoryReference; 206 207 /** 208 * @brief Describes a parameter that carries small raw data passed by <b>value</b>. 209 * 210 * @since 20 211 */ 212 typedef struct { 213 /** The first value. */ 214 uint32_t a; 215 /** The second value. */ 216 uint32_t b; 217 } TEEC_Value; 218 219 /** 220 * @brief Describes the size and handle of the ION memory. 221 * 222 * @since 20 223 */ 224 typedef struct { 225 /** File descriptor for the shared ion memory. */ 226 int ion_share_fd; 227 /** Size of the ion memory. */ 228 uint32_t ion_size; 229 } TEEC_IonReference; 230 231 /** 232 * @brief Defines a parameter of {@code TEEC_Operation}. 233 * 234 * @since 20 235 */ 236 typedef union { 237 /** Temporary memory reference. */ 238 TEEC_TempMemoryReference tmpref; 239 /** Registered memory reference. */ 240 TEEC_RegisteredMemoryReference memref; 241 /** A value containing two 32-bit values. */ 242 TEEC_Value value; 243 /** Ion memory reference. */ 244 TEEC_IonReference ionref; 245 } TEEC_Parameter; 246 247 /** 248 * @brief Defines the parameters for the Trusted User Interface (TUI). 249 * 250 * @since 20 251 */ 252 typedef struct { 253 /** TUI event type. */ 254 uint32_t event_type; 255 /** Return value, is keycode if TUI event is getKeycode. */ 256 uint32_t value; 257 /** Notch size of the screen for the TUI. */ 258 uint32_t notch; 259 /** Width of the foldable screen for the TUI. */ 260 uint32_t width; 261 /** Height of the foldable screen for the TUI. */ 262 uint32_t height; 263 /** State of the foldable screen for the TUI. */ 264 uint32_t fold_state; 265 /** One state of the folded screen for the TUI. */ 266 uint32_t display_state; 267 /** Real width of the mobile device for the TUI. */ 268 uint32_t phy_width; 269 /** Real height of the mobile device for the TUI. */ 270 uint32_t phy_height; 271 } TEEC_TUI_Parameter; 272 273 /** 274 * @brief Defines the parameters for opening a session or sending a command. 275 * 276 * @since 20 277 */ 278 typedef struct { 279 /** The value 0 means to cancel the command, and other values mean to execute the command. */ 280 uint32_t started; 281 /** Use {@code TEEC_PARAM_TYPES} to create this parameter. */ 282 uint32_t paramTypes; 283 /** Array of parameters for the operation. */ 284 TEEC_Parameter params[TEEC_PARAM_NUM]; 285 /** Pointer to the session associated with the operation. */ 286 TEEC_Session *session; 287 /** Flag indicating whether the operation is canceled. */ 288 bool cancel_flag; 289 } TEEC_Operation; 290 291 #ifdef __cplusplus 292 } 293 #endif 294 295 #endif 296 /** @} */