1 /* 2 * Copyright (c) 2024-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 #ifndef ASSET_SYSTEM_TYPE_H 17 #define ASSET_SYSTEM_TYPE_H 18 19 /** 20 * @file asset_system_type.h 21 * 22 * @brief Defines the enums, structs, and error codes used in the Asset APIs. 23 * 24 * @since 11 25 */ 26 27 #include <stdbool.h> 28 #include <stdint.h> 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 /** 35 * @brief Enumerates the types of the asset attribute tags. 36 */ 37 typedef enum { 38 /** 39 * The asset attribute tag is a Boolean value. 40 */ 41 SEC_ASSET_TYPE_BOOL = 0x1 << 28, 42 /** 43 * The asset attribute tag is a number. 44 */ 45 SEC_ASSET_TYPE_NUMBER = 0x2 << 28, 46 /** 47 * The asset attribute tag is an array of bytes. 48 */ 49 SEC_ASSET_TYPE_BYTES = 0x3 << 28, 50 } AssetTagType; 51 52 /** 53 * @brief Defines the mask used to obtain the type of the asset attribute tag. 54 */ 55 #define SEC_ASSET_TAG_TYPE_MASK (0xF << 28) 56 57 /** 58 * @brief Enumerates the asset attribute tags. 59 */ 60 typedef enum { 61 /** 62 * Sensitive user data in the form of bytes, such as passwords and tokens. 63 */ 64 SEC_ASSET_TAG_SECRET = SEC_ASSET_TYPE_BYTES | 0x01, 65 /** 66 * Asset alias (identifier) in the form of bytes. 67 */ 68 SEC_ASSET_TAG_ALIAS = SEC_ASSET_TYPE_BYTES | 0x02, 69 /** 70 * Time when the asset is accessible. The value is of the uint32 type, which is a 32-bit unsigned integer. 71 */ 72 SEC_ASSET_TAG_ACCESSIBILITY = SEC_ASSET_TYPE_NUMBER | 0x03, 73 /** 74 * A Boolean value indicating whether the asset is available only with a lock screen password. 75 */ 76 SEC_ASSET_TAG_REQUIRE_PASSWORD_SET = SEC_ASSET_TYPE_BOOL | 0x04, 77 /** 78 * User authentication type for the asset. The value is of the uint32 type. 79 */ 80 SEC_ASSET_TAG_AUTH_TYPE = SEC_ASSET_TYPE_NUMBER | 0x05, 81 /** 82 * Validity period of the user authentication, in seconds. The value is of the uint32 type. 83 */ 84 SEC_ASSET_TAG_AUTH_VALIDITY_PERIOD = SEC_ASSET_TYPE_NUMBER | 0x06, 85 /** 86 * Challenge value, in the form of bytes, used for anti-replay during the authentication. 87 */ 88 SEC_ASSET_TAG_AUTH_CHALLENGE = SEC_ASSET_TYPE_BYTES | 0x07, 89 /** 90 * Authentication token, in the form of bytes, obtained after a successful user authentication. 91 */ 92 SEC_ASSET_TAG_AUTH_TOKEN = SEC_ASSET_TYPE_BYTES | 0x08, 93 /** 94 * Asset synchronization type. The value is of the uint32 type. 95 */ 96 SEC_ASSET_TAG_SYNC_TYPE = SEC_ASSET_TYPE_NUMBER | 0x10, 97 /** 98 * A Boolean value indicating whether the asset needs to be stored persistently. 99 * The ohos.permission.STORE_PERSISTENT_DATA permission is required if <b>OH_Asset_Add</b> is called with this tag. 100 * 101 * @permission ohos.permission.STORE_PERSISTENT_DATA 102 */ 103 SEC_ASSET_TAG_IS_PERSISTENT = SEC_ASSET_TYPE_BOOL | 0x11, 104 /** 105 * An immutable custom field, in the form of bytes. 106 */ 107 SEC_ASSET_TAG_DATA_LABEL_CRITICAL_1 = SEC_ASSET_TYPE_BYTES | 0x20, 108 /** 109 * An immutable custom field, in the form of bytes. 110 */ 111 SEC_ASSET_TAG_DATA_LABEL_CRITICAL_2 = SEC_ASSET_TYPE_BYTES | 0x21, 112 /** 113 * An immutable custom field, in the form of bytes. 114 */ 115 SEC_ASSET_TAG_DATA_LABEL_CRITICAL_3 = SEC_ASSET_TYPE_BYTES | 0x22, 116 /** 117 * An immutable custom field, in the form of bytes. 118 */ 119 SEC_ASSET_TAG_DATA_LABEL_CRITICAL_4 = SEC_ASSET_TYPE_BYTES | 0x23, 120 /** 121 * A mutable custom field, in the form of bytes. 122 */ 123 SEC_ASSET_TAG_DATA_LABEL_NORMAL_1 = SEC_ASSET_TYPE_BYTES | 0x30, 124 /** 125 * A mutable custom field, in the form of bytes. 126 */ 127 SEC_ASSET_TAG_DATA_LABEL_NORMAL_2 = SEC_ASSET_TYPE_BYTES | 0x31, 128 /** 129 * A mutable custom field, in the form of bytes. 130 */ 131 SEC_ASSET_TAG_DATA_LABEL_NORMAL_3 = SEC_ASSET_TYPE_BYTES | 0x32, 132 /** 133 * A mutable custom field, in the form of bytes. 134 */ 135 SEC_ASSET_TAG_DATA_LABEL_NORMAL_4 = SEC_ASSET_TYPE_BYTES | 0x33, 136 /** 137 * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized. 138 */ 139 SEC_ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_1 = SEC_ASSET_TYPE_BYTES | 0x34, 140 /** 141 * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized. 142 */ 143 SEC_ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_2 = SEC_ASSET_TYPE_BYTES | 0x35, 144 /** 145 * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized. 146 */ 147 SEC_ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_3 = SEC_ASSET_TYPE_BYTES | 0x36, 148 /** 149 * A mutable custom field, in the form of bytes. The information of a local tag will not be synchronized. 150 */ 151 SEC_ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_4 = SEC_ASSET_TYPE_BYTES | 0x37, 152 /** 153 * Return type of the queried asset. The value is of the uint32 type. 154 */ 155 SEC_ASSET_TAG_RETURN_TYPE = SEC_ASSET_TYPE_NUMBER | 0x40, 156 /** 157 * Maximum number of assets that can be returned at a time if multiple asset records match the specified conditions. 158 * The value is of the uint32 type. 159 */ 160 SEC_ASSET_TAG_RETURN_LIMIT = SEC_ASSET_TYPE_NUMBER | 0x41, 161 /** 162 * Offset that indicates the start asset when multiple asset records are returned. The value is of the uint32 type. 163 */ 164 SEC_ASSET_TAG_RETURN_OFFSET = SEC_ASSET_TYPE_NUMBER | 0x42, 165 /** 166 * Sorting order of the assets in the query result. The value is of the uint32 type. 167 */ 168 SEC_ASSET_TAG_RETURN_ORDERED_BY = SEC_ASSET_TYPE_NUMBER | 0x43, 169 /** 170 * Policy used to resolve the conflict occurred when an asset is added. The value is of the uint32 type. 171 */ 172 SEC_ASSET_TAG_CONFLICT_RESOLUTION = SEC_ASSET_TYPE_NUMBER | 0x44, 173 /** 174 * A tag whose value is a byte array indicating the update time of an Asset. 175 */ 176 SEC_ASSET_TAG_UPDATE_TIME = SEC_ASSET_TYPE_BYTES | 0x45, 177 /** 178 * A tag whose value is the uint32 type indicating the additional action. 179 */ 180 SEC_ASSET_TAG_OPERATION_TYPE = SEC_ASSET_TYPE_NUMBER | 0x46, 181 /** 182 * A tag whose value is a bool indicating whether the attributes of an asset are required to be encrypted. 183 */ 184 SEC_ASSET_TAG_REQUIRE_ATTR_ENCRYPTED = SEC_ASSET_TYPE_BOOL | 0x47, 185 /** 186 * A tag whose value is a byte array indicating the group id an asset belongs to. 187 */ 188 SEC_ASSET_TAG_GROUP_ID = SEC_ASSET_TYPE_BYTES | 0x48, 189 /** 190 * A tag whose value is a 32-bit unsigned integer indicating the type of Asset encapsulation. 191 */ 192 SEC_ASSET_TAG_WRAP_TYPE = SEC_ASSET_TYPE_NUMBER | 0x49, 193 /** 194 * Tag used to store specific user id. The value is of the uint32 type. 195 */ 196 SEC_ASSET_TAG_USER_ID = SEC_ASSET_TYPE_NUMBER | 0x100, 197 } AssetTag; 198 199 /** 200 * @brief Enumerates the result codes used in the ASSET APIs. 201 */ 202 typedef enum { 203 /** 204 * The operation is successful. 205 */ 206 SEC_ASSET_SUCCESS = 0, 207 /** 208 * The caller does not have the required permission. 209 */ 210 SEC_ASSET_PERMISSION_DENIED = 201, 211 /** 212 * The caller not system application. 213 */ 214 SEC_ASSET_NOT_SYSTEM_APPLICATION = 202, 215 /** 216 * The parameter is invalid. 217 */ 218 SEC_ASSET_INVALID_ARGUMENT = 401, 219 /** 220 * The asset service is unavailable. 221 */ 222 SEC_ASSET_SERVICE_UNAVAILABLE = 24000001, 223 /** 224 * The asset is not found. 225 */ 226 SEC_ASSET_NOT_FOUND = 24000002, 227 /** 228 * The asset already exists. 229 */ 230 SEC_ASSET_DUPLICATED = 24000003, 231 /** 232 * The access to the asset is denied. 233 */ 234 SEC_ASSET_ACCESS_DENIED = 24000004, 235 /** 236 * The lock screen status does not match the access control type specified. 237 */ 238 SEC_ASSET_STATUS_MISMATCH = 24000005, 239 /** 240 * The system memory is insufficient. 241 */ 242 SEC_ASSET_OUT_OF_MEMORY = 24000006, 243 /** 244 * The asset is corrupted. 245 */ 246 SEC_ASSET_DATA_CORRUPTED = 24000007, 247 /** 248 * The database operation failed. 249 */ 250 SEC_ASSET_DATABASE_ERROR = 24000008, 251 /** 252 * The cryptography operation failed. 253 */ 254 SEC_ASSET_CRYPTO_ERROR = 24000009, 255 /** 256 * The inter-process communication (IPC) failed. 257 */ 258 SEC_ASSET_IPC_ERROR = 24000010, 259 /** 260 * The Bundle Manager service is abnormal. 261 */ 262 SEC_ASSET_BMS_ERROR = 24000011, 263 /** 264 * The Account service is abnormal. 265 */ 266 SEC_ASSET_ACCOUNT_ERROR = 24000012, 267 /** 268 * The Access Token service is abnormal. 269 */ 270 SEC_ASSET_ACCESS_TOKEN_ERROR = 24000013, 271 /** 272 * The file operation failed. 273 */ 274 SEC_ASSET_FILE_OPERATION_ERROR = 24000014, 275 /** 276 * The operation for obtaining the system time failed. 277 */ 278 SEC_ASSET_GET_SYSTEM_TIME_ERROR = 24000015, 279 /** 280 * The number of cached assets exceeds the limit. 281 */ 282 SEC_ASSET_LIMIT_EXCEEDED = 24000016, 283 /** 284 * The function is not supported. 285 */ 286 SEC_ASSET_UNSUPPORTED = 24000017, 287 /** 288 * Parameter verification failed. 289 */ 290 SEC_ASSET_PARAM_VERIFICATION_FAILED = 24000018, 291 } AssetResultCode; 292 293 /** 294 * @brief Enumerates the types of the access control based on the lock screen status. 295 */ 296 typedef enum { 297 /** 298 * The asset can be accessed after the device is powered on. 299 */ 300 SEC_ASSET_ACCESSIBILITY_DEVICE_POWERED_ON = 0, 301 /** 302 * The asset can be accessed only after the device is unlocked for the first time. 303 */ 304 SEC_ASSET_ACCESSIBILITY_DEVICE_FIRST_UNLOCKED = 1, 305 /** 306 * The asset can be accessed only after the device is unlocked. 307 */ 308 SEC_ASSET_ACCESSIBILITY_DEVICE_UNLOCKED = 2, 309 } AssetAccessibility; 310 311 /** 312 * @brief Enumerates the user authentication types supported for assets. 313 */ 314 typedef enum { 315 /** 316 * No user authentication is required before the asset is accessed. 317 */ 318 SEC_ASSET_AUTH_TYPE_NONE = 0x00, 319 /** 320 * The asset can be accessed if any user authentication (such as PIN, facial, or fingerprint authentication) is 321 * successful. 322 */ 323 SEC_ASSET_AUTH_TYPE_ANY = 0xFF, 324 } AssetAuthType; 325 326 /** 327 * @brief Enumerates the asset synchronization types. 328 */ 329 typedef enum { 330 /** 331 * Asset synchronization is not allowed. 332 */ 333 SEC_ASSET_SYNC_TYPE_NEVER = 0, 334 /** 335 * Asset synchronization is allowed only on the local device, for example, in data restoration on the local device. 336 */ 337 SEC_ASSET_SYNC_TYPE_THIS_DEVICE = 1 << 0, 338 /** 339 * Asset synchronization is allowed only between trusted devices, for example, in the case of cloning. 340 */ 341 SEC_ASSET_SYNC_TYPE_TRUSTED_DEVICE = 1 << 1, 342 /** 343 * Asset synchronization is allowed only between trusted devices, for example, in the case of cloning. 344 */ 345 SEC_ASSET_SYNC_TYPE_TRUSTED_ACCOUNT = 1 << 2, 346 } AssetSyncType; 347 348 /** 349 * @brief An enum type indicates the type of Asset encapsulation. 350 */ 351 typedef enum { 352 /** 353 * An Asset with this attribute value is never allowed to be wrapped up. 354 */ 355 SEC_ASSET_WRAP_TYPE_NEVER = 0, 356 /** 357 * An Asset with this attribute value can only be wrapped or unwrapped on devices logged in with trusted accounts. 358 */ 359 SEC_ASSET_WRAP_TYPE_TRUSTED_ACCOUNT = 1, 360 } AssetWrapType; 361 362 /** 363 * @brief Enumerates the policies for resolving the conflict (for example, duplicate alias) occurred when 364 * an asset is added. 365 */ 366 typedef enum { 367 /** 368 * Overwrite the existing asset. 369 */ 370 SEC_ASSET_CONFLICT_OVERWRITE = 0, 371 /** 372 * Throw an exception for the service to perform subsequent processing. 373 */ 374 SEC_ASSET_CONFLICT_THROW_ERROR = 1, 375 } AssetConflictResolution; 376 377 /** 378 * @brief Enumerates the types of the asset query result. 379 */ 380 typedef enum { 381 /** 382 * The query result contains the asset in plaintext and its attributes. 383 */ 384 SEC_ASSET_RETURN_ALL = 0, 385 /** 386 * The query result contains only the asset attributes. 387 */ 388 SEC_ASSET_RETURN_ATTRIBUTES = 1, 389 } AssetReturnType; 390 391 /** 392 * @brief Enumerates the types of the asset query result. 393 */ 394 typedef enum { 395 /** 396 * Trigger Sync. 397 */ 398 SEC_ASSET_NEED_SYNC = 0, 399 /** 400 * Logout account to clean cloud flag. 401 */ 402 SEC_ASSET_NEED_LOGOUT = 1, 403 /** 404 * Delete cloud data. 405 */ 406 SEC_ASSET_NEED_DELETE_CLOUD_DATA = 2, 407 } AssetOperationType; 408 409 /** 410 * @brief Defines an asset value in the forma of a binary array, that is, a variable-length byte array. 411 */ 412 typedef struct { 413 /** 414 * Size of the byte array. 415 */ 416 uint32_t size; 417 /** 418 * Pointer to the byte array. 419 */ 420 uint8_t *data; 421 } AssetBlob; 422 423 /** 424 * @brief Defines the value (content) of an asset attribute. 425 */ 426 typedef union { 427 /** 428 * Asset of the Boolean type. 429 */ 430 bool boolean; 431 /** 432 * Asset of the uint32 type. 433 */ 434 uint32_t u32; 435 /** 436 * Asset of the bytes type. 437 */ 438 AssetBlob blob; 439 } AssetValue; 440 441 /** 442 * @brief Defines an asset attribute. 443 */ 444 typedef struct { 445 /** 446 * Tag of the asset attribute. 447 */ 448 uint32_t tag; 449 /** 450 * Value of the asset attribute. 451 */ 452 AssetValue value; 453 } AssetAttr; 454 455 /** 456 * @brief Represents information about an asset. 457 */ 458 typedef struct { 459 /** 460 * Number of asset attributes. 461 */ 462 uint32_t count; 463 /** 464 * Pointer to the array of the asset attributes. 465 */ 466 AssetAttr *attrs; 467 } AssetResult; 468 469 /** 470 * @brief Represents information about a set of assets. 471 */ 472 typedef struct { 473 /** 474 * Number of assets. 475 */ 476 uint32_t count; 477 /** 478 * Pointer to the array of the assets. 479 */ 480 AssetResult *results; 481 } AssetResultSet; 482 483 /** 484 * @brief Represents information about the synchronization result. 485 * 486 * @since 20 487 */ 488 typedef struct { 489 /** 490 * The result code of synchronization. 491 */ 492 int32_t resultCode; 493 /** 494 * The total count of synchronized Assets. 495 */ 496 uint32_t totalCount; 497 /** 498 * The count of Assets that fail to synchronize. 499 */ 500 uint32_t failedCount; 501 } AssetSyncResult; 502 503 #ifdef __cplusplus 504 } 505 #endif 506 507 #endif // ASSET_SYSTEM_TYPE_H