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