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_OBJECT_API_H 14 #define __TEE_OBJECT_API_H 15 16 #include "tee_defines.h" 17 18 /* 19 * Definition of HANDLE_NULL, invalid object handle 20 */ 21 #define TEE_HANDLE_NULL 0x00000000 22 23 /* 24 * The keyUsage of TEE_ObjectHandle determines the usage of the object key 25 */ 26 enum Usage_Constants { 27 TEE_USAGE_EXTRACTABLE = 0x00000001, /* The key of the object can be extracted */ 28 TEE_USAGE_ENCRYPT = 0x00000002, /* The key of the object can be used for encryption */ 29 TEE_USAGE_DECRYPT = 0x00000004, /* The key of the object can be used for decryption */ 30 TEE_USAGE_MAC = 0x00000008, /* The key of the object can be used for hash */ 31 TEE_USAGE_SIGN = 0x00000010, /* The key of the object can be used for signing */ 32 TEE_USAGE_VERIFY = 0x00000020, /* The key of the object can be used for verification */ 33 TEE_USAGE_DERIVE = 0x00000040, /* The key of the object can be used to derive */ 34 TEE_USAGE_DEFAULT = 0xFFFFFFFF, /* object initialization, all permissions are assigned by default */ 35 }; 36 37 /* 38 * The handleFlags of TEE_ObjectHandle indicate some information of the object, 39 * whether it is a permanent object, whether it is initialized, etc. 40 */ 41 enum Handle_Flag_Constants { 42 TEE_HANDLE_FLAG_PERSISTENT = 0x00010000, /* Persistent object */ 43 TEE_HANDLE_FLAG_INITIALIZED = 0x00020000, /* Object has been initialized */ 44 TEE_HANDLE_FLAG_KEY_SET = 0x00040000, /* Unused */ 45 TEE_HANDLE_FLAG_EXPECT_TWO_KEYS = 0x00080000, /* Unused */ 46 }; 47 48 /* 49 * List of attribute identifier flags 50 */ 51 #define TEE_ATTR_FLAG_VALUE 0x20000000 52 #define TEE_ATTR_FLAG_PUBLIC 0x10000000 53 54 #define TEE_ATTR_IS_BUFFER(attribute_id) ((((attribute_id) << 2) >> 31) == 0) 55 #define TEE_ATTR_IS_VALUE(attribute_id) ((((attribute_id) << 2) >> 31) == 1) 56 57 #define TEE_ATTR_IS_PROTECTED(attribute_id) ((((attribute_id) << 3) >> 31) == 0) 58 #define TEE_ATTR_IS_PUBLIC(attribute_id) ((((attribute_id) << 3) >> 31) == 1) 59 60 /* 61 * Get the buffer content of the union in the TEE_Attribute structure of the object pointed 62 * to by TEE_ObjectHandle, and the union member must be ref 63 * 64 * @attention The union member in the TEE_Attribute structure must be ref. If the TEE_Attribute is private, 65 * the Usage_Constants of the object must include TEE_USAGE_EXTRACTABLE 66 * @param object [IN] The source TEE_ObjectHandle 67 * @param attributeID [IN] The Attribute ID you want to obtain, such as TEE_ObjectAttribute, can also be customized 68 * @param buffer [OUT] Pointer, the buffer pointed to is used to store the contents of the obtained buffer 69 * @param size [INOUT] Pointer, storing content byte length 70 * 71 * @return TEE_SUCCESS Indicates that the function was executed successfully 72 * @return TEE_ERROR_ITEM_NOT_FOUND The TEE_Attribute you are looking for is not found in the object, 73 * or the object is not initialized 74 * @return TEE_ERROR_SHORT_BUFFER The provided buffer is too small to store the acquired content 75 */ 76 TEE_Result TEE_GetObjectBufferAttribute(TEE_ObjectHandle object, uint32_t attributeID, void *buffer, size_t *size); 77 78 /* 79 * Get the value of the union in the TEE_Attribute in the object, and the union member must be the value 80 * 81 * @attention The member of the union in the TEE_Attribute structure must be value. If the TEE_Attribute is private, 82 * the Usage_Constants of the object must include TEE_USAGE_EXTRACTABLE 83 * @param object [IN] The source TEE_ObjectHandle 84 * @param attributeID [IN] The Attribute ID you want to obtain, such as TEE_ObjectAttribute, can also be customized 85 * @param a [OUT] Pointer, the space pointed to is used to store a 86 * @param b [OUT] Pointer, the space pointed to is used to store b 87 * 88 * @return TEE_SUCCESS Indicates that the function was executed successfully 89 * @return TEE_ERROR_ITEM_NOT_FOUND The TEE_Attribute you are looking for is not found in the object, 90 * or the object is not initialized 91 * @return TEE_ERROR_ACCESS_DENIED Attempt to obtain a private TEE_Attribute but did not set TEE_USAGE_EXTRACTABLE 92 */ 93 TEE_Result TEE_GetObjectValueAttribute(TEE_ObjectHandle object, uint32_t attributeID, uint32_t *a, uint32_t *b); 94 95 /* 96 * Close the opened TEE_ObjectHandle, the object can be a persistent object or a transient object 97 * 98 * @param object [IN] TEE_ObjectHandle to be closed 99 * 100 * @return void 101 */ 102 void TEE_CloseObject(TEE_ObjectHandle object); 103 104 /* 105 * Allocate an uninitialized object to store the key, in which objectType and maxObjectSize 106 * must be specified to pre-allocate 107 * 108 * @param objectType [IN] The type of the object to be created, the value can be TEE_ObjectType 109 * @param maxObjectSize [IN] Maximum bytes of object 110 * @param object [OUT] Pointer to the handle of the newly created object 111 * 112 * @return TEE_SUCCESS Indicates that the function was executed successfully 113 * @return TEE_ERROR_OUT_OF_MEMORY Not enough to allocate 114 * @return TEE_ERROR_NOT_SUPPORTED The bytes provided by the object is not supported 115 */ 116 TEE_Result TEE_AllocateTransientObject(uint32_t objectType, uint32_t maxObjectSize, TEE_ObjectHandle *object); 117 118 /* 119 * Release a transient object that has allocated. After the function is called, the handle becomes invalid, 120 * and all allocated are released. Paired with TEE_AllocateTransientObject 121 * 122 * @param object [IN] TEE_ObjectHandle to be released 123 * 124 * @return void 125 */ 126 void TEE_FreeTransientObject(TEE_ObjectHandle object); 127 128 /* 129 * Reset the transient object to initial state, that is, the state just after the allocate. 130 * The uninitialized object that has allocated but has not stored the key can be reused to store the key 131 * 132 * @param object [IN] TEE_ObjectHandle to be reset 133 * 134 * @return void 135 */ 136 void TEE_ResetTransientObject(TEE_ObjectHandle object); 137 138 /* 139 * This function assigns the attributes in the parameter attrs to an uninitialized transient object, 140 * and the parameter attrs is provided by the trusted application (TA) 141 * 142 * @param object [IN/OUT] TEE_ObjectHandle created but not initialized 143 * @param attrs [IN] object attribute array, can be one or more TEE_Attribute 144 * @param attrCount [IN] Number of array members 145 * 146 * @return TEE_SUCCESS Indicates that the function was executed successfully 147 * @return TEE_ERROR_BAD_PARAMETERS The attribute is incorrect or inconsistent. 148 * Ensure that the object is still uninitialized 149 */ 150 TEE_Result TEE_PopulateTransientObject(TEE_ObjectHandle object, TEE_Attribute *attrs, uint32_t attrCount); 151 152 /* 153 * Initialize a buffer type TEE_Attribute, that is, the member of union in the TEE_Attribute structure must be ref 154 * 155 * @param attr [OUT] TEE_Attribute to be initialized 156 * @param attributeID [IN] ID assigned to TEE_Attribute 157 * @param buffer [IN] The buffer stores the content to be assigned 158 * @param length [IN] The byte length of the assignment content 159 * 160 * @return void 161 */ 162 void TEE_InitRefAttribute(TEE_Attribute *attr, uint32_t attributeID, void *buffer, size_t length); 163 164 /* 165 * Initialize a value type TEE_Attribute 166 * 167 * @param attr [OUT] TEE_Attribute to be initialized 168 * @param attributeID [IN] ID assigned to TEE_Attribute 169 * @param a [IN] Assign the value to the member value a of the union in the TEE_Attribute 170 * @param b [IN] Assign the value to the member value b of the union in the TEE_Attribute 171 * 172 * @return void 173 */ 174 void TEE_InitValueAttribute(TEE_Attribute *attr, uint32_t attributeID, uint32_t a, uint32_t b); 175 176 /* 177 * This function generates a random key or key-pair and assigns it to the transient object 178 * 179 * @param object [IN] Transient object, used to store the generated key 180 * @param keySize [IN] The bytes of the required key 181 * @param params [IN] Parameters required for key generation 182 * @param paramCount [IN] The number of parameters required to generate the key 183 * 184 * @return TEE_SUCCESS Indicates that the function was executed successfully 185 * @return TEE_ERROR_BAD_PARAMETERS The generated key is inconsistent with the key type 186 * that the transient object can store 187 */ 188 TEE_Result TEE_GenerateKey(TEE_ObjectHandle object, uint32_t keySize, TEE_Attribute *params, uint32_t paramCount); 189 190 /* 191 * Get the information of the object data part, the total length of the data part and the current 192 * position of the data stream 193 * 194 * @param object [IN] TEE_ObjectHandle to be obtained 195 * @param pos [out] Data stream position 196 * @param len [IN] Data stream length 197 * 198 * @return void 199 */ 200 TEE_Result TEE_InfoObjectData(TEE_ObjectHandle object, uint32_t *pos, uint32_t *len); 201 202 #if defined(API_LEVEL) && (API_LEVEL >= 2) 203 204 /* 205 * Obtain the TEE_ObjectInfo of the object and copy it to the space pointed 206 * to by the parameter objectInfo, which is pre-allocated by the user 207 * 208 * @param object [IN] Source TEE_ObjectHandle 209 * @param objectInfo [OUT] Pointer to the structure used to store the TEE_ObjectInfo 210 * 211 * @return TEE_SUCCESS Indicates that the function was executed successfully 212 * @return TEE_ERROR_CORRUPT_OBJECT The file is damaged and the file handle will be closed 213 * @return TEE_ERROR_STORAGE_NOT_AVAILABLE Cannot access the storage area where the file is located 214 */ 215 TEE_Result TEE_GetObjectInfo1(TEE_ObjectHandle object, TEE_ObjectInfo *objectInfo); 216 217 /* 218 * This function uses an initialized object to assign TEE_Attribute to an uninitialized object, 219 * which is equivalent to copying the TEE_Attribute of srcobject to destobject 220 * 221 * @attention The TEE_Attribute type and number of the two objects must match 222 * @param destObject [IN] The uninitialized TEE_ObjectHandle to be assigned 223 * @param srcObject [IN] The initialized TEE_ObjectHandle is used to assign a value to another object 224 * 225 * @return TEE_SUCCESS Indicates that the function was executed successfully 226 * @return TEE_ERROR_CORRUPT_OBJECT The file is damaged and the file handle will be closed 227 * @return TEE_ERROR_STORAGE_NOT_AVAILABLE Cannot access the storage area where the file is located 228 */ 229 TEE_Result TEE_CopyObjectAttributes1(TEE_ObjectHandle destObject, TEE_ObjectHandle srcObject); 230 231 /* 232 * Limit the objectUsage bit of the object. This bit determines the usage of the key in the object. 233 * The value range is Usage_Constants. For the flag bit of the parameter objectUsage: 234 * If this bit is set to 1, the use flag of object will not be changed 235 * If this bit is set to 0, the corresponding object usage flag of the object is cleared 236 * 237 * @attention The newly created object will contain all Usage_Constants, and the usage flag can 238 * only be cleared, not set 239 * @param object [IN] Need to restrict TEE_ObjectHandle 240 * @param objectUsage [IN] ObjectUsage users want to change 241 * 242 * @return TEE_SUCCESS Indicates that the function was executed successfully 243 * @return TEE_ERROR_CORRUPT_OBJECT The file is damaged and the file handle will be closed 244 * @return TEE_ERROR_STORAGE_NOT_AVAILABLE Cannot access the storage area where the file is located 245 */ 246 TEE_Result TEE_RestrictObjectUsage1(TEE_ObjectHandle object, uint32_t objectUsage); 247 248 #endif /* API_LEVEL */ 249 #endif 250