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