1 /* 2 * Copyright (c) 2023-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 AssetType 18 * @{ 19 * 20 * @brief Provides the enums, structs, and error codes used in the Asset APIs. 21 * 22 * @since 11 23 */ 24 25 /** 26 * @file asset_type.h 27 * 28 * @brief Defines the enums, structs, and error codes used in the Asset APIs. 29 * 30 * @library libasset_ndk.z.so 31 * @kit AssetStoreKit 32 * @syscap SystemCapability.Security.Asset 33 * @since 11 34 */ 35 36 #ifndef ASSET_TYPE_H 37 #define ASSET_TYPE_H 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 * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized. 156 * 157 * @since 12 158 */ 159 ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_1 = ASSET_TYPE_BYTES | 0x34, 160 /** 161 * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized. 162 * 163 * @since 12 164 */ 165 ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_2 = ASSET_TYPE_BYTES | 0x35, 166 /** 167 * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized. 168 * 169 * @since 12 170 */ 171 ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_3 = ASSET_TYPE_BYTES | 0x36, 172 /** 173 * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized. 174 * 175 * @since 12 176 */ 177 ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_4 = ASSET_TYPE_BYTES | 0x37, 178 /** 179 * Return type of the queried asset. The value is of the uint32 type. 180 */ 181 ASSET_TAG_RETURN_TYPE = ASSET_TYPE_NUMBER | 0x40, 182 /** 183 * Maximum number of assets that can be returned at a time if multiple asset records match the specified conditions. 184 * The value is of the uint32 type. 185 */ 186 ASSET_TAG_RETURN_LIMIT = ASSET_TYPE_NUMBER | 0x41, 187 /** 188 * Offset that indicates the start asset when multiple asset records are returned. The value is of the uint32 type. 189 */ 190 ASSET_TAG_RETURN_OFFSET = ASSET_TYPE_NUMBER | 0x42, 191 /** 192 * Sorting order of the assets in the query result. The value is of the uint32 type. 193 */ 194 ASSET_TAG_RETURN_ORDERED_BY = ASSET_TYPE_NUMBER | 0x43, 195 /** 196 * Policy used to resolve the conflict occurred when an asset is added. The value is of the uint32 type. 197 */ 198 ASSET_TAG_CONFLICT_RESOLUTION = ASSET_TYPE_NUMBER | 0x44, 199 /** 200 * A tag whose value is a byte array indicating the update time of an Asset. 201 * 202 * @since 12 203 */ 204 ASSET_TAG_UPDATE_TIME = ASSET_TYPE_BYTES | 0x45, 205 /** 206 * A tag whose value is the uint32 type indicating the additional action. 207 * 208 * @since 12 209 */ 210 ASSET_TAG_OPERATION_TYPE = ASSET_TYPE_NUMBER | 0x46, 211 /** 212 * A tag whose value is a bool indicating whether the attributes of an asset are required to be encrypted. 213 * 214 * @since 14 215 */ 216 ASSET_TAG_REQUIRE_ATTR_ENCRYPTED = ASSET_TYPE_BOOL | 0x47, 217 /** 218 * A tag whose value is a byte array indicating the group id an asset belongs to. 219 * 220 * @since 16 221 */ 222 ASSET_TAG_GROUP_ID = ASSET_TYPE_BYTES | 0x48, 223 /** 224 * A tag whose value is a 32-bit unsigned integer indicating the type of Asset encapsulation. 225 * 226 * @since 16 227 */ 228 ASSET_TAG_WRAP_TYPE = ASSET_TYPE_BYTES | 0x49, 229 } Asset_Tag; 230 231 /** 232 * @brief Enumerates the result codes used in the ASSET APIs. 233 * 234 * @since 11 235 */ 236 typedef enum { 237 /** @error The operation is successful. */ 238 ASSET_SUCCESS = 0, 239 /** @error The caller doesn't have the permission. */ 240 ASSET_PERMISSION_DENIED = 201, 241 /** @error The parameter is invalid. */ 242 ASSET_INVALID_ARGUMENT = 401, 243 /** @error The ASSET service is unavailable. */ 244 ASSET_SERVICE_UNAVAILABLE = 24000001, 245 /** @error The asset is not found. */ 246 ASSET_NOT_FOUND = 24000002, 247 /** @error The asset already exists. */ 248 ASSET_DUPLICATED = 24000003, 249 /** @error Access to the asset is denied. */ 250 ASSET_ACCESS_DENIED = 24000004, 251 /** @error The screen lock status does not match. */ 252 ASSET_STATUS_MISMATCH = 24000005, 253 /** @error Insufficient memory. */ 254 ASSET_OUT_OF_MEMORY = 24000006, 255 /** @error The asset is corrupted. */ 256 ASSET_DATA_CORRUPTED = 24000007, 257 /** @error The database operation failed. */ 258 ASSET_DATABASE_ERROR = 24000008, 259 /** @error The cryptography operation failed. */ 260 ASSET_CRYPTO_ERROR = 24000009, 261 /** @error IPC failed. */ 262 ASSET_IPC_ERROR = 24000010, 263 /** @error Calling the Bundle Manager service failed. */ 264 ASSET_BMS_ERROR = 24000011, 265 /** @error Calling the OS Account service failed. */ 266 ASSET_ACCOUNT_ERROR = 24000012, 267 /** @error Calling the Access Token service failed. */ 268 ASSET_ACCESS_TOKEN_ERROR = 24000013, 269 /** @error The file operation failed. */ 270 ASSET_FILE_OPERATION_ERROR = 24000014, 271 /** @error Getting the system time failed. */ 272 ASSET_GET_SYSTEM_TIME_ERROR = 24000015, 273 /** @error The cache exceeds the limit. */ 274 ASSET_LIMIT_EXCEEDED = 24000016, 275 /** @error The capability is not supported. */ 276 ASSET_UNSUPPORTED = 24000017, 277 /** 278 * @error Parameter verification failed. 279 * 280 * @since 20 281 */ 282 ASSET_PARAM_VERIFICATION_FAILED = 24000018, 283 } Asset_ResultCode; 284 285 /** 286 * @brief Enumerates the types of the access control based on the lock screen status. 287 * 288 * @since 11 289 */ 290 typedef enum { 291 /** 292 * The asset can be accessed after the device is powered on. 293 */ 294 ASSET_ACCESSIBILITY_DEVICE_POWERED_ON = 0, 295 /** 296 * The asset can be accessed only after the device is unlocked for the first time. 297 */ 298 ASSET_ACCESSIBILITY_DEVICE_FIRST_UNLOCKED = 1, 299 /** 300 * The asset can be accessed only after the device is unlocked. 301 */ 302 ASSET_ACCESSIBILITY_DEVICE_UNLOCKED = 2, 303 } Asset_Accessibility; 304 305 /** 306 * @brief Enumerates the user authentication types supported for assets. 307 * 308 * @since 11 309 */ 310 typedef enum { 311 /** 312 * No user authentication is required before the asset is accessed. 313 */ 314 ASSET_AUTH_TYPE_NONE = 0x00, 315 /** 316 * The asset can be accessed if any user authentication (such as PIN, facial, or fingerprint authentication) is 317 * successful. 318 */ 319 ASSET_AUTH_TYPE_ANY = 0xFF, 320 } Asset_AuthType; 321 322 /** 323 * @brief Enumerates the asset synchronization types. 324 * 325 * @since 11 326 */ 327 typedef enum { 328 /** 329 * Asset synchronization is not allowed. 330 */ 331 ASSET_SYNC_TYPE_NEVER = 0, 332 /** 333 * Asset synchronization is allowed only on the local device, for example, in data restoration on the local device. 334 */ 335 ASSET_SYNC_TYPE_THIS_DEVICE = 1 << 0, 336 /** 337 * Asset synchronization is allowed only between trusted devices, for example, in the case of cloning. 338 */ 339 ASSET_SYNC_TYPE_TRUSTED_DEVICE = 1 << 1, 340 /** 341 * Asset synchronization is allowed only between devices with trusted accounts. 342 * 343 * @since 12 344 */ 345 ASSET_SYNC_TYPE_TRUSTED_ACCOUNT = 1 << 2, 346 } Asset_SyncType; 347 348 /** 349 * @brief An enum type indicates the type of Asset encapsulation. 350 * 351 * @since 16 352 */ 353 typedef enum { 354 /** 355 * An Asset with this attribute value is never allowed to be wrapped up. 356 */ 357 ASSET_WRAP_TYPE_NEVER = 0, 358 /** 359 * An Asset with this attribute value can only be wrapped or unwrapped on devices logged in with trusted accounts. 360 */ 361 ASSET_WRAP_TYPE_TRUSTED_ACCOUNT = 1, 362 } Asset_WrapType; 363 364 /** 365 * @brief Enumerates the policies for resolving the conflict (for example, duplicate alias) occurred when 366 * an asset is added. 367 * 368 * @since 11 369 */ 370 typedef enum { 371 /** 372 * Overwrite the existing asset. 373 */ 374 ASSET_CONFLICT_OVERWRITE = 0, 375 /** 376 * Throw an exception for the service to perform subsequent processing. 377 */ 378 ASSET_CONFLICT_THROW_ERROR = 1, 379 } Asset_ConflictResolution; 380 381 /** 382 * @brief Enumerates the types of the asset query result. 383 * 384 * @since 11 385 */ 386 typedef enum { 387 /** 388 * The query result contains the asset in plaintext and its attributes. 389 */ 390 ASSET_RETURN_ALL = 0, 391 /** 392 * The query result contains only the asset attributes. 393 */ 394 ASSET_RETURN_ATTRIBUTES = 1, 395 } Asset_ReturnType; 396 397 /** 398 * @brief Enumerates the types of the additional action. 399 * 400 * @since 12 401 */ 402 typedef enum { 403 /** 404 * Synchronization is required during operation. 405 */ 406 ASSET_NEED_SYNC = 0, 407 /** 408 * Logout is required during operation. 409 */ 410 ASSET_NEED_LOGOUT = 1, 411 } Asset_OperationType; 412 413 /** 414 * @brief Defines an asset value in the forma of a binary array, that is, a variable-length byte array. 415 * 416 * @since 11 417 */ 418 typedef struct { 419 /** 420 * Size of the byte array. 421 */ 422 uint32_t size; 423 /** 424 * Pointer to the byte array. 425 */ 426 uint8_t *data; 427 } Asset_Blob; 428 429 /** 430 * @brief Defines the value (content) of an asset attribute. 431 * 432 * @since 11 433 */ 434 typedef union { 435 /** 436 * Asset of the Boolean type. 437 */ 438 bool boolean; 439 /** 440 * Asset of the uint32 type. 441 */ 442 uint32_t u32; 443 /** 444 * Asset of the bytes type. 445 */ 446 Asset_Blob blob; 447 } Asset_Value; 448 449 /** 450 * @brief Defines an asset attribute. 451 * 452 * @since 11 453 */ 454 typedef struct { 455 /** 456 * Tag of the asset attribute. 457 */ 458 uint32_t tag; 459 /** 460 * Value of the asset attribute. 461 */ 462 Asset_Value value; 463 } Asset_Attr; 464 465 /** 466 * @brief Represents information about an asset. 467 * 468 * @since 11 469 */ 470 typedef struct { 471 /** 472 * Number of asset attributes. 473 */ 474 uint32_t count; 475 /** 476 * Pointer to the array of the asset attributes. 477 */ 478 Asset_Attr *attrs; 479 } Asset_Result; 480 481 /** 482 * @brief Represents information about a set of assets. 483 * 484 * @since 11 485 */ 486 typedef struct { 487 /** 488 * Number of assets. 489 */ 490 uint32_t count; 491 /** 492 * Pointer to the array of the assets. 493 */ 494 Asset_Result *results; 495 } Asset_ResultSet; 496 497 /** 498 * @brief Represents information about the synchronization result. 499 * 500 * @since 20 501 */ 502 typedef struct { 503 /** 504 * The result code of synchronization. 505 */ 506 int32_t resultCode; 507 /** 508 * The total count of synchronized Assets. 509 */ 510 uint32_t totalCount; 511 /** 512 * The count of Assets that fail to synchronize. 513 */ 514 uint32_t failedCount; 515 } Asset_SyncResult; 516 517 #ifdef __cplusplus 518 } 519 #endif 520 521 /** @} */ 522 #endif // ASSET_TYPE_H