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_object_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_OBJECT_API_H 41 #define __TEE_OBJECT_API_H 42 43 #include "tee_defines.h" 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @brief Defines <b>HANDLE_NULL</b>, which is used to denote the absence of a handle. 51 * 52 * @since 20 53 */ 54 #define TEE_HANDLE_NULL 0x00000000 55 56 /** 57 * @brief Enumerates the usages of the key of the <b>TEE_ObjectHandle</b>. 58 * 59 * @since 20 60 */ 61 enum Usage_Constants { 62 /** The object's key is extractable. */ 63 TEE_USAGE_EXTRACTABLE = 0x00000001, 64 /** Used for encryption. */ 65 TEE_USAGE_ENCRYPT = 0x00000002, 66 /** Used for decryption. */ 67 TEE_USAGE_DECRYPT = 0x00000004, 68 /** Used for hash calculation. */ 69 TEE_USAGE_MAC = 0x00000008, 70 /** Used for creating a signature. */ 71 TEE_USAGE_SIGN = 0x00000010, 72 /** Used for signature verification. */ 73 TEE_USAGE_VERIFY = 0x00000020, 74 /** Used for key derivation. */ 75 TEE_USAGE_DERIVE = 0x00000040, 76 /** Used for object initialization, with all permissions assigned by default. */ 77 TEE_USAGE_DEFAULT = 0xFFFFFFFF, 78 }; 79 80 /** 81 * @brief Defines information about the object pointed to by the flag of the <b>TEE_ObjectHandle</b>, 82 * for example, whether the object is a persistent object or is initialized. 83 * 84 * @since 20 85 */ 86 enum Handle_Flag_Constants { 87 /** The object is a persistent object. */ 88 TEE_HANDLE_FLAG_PERSISTENT = 0x00010000, 89 /** The object is initialized. */ 90 TEE_HANDLE_FLAG_INITIALIZED = 0x00020000, 91 /** The object is a key set. */ 92 TEE_HANDLE_FLAG_KEY_SET = 0x00040000, 93 /** The object is expected to have two keys. */ 94 TEE_HANDLE_FLAG_EXPECT_TWO_KEYS = 0x00080000, 95 }; 96 97 /** 98 * @brief Defines a value attribute identifier flag. 99 * 100 * @since 20 101 */ 102 #define TEE_ATTR_FLAG_VALUE 0x20000000 103 104 /** 105 * @brief Defines a public attribute identifier flag. 106 * 107 * @since 20 108 */ 109 #define TEE_ATTR_FLAG_PUBLIC 0x10000000 110 111 /** 112 * @brief Check whether the attribute is a buffer. 113 * 114 * @since 20 115 */ 116 #define TEE_ATTR_IS_BUFFER(attribute_id) ((((attribute_id) << 2) >> 31) == 0) 117 118 /** 119 * @brief Check whether the attribute is a value. 120 * 121 * @since 20 122 */ 123 #define TEE_ATTR_IS_VALUE(attribute_id) ((((attribute_id) << 2) >> 31) == 1) 124 125 /** 126 * @brief Check whether the attribute is protected. 127 * 128 * @since 20 129 */ 130 #define TEE_ATTR_IS_PROTECTED(attribute_id) ((((attribute_id) << 3) >> 31) == 0) 131 132 /** 133 * @brief Check whether the attribute is public. 134 * 135 * @since 20 136 */ 137 #define TEE_ATTR_IS_PUBLIC(attribute_id) ((((attribute_id) << 3) >> 31) == 1) 138 139 /** 140 * @brief Obtains a buffer attribute from the <b>TEE_Attribute</b> struct of the object pointed 141 * to by <b>TEE_ObjectHandle</b>. 142 * 143 * The members in the <b>TEE_Attribute</b> struct must be <b>ref</b>. If the <b>TEE_Attribute</b> is private, 144 * the <b>Usage_Constants</b> of the object must include <b>TEE_USAGE_EXTRACTABLE</b>. 145 * 146 * @param object Indicates the handle of the object. 147 * @param attributeID Indicates the ID of the attribute to obtain, for example, <b>TEE_ObjectAttribute</b>. 148 * The attribute ID can also be customized. 149 * @param buffer Indicates the pointer to the buffer that stores the attribute obtained. 150 * @param size Indicates the pointer to the length of the content stored. 151 * 152 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 153 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the <b>TEE_Attribute</b> cannot be found in the object 154 * or the object is not initialized. 155 * @return Returns <b>TEE_ERROR_SHORT_BUFFER</b> if the buffer is too small to store the content obtained. 156 * 157 * @since 20 158 */ 159 TEE_Result TEE_GetObjectBufferAttribute(TEE_ObjectHandle object, uint32_t attributeID, void *buffer, size_t *size); 160 161 /** 162 * @brief Obtains a value attribute from the <b>TEE_Attribute</b> of an object. 163 * 164 * The members of the <b>TEE_Attribute</b> struct must be values. If the <b>TEE_Attribute</b> is private, 165 * the <b>Usage_Constants</b> of the object must include <b>TEE_USAGE_EXTRACTABLE</b>. 166 * 167 * @param object Indicates the handle of the object. 168 * @param attributeID Indicates the ID of the attribute to obtain, for example, <b>TEE_ObjectAttribute</b>. 169 * The attribute ID can also be customized. 170 * @param a Indicates the pointer to the placeholder filled with the attribute field <b>a</b>. 171 * @param b Indicates the pointer to the placeholder filled with the attribute field <b>b</b>. 172 * 173 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 174 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the <b>TEE_Attribute</b> cannot be found in the object 175 * or the object is not initialized. 176 * @return Returns <b>TEE_ERROR_ACCESS_DENIED</b> if <b>TEE_Attribute</b> is private 177 * but the object <b>Usage_Constants</b> does not contain the <b>TEE_USAGE_EXTRACTABLE</b> flag. 178 * 179 * @since 20 180 */ 181 TEE_Result TEE_GetObjectValueAttribute(TEE_ObjectHandle object, uint32_t attributeID, uint32_t *a, uint32_t *b); 182 183 /** 184 * @brief Closes a <b>TEE_ObjectHandle</b> object. 185 * 186 * The object can be persistent or transient. 187 * 188 * @param object Indicates the <b>TEE_ObjectHandle</b> object to close. 189 * 190 * @since 20 191 */ 192 void TEE_CloseObject(TEE_ObjectHandle object); 193 194 /** 195 * @brief Allocates an uninitialized object to store keys. 196 * 197 * <b>objectType</b> and <b>maxObjectSize</b> must be specified. 198 * 199 * @param objectType Indicates the type of the object to create. The value is <b>TEE_ObjectType</b>. 200 * @param maxObjectSize Indicates the maximum number of bytes of the object. 201 * @param object Indicates the pointer to the handle of the newly created object. 202 * 203 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 204 * @return Returns <b>TEE_ERROR_OUT_OF_MEMORY</b> if the memory is insufficient. 205 * @return Returns <b>TEE_ERROR_NOT_SUPPORTED</b> if the object type is not supported. 206 * 207 * @since 20 208 */ 209 TEE_Result TEE_AllocateTransientObject(uint32_t objectType, uint32_t maxObjectSize, TEE_ObjectHandle *object); 210 211 /** 212 * @brief Releases a transient object that is previously allocated with <b>TEE_AllocateTransientObject</b>. 213 * 214 * After the function is called, the handle becomes invalid and all allocated resources are released. 215 * <b>TEE_FreeTransientObject</b> and <b>TEE_AllocateTransientObject</b> are used in pairs. 216 * 217 * @param object Indicates the <b>TEE_ObjectHandle</b> to release. 218 * 219 * @since 20 220 */ 221 void TEE_FreeTransientObject(TEE_ObjectHandle object); 222 223 /** 224 * @brief Resets a transient object to its initial state after allocation. 225 * 226 * You can use an allocated object, which has not been initialized or used to store a key, to store a key. 227 * 228 * @param object Indicates the <b>TEE_ObjectHandle</b> to reset. 229 * 230 * @since 20 231 */ 232 void TEE_ResetTransientObject(TEE_ObjectHandle object); 233 234 /** 235 * @brief Populates an uninitialized object with object attributes passed by the TA in the <b>attrs</b> parameter. 236 * 237 * The object must be uninitialized. \n 238 * The <b>attrs</b> parameter is passed by a TA. 239 * 240 * @param object Indicates the handle on a created but uninitialized object. 241 * @param attrs Indicates the pointer to an array of object attributes, which can be one or more <b>TEE_Attribute</b>s. 242 * @param attrCount Indicates the number of members in the attribute array. 243 * 244 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 245 * @return Returns <b>TEE_ERROR_BAD_PARAMETERS</b> if an incorrect or inconsistent attribute value is detected. 246 * 247 * @since 20 248 */ 249 TEE_Result TEE_PopulateTransientObject(TEE_ObjectHandle object, TEE_Attribute *attrs, uint32_t attrCount); 250 251 /** 252 * @brief Initializes the <b>TEE_Attribute</b> of the buffer type. 253 * 254 * The members in the <b>TEE_Attribute</b> struct must be <b>ref</b>. 255 * 256 * @param attr Indicates the pointer to the <b>TEE_Attribute</b> initialized. 257 * @param attributeID Indicates the ID assigned to the <b>TEE_Attribute</b>. 258 * @param buffer Indicates the pointer to the buffer that stores the content to be allocated. 259 * @param length Indicates the length of the assigned value, in bytes. 260 * 261 * @since 20 262 */ 263 void TEE_InitRefAttribute(TEE_Attribute *attr, uint32_t attributeID, void *buffer, size_t length); 264 265 /** 266 * @brief Initializes a <b>TEE_Attribute</b>. 267 * 268 * @param attr Indicates the pointer to the <b>TEE_Attribute</b> initialized. 269 * @param attributeID Indicates the ID assigned to the <b>TEE_Attribute</b>. 270 * @param a Indicates the value to be assigned to the member <b>a</b> in the <b>TEE_Attribute</b>. 271 * @param b Indicates the value to be assigned to the member <b>b</b> in the <b>TEE_Attribute</b>. 272 * 273 * @since 20 274 */ 275 void TEE_InitValueAttribute(TEE_Attribute *attr, uint32_t attributeID, uint32_t a, uint32_t b); 276 277 /** 278 * @brief Generates a random key or a key pair and populates a transient key object with the generated key. 279 * 280 * @param object Indicates a transient object used to hold the generated key. 281 * @param keySize Indicates the number of bytes of the key. 282 * @param params Indicates the pointer to the parameters for key generation. 283 * @param paramCount Indicates the number of parameters required for key generation. 284 * 285 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 286 * @return Returns <b>TEE_ERROR_BAD_PARAMETERS</b> if the type of the key generated does not match 287 * the key that can be held in the transient object. 288 * 289 * @since 20 290 */ 291 TEE_Result TEE_GenerateKey(TEE_ObjectHandle object, uint32_t keySize, TEE_Attribute *params, uint32_t paramCount); 292 293 /** 294 * @brief Get the information of the object data part, the total length of the data part and the current 295 * position of the data stream. 296 * 297 * @param object Indicates the handle of the object. 298 * @param pos Indicates the data stream position. 299 * @param len Indicates the data stream length. 300 * 301 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 302 * @return Returns others if the operation is failed. 303 * 304 * @since 20 305 */ 306 TEE_Result TEE_InfoObjectData(TEE_ObjectHandle object, uint32_t *pos, uint32_t *len); 307 308 /** 309 * @brief Obtains <b>TEE_ObjectInfo</b>. 310 * 311 * This function obtains <b>TEE_ObjectInfo</b> and copies the obtained information to the pre-allocated space 312 * pointed to by <b>objectInfo</b>. 313 * 314 * @param object Indicates the handle of the object. 315 * @param objectInfo Indicates the pointer to the <b>TEE_ObjectInfo</b> obtained. 316 * 317 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 318 * @return Returns <b>TEE_ERROR_CORRUPT_OBJECT</b> if the object is corrupted and the object handle will be closed. 319 * @return Returns <b>TEE_ERROR_STORAGE_NOT_AVAILABLE</b> if the object is stored 320 * in a storage area that is inaccessible currently. 321 * 322 * @since 20 323 */ 324 TEE_Result TEE_GetObjectInfo1(TEE_ObjectHandle object, TEE_ObjectInfo *objectInfo); 325 326 /** 327 * @brief Assigns the <b>TEE_Attribute</b> of an initialized object to an uninitialized object. 328 * 329 * This function populates an uninitialized object with <b>TEE_Attribute</b>. 330 * That is, it copies <b>TEE_Attribute</b> of <b>srcobject</b> to <b>destobject</b>. 331 * The <b>TEE_Attribute</b> types and IDs of the two objects must match. 332 * 333 * @param destObject Indicates the uninitialized object. 334 * @param srcObject Indicates the initialized object. 335 * 336 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 337 * @return Returns <b>TEE_ERROR_CORRUPT_OBJECT</b> if the object is corrupted and the object handle will be closed. 338 * @return Returns <b>TEE_ERROR_STORAGE_NOT_AVAILABLE</b> if the object is stored 339 * in a storage area that is inaccessible currently. 340 * 341 * @since 20 342 */ 343 TEE_Result TEE_CopyObjectAttributes1(TEE_ObjectHandle destObject, TEE_ObjectHandle srcObject); 344 345 /** 346 * @brief Restricts the <b>objectUse</b> bit of an object. 347 * 348 * This bit determines the usage of the key in the object. The value range is <b>Usage_Constant</b>. 349 * The bit in the <b>objectUse</b> parameter can be set as follows: \n 350 * If it is set to <b>1</b>, the corresponding usage flag in the object is left unchanged. \n 351 * If it is set to <b>0</b>, the corresponding usage flag in the object is cleared. \n 352 * The newly created object contains all <b>Usage_Constant</b>, and the usage flag can be cleared only. 353 * 354 * @param object Indicates the <b>TEE_ObjectHandle</b> of the target object. 355 * @param objectUsage Indicates the new object usage. 356 * 357 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 358 * @return Returns <b>TEE_ERROR_CORRUPT_OBJECT</b> if the object is corrupted and the object handle will be closed. 359 * @return Returns <b>TEE_ERROR_STORAGE_NOT_AVAILABLE</b> if the object is stored 360 * in a storage area that is inaccessible currently. 361 * 362 * @since 20 363 */ 364 TEE_Result TEE_RestrictObjectUsage1(TEE_ObjectHandle object, uint32_t objectUsage); 365 #ifdef __cplusplus 366 } 367 #endif 368 369 #endif 370 /** @} */