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