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_property_api.h 29 * 30 * @brief Reference of TEE object api definitions. 31 * 32 * @library NA 33 * @kit TEEKit 34 * @syscap SystemCapability.Tee.TeeClient 35 * @since 20 36 */ 37 38 #ifndef TEE_PROPERTY_API_H 39 #define TEE_PROPERTY_API_H 40 41 #include "tee_defines.h" 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** 48 * @brief Enumerates the types of the property set. 49 * 50 * @since 20 51 */ 52 typedef enum { 53 /** Unknown property set type. */ 54 TEE_PROPSET_UNKNOW = 0, 55 /** Property set type for TEE implementation. */ 56 TEE_PROPSET_TEE_IMPLEMENTATION = 0xFFFFFFFD, 57 /** Property set type for the current client. */ 58 TEE_PROPSET_CURRENT_CLIENT = 0xFFFFFFFE, 59 /** Property set type for the current Trusted Application (TA). */ 60 TEE_PROPSET_CURRENT_TA = 0xFFFFFFFF, 61 } Pseudo_PropSetHandle; 62 63 /** 64 * @brief Defines the property set handle type. 65 * 66 * @since 20 67 */ 68 typedef uint32_t TEE_PropSetHandle; 69 70 /** 71 * @brief Obtains a property from a property set and converts its value into a printable string. 72 * 73 * 74 * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator. 75 * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain. 76 * @param valueBuffer Indicates the pointer to the buffer for holding the property value obtained. 77 * @param valueBufferLen Indicates the pointer to the buffer length. 78 * 79 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 80 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the target property cannot be obtained. 81 * @return Returns <b>TEE_ERROR_SHORT_BUFFER</b> if the value buffer is too small to hold the property value obtained. 82 * 83 * @since 20 84 */ 85 TEE_Result TEE_GetPropertyAsString(TEE_PropSetHandle propsetOrEnumerator, const char *name, char *valueBuffer, 86 size_t *valueBufferLen); 87 88 /** 89 * @brief Obtains a property from a property set and converts its value into a Boolean value. 90 * 91 * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator. 92 * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain. 93 * @param value Indicates the pointer to the variable that holds the property value obtained. 94 * 95 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 96 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the target property cannot be obtained. 97 * 98 * @since 20 99 */ 100 TEE_Result TEE_GetPropertyAsBool(TEE_PropSetHandle propsetOrEnumerator, const char *name, bool *value); 101 102 /** 103 * @brief Obtains a property from a property set and converts its value into a 32-bit unsigned integer. 104 * 105 * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator. 106 * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain. 107 * @param value Indicates the pointer to the variable that holds the property value obtained. 108 * 109 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 110 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the target property cannot be obtained. 111 * 112 * @since 20 113 */ 114 TEE_Result TEE_GetPropertyAsU32(TEE_PropSetHandle propsetOrEnumerator, const char *name, uint32_t *value); 115 116 /** 117 * @brief Obtains a property from a property set and converts its value into a 64-bit unsigned integer. 118 * 119 * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator. 120 * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain. 121 * @param value Indicates the pointer to the variable that holds the property value obtained. 122 * 123 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 124 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the target property cannot be obtained. 125 * 126 * @since 20 127 */ 128 TEE_Result TEE_GetPropertyAsU64(TEE_PropSetHandle propsetOrEnumerator, const char *name, uint64_t *value); 129 130 /** 131 * @brief Obtains a property from a property set and converts its value into a binary block. 132 * 133 * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator. 134 * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain. 135 * @param valueBuffer Indicates the pointer to the buffer for holding the property value obtained. 136 * @param valueBufferLen Indicates the pointer to the buffer length. 137 * 138 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 139 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the target property cannot be obtained. 140 * @return TEE_ERROR_SHORT_BUFFER the value buffer is not large enough to hold the whole property value 141 * 142 * @since 20 143 */ 144 TEE_Result TEE_GetPropertyAsBinaryBlock(TEE_PropSetHandle propsetOrEnumerator, const char *name, void *valueBuffer, 145 size_t *valueBufferLen); 146 147 /** 148 * @brief Obtains a property from a property set and converts its value to the <b>TEE_UUID</b> struct. 149 * 150 * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator. 151 * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain. 152 * @param value Indicates the pointer to the variable that holds the property value obtained. 153 * 154 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 155 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the target property cannot be obtained. 156 * 157 * @since 20 158 */ 159 TEE_Result TEE_GetPropertyAsUUID(TEE_PropSetHandle propsetOrEnumerator, const char *name, TEE_UUID *value); 160 161 /** 162 * @brief Obtains a property from a property set and converts its value to the <b>TEE_Identity</b> struct. 163 * 164 * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator. 165 * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain. 166 * @param value Indicates the pointer to the variable that holds the property value obtained. 167 * 168 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 169 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the target property cannot be obtained. 170 * 171 * @since 20 172 */ 173 TEE_Result TEE_GetPropertyAsIdentity(TEE_PropSetHandle propsetOrEnumerator, const char *name, TEE_Identity *value); 174 175 /** 176 * @brief Allocates a property enumerator object. 177 * 178 * @param enumerator Indicates the pointer to the property enumerator filled with an opaque handle. 179 * 180 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 181 * @return Returns <b>TEE_ERROR_OUT_OF_MEMORY</b> if there is no enough resources to allocate the property enumerator. 182 * 183 * @since 20 184 */ 185 TEE_Result TEE_AllocatePropertyEnumerator(TEE_PropSetHandle *enumerator); 186 187 /** 188 * @brief Releases a property enumerator object. 189 * 190 * @param enumerator Indicates the handle on the property enumerator to release. 191 * 192 * @return void 193 * 194 * @since 20 195 */ 196 void TEE_FreePropertyEnumerator(TEE_PropSetHandle enumerator); 197 198 /** 199 * @brief Starts to enumerate the properties in an enumerator. 200 * 201 * @param enumerator Indicates the handle on the enumerator. 202 * @param propSet Indicates the pseudo-handle on the property set to enumerate. 203 * 204 * @return void 205 * 206 * @since 20 207 */ 208 void TEE_StartPropertyEnumerator(TEE_PropSetHandle enumerator, TEE_PropSetHandle propSet); 209 210 /** 211 * @brief Resets a property enumerator immediately after allocation. 212 * 213 * @param enumerator Indicates the handle on the enumerator to reset. 214 * 215 * @return void 216 * 217 * @since 20 218 */ 219 void TEE_ResetPropertyEnumerator(TEE_PropSetHandle enumerator); 220 221 /** 222 * @brief Obtains the name of this property in an enumerator. 223 * 224 * @param enumerator Indicates the handle on the enumerator. 225 * @param nameBuffer Indicates the pointer to the buffer that stores the property name obtained. 226 * @param nameBufferLen Indicates the pointer to the buffer length. 227 * 228 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 229 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the property is not found because the enumerator has not started 230 * or has reached the end of the property set. 231 * @return Returns <b>TEE_ERROR_SHORT_BUFFER</b> if the buffer is too small to hold the property name. 232 * 233 * @since 20 234 */ 235 TEE_Result TEE_GetPropertyName(TEE_PropSetHandle enumerator, void *nameBuffer, size_t *nameBufferLen); 236 237 /** 238 * @brief Obtains the next property in an enumerator. 239 * 240 * @param enumerator Indicates the handle on the enumerator. 241 * 242 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 243 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the property is not found because the enumerator 244 * has not started or has reached the end of the property set. 245 * 246 * @since 20 247 */ 248 TEE_Result TEE_GetNextProperty(TEE_PropSetHandle enumerator); 249 250 #ifdef __cplusplus 251 } 252 #endif 253 254 #endif 255 /** @} */