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_TRUSTED_STORAGE_API_H 14 #define __TEE_TRUSTED_STORAGE_API_H 15 16 #include "tee_defines.h" 17 #include "tee_object_api.h" 18 19 /* 20 * Data stream positioning start position option, used in TEE_SeekObjectData function 21 */ 22 enum __TEE_Whence { 23 TEE_DATA_SEEK_SET = 0, /* Position the starting position as the beginning of the data stream */ 24 TEE_DATA_SEEK_CUR, /* Position the starting position as the current data stream position */ 25 TEE_DATA_SEEK_END /* Position the starting position at the end of the data stream */ 26 }; 27 28 struct __TEE_ObjectEnumHandle; 29 typedef struct __TEE_ObjectEnumHandle *TEE_ObjectEnumHandle; 30 31 typedef uint32_t TEE_Whence; 32 33 /* 34 * Storage ID, which defines the storage space of the corresponding application 35 */ 36 enum Object_Storage_Constants { 37 TEE_OBJECT_STORAGE_PRIVATE = 0x00000001, /* Separate private storage space for each application */ 38 TEE_OBJECT_STORAGE_PERSO = 0x00000002, /* Separate perso storage space for application */ 39 TEE_OBJECT_STORAGE_CE = 0x80000002, /* Add for storage ce */ 40 }; 41 42 /* 43 * System resource constraints, such as the maximum value that the data stream position indicator can take 44 */ 45 enum Miscellaneous_Constants { 46 TEE_DATA_MAX_POSITION = 0xFFFFFFFF, /* The maximum length that the position indicator of the data stream can take */ 47 TEE_OBJECT_ID_MAX_LEN = 64, /* The maximum length of objectID, which actually extends to 128 bytes */ 48 }; 49 50 /* 51 * The maximum number of bytes of data that the data stream can store 52 */ 53 enum TEE_DATA_Size { 54 TEE_DATA_OBJECT_MAX_SIZE = 0xFFFFFFFF /* The maximum bytes of data that the object data stream can store */ 55 }; 56 57 /* 58 * The handleFlags of TEE_ObjectHandle determines the access authority of 59 * the TEE_ObjectHandle to the object data stream 60 */ 61 enum Data_Flag_Constants { 62 /* Have read permission to the data stream, and can read */ 63 TEE_DATA_FLAG_ACCESS_READ = 0x00000001, 64 /* Have write permission to the data stream, and can write and truncate */ 65 TEE_DATA_FLAG_ACCESS_WRITE = 0x00000002, 66 /* Have WRITE_META permission for data stream, and can delete and rename operation */ 67 TEE_DATA_FLAG_ACCESS_WRITE_META = 0x00000004, 68 /* 69 * Have shared read permissions on the data stream, you can open multiple 70 * TEE_ObjectHandles for concurrent reading 71 */ 72 TEE_DATA_FLAG_SHARE_READ = 0x00000010, 73 /* 74 * Have shared write permissions for the data stream, and multiple TEE_ObjectHandles 75 * can be opened for concurrent writing 76 */ 77 TEE_DATA_FLAG_SHARE_WRITE = 0x00000020, 78 /* Unused */ 79 TEE_DATA_FLAG_CREATE = 0x00000200, 80 /* 81 * Protect an existing file with the same name. If the file with the same name does not exist, 82 * create a new data file; if the file with the same name exists, an error will be reported. 83 * Used in GP v1.1, deprecated in GP v1.2 84 */ 85 TEE_DATA_FLAG_EXCLUSIVE = 0x00000400, 86 /* 87 * Protect an existing file with the same name. If the file with the same name does not exist, 88 * create a new data file; if the file with the same name exists, an error will be reported. 89 * Used in GP v1.2 90 */ 91 TEE_DATA_FLAG_OVERWRITE = 0x00000400, 92 /* 93 * If the bit27 is set to 1, it means deriving the 32-bytes TA root key at one time, 94 * if it is 0, it means deriving two 16-bytes TA root keys and combined them together 95 */ 96 TEE_DATA_FLAG_DERIVE_32BYTES_KEY_ONCE = 0x08000000, 97 /* If bit28 is set to 1, it means AES256, if it is 0, it means AES128 */ 98 TEE_DATA_FLAG_AES256 = 0x10000000, 99 /* If bit29 is set to 1, it means that the lower version will be opened first */ 100 TEE_DATA_FLAG_OPEN_AESC = 0x20000000, 101 }; 102 103 /* 104 * Create a new persistent object, you can directly initialize the data stream and TEE_Attribute, 105 * the user can use the returned handle to access the object's TEE_Attribute and data stream 106 * 107 * @param storageID [IN] Corresponding to a separate storage space for each application, 108 * the value is Object_Storage_Constants 109 * @param objectID [IN] Object identifier, the name of the object to be created 110 * @param objectIDLen [IN] The length of the object identifier by byte, no more than 128 bytes 111 * @param flags [IN] Flags after object creation, the value can be one or more of Data_Flag_Constants 112 * or Handle_Flag_Constants 113 * @param attributes [IN] The TEE_ObjectHandle of the transient object, used to initialize the 114 * TEE_Attribute of the object, can be TEE_HANDLE_NULL 115 * @param initialData [IN] Initial data, used to initialize data stream data 116 * @param initialDataLen [IN] InitialData length in byte 117 * @param object [OUT] TEE_ObjectHandle returned after the function is successfully executed 118 * 119 * @return TEE_SUCCESS Indicates that the function was executed successfully 120 * @return TEE_ERROR_ITEM_NOT_FOUND: The storageID does not exist 121 * @return TEE_ERROR_ACCESS_CONFLICT Access conflict 122 * @return TEE_ERROR_OUT_OF_MEMORY Insufficient memory to complete the operation 123 * @return TEE_ERROR_STORAGE_NO_SPACE There is not enough space to create the object 124 */ 125 TEE_Result TEE_CreatePersistentObject(uint32_t storageID, const void *ojbectID, size_t objectIDLen, uint32_t flags, 126 TEE_ObjectHandle attributes, const void *initialData, size_t initialDataLen, 127 TEE_ObjectHandle *object); 128 129 /* 130 * Open an existing permanent object, the returned handle can be used by the user to access 131 * the object's TEE_Attribute and data stream 132 * 133 * @param storageID [IN] orresponding to a separate storage space for each application, 134 * the value is Object_Storage_Constants 135 * @param objectID [IN] object identifier, the name of the object to be opened 136 * @param objectIDLen [IN] The length of the object identifier by byte, no more than 128 bytes 137 * @param flags [IN] Flags after object opened, the value can be one or more of 138 * Data_Flag_Constants or Handle_Flag_Constants 139 * @param object [OUT] TEE_ObjectHandle returned after the function is successfully executed 140 * 141 * @return TEE_SUCCESS Indicates that the function was executed successfully 142 * @return TEE_ERROR_ITEM_NOT_FOUND: The storageID does not exist or cannot find object identifier 143 * @return TEE_ERROR_ACCESS_CONFLICT Access conflict 144 * @return TEE_ERROR_OUT_OF_MEMORY Insufficient memory to complete the operation 145 */ 146 TEE_Result TEE_OpenPersistentObject(uint32_t storageID, const void *ojbectID, size_t objectIDLen, uint32_t flags, 147 TEE_ObjectHandle *object); 148 149 /* 150 * Read size bytes of data from the object's data stream to the buffer, 151 * the TEE_ObjectHandle must have been opened with TEE_DATA_FLAG_ACCESS_READ permission 152 * 153 * @param objbect [IN] The TEE_ObjectHandle to be read 154 * @param buffer [OUT] Buffer for storing read data 155 * @param size [IN] Size of data to be read by byte 156 * @param count [OUT] Size of data actually read by byte 157 * 158 * @return TEE_SUCCESS Indicates that the function was executed successfully 159 * @return TEE_ERROR_OUT_OF_MEMORY Insufficient memory to complete the operation 160 */ 161 TEE_Result TEE_ReadObjectData(TEE_ObjectHandle ojbect, void *buffer, size_t size, uint32_t *count); 162 163 /* 164 * Write size bytes of data from the buffer to the data stream of the object. 165 * TEE_ObjectHandle must have been opened with TEE_DATA_FLAG_ACCESS_WRITE permission 166 * 167 * @param ojbect [IN] The TEE_ObjectHandle to be write 168 * @param buffer [IN] Store the data to be written 169 * @param size [IN] The length of the data to be written, the size does not exceed 4096 bytes 170 * 171 * @return TEE_SUCCESS Indicates that the function was executed successfully 172 * @return TEE_ERROR_OUT_OF_MEMORY Insufficient memory to complete the operation 173 * @return TEE_ERROR_STORAGE_NO_SPACE There is not enough space to perform the operation 174 */ 175 TEE_Result TEE_WriteObjectData(TEE_ObjectHandle ojbect, const void *buffer, size_t size); 176 177 /* 178 * This function changes the size of the data stream. If the size is smaller than the size of 179 * the current data stream, delete all excess bytes. If size is greater than the size of the 180 * current data stream, use '0' to expand 181 * TEE_ObjectHandle must be opened with TEE_DATA_FLAG_ACCESS_WRITE permission 182 * 183 * @param object [IN] TEE_ObjectHandle to be truncated 184 * @param size [IN] The new length of the data stream, the size does not exceed 4096 bytes 185 * 186 * @return TEE_SUCCESS Indicates that the function was executed successfully 187 * @return TEE_ERROR_STORAGE_NO_SPACE There is not enough space to perform the operation 188 */ 189 TEE_Result TEE_TruncateObjectData(TEE_ObjectHandle object, size_t size); 190 191 /* 192 * Set the data stream position pointed to by TEE_ObjectHandle, and set the data stream position to: 193 * start position + offset 194 * The parameter whence controls the starting position of the offset, the value can choose in TEE_Whence, 195 * and the meaning is as follows: 196 * TEE_DATA_SEEK_SET, the starting position of the data stream offset is the file header, which is 0 197 * TEE_DATA_SEEK_CUR, the starting position of the data stream offset is the current position 198 * TEE_DATA_SEEK_END, the starting position of the data stream offset is the end of the file 199 * When the parameter offset is a positive number, it is offset backward, and when it is negative, it is offset forward. 200 * 201 * @param object [IN] TEE_ObjectHandle to be set 202 * @param offset [IN] The size of the data stream position movement, the size does not exceed 4096 bytes 203 * @param whence [IN] The initial position of the data stream offset 204 * 205 * @return TEE_SUCCESS Indicates that the function was executed successfully 206 * @return TEE_ERROR_OVERFLOW The operation causes the value of the position indicator to exceed its 207 * system limit TEE_DATA_MAX_POSITION 208 */ 209 TEE_Result TEE_SeekObjectData(TEE_ObjectHandle object, int32_t offset, TEE_Whence whence); 210 211 /* 212 * Close the opened TEE_ObjectHandle and delete the object. The object must be a persistent object 213 * and must have been opened with TEE_DATA_FLAG_ACCESS_WRITE_META permission 214 * 215 * @param object [IN] TEE_ObjectHandle to be closed and deleted 216 * 217 * @return void 218 */ 219 void TEE_CloseAndDeletePersistentObject(TEE_ObjectHandle object); 220 221 /* 222 * Synchronize the opened TEE_ObjectHandle, and synchronize the corresponding security attribute files to the disk 223 * 224 * @param object [IN] TEE_ObjectHandle to be synchronized 225 * 226 * @return TEE_SUCCESS Indicates that the function was executed successfully 227 */ 228 TEE_Result TEE_SyncPersistentObject(TEE_ObjectHandle object); 229 230 /* 231 * Change the object identifier, the TEE_ObjectHandle must be opened with TEE_DATA_FLAG_ACCESS_WRITE_META permission 232 * 233 * @param ojbect [IN/OUT] The object handle to be modified 234 * @param newObjectID [IN] New object identifier 235 * @param newObjectIDLen [IN] New object identifier length 236 * 237 * @return TEE_SUCCESS Indicates that the function was executed successfully 238 */ 239 TEE_Result TEE_RenamePersistentObject(TEE_ObjectHandle object, void *newObjectID, size_t newObjectIDLen); 240 241 /* 242 * Allocate the handle of an uninitialized object enumerator 243 * 244 * @param object [OUT] Pointer to the handle of the newly created object enumerator 245 * 246 * @return TEE_SUCCESS Indicates that the function was executed successfully 247 * @return TEE_ERROR_OUT_OF_MEMORY No enough memory to allocate 248 */ 249 TEE_Result TEE_AllocatePersistentObjectEnumerator(TEE_ObjectEnumHandle *obj_enumerator); 250 251 /* 252 * Release a object enumerator handle that has allocated. The handle becomes invalid after the function is called, 253 * and all allocated are released. Use it in pair with TEE_AllocatePersistentObjectEnumerator 254 * 255 * @param object [IN] TEE_ObjectEnumHandle to be released 256 * 257 * @return void 258 */ 259 void TEE_FreePersistentObjectEnumerator(TEE_ObjectEnumHandle obj_enumerator); 260 261 /* 262 * Reset the temporary object enumerator to its initial state, that is, the state just after the allocate 263 * 264 * @param object [IN] TEE_ObjectEnumHandle of the object enumerator to be reset 265 * 266 * @return void 267 */ 268 void TEE_ResetPersistentObjectEnumerator(TEE_ObjectEnumHandle obj_enumerator); 269 270 /* 271 * Start enumerating all objects in a given storage space, the information of the object can be obtained 272 * through the TEE_GetNextPersistentObject function 273 * 274 * @param object [IN] TEE_ObjectEnumHandle of the allocated object enumerator 275 * @param storageID [IN] Correspond to a separate storage space for each application, the value is 276 * Object_Storage_Constants, currently only supports TEE_STORAGE_PRIVATE 277 * 278 * @return TEE_SUCCESS Indicates that the function was executed successfully 279 * @return TEE_ITEM_NOT_FOUND storageID is not TEE_STORAGE_PRIVATE or there is no object in the storage space 280 */ 281 TEE_Result TEE_StartPersistentObjectEnumerator(TEE_ObjectEnumHandle obj_enumerator, uint32_t storage_id); 282 283 /* 284 * Get the next object in the object enumerator, and return the object's TEE_ObjectInfo, objectID, 285 * objectIDLen information 286 * 287 * @param object [IN] TEE_ObjectEnumHandle of the initialized object enumerator 288 * @param objectInfo [OUT] Pointer to the structure used to store the obtained TEE_ObjectInfo 289 * @param objectInfo [OUT] Pointer to a buffer, used to store the obtained objectID 290 * @param objectInfo [OUT] Used to store the obtained objectIDLen 291 * 292 * @return TEE_SUCCESS Indicates that the function was executed successfully 293 * @return TEE_ITEM_NOT_FOUND The enumerator has no object or the enumerator has not been initialized 294 */ 295 TEE_Result TEE_GetNextPersistentObject(TEE_ObjectEnumHandle obj_enumerator, 296 TEE_ObjectInfo *object_info, void *object_id, size_t *object_id_len); 297 298 #if defined(API_LEVEL) && (API_LEVEL >= 2) 299 300 /* 301 * Close the opened TEE_ObjectHandle and delete the object. The object must be a persistent object 302 * and must have been opened with TEE_DATA_FLAG_ACCESS_WRITE_META permission 303 * 304 * @param object [IN] TEE_ObjectHandle to be closed and deleted 305 * 306 * @return TEE_SUCCESS Indicates that the function was executed successfully 307 * @return TEE_ERROR_STORAGE_NOT_AVAILABLE Cannot access the storage area where the file is located 308 */ 309 TEE_Result TEE_CloseAndDeletePersistentObject1(TEE_ObjectHandle object); 310 311 #endif // API_LEVEL 312 #endif 313