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 TeeTrusted 18 * @{ 19 * 20 * @brief TEE(Trusted Excution Environment) API. 21 * Provides security capability APIs such as trusted storage, encryption and decryption, 22 * and trusted time for trusted application development. 23 * 24 * @since 20 25 */ 26 27 /** 28 * @file tee_trusted_storage_api.h 29 * 30 * @brief Provides trusted storage APIs. 31 * 32 * You can use these APIs to implement trusted storage features. 33 * 34 * @library NA 35 * @kit TEEKit 36 * @syscap SystemCapability.Tee.TeeClient 37 * @since 20 38 */ 39 40 #ifndef __TEE_TRUSTED_STORAGE_API_H 41 #define __TEE_TRUSTED_STORAGE_API_H 42 43 #include "tee_defines.h" 44 #include "tee_object_api.h" 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** 51 * @brief Defines the start position in the data stream associated with an object. 52 * It is used in the <b>TEE_SeekObjectData</b> function. 53 * 54 * @since 20 55 */ 56 enum __TEE_Whence { 57 /** Set the start position to the beginning of the data stream. */ 58 TEE_DATA_SEEK_SET = 0, 59 /** Set the start position to the current data stream position. */ 60 TEE_DATA_SEEK_CUR, 61 /** Set the start position to the end of the data stream. */ 62 TEE_DATA_SEEK_END 63 }; 64 65 /** 66 * @brief Defines the handle for enumerating objects. 67 * 68 * @since 20 69 */ 70 struct __TEE_ObjectEnumHandle; 71 72 /** 73 * @brief Defines the type for the data stream position. 74 * 75 * @since 20 76 */ 77 typedef uint32_t TEE_Whence; 78 79 /** 80 * @brief Defines the storage ID, which identifies the storage space of the application. 81 * 82 * @since 20 83 */ 84 enum Object_Storage_Constants { 85 /** Separate private storage space for each application. */ 86 TEE_OBJECT_STORAGE_PRIVATE = 0x00000001, 87 /** Separate personal storage space for application. */ 88 TEE_OBJECT_STORAGE_PERSO = 0x00000002, 89 /** Space for secure flash storage. */ 90 TEE_OBJECT_SEC_FLASH = 0x80000000, 91 /** Space for RPMB storage. */ 92 TEE_OBJECT_STORAGE_RPMB = 0x80000001, 93 /** Credential encrypted storage space. */ 94 TEE_OBJECT_STORAGE_CE = 0x80000002, 95 /** Anti-rollback storage space. */ 96 TEE_OBJECT_STORAGE_ANTIROLLBACK = 0x80000003, 97 }; 98 99 /** 100 * @brief Defines the system resource constraints, such as the maximum value for the data stream position indicator. 101 * 102 * @since 20 103 */ 104 enum Miscellaneous_Constants { 105 /** Maximum length that the position indicator of the data stream can take. */ 106 TEE_DATA_MAX_POSITION = 0xFFFFFFFF, 107 /** Maximum length of the object ID, which can extend to 128 bytes. */ 108 TEE_OBJECT_ID_MAX_LEN = 64, 109 }; 110 111 /** 112 * @brief Defines the maximum number of bytes that can be held in a data stream. 113 * 114 * @since 20 115 */ 116 enum TEE_DATA_Size { 117 TEE_DATA_OBJECT_MAX_SIZE = 0xFFFFFFFF 118 }; 119 120 /** 121 * @brief Defines the <b>handleFlags</b> of a <b>TEE_ObjectHandle</b>. 122 * The <b>handleFlags</b> determines the access permissions to the data stream associated with the object. 123 * 124 * @since 20 125 */ 126 enum Data_Flag_Constants { 127 /** The data stream can be read. */ 128 TEE_DATA_FLAG_ACCESS_READ = 0x00000001, 129 /** The data stream can be written or truncated. */ 130 TEE_DATA_FLAG_ACCESS_WRITE = 0x00000002, 131 /** The data stream can be deleted or renamed. */ 132 TEE_DATA_FLAG_ACCESS_WRITE_META = 0x00000004, 133 /** Multiple TEE_ObjectHandles can be opened for concurrent read. */ 134 TEE_DATA_FLAG_SHARE_READ = 0x00000010, 135 /** Multiple TEE_ObjectHandles can be opened for concurrent write. */ 136 TEE_DATA_FLAG_SHARE_WRITE = 0x00000020, 137 /** Reserved. */ 138 TEE_DATA_FLAG_CREATE = 0x00000200, 139 /** 140 * Protect the existing file with the same name. Throw an error if the file with the same name exists; 141 * create a data file otherwise. 142 */ 143 TEE_DATA_FLAG_EXCLUSIVE = 0x00000400, 144 /** 145 * Protect the existing file with the same name. Throw an error if the file with the same name exists; 146 * create a data file otherwise. 147 */ 148 TEE_DATA_FLAG_OVERWRITE = 0x00000400, 149 /** If the bit25 is set to 1, it means deriving TA root key by using gid */ 150 TEE_DATA_FLAG_GID = 0x02000000, 151 /** If the bit26 is set to 1, it means deriving TA root key by using huk2 */ 152 TEE_DATA_FLAG_HUK2 = 0x04000000, 153 /** 154 * If the bit27 os set to 1, it means deriving the 32-bytes TA root key at one time, 155 * if it is 0, it means deriving TA root keys and combined them together. 156 */ 157 TEE_DATA_FLAG_DERIVE_32BYTES_KEY_ONCE = 0x08000000, 158 /** Use AES256 if bit 28 is 1; use AES128 if bit 28 is 0. */ 159 TEE_DATA_FLAG_AES256 = 0x10000000, 160 /** If bit 29 is set to 1, open the earlier version preferentially. */ 161 TEE_DATA_FLAG_OPEN_AESC = 0x20000000, 162 /** If bit30 is set to 1, it means use GM algorithm to protect data */ 163 TEE_DATA_FLAG_GM = 0x40000000, 164 }; 165 166 /** 167 * @brief Creates a persistent object. 168 * 169 * This function creates a persistent object with initialized <b>TEE_Attribute</b> and data stream. 170 * You can use the returned handle to access the <b>TEE_Attribute</b> and data stream of the object. 171 * 172 * @param storageID Indicates the storage to use. The value is specified by <b>Object_Storage_Constants</b>. 173 * @param objectID Indicates the pointer to the object identifier, that is, the name of the object to create. 174 * @param objectIDLen Indicates the length of the object identifier, in bytes. It cannot exceed 128 bytes. 175 * @param flags Indicates the flags of the object created. The value can be 176 * one or more of <b>Data_Flag_Constants</b> or <b>Handle_Flag_Constants</b>. 177 * @param attributes Indicates the <b>TEE_ObjectHandle</b> of a transient object from which to take 178 * <b>TEE_Attribute</b>. It can be <b>TEE_HANDLE_NULL</b> if the persistent object contains no attribute. 179 * @param initialData Indicates the pointer to the initial data used to initialize the data stream data. 180 * @param initialDataLen Indicates the length of the initial data, in bytes. 181 * @param object Indicates the pointer to the <b>TEE_ObjectHandle</b> returned 182 * after the function is successfully executed. 183 * 184 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 185 * Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the storage specified by <b>storageID</b> does not exist. 186 * Returns <b>TEE_ERROR_ACCESS_CONFLICT</b> if an access conflict occurs. 187 * Returns <b>TEE_ERROR_OUT_OF_MEMORY</b> if the memory is not sufficient to complete the operation. 188 * Returns <b>TEE_ERROR_STORAGE_NO_SPACE</b> if there is no enough space to create the object. 189 * 190 * @since 20 191 */ 192 TEE_Result TEE_CreatePersistentObject(uint32_t storageID, const void *objectID, size_t objectIDLen, uint32_t flags, 193 TEE_ObjectHandle attributes, const void *initialData, size_t initialDataLen, 194 TEE_ObjectHandle *object); 195 196 /** 197 * @brief Opens an existing persistent object. 198 * 199 * The handle returned can be used to access the <b>TEE_Attribute</b> and data stream of the object. 200 * 201 * @param storageID Indicates the storage to use. The value is specified by <b>Object_Storage_Constants</b>. 202 * @param objectID Indicates the pointer to the object identifier, that is, the name of the object to open. 203 * @param objectIDLen Indicates the length of the object identifier, in bytes. It cannot exceed 128 bytes. 204 * @param flags Indicates the flags of the object opened. 205 * The value can be one or more of <b>Data_Flag_Constants</b> or <b>Handle_Flag_Constants</b>. 206 * @param object Indicates the pointer to the <b>TEE_ObjectHandle</b> returned 207 * after the function is successfully executed. 208 * 209 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 210 * Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the storage specified by <b>storageID</b> does not exist 211 * or the object identifier cannot be found in the storage. 212 * Returns <b>TEE_ERROR_ACCESS_CONFLICT</b> if an access conflict occurs. 213 * Returns <b>TEE_ERROR_OUT_OF_MEMORY</b> if the memory is not sufficient to complete the operation. 214 * 215 * @since 20 216 */ 217 TEE_Result TEE_OpenPersistentObject(uint32_t storageID, const void *objectID, size_t objectIDLen, uint32_t flags, 218 TEE_ObjectHandle *object); 219 220 /** 221 * @brief Reads data from the data stream associated with an object into the buffer. 222 * 223 * The <b>TEE_ObjectHandle</b> of the object must have been opened with the <b>TEE_DATA_FLAG_ACCESS_READ</b> permission. 224 * 225 * @param object Indicates the <b>TEE_ObjectHandle</b> of the object to read. 226 * @param buffer Indicates the pointer to the buffer used to store the data read. 227 * @param size Indicates the number of bytes to read. 228 * @param count Indicates the pointer to the variable that contains the number of bytes read. 229 * 230 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 231 * Returns <b>TEE_ERROR_OUT_OF_MEMORY</b> if the memory is not sufficient to complete the operation. 232 * 233 * @since 20 234 */ 235 TEE_Result TEE_ReadObjectData(TEE_ObjectHandle object, void *buffer, size_t size, uint32_t *count); 236 237 /** 238 * @brief Writes bytes from the buffer to the data stream associated with an object. 239 * 240 * The <b>TEE_ObjectHandle</b> must have been opened with the <b>TEE_DATA_FLAG_ACCESS_WRITE</b> permission. 241 * 242 * @param object Indicates the <b>TEE_ObjectHandle</b> of the object. 243 * @param buffer Indicates the pointer to the buffer that stores the data to be written. 244 * @param size Indicates the number of bytes to be written. It cannot exceed 4096 bytes. 245 * 246 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 247 * Returns <b>TEE_ERROR_OUT_OF_MEMORY</b> if the memory is not sufficient to complete the operation. 248 * Returns <b>TEE_ERROR_STORAGE_NO_SPACE</b> if the storage space is not sufficient to complete the operation. 249 * 250 * @since 20 251 */ 252 TEE_Result TEE_WriteObjectData(TEE_ObjectHandle object, const void *buffer, size_t size); 253 254 /** 255 * @brief Changes the size of a data stream. 256 * 257 * If the size is less than the current size of the data stream, all bytes beyond <b>size</b> are deleted. If the size 258 * is greater than the current size of the data stream, add 0s at the end of the stream to extend the stream. 259 * The object handle must be opened with the <b>TEE_DATA_FLAG_ACCESS_WRITE</b> permission. 260 * 261 * @param object Indicates the <b>TEE_ObjectHandle</b> of the object. 262 * @param size Indicates the new size of the data stream. It cannot exceed 4096 bytes. 263 * 264 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 265 * Returns <b>TEE_ERROR_STORAGE_NO_SPACE</b> if the storage space is not sufficient to complete the operation. 266 * 267 * @since 20 268 */ 269 TEE_Result TEE_TruncateObjectData(TEE_ObjectHandle object, size_t size); 270 271 /** 272 * @brief Sets the position of the data stream to which <b>TEE_ObjectHandle</b> points. 273 * 274 * The data position indicator is determined by the start position and an offset together. 275 * The <b>whence</b> parameter determines the start position. Its value is set in <b>TEE_Whence</b> as follows: 276 * <b>TEE_DATA_SEEK_SET = 0</b>: The start position is the beginning of the data stream. 277 * <b>TEE_DATA_SEEK_CUR</b>: The start position is the current position of the data stream. 278 * <b>TEE_DATA_SEEK_END</b>: The start position is the end of the data stream. 279 * If the parameter <b>offset</b> is a positive number, the data position is moved forward. 280 * If <b>offset</b> is a negative number, the data position is moved backward. 281 * 282 * @param object Indicates the <b>TEE_ObjectHandle</b> of the object. 283 * @param offset Indicates the number of bytes to move the data position. It cannot exceed 4096 bytes. 284 * @param whence Indicates the start position in the data stream to calculate the new position. 285 * 286 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 287 * Returns <b>TEE_ERROR_OVERFLOW</b> if the position indicator resulting from this operation 288 * is greater than <b>TEE_DATA_MAX_POSIT</b>. 289 * 290 * @since 20 291 */ 292 TEE_Result TEE_SeekObjectData(TEE_ObjectHandle object, int32_t offset, TEE_Whence whence); 293 294 /** 295 * @brief Synchronizes the opened <b>TEE_ObjectHandle</b> and the corresponding security attribute file to the disk. 296 * 297 * @param object Indicates the <b>TEE_ObjectHandle</b> of the object. 298 * 299 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 300 * 301 * @since 20 302 */ 303 TEE_Result TEE_SyncPersistentObject(TEE_ObjectHandle object); 304 305 /** 306 * @brief Changes the object identifier. 307 * 308 * The <b>TEE_ObjectHandle</b> must have been opened with the <b>TEE_DATA_FLAG_ACCESS_WRITE_META</b> permission. 309 * 310 * @param object Indicates the handle of the target object. 311 * @param newObjectID Indicates the pointer to the new object identifier. 312 * @param newObjectIDLen Indicates the length of the new object identifier. 313 * 314 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 315 * 316 * @since 20 317 */ 318 TEE_Result TEE_RenamePersistentObject(TEE_ObjectHandle object, void *newObjectID, size_t newObjectIDLen); 319 320 /** 321 * @brief Allocates a handle on an uninitialized object enumerator. 322 * 323 * @param obj_enumerator Indicates the pointer to the handle of the newly created object enumerator. 324 * 325 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 326 * Returns <b>TEE_ERROR_OUT_OF_MEMORY</b> if the memory is not sufficient to complete the operation. 327 * 328 * @since 20 329 */ 330 TEE_Result TEE_AllocatePersistentObjectEnumerator(TEE_ObjectEnumHandle *obj_enumerator); 331 332 /** 333 * @brief Releases all resources associated with an object enumerator handle. 334 * 335 * After this function is called, the object handle is no longer valid and all resources associated with 336 * the object enumerator handle will be reclaimed. 337 * <b>TEE_FreePersistentObjectEnumerator</b> and <b>TEE_AllocatePersistentObjectEnumerator</b>are used in pairs. 338 * 339 * @param obj_enumerator Indicates the <b>TEE_ObjectEnumHandle</b> to release. 340 * 341 * @since 20 342 */ 343 void TEE_FreePersistentObjectEnumerator(TEE_ObjectEnumHandle obj_enumerator); 344 345 /** 346 * @brief Resets an object enumerator handle to its initial state after allocation. 347 * 348 * @param obj_enumerator Indicates the <b>TEE_ObjectEnumHandle</b> of the object enumerator to reset. 349 * 350 * @since 20 351 */ 352 void TEE_ResetPersistentObjectEnumerator(TEE_ObjectEnumHandle obj_enumerator); 353 354 /** 355 * @brief Starts the enumeration of all the objects in the given trusted storage. 356 * 357 * The object information can be obtained by using <b>TEE_GetNextPersistentObject</b>. 358 * 359 * @param obj_enumerator Indicates the <b>TEE_ObjectEnumHandle</b> of the object enumerator. 360 * @param storage_id Indicates the storage, in which the objects are enumerated. 361 * The value is specified by <b>Object_Storage_Constants</b>. 362 * Currently, only <b>TEE_STORAGE_PRIVATE</b> is supported. 363 * 364 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 365 * Returns <b>TEE_ITEM_NOT_FOUND</b> if <b>storageID</b> is not <b>TEE_STORAGE_PRIVATE</b> 366 * or there is no object in the specified storage. 367 * 368 * @since 20 369 */ 370 TEE_Result TEE_StartPersistentObjectEnumerator(TEE_ObjectEnumHandle obj_enumerator, uint32_t storage_id); 371 372 /** 373 * @brief Obtains the next object in the object enumerator. 374 * 375 * Information such as <b>TEE_ObjectInfo</b>, <b>objectID</b>, and <b>objectIDLen</b> will be obtained. 376 * 377 * @param obj_enumerator Indicates the <b>TEE_ObjectEnumHandle</b> of the object enumerator. 378 * @param object_info Indicates the pointer to the obtained<b>TEE_ObjectInfo</b>. 379 * @param object_id Indicates the pointer to the buffer used to store the obtained <b>objectID</b>. 380 * @param object_id_len Indicates the pointer to the <b>objectIDLen</b>. 381 * 382 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 383 * Returns <b>TEE_ITEM_NOT_FOUND</b> if the object enumerator has no element 384 * or the enumerator has not been initialized. 385 * 386 * @since 20 387 */ 388 TEE_Result TEE_GetNextPersistentObject(TEE_ObjectEnumHandle obj_enumerator, 389 TEE_ObjectInfo *object_info, void *object_id, size_t *object_id_len); 390 391 /** 392 * @brief Closes a <b>TEE_ObjectHandle</b> and deletes the object. 393 * 394 * The object must be a persistent object, and the object handle must have been opened with 395 * the <b>TEE_DATA_FLAG_ACCESS_WRITE_META</b> permission. 396 * 397 * @param object Indicates the object handle to close. 398 * 399 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 400 * Returns <b>TEE_ERROR_STORAGE_NOT_AVAILABLE</b> if the object is stored 401 * in a storage area that is inaccessible currently. 402 * 403 * @since 20 404 */ 405 TEE_Result TEE_CloseAndDeletePersistentObject1(TEE_ObjectHandle object); 406 407 #ifdef __cplusplus 408 } 409 #endif 410 411 #endif 412 /** @} */