1 /* 2 * Copyright (c) 2023 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 ASSET_TYPE_H 17 #define ASSET_TYPE_H 18 19 /** 20 * @addtogroup AssetType 21 * @{ 22 * 23 * @brief Provides the enums, structs, and error codes used in the Asset APIs. 24 * 25 * @since 11 26 */ 27 28 /** 29 * @file asset_type.h 30 * 31 * @brief Defines the enums, structs, and error codes used in the Asset APIs. 32 * 33 * @library libasset_ndk.z.so 34 * @kit Asset Store Kit 35 * @syscap SystemCapability.Security.Asset 36 * @since 11 37 */ 38 39 #include <stdbool.h> 40 #include <stdint.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @brief Enumerates the types of the asset attribute tags. 48 * 49 * @since 11 50 */ 51 typedef enum { 52 /** 53 * The asset attribute tag is a Boolean value. 54 */ 55 ASSET_TYPE_BOOL = 0x1 << 28, 56 /** 57 * The asset attribute tag is a number. 58 */ 59 ASSET_TYPE_NUMBER = 0x2 << 28, 60 /** 61 * The asset attribute tag is an array of bytes. 62 */ 63 ASSET_TYPE_BYTES = 0x3 << 28, 64 } Asset_TagType; 65 66 /** 67 * @brief Defines the mask used to obtain the type of the asset attribute tag. 68 * 69 * @since 11 70 */ 71 #define ASSET_TAG_TYPE_MASK (0xF << 28) 72 73 /** 74 * @brief Enumerates the asset attribute tags. 75 * 76 * @since 11 77 */ 78 typedef enum { 79 /** 80 * Sensitive user data in the form of bytes, such as passwords and tokens. 81 */ 82 ASSET_TAG_SECRET = ASSET_TYPE_BYTES | 0x01, 83 /** 84 * Asset alias (identifier) in the form of bytes. 85 */ 86 ASSET_TAG_ALIAS = ASSET_TYPE_BYTES | 0x02, 87 /** 88 * Time when the asset is accessible. The value is of the uint32 type, which is a 32-bit unsigned integer. 89 */ 90 ASSET_TAG_ACCESSIBILITY = ASSET_TYPE_NUMBER | 0x03, 91 /** 92 * A Boolean value indicating whether the asset is available only with a lock screen password. 93 */ 94 ASSET_TAG_REQUIRE_PASSWORD_SET = ASSET_TYPE_BOOL | 0x04, 95 /** 96 * User authentication type for the asset. The value is of the uint32 type. 97 */ 98 ASSET_TAG_AUTH_TYPE = ASSET_TYPE_NUMBER | 0x05, 99 /** 100 * Validity period of the user authentication, in seconds. The value is of the uint32 type. 101 */ 102 ASSET_TAG_AUTH_VALIDITY_PERIOD = ASSET_TYPE_NUMBER | 0x06, 103 /** 104 * Challenge value, in the form of bytes, used for anti-replay during the authentication. 105 */ 106 ASSET_TAG_AUTH_CHALLENGE = ASSET_TYPE_BYTES | 0x07, 107 /** 108 * Authentication token, in the form of bytes, obtained after a successful user authentication. 109 */ 110 ASSET_TAG_AUTH_TOKEN = ASSET_TYPE_BYTES | 0x08, 111 /** 112 * Asset synchronization type. The value is of the uint32 type. 113 */ 114 ASSET_TAG_SYNC_TYPE = ASSET_TYPE_NUMBER | 0x10, 115 /** 116 * A Boolean value indicating whether the asset needs to be stored persistently. 117 * The ohos.permission.STORE_PERSISTENT_DATA permission is required if <b>OH_Asset_Add</b> is called with this tag. 118 * 119 * @permission ohos.permission.STORE_PERSISTENT_DATA 120 */ 121 ASSET_TAG_IS_PERSISTENT = ASSET_TYPE_BOOL | 0x11, 122 /** 123 * An immutable custom field, in the form of bytes. 124 */ 125 ASSET_TAG_DATA_LABEL_CRITICAL_1 = ASSET_TYPE_BYTES | 0x20, 126 /** 127 * An immutable custom field, in the form of bytes. 128 */ 129 ASSET_TAG_DATA_LABEL_CRITICAL_2 = ASSET_TYPE_BYTES | 0x21, 130 /** 131 * An immutable custom field, in the form of bytes. 132 */ 133 ASSET_TAG_DATA_LABEL_CRITICAL_3 = ASSET_TYPE_BYTES | 0x22, 134 /** 135 * An immutable custom field, in the form of bytes. 136 */ 137 ASSET_TAG_DATA_LABEL_CRITICAL_4 = ASSET_TYPE_BYTES | 0x23, 138 /** 139 * A mutable custom field, in the form of bytes. 140 */ 141 ASSET_TAG_DATA_LABEL_NORMAL_1 = ASSET_TYPE_BYTES | 0x30, 142 /** 143 * A mutable custom field, in the form of bytes. 144 */ 145 ASSET_TAG_DATA_LABEL_NORMAL_2 = ASSET_TYPE_BYTES | 0x31, 146 /** 147 * A mutable custom field, in the form of bytes. 148 */ 149 ASSET_TAG_DATA_LABEL_NORMAL_3 = ASSET_TYPE_BYTES | 0x32, 150 /** 151 * A mutable custom field, in the form of bytes. 152 */ 153 ASSET_TAG_DATA_LABEL_NORMAL_4 = ASSET_TYPE_BYTES | 0x33, 154 /** 155 * Return type of the queried asset. The value is of the uint32 type. 156 */ 157 ASSET_TAG_RETURN_TYPE = ASSET_TYPE_NUMBER | 0x40, 158 /** 159 * Maximum number of assets that can be returned at a time if multiple asset records match the specified conditions. 160 * The value is of the uint32 type. 161 */ 162 ASSET_TAG_RETURN_LIMIT = ASSET_TYPE_NUMBER | 0x41, 163 /** 164 * Offset that indicates the start asset when multiple asset records are returned. The value is of the uint32 type. 165 */ 166 ASSET_TAG_RETURN_OFFSET = ASSET_TYPE_NUMBER | 0x42, 167 /** 168 * Sorting order of the assets in the query result. The value is of the uint32 type. 169 */ 170 ASSET_TAG_RETURN_ORDERED_BY = ASSET_TYPE_NUMBER | 0x43, 171 /** 172 * Policy used to resolve the conflict occurred when an asset is added. The value is of the uint32 type. 173 */ 174 ASSET_TAG_CONFLICT_RESOLUTION = ASSET_TYPE_NUMBER | 0x44, 175 } Asset_Tag; 176 177 /** 178 * @brief Enumerates the result codes used in the ASSET APIs. 179 * 180 * @since 11 181 */ 182 typedef enum { 183 /** 184 * The operation is successful. 185 */ 186 ASSET_SUCCESS = 0, 187 /** 188 * The caller does not have the required permission. 189 */ 190 ASSET_PERMISSION_DENIED = 201, 191 /** 192 * The parameter is invalid. 193 */ 194 ASSET_INVALID_ARGUMENT = 401, 195 /** 196 * The asset service is unavailable. 197 */ 198 ASSET_SERVICE_UNAVAILABLE = 24000001, 199 /** 200 * The asset is not found. 201 */ 202 ASSET_NOT_FOUND = 24000002, 203 /** 204 * The asset already exists. 205 */ 206 ASSET_DUPLICATED = 24000003, 207 /** 208 * The access to the asset is denied. 209 */ 210 ASSET_ACCESS_DENIED = 24000004, 211 /** 212 * The lock screen status does not match the access control type specified. 213 */ 214 ASSET_STATUS_MISMATCH = 24000005, 215 /** 216 * The system memory is insufficient. 217 */ 218 ASSET_OUT_OF_MEMORY = 24000006, 219 /** 220 * The asset is corrupted. 221 */ 222 ASSET_DATA_CORRUPTED = 24000007, 223 /** 224 * The database operation failed. 225 */ 226 ASSET_DATABASE_ERROR = 24000008, 227 /** 228 * The cryptography operation failed. 229 */ 230 ASSET_CRYPTO_ERROR = 24000009, 231 /** 232 * The inter-process communication (IPC) failed. 233 */ 234 ASSET_IPC_ERROR = 24000010, 235 /** 236 * The Bundle Manager service is abnormal. 237 */ 238 ASSET_BMS_ERROR = 24000011, 239 /** 240 * The Account service is abnormal. 241 */ 242 ASSET_ACCOUNT_ERROR = 24000012, 243 /** 244 * The Access Token service is abnormal. 245 */ 246 ASSET_ACCESS_TOKEN_ERROR = 24000013, 247 /** 248 * The file operation failed. 249 */ 250 ASSET_FILE_OPERATION_ERROR = 24000014, 251 /** 252 * The operation for obtaining the system time failed. 253 */ 254 ASSET_GET_SYSTEM_TIME_ERROR = 24000015, 255 /** 256 * The number of cached assets exceeds the limit. 257 */ 258 ASSET_LIMIT_EXCEEDED = 24000016, 259 /** 260 * The function is not supported. 261 */ 262 ASSET_UNSUPPORTED = 24000017, 263 } Asset_ResultCode; 264 265 /** 266 * @brief Enumerates the types of the access control based on the lock screen status. 267 * 268 * @since 11 269 */ 270 typedef enum { 271 /** 272 * The asset can be accessed after the device is powered on. 273 */ 274 ASSET_ACCESSIBILITY_DEVICE_POWERED_ON = 0, 275 /** 276 * The asset can be accessed only after the device is unlocked for the first time. 277 */ 278 ASSET_ACCESSIBILITY_DEVICE_FIRST_UNLOCKED = 1, 279 /** 280 * The asset can be accessed only after the device is unlocked. 281 */ 282 ASSET_ACCESSIBILITY_DEVICE_UNLOCKED = 2, 283 } Asset_Accessibility; 284 285 /** 286 * @brief Enumerates the user authentication types supported for assets. 287 * 288 * @since 11 289 */ 290 typedef enum { 291 /** 292 * No user authentication is required before the asset is accessed. 293 */ 294 ASSET_AUTH_TYPE_NONE = 0x00, 295 /** 296 * The asset can be accessed if any user authentication (such as PIN, facial, or fingerprint authentication) is 297 * successful. 298 */ 299 ASSET_AUTH_TYPE_ANY = 0xFF, 300 } Asset_AuthType; 301 302 /** 303 * @brief Enumerates the asset synchronization types. 304 * 305 * @since 11 306 */ 307 typedef enum { 308 /** 309 * Asset synchronization is not allowed. 310 */ 311 ASSET_SYNC_TYPE_NEVER = 0, 312 /** 313 * Asset synchronization is allowed only on the local device, for example, in data restoration on the local device. 314 */ 315 ASSET_SYNC_TYPE_THIS_DEVICE = 1 << 0, 316 /** 317 * Asset synchronization is allowed only between trusted devices, for example, in the case of cloning. 318 */ 319 ASSET_SYNC_TYPE_TRUSTED_DEVICE = 1 << 1, 320 } Asset_SyncType; 321 322 /** 323 * @brief Enumerates the policies for resolving the conflict (for example, duplicate alias) occurred when 324 * an asset is added. 325 * 326 * @since 11 327 */ 328 typedef enum { 329 /** 330 * Overwrite the existing asset. 331 */ 332 ASSET_CONFLICT_OVERWRITE = 0, 333 /** 334 * Throw an exception for the service to perform subsequent processing. 335 */ 336 ASSET_CONFLICT_THROW_ERROR = 1, 337 } Asset_ConflictResolution; 338 339 /** 340 * @brief Enumerates the types of the asset query result. 341 * 342 * @since 11 343 */ 344 typedef enum { 345 /** 346 * The query result contains the asset in plaintext and its attributes. 347 */ 348 ASSET_RETURN_ALL = 0, 349 /** 350 * The query result contains only the asset attributes. 351 */ 352 ASSET_RETURN_ATTRIBUTES = 1, 353 } Asset_ReturnType; 354 355 /** 356 * @brief Defines an asset value in the forma of a binary array, that is, a variable-length byte array. 357 * 358 * @since 11 359 */ 360 typedef struct { 361 /** 362 * Size of the byte array. 363 */ 364 uint32_t size; 365 /** 366 * Pointer to the byte array. 367 */ 368 uint8_t *data; 369 } Asset_Blob; 370 371 /** 372 * @brief Defines the value (content) of an asset attribute. 373 * 374 * @since 11 375 */ 376 typedef union { 377 /** 378 * Asset of the Boolean type. 379 */ 380 bool boolean; 381 /** 382 * Asset of the uint32 type. 383 */ 384 uint32_t u32; 385 /** 386 * Asset of the bytes type. 387 */ 388 Asset_Blob blob; 389 } Asset_Value; 390 391 /** 392 * @brief Defines an asset attribute. 393 * 394 * @since 11 395 */ 396 typedef struct { 397 /** 398 * Tag of the asset attribute. 399 */ 400 uint32_t tag; 401 /** 402 * Value of the asset attribute. 403 */ 404 Asset_Value value; 405 } Asset_Attr; 406 407 /** 408 * @brief Represents information about an asset. 409 * 410 * @since 11 411 */ 412 typedef struct { 413 /** 414 * Number of asset attributes. 415 */ 416 uint32_t count; 417 /** 418 * Pointer to the array of the asset attributes. 419 */ 420 Asset_Attr *attrs; 421 } Asset_Result; 422 423 /** 424 * @brief Represents information about a set of assets. 425 * 426 * @since 11 427 */ 428 typedef struct { 429 /** 430 * Number of assets. 431 */ 432 uint32_t count; 433 /** 434 * Pointer to the array of the assets. 435 */ 436 Asset_Result *results; 437 } Asset_ResultSet; 438 439 #ifdef __cplusplus 440 } 441 #endif 442 443 /** @} */ 444 #endif // ASSET_TYPE_H