1# @ohos.security.asset (Asset Store Service) 2 3The asset store service (ASSET) provides secure storage and management of sensitive data less than 1024 bytes in size, including passwords, app tokens, and other critical data (such as bank card numbers). 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```typescript 12import { asset } from '@kit.AssetStoreKit'; 13``` 14 15## asset.add 16 17add(attributes: AssetMap): Promise\<void> 18 19Add an asset. This API uses a promise to return the result. 20 21To set [IS_PERSISTENT](#tag), the application must have the ohos.permission.STORE_PERSISTENT_DATA permission. 22 23**Atomic service API**: This API can be used in atomic services since API version 14. 24 25**System capability**: SystemCapability.Security.Asset 26 27**Parameters** 28 29| Name | Type | Mandatory| Description | 30| ---------- | -------- | ---- | ------------------------------------------------------------ | 31| attributes | [AssetMap](#assetmap) | Yes | Attributes of the asset to add, including the asset plaintext, access control attributes, and custom data.| 32 33**Return value** 34 35| Type | Description | 36| ------------- | ----------------------- | 37| Promise\<void> | Promise that returns no value.| 38 39**Error codes** 40 41For details about the error codes, see [Asset Store Service Error Codes](errorcode-asset.md). 42 43| ID| Error Message | 44| -------- | ---------------------------------------------------------- | 45| 201 | The caller doesn't have the permission. | 46| 401 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameter types. <br> 3. Parameter verification failed. | 47| 24000001 | The ASSET service is unavailable. | 48| 24000003 | The asset already exists. | 49| 24000005 | The screen lock status does not match. | 50| 24000006 | Insufficient memory. | 51| 24000007 | The asset is corrupted. | 52| 24000008 | The database operation failed. | 53| 24000009 | The cryptography operation failed. | 54| 24000010 | IPC failed. | 55| 24000011 | Calling the Bundle Manager service failed. | 56| 24000012 | Calling the OS Account service failed. | 57| 24000013 | Calling the Access Token service failed. | 58| 24000014 | The file operation failed. | 59| 24000015 | Getting the system time failed. | 60 61**Example** 62 63```typescript 64import { asset } from '@kit.AssetStoreKit'; 65import { util } from '@kit.ArkTS'; 66import { BusinessError } from '@kit.BasicServicesKit'; 67 68function stringToArray(str: string): Uint8Array { 69 let textEncoder = new util.TextEncoder(); 70 return textEncoder.encodeInto(str); 71} 72 73let attr: asset.AssetMap = new Map(); 74attr.set(asset.Tag.SECRET, stringToArray('demo_pwd')); 75attr.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 76attr.set(asset.Tag.ACCESSIBILITY, asset.Accessibility.DEVICE_FIRST_UNLOCKED); 77attr.set(asset.Tag.DATA_LABEL_NORMAL_1, stringToArray('demo_label')); 78try { 79 asset.add(attr).then(() => { 80 console.info(`Asset added successfully.`); 81 }).catch((err: BusinessError) => { 82 console.error(`Failed to add Asset. Code is ${err.code}, message is ${err.message}`); 83 }) 84} catch (error) { 85 let err = error as BusinessError; 86 console.error(`Failed to add Asset. Code is ${err.code}, message is ${err.message}`); 87} 88``` 89 90## asset.addSync<sup>12+</sup> 91 92addSync(attributes: AssetMap): void 93 94Add an asset. This API returns the result synchronously. 95 96To set [IS_PERSISTENT](#tag), the application must have the ohos.permission.STORE_PERSISTENT_DATA permission. 97 98**Atomic service API**: This API can be used in atomic services since API version 14. 99 100**System capability**: SystemCapability.Security.Asset 101 102**Parameters** 103 104| Name | Type | Mandatory| Description | 105| ---------- | -------- | ---- | ------------------------------------------------------------ | 106| attributes | [AssetMap](#assetmap) | Yes | Attributes of the asset to add, including the asset plaintext, access control attributes, and custom data.| 107 108**Error codes** 109 110For details about the error codes, see [Asset Store Service Error Codes](errorcode-asset.md). 111 112| ID| Error Message | 113| -------- | ---------------------------------------------------------- | 114| 201 | The caller doesn't have the permission. | 115| 401 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameter types. <br> 3. Parameter verification failed. | 116| 24000001 | The ASSET service is unavailable. | 117| 24000003 | The asset already exists. | 118| 24000005 | The screen lock status does not match. | 119| 24000006 | Insufficient memory. | 120| 24000007 | The asset is corrupted. | 121| 24000008 | The database operation failed. | 122| 24000009 | The cryptography operation failed. | 123| 24000010 | IPC failed. | 124| 24000011 | Calling the Bundle Manager service failed. | 125| 24000012 | Calling the OS Account service failed. | 126| 24000013 | Calling the Access Token service failed. | 127| 24000014 | The file operation failed. | 128| 24000015 | Getting the system time failed. | 129 130**Example** 131 132```typescript 133import { asset } from '@kit.AssetStoreKit'; 134import { util } from '@kit.ArkTS'; 135import { BusinessError } from '@kit.BasicServicesKit'; 136 137function stringToArray(str: string): Uint8Array { 138 let textEncoder = new util.TextEncoder(); 139 return textEncoder.encodeInto(str); 140} 141 142let attr: asset.AssetMap = new Map(); 143attr.set(asset.Tag.SECRET, stringToArray('demo_pwd')); 144attr.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 145attr.set(asset.Tag.ACCESSIBILITY, asset.Accessibility.DEVICE_FIRST_UNLOCKED); 146attr.set(asset.Tag.DATA_LABEL_NORMAL_1, stringToArray('demo_label')); 147try { 148 asset.addSync(attr); 149} catch (error) { 150 let err = error as BusinessError; 151 console.error(`Failed to add Asset. Code is ${err.code}, message is ${err.message}`); 152} 153``` 154 155## asset.remove 156 157remove(query: AssetMap): Promise\<void> 158 159Removes one or more assets. This API uses a promise to return the result. 160 161**Atomic service API**: This API can be used in atomic services since API version 14. 162 163**System capability**: SystemCapability.Security.Asset 164 165**Parameters** 166 167| Name| Type | Mandatory| Description | 168| ------ | -------- | ---- | ------------------------------------------------------ | 169| query | [AssetMap](#assetmap) | Yes | Attributes of the asset to remove, such as the asset alias, access control attributes, and custom data.| 170 171**Return value** 172 173| Type | Description | 174| ------------- | ----------------------- | 175| Promise\<void> | Promise that returns no value.| 176 177**Error codes** 178 179For details about the error codes, see [Asset Store Service Error Codes](errorcode-asset.md). 180 181| ID| Error Message | 182| -------- | ---------------------------------------------------------- | 183| 401 | Parameter error. Possible causes: <br> 1. Incorrect parameter types. <br> 2. Parameter verification failed. | 184| 24000001 | The ASSET service is unavailable. | 185| 24000002 | The asset is not found. | 186| 24000006 | Insufficient memory. | 187| 24000007 | The asset is corrupted. | 188| 24000008 | The database operation failed. | 189| 24000010 | IPC failed. | 190| 24000011 | Calling the Bundle Manager service failed. | 191| 24000012 | Calling the OS Account service failed. | 192| 24000013 | Calling the Access Token service failed. | 193| 24000015 | Getting the system time failed. | 194 195**Example** 196 197```typescript 198import { asset } from '@kit.AssetStoreKit'; 199import { util } from '@kit.ArkTS'; 200import { BusinessError } from '@kit.BasicServicesKit'; 201 202function stringToArray(str: string): Uint8Array { 203 let textEncoder = new util.TextEncoder(); 204 return textEncoder.encodeInto(str); 205} 206 207let query: asset.AssetMap = new Map(); 208query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 209try { 210 asset.remove(query).then(() => { 211 console.info(`Asset removed successfully.`); 212 }).catch((err: BusinessError) => { 213 console.error(`Failed to remove Asset. Code is ${err.code}, message is ${err.message}`); 214 }); 215} catch (error) { 216 let err = error as BusinessError; 217 console.error(`Failed to remove Asset. Code is ${err.code}, message is ${err.message}`); 218} 219``` 220 221## asset.removeSync<sup>12+</sup> 222 223removeSync(query: AssetMap): void 224 225Removes one or more assets. This API returns the result synchronously. 226 227**Atomic service API**: This API can be used in atomic services since API version 14. 228 229**System capability**: SystemCapability.Security.Asset 230 231**Parameters** 232 233| Name| Type | Mandatory| Description | 234| ------ | -------- | ---- | ------------------------------------------------------ | 235| query | [AssetMap](#assetmap) | Yes | Attributes of the asset to remove, such as the asset alias, access control attributes, and custom data.| 236 237**Error codes** 238 239For details about the error codes, see [Asset Store Service Error Codes](errorcode-asset.md). 240 241| ID| Error Message | 242| -------- | ---------------------------------------------------------- | 243| 401 | Parameter error. Possible causes: <br> 1. Incorrect parameter types. <br> 2. Parameter verification failed. | 244| 24000001 | The ASSET service is unavailable. | 245| 24000002 | The asset is not found. | 246| 24000006 | Insufficient memory. | 247| 24000007 | The asset is corrupted. | 248| 24000008 | The database operation failed. | 249| 24000010 | IPC failed. | 250| 24000011 | Calling the Bundle Manager service failed. | 251| 24000012 | Calling the OS Account service failed. | 252| 24000013 | Calling the Access Token service failed. | 253| 24000015 | Getting the system time failed. | 254 255**Example** 256 257```typescript 258import { asset } from '@kit.AssetStoreKit'; 259import { util } from '@kit.ArkTS'; 260import { BusinessError } from '@kit.BasicServicesKit'; 261 262function stringToArray(str: string): Uint8Array { 263 let textEncoder = new util.TextEncoder(); 264 return textEncoder.encodeInto(str); 265} 266 267let query: asset.AssetMap = new Map(); 268query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 269try { 270 asset.removeSync(query); 271} catch (error) { 272 let err = error as BusinessError; 273 console.error(`Failed to remove Asset. Code is ${err.code}, message is ${err.message}`); 274} 275``` 276 277## asset.update 278 279update(query: AssetMap, attributesToUpdate: AssetMap): Promise\<void> 280 281Updates an asset. This API uses a promise to return the result. 282 283**Atomic service API**: This API can be used in atomic services since API version 14. 284 285**System capability**: SystemCapability.Security.Asset 286 287**Parameters** 288 289| Name | Type | Mandatory| Description | 290| ------------------ | -------- | ---- | ------------------------------------------------------------ | 291| query | [AssetMap](#assetmap) | Yes | Attributes of the asset to update, such as the asset alias, access control attributes, and custom data.| 292| attributesToUpdate | [AssetMap](#assetmap) | Yes | New attributes of the asset, such as the asset plaintext and custom data. | 293 294**Return value** 295 296| Type | Description | 297| ------------- | ----------------------- | 298| Promise\<void> | Promise that returns no value.| 299 300**Error codes** 301 302For details about the error codes, see [Asset Store Service Error Codes](errorcode-asset.md). 303 304| ID| Error Message | 305| -------- | ---------------------------------------------------------- | 306| 401 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameter types. <br> 3. Parameter verification failed. | 307| 24000001 | The ASSET service is unavailable. | 308| 24000002 | The asset is not found. | 309| 24000005 | The screen lock status does not match. | 310| 24000006 | Insufficient memory. | 311| 24000007 | The asset is corrupted. | 312| 24000008 | The database operation failed. | 313| 24000009 | The cryptography operation failed. | 314| 24000010 | IPC failed. | 315| 24000011 | Calling the Bundle Manager service failed. | 316| 24000012 | Calling the OS Account service failed. | 317| 24000013 | Calling the Access Token service failed. | 318| 24000015 | Getting the system time failed. | 319 320**Example** 321 322```typescript 323import { asset } from '@kit.AssetStoreKit'; 324import { util } from '@kit.ArkTS'; 325import { BusinessError } from '@kit.BasicServicesKit'; 326 327function stringToArray(str: string): Uint8Array { 328 let textEncoder = new util.TextEncoder(); 329 return textEncoder.encodeInto(str); 330} 331 332let query: asset.AssetMap = new Map(); 333query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 334let attrsToUpdate: asset.AssetMap = new Map(); 335attrsToUpdate.set(asset.Tag.SECRET, stringToArray('demo_pwd_new')); 336try { 337 asset.update(query, attrsToUpdate).then(() => { 338 console.info(`Asset updated successfully.`); 339 }).catch((err: BusinessError) => { 340 console.error(`Failed to update Asset. Code is ${err.code}, message is ${err.message}`); 341 }); 342} catch (error) { 343 let err = error as BusinessError; 344 console.error(`Failed to update Asset. Code is ${err.code}, message is ${err.message}`); 345} 346``` 347 348## asset.updateSync<sup>12+</sup> 349 350updateSync(query: AssetMap, attributesToUpdate: AssetMap): void 351 352Updates an asset. This API returns the result synchronously. 353 354**Atomic service API**: This API can be used in atomic services since API version 14. 355 356**System capability**: SystemCapability.Security.Asset 357 358**Parameters** 359 360| Name | Type | Mandatory| Description | 361| ------------------ | -------- | ---- | ------------------------------------------------------------ | 362| query | [AssetMap](#assetmap) | Yes | Attributes of the asset to update, such as the asset alias, access control attributes, and custom data.| 363| attributesToUpdate | [AssetMap](#assetmap) | Yes | New attributes of the asset, such as the asset plaintext and custom data. | 364 365**Error codes** 366 367For details about the error codes, see [Asset Store Service Error Codes](errorcode-asset.md). 368 369| ID| Error Message | 370| -------- | ---------------------------------------------------------- | 371| 401 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameter types. <br> 3. Parameter verification failed. | 372| 24000001 | The ASSET service is unavailable. | 373| 24000002 | The asset is not found. | 374| 24000005 | The screen lock status does not match. | 375| 24000006 | Insufficient memory. | 376| 24000007 | The asset is corrupted. | 377| 24000008 | The database operation failed. | 378| 24000009 | The cryptography operation failed. | 379| 24000010 | IPC failed. | 380| 24000011 | Calling the Bundle Manager service failed. | 381| 24000012 | Calling the OS Account service failed. | 382| 24000013 | Calling the Access Token service failed. | 383| 24000015 | Getting the system time failed. | 384 385**Example** 386 387```typescript 388import { asset } from '@kit.AssetStoreKit'; 389import { util } from '@kit.ArkTS'; 390import { BusinessError } from '@kit.BasicServicesKit'; 391 392function stringToArray(str: string): Uint8Array { 393 let textEncoder = new util.TextEncoder(); 394 return textEncoder.encodeInto(str); 395} 396 397let query: asset.AssetMap = new Map(); 398query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 399let attrsToUpdate: asset.AssetMap = new Map(); 400attrsToUpdate.set(asset.Tag.SECRET, stringToArray('demo_pwd_new')); 401try { 402 asset.updateSync(query, attrsToUpdate); 403} catch (error) { 404 let err = error as BusinessError; 405 console.error(`Failed to update Asset. Code is ${err.code}, message is ${err.message}`); 406} 407``` 408 409## asset.preQuery 410 411preQuery(query: AssetMap): Promise\<Uint8Array> 412 413Performs preprocessing for the asset query. This API is used when user authentication is required for the access to the asset. After the user authentication is successful, call [asset.query](#assetquery) and [asset.postQuery](#assetpostquery). This API uses a promise to return the result. 414 415**Atomic service API**: This API can be used in atomic services since API version 14. 416 417**System capability**: SystemCapability.Security.Asset 418 419**Parameters** 420 421| Name| Type | Mandatory| Description | 422| ------ | -------- | ---- | ------------------------------------------------------ | 423| query | [AssetMap](#assetmap) | Yes | Attributes of the asset to query, such as the asset alias, access control attributes, and custom data.| 424 425**Return value** 426 427| Type | Description | 428| ------------------- | ----------------------------------------------------- | 429| Promise\<Uint8Array> | Promise used to return a challenge value.<br>**NOTE**: The challenge value is used for subsequent user authentication.| 430 431**Error codes** 432 433For details about the error codes, see [Asset Store Service Error Codes](errorcode-asset.md). 434 435| ID| Error Message | 436| -------- | ------------------------------------------------------------ | 437| 401 | Parameter error. Possible causes: <br> 1. Incorrect parameter types. <br> 2. Parameter verification failed. | 438| 24000001 | The ASSET service is unavailable. | 439| 24000002 | The asset is not found. | 440| 24000005 | The screen lock status does not match. | 441| 24000006 | Insufficient memory. | 442| 24000007 | The asset is corrupted. | 443| 24000008 | The database operation failed. | 444| 24000009 | The cryptography operation failed. | 445| 24000010 | IPC failed. | 446| 24000011 | Calling the Bundle Manager service failed. | 447| 24000012 | Calling the OS Account service failed. | 448| 24000013 | Calling the Access Token service failed. | 449| 24000016 | The cache exceeds the limit. | 450| 24000017 | The capability is not supported. | 451 452**Example** 453 454```typescript 455import { asset } from '@kit.AssetStoreKit'; 456import { util } from '@kit.ArkTS'; 457import { BusinessError } from '@kit.BasicServicesKit'; 458 459function stringToArray(str: string): Uint8Array { 460 let textEncoder = new util.TextEncoder(); 461 return textEncoder.encodeInto(str); 462} 463 464let query: asset.AssetMap = new Map(); 465query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 466try { 467 asset.preQuery(query).then((challenge: Uint8Array) => { 468 console.info(`Succeeded in pre-querying Asset.`); 469 }).catch ((err: BusinessError) => { 470 console.error(`Failed to pre-query Asset. Code is ${err.code}, message is ${err.message}`); 471 }); 472} catch (error) { 473 let err = error as BusinessError; 474 console.error(`Failed to pre-query Asset. Code is ${err.code}, message is ${err.message}`); 475} 476``` 477 478## asset.preQuerySync<sup>12+</sup> 479 480preQuerySync(query: AssetMap): Uint8Array 481 482Performs preprocessing for the asset query. This API is used when user authentication is required for the access to the asset. After the user authentication is successful, call [asset.querySync](#assetquerysync12) and [asset.postQuerySync](#assetpostquerysync12). This API returns the result synchronously. 483 484**Atomic service API**: This API can be used in atomic services since API version 14. 485 486**System capability**: SystemCapability.Security.Asset 487 488**Parameters** 489 490| Name| Type | Mandatory| Description | 491| ------ | -------- | ---- | ------------------------------------------------------ | 492| query | [AssetMap](#assetmap) | Yes | Attributes of the asset to query, such as the asset alias, access control attributes, and custom data.| 493 494**Return value** 495 496| Type | Description | 497| ------------------- | ----------------------------------------------------- | 498| Uint8Array | Challenge value.<br>**NOTE**: The challenge value is used for subsequent user authentication.| 499 500**Error codes** 501 502For details about the error codes, see [Asset Store Service Error Codes](errorcode-asset.md). 503 504| ID| Error Message | 505| -------- | ------------------------------------------------------------ | 506| 401 | Parameter error. Possible causes: <br> 1. Incorrect parameter types. <br> 2. Parameter verification failed. | 507| 24000001 | The ASSET service is unavailable. | 508| 24000002 | The asset is not found. | 509| 24000005 | The screen lock status does not match. | 510| 24000006 | Insufficient memory. | 511| 24000007 | The asset is corrupted. | 512| 24000008 | The database operation failed. | 513| 24000009 | The cryptography operation failed. | 514| 24000010 | IPC failed. | 515| 24000011 | Calling the Bundle Manager service failed. | 516| 24000012 | Calling the OS Account service failed. | 517| 24000013 | Calling the Access Token service failed. | 518| 24000016 | The cache exceeds the limit. | 519| 24000017 | The capability is not supported. | 520 521**Example** 522 523```typescript 524import { asset } from '@kit.AssetStoreKit'; 525import { util } from '@kit.ArkTS'; 526import { BusinessError } from '@kit.BasicServicesKit'; 527 528function stringToArray(str: string): Uint8Array { 529 let textEncoder = new util.TextEncoder(); 530 return textEncoder.encodeInto(str); 531} 532 533let query: asset.AssetMap = new Map(); 534query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 535try { 536 let challenge: Uint8Array = asset.preQuerySync(query); 537} catch (error) { 538 let err = error as BusinessError; 539 console.error(`Failed to pre-query Asset. Code is ${err.code}, message is ${err.message}`); 540} 541``` 542 543## asset.query 544 545query(query: AssetMap): Promise\<Array\<AssetMap>> 546 547Queries one or more assets. If user authentication is required for the access to the asset, call [asset.preQuery](#assetprequery) before this API and call [asset.postQuery](#assetpostquery) after this API. For details about the development procedure, see [Querying an Asset with User Authentication](../../security/AssetStoreKit/asset-js-query-auth.md). This API uses a promise to return the result. 548 549**Atomic service API**: This API can be used in atomic services since API version 14. 550 551**System capability**: SystemCapability.Security.Asset 552 553**Parameters** 554 555| Name | Type | Mandatory| Description | 556| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 557| query | [AssetMap](#assetmap) | Yes | Attributes of the asset to query, such as the asset alias, access control attributes, and custom data. | 558 559**Return value** 560 561| Type | Description | 562| ------------------------ | ------------------------------------- | 563| Promise\<Array\<AssetMap>> | Promise used to return the result obtained.| 564 565**Error codes** 566 567For details about the error codes, see [Asset Store Service Error Codes](errorcode-asset.md). 568 569| ID| Error Message | 570| -------- | ---------------------------------------------------------- | 571| 401 | Parameter error. Possible causes: <br> 1. Incorrect parameter types. <br> 2. Parameter verification failed. | 572| 24000001 | The ASSET service is unavailable. | 573| 24000002 | The asset is not found. | 574| 24000004 | Access denied. | 575| 24000005 | The screen lock status does not match. | 576| 24000006 | Insufficient memory. | 577| 24000007 | The asset is corrupted. | 578| 24000008 | The database operation failed. | 579| 24000009 | The cryptography operation failed. | 580| 24000010 | IPC failed. | 581| 24000011 | Calling the Bundle Manager service failed. | 582| 24000012 | Calling the OS Account service failed. | 583| 24000013 | Calling the Access Token service failed. | 584| 24000017 | The capability is not supported. | 585 586**Example** 587 588```typescript 589import { asset } from '@kit.AssetStoreKit'; 590import { util } from '@kit.ArkTS'; 591import { BusinessError } from '@kit.BasicServicesKit'; 592 593function stringToArray(str: string): Uint8Array { 594 let textEncoder = new util.TextEncoder(); 595 return textEncoder.encodeInto(str); 596} 597 598let query: asset.AssetMap = new Map(); 599query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 600try { 601 asset.query(query).then((res: Array<asset.AssetMap>) => { 602 for (let i = 0; i < res.length; i++) { 603 // parse the attribute. 604 let accessibility: number = res[i].get(asset.Tag.ACCESSIBILITY) as number; 605 } 606 console.info(`Asset query succeeded.`); 607 }).catch ((err: BusinessError) => { 608 console.error(`Failed to query Asset. Code is ${err.code}, message is ${err.message}`); 609 }); 610} catch (error) { 611 let err = error as BusinessError; 612 console.error(`Failed to query Asset. Code is ${err.code}, message is ${err.message}`); 613} 614``` 615 616## asset.querySync<sup>12+</sup> 617 618querySync(query: AssetMap): Array\<AssetMap> 619 620Queries one or more assets. If user authentication is required for the access to the asset, call [asset.preQuerySync](#assetprequerysync12) before this API and call [asset.postQuerySync](#assetpostquerysync12) after this API. For details about the development procedure, see [Querying an Asset with User Authentication](../../security/AssetStoreKit/asset-js-query-auth.md). This API returns the result synchronously. 621 622**Atomic service API**: This API can be used in atomic services since API version 14. 623 624**System capability**: SystemCapability.Security.Asset 625 626**Parameters** 627 628| Name | Type | Mandatory| Description | 629| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 630| query | [AssetMap](#assetmap) | Yes | Attributes of the asset to query, such as the asset alias, access control attributes, and custom data. | 631 632**Return value** 633 634| Type | Description | 635| ------------------------ | ------------------------------------- | 636| Array\<AssetMap> | Array of query results.| 637 638**Error codes** 639 640For details about the error codes, see [Asset Store Service Error Codes](errorcode-asset.md). 641 642| ID| Error Message | 643| -------- | ---------------------------------------------------------- | 644| 401 | Parameter error. Possible causes: <br> 1. Incorrect parameter types. <br> 2. Parameter verification failed. | 645| 24000001 | The ASSET service is unavailable. | 646| 24000002 | The asset is not found. | 647| 24000004 | Access denied. | 648| 24000005 | The screen lock status does not match. | 649| 24000006 | Insufficient memory. | 650| 24000007 | The asset is corrupted. | 651| 24000008 | The database operation failed. | 652| 24000009 | The cryptography operation failed. | 653| 24000010 | IPC failed. | 654| 24000011 | Calling the Bundle Manager service failed. | 655| 24000012 | Calling the OS Account service failed. | 656| 24000013 | Calling the Access Token service failed. | 657| 24000017 | The capability is not supported. | 658 659**Example** 660 661```typescript 662import { asset } from '@kit.AssetStoreKit'; 663import { util } from '@kit.ArkTS'; 664import { BusinessError } from '@kit.BasicServicesKit'; 665 666function stringToArray(str: string): Uint8Array { 667 let textEncoder = new util.TextEncoder(); 668 return textEncoder.encodeInto(str); 669} 670 671let query: asset.AssetMap = new Map(); 672query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 673try { 674 let res: Array<asset.AssetMap> = asset.querySync(query); 675 let accessibility: number; 676 for (let i = 0; i < res.length; i++) { 677 // parse the attribute. 678 if (res[i] != null) { 679 accessibility = res[i].get(asset.Tag.ACCESSIBILITY) as number; 680 } 681 } 682} catch (error) { 683 let err = error as BusinessError; 684 console.error(`Failed to query Asset. Code is ${err.code}, message is ${err.message}`); 685} 686``` 687 688## asset.postQuery 689 690postQuery(handle: AssetMap): Promise\<void> 691 692Performs postprocessing for the asset query. This API is used when user authentication is required for the access to the asset. This API must be used with [asset.preQuery](#assetprequery) together. This API uses a promise to return the result. 693 694**Atomic service API**: This API can be used in atomic services since API version 14. 695 696**System capability**: SystemCapability.Security.Asset 697 698**Parameters** 699 700| Name| Type | Mandatory| Description | 701| ------ | -------- | ---- | ------------------------------------------------------------ | 702| handle | [AssetMap](#assetmap) | Yes | Handle of the query operation, including the challenge value returned by [asset.preQuery](#assetprequery).| 703 704**Return value** 705 706| Type | Description | 707| ------------- | ----------------------- | 708| Promise\<void> | Promise that returns no value.| 709 710**Error codes** 711 712For details about the error codes, see [Asset Store Service Error Codes](errorcode-asset.md). 713 714| ID| Error Message | 715| -------- | ---------------------------------------------------------- | 716| 401 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameter types. <br> 3. Parameter verification failed. | 717| 24000001 | The ASSET service is unavailable. | 718| 24000006 | Insufficient memory. | 719| 24000010 | IPC failed. | 720| 24000011 | Calling the Bundle Manager service failed. | 721| 24000012 | Calling the OS Account service failed. | 722| 24000013 | Calling the Access Token service failed. | 723 724**Example** 725 726```typescript 727import { asset } from '@kit.AssetStoreKit'; 728import { BusinessError } from '@kit.BasicServicesKit'; 729 730let handle: asset.AssetMap = new Map(); 731// The new Uint8Array(32) is only an example. Pass in the challenge value returned by asset.preQuery. 732handle.set(asset.Tag.AUTH_CHALLENGE, new Uint8Array(32)); 733try { 734 asset.postQuery(handle).then(() => { 735 console.info(`Succeeded in post-querying Asset.`); 736 }).catch ((err: BusinessError) => { 737 console.error(`Failed to post-query Asset. Code is ${err.code}, message is ${err.message}`); 738 }); 739} catch (error) { 740 let err = error as BusinessError; 741 console.error(`Failed to post-query Asset. Code is ${err.code}, message is ${err.message}`); 742} 743``` 744 745## asset.postQuerySync<sup>12+</sup> 746 747postQuerySync(handle: AssetMap): void 748 749Performs postprocessing for the asset query. This API is used when user authentication is required for the access to the asset. This API must be used with [asset.preQuerySync](#assetprequerysync12) together. This API returns the result synchronously. 750 751**Atomic service API**: This API can be used in atomic services since API version 14. 752 753**System capability**: SystemCapability.Security.Asset 754 755**Parameters** 756 757| Name| Type | Mandatory| Description | 758| ------ | -------- | ---- | ------------------------------------------------------------ | 759| handle | [AssetMap](#assetmap) | Yes | Handle of the query operation, including the challenge value returned by [asset.preQuerySync](#assetprequerysync12).| 760 761**Error codes** 762 763For details about the error codes, see [Asset Store Service Error Codes](errorcode-asset.md). 764 765| ID| Error Message | 766| -------- | ---------------------------------------------------------- | 767| 401 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameter types. <br> 3. Parameter verification failed. | 768| 24000001 | The ASSET service is unavailable. | 769| 24000006 | Insufficient memory. | 770| 24000010 | IPC failed. | 771| 24000011 | Calling the Bundle Manager service failed. | 772| 24000012 | Calling the OS Account service failed. | 773| 24000013 | Calling the Access Token service failed. | 774 775**Example** 776 777```typescript 778import { asset } from '@kit.AssetStoreKit'; 779import { BusinessError } from '@kit.BasicServicesKit'; 780 781let handle: asset.AssetMap = new Map(); 782// The new Uint8Array(32) is only an example. Pass in the challenge value returned by asset.preQuerySync. 783handle.set(asset.Tag.AUTH_CHALLENGE, new Uint8Array(32)); 784try { 785 asset.postQuerySync(handle) 786} catch (error) { 787 let err = error as BusinessError; 788 console.error(`Failed to post-query Asset. Code is ${err.code}, message is ${err.message}`); 789} 790``` 791 792## TagType 793 794Enumerates the asset attribute types. 795 796**Atomic service API**: This API can be used in atomic services since API version 14. 797 798**System capability**: SystemCapability.Security.Asset 799 800| Name | Value | Description | 801| ------ | ---------- | ---------------------------------------- | 802| BOOL | 0x01 << 28 | Boolean. | 803| NUMBER | 0x02 << 28 | Number. | 804| BYTES | 0x03 << 28 | Byte array.| 805 806## Tag 807 808Enumerate the keys of asset attributes ([AssetMap](#assetmap)), which are in key-value (KV) pairs. 809 810**System capability**: SystemCapability.Security.Asset 811 812> **NOTE** 813> 814> The following table lists all enums of **Tag**. The specific tags and the value range of tag values vary with the API you use. For details, see [Introduction to Asset Store Kit](../../security/AssetStoreKit/asset-store-kit-overview.md). 815 816| Name| Value | Description | 817| ------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 818| SECRET | TagType.BYTES | 0x01 | Asset plaintext.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 819| ALIAS | TagType.BYTES | 0x02 | Asset alias, which uniquely identifies an asset.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 820| ACCESSIBILITY | TagType.NUMBER | 0x03 | Access control based on the lock screen status.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 821| REQUIRE_PASSWORD_SET | TagType.BOOL | 0x04 | Whether the asset is accessible only when a lock screen password is set.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 822| AUTH_TYPE | TagType.NUMBER | 0x05 | Type of user authentication required for accessing the asset.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 823| AUTH_VALIDITY_PERIOD | TagType.NUMBER | 0x06 | Validity period of the user authentication.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 824| AUTH_CHALLENGE | TagType.BYTES | 0x07 | Challenge for the user authentication.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 825| AUTH_TOKEN | TagType.BYTES | 0x08 | Authorization token obtained after the user authentication is successful.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 826| SYNC_TYPE | TagType.NUMBER | 0x10 | Asset sync type.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 827| IS_PERSISTENT | TagType.BOOL | 0x11 | Whether to retain the asset when the application is uninstalled.| 828| DATA_LABEL_CRITICAL_1 | TagType.BYTES | 0x20 | Additional asset data customized by the service with integrity protection.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 829| DATA_LABEL_CRITICAL_2 | TagType.BYTES | 0x21 | Additional asset data customized by the service with integrity protection.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 830| DATA_LABEL_CRITICAL_3 | TagType.BYTES | 0x22 | Additional asset data customized by the service with integrity protection.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 831| DATA_LABEL_CRITICAL_4 | TagType.BYTES | 0x23 | Additional asset data customized by the service with integrity protection.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 832| DATA_LABEL_NORMAL_1 | TagType.BYTES | 0x30 | Additional asset data customized by the service without integrity protection.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 833| DATA_LABEL_NORMAL_2 | TagType.BYTES | 0x31 | Additional asset data customized by the service without integrity protection.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 834| DATA_LABEL_NORMAL_3 | TagType.BYTES | 0x32 | Additional asset data customized by the service without integrity protection.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 835| DATA_LABEL_NORMAL_4 | TagType.BYTES | 0x33 | Additional asset data customized by the service without integrity protection.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 836| DATA_LABEL_NORMAL_LOCAL_1<sup>12+</sup> | TagType.BYTES | 0x34 | Local information about the asset. The value is assigned by the service without integrity protection and will not be synced.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 837| DATA_LABEL_NORMAL_LOCAL_2<sup>12+</sup> | TagType.BYTES | 0x35 | Local information about the asset. The value is assigned by the service without integrity protection and will not be synced.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 838| DATA_LABEL_NORMAL_LOCAL_3<sup>12+</sup> | TagType.BYTES | 0x36 | Local information about the asset. The value is assigned by the service without integrity protection and will not be synced.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 839| DATA_LABEL_NORMAL_LOCAL_4<sup>12+</sup> | TagType.BYTES | 0x37 | Local information about the asset. The value is assigned by the service without integrity protection and will not be synced.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 840| RETURN_TYPE | TagType.NUMBER | 0x40 | Type of the asset query result to return.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 841| RETURN_LIMIT | TagType.NUMBER | 0x41 | Maximum number of asset records to return.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 842| RETURN_OFFSET | TagType.NUMBER | 0x42 | Offset of the asset query result.<br>**NOTE**: This parameter specifies the starting asset record to return in batch asset query.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 843| RETURN_ORDERED_BY | TagType.NUMBER | 0x43 | Sorting order of the query results. Currently, the results can be sorted only by **ASSET_TAG_DATA_LABEL**.<br>**NOTE**: By default, assets are returned in the order in which they are added.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 844| CONFLICT_RESOLUTION | TagType.NUMBER | 0x44 | Policy for resolving the conflict (for example, a duplicate alias).<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 845| UPDATE_TIME<sup>12+</sup> | TagType.BYTES | 0x45 | Data update time, in timestamp.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 846| OPERATION_TYPE<sup>12+</sup> | TagType.NUMBER | 0x46 | Additional operation type.| 847| REQUIRE_ATTR_ENCRYPTED<sup>14+</sup> | TagType.BOOL | 0x47 | Whether to encrypt the additional asset information customized by the service.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 848 849## Value 850 851type Value = boolean | number | Uint8Array; 852 853Represents the value of each attribute in [AssetMap](#assetmap). 854 855**Atomic service API**: This API can be used in atomic services since API version 14. 856 857**System capability**: SystemCapability.Security.Asset 858 859| Type | Description | 860| ------- | ------------------------------------------------| 861| boolean | The value is a Boolean value, that is, **true** or **false**. | 862| number | The value is a number. It can be an enumerated value or a numeric value.| 863| Uint8Array | The value is a byte array, and the content is defined by the service. | 864 865## AssetMap 866 867type AssetMap = Map\<Tag, Value> 868 869Represents a set of asset attributes in the form of KV pairs. 870 871**Atomic service API**: This API can be used in atomic services since API version 14. 872 873**System capability**: SystemCapability.Security.Asset 874 875| Type | Description | 876| ---------------- | ------------------------------------------------------------------| 877| Map\<Tag, Value> | The value type is Map. For details about the range of the KV pair, see [Tag](#tag) and [Value](#value).| 878 879## Accessibility 880 881Enumerates the types of access control based on the lock screen status. 882 883**Atomic service API**: This API can be used in atomic services since API version 14. 884 885**System capability**: SystemCapability.Security.Asset 886 887| Name | Value | Description | 888| --------------------- | ---- | ------------------------------------------------------------ | 889| DEVICE_POWERED_ON | 0 | The asset can be accessed after the device is powered on. | 890| DEVICE_FIRST_UNLOCKED | 1 | The asset can be accessed only after the device is unlocked for the first time.<br>**NOTE**: If no lock screen password is set, this option is equivalent to **DEVICE_POWERED_ON**.| 891| DEVICE_UNLOCKED | 2 | The asset can be accessed only when the device is unlocked.<br>**NOTE**: If no lock screen password is set, this option is equivalent to **DEVICE_POWERED_ON**.| 892 893## AuthType 894 895Enumerates the types of user authentication supported by an asset. 896 897**Atomic service API**: This API can be used in atomic services since API version 14. 898 899**System capability**: SystemCapability.Security.Asset 900 901| Name| Value | Description | 902| ---- | ---- | ------------------------------------------------------------ | 903| NONE | 0 | No user authentication is required before the asset is accessed. | 904| ANY | 255 | The asset can be accessed if any user authentication (such as PIN, facial, or fingerprint authentication) is successful.| 905 906## SyncType 907 908Enumerates the sync types supported by an asset. 909 910> **NOTE** 911> 912> This field is an embedded parameter. Currently, asset sync is not supported. 913 914**Atomic service API**: This API can be used in atomic services since API version 14. 915 916**System capability**: SystemCapability.Security.Asset 917 918| Name | Value | Description | 919| ----------------------------- | ------ | ------------------------------------------------ | 920| NEVER | 0 | Asset sync is not allowed. | 921| THIS_DEVICE | 1 << 0 | Asset sync is allowed only on the local device, for example, in data restore on the local device.| 922| TRUSTED_DEVICE | 1 << 1 | Asset sync is allowed only between trusted devices, for example, in the case of cloning. | 923| TRUSTED_ACCOUNT<sup>12+</sup> | 1 << 2 | Asset sync is allowed only between the devices that are logged in with trusted accounts, for example, in cloud sync scenarios.| 924 925## ReturnType 926 927Enumerates the type of information returned by an asset query operation. 928 929**Atomic service API**: This API can be used in atomic services since API version 14. 930 931**System capability**: SystemCapability.Security.Asset 932 933| Name | Value | Description | 934| ---------- | ---- | ------------------------------------------------------------ | 935| ALL | 0 | The query result contains the asset plaintext and its attributes.<br>**NOTE**: Use this option when you need to query the plaintext of a single asset.| 936| ATTRIBUTES | 1 | The query result contains only the asset attributes.<br>**NOTE**: Use this option when you need to query attributes of multiple assets.| 937 938## ConflictResolution 939 940Enumerates the policies for resolving conflicts (for example, a duplicate alias) when an asset is added. 941 942**Atomic service API**: This API can be used in atomic services since API version 14. 943 944**System capability**: SystemCapability.Security.Asset 945 946| Name | Value | Description | 947| ----------- | ---- | ---------------------------- | 948| OVERWRITE | 0 | Overwrite the original asset. | 949| THROW_ERROR | 1 | Throw an exception for the service to perform subsequent processing.| 950 951## OperationType<sup>12+</sup> 952 953Enumerates the types of additional operation to perform. 954 955**System capability**: SystemCapability.Security.Asset 956 957| Name | Value | Description | 958| ----------- | ---- | ------------------ | 959| NEED_SYNC | 0 | Sync.| 960| NEED_LOGOUT | 1 | Logout.| 961 962## ErrorCode 963 964Enumerates the error codes. 965 966**System capability**: SystemCapability.Security.Asset 967 968| Name | Value | Description| 969| -------------------------- | ----- | ---- | 970| PERMISSION_DENIED | 201 |The caller does not have the permission.| 971| NOT_SYSTEM_APPLICATION<sup>12+</sup> | 202 |The caller is not a system application.| 972| INVALID_ARGUMENT | 401 |Incorrect parameters are detected.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 973| SERVICE_UNAVAILABLE | 24000001 |The asset store service is unavailable.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 974| NOT_FOUND | 24000002 |Failed to find the asset.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 975| DUPLICATED | 24000003 |The specified asset already exists.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 976| ACCESS_DENIED | 24000004 |The access to the asset is denied.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 977| STATUS_MISMATCH | 24000005 |The screen lock status does not match.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 978| OUT_OF_MEMORY | 24000006 |The system memory is insufficient.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 979| DATA_CORRUPTED | 24000007 |The asset is corrupted.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 980| DATABASE_ERROR | 24000008 |The database operation failed.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 981| CRYPTO_ERROR | 24000009 |The crypto operation failed.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 982| IPC_ERROR | 24000010 |IPC failed.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 983| BMS_ERROR | 24000011 |The Bundle Manager service is abnormal.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 984| ACCOUNT_ERROR | 24000012 |The account service is abnormal.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 985| ACCESS_TOKEN_ERROR | 24000013 |The Access Token service is abnormal.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 986| FILE_OPERATION_ERROR | 24000014 |The file operation failed.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 987| GET_SYSTEM_TIME_ERROR | 24000015 |Failed to obtain the system time.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 988| LIMIT_EXCEEDED | 24000016 |The number of cached records exceeds the upper limit.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 989| UNSUPPORTED | 24000017 |The feature is not supported.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 990