1# @ohos.security.asset (关键资产存储服务)(系统接口) 2 3<!--Kit: Asset Store Kit--> 4<!--Subsystem: Security--> 5<!--Owner: @JeremyXu--> 6<!--Designer: @skye_you--> 7<!--Tester: @nacyli--> 8<!--Adviser: @zengyawen--> 9 10关键资产存储服务提供了用户短敏感数据的安全存储及管理能力。其中，短敏感数据可以是密码类（账号/密码）、Token类（应用凭据）、其他关键明文（如银行卡号）等长度较短的用户敏感数据。 11 12> **说明：** 13> 14> - 本模块首批接口从API version 12 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15> - 当前页面仅包含本模块的系统接口，其他公开接口参见[ohos.security.asset (关键资产存储服务)](js-apis-asset.md)。 16 17## 导入模块 18 19```typescript 20import { asset } from '@kit.AssetStoreKit'; 21``` 22 23## asset.addAsUser 24 25addAsUser(userId: number, attributes: AssetMap): Promise\<void> 26 27在指定用户空间中新增一条关键资产。使用Promise异步回调。 28 29设置[IS_PERSISTENT](js-apis-asset.md#tag)属性，需申请ohos.permission.STORE_PERSISTENT_DATA权限。 30 31**系统接口：** 此接口为系统接口。 32 33**需要权限：** ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 34 35**系统能力：** SystemCapability.Security.Asset 36 37**参数：** 38 39| 参数名 | 类型 | 必填 | 说明 | 40| ---------- | -------- | ---- | ------------------------------------------------------------ | 41| userId | number | 是 | 用户ID。取值范围大于等于100。 | 42| attributes | [AssetMap](js-apis-asset.md#assetmap) | 是 | 待新增关键资产的属性集合，包括关键资产明文、访问控制属性、自定义数据等。 | 43 44**返回值：** 45 46| 类型 | 说明 | 47| ------------- | ----------------------- | 48| Promise\<void> | Promise对象，无返回结果。 | 49 50**错误码：** 51 52以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 53 54| 错误码ID | 错误信息 | 55| -------- | ---------------------------------------------------------- | 56| 201 | The caller doesn't have the permission. | 57| 202 | Non-system applications use system APIs. | 58| 401 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameter types. <br> 3. Parameter verification failed. | 59| 24000001 | The ASSET service is unavailable. | 60| 24000003 | The asset already exists. | 61| 24000005 | The screen lock status does not match. | 62| 24000006 | Insufficient memory. | 63| 24000007 | The asset is corrupted. | 64| 24000008 | The database operation failed. | 65| 24000009 | The cryptography operation failed. | 66| 24000010 | IPC failed. | 67| 24000011 | Calling the Bundle Manager service failed. | 68| 24000012 | Calling the OS Account service failed. | 69| 24000013 | Calling the Access Token service failed. | 70| 24000014 | The file operation failed. | 71| 24000015 | Getting the system time failed. | 72 73**示例：** 74 75```typescript 76import { asset } from '@kit.AssetStoreKit'; 77import { util } from '@kit.ArkTS'; 78 79function stringToArray(str: string): Uint8Array { 80 let textEncoder = new util.TextEncoder(); 81 return textEncoder.encodeInto(str); 82} 83 84let userId: number = 100; 85let attr: asset.AssetMap = new Map(); 86attr.set(asset.Tag.SECRET, stringToArray('demo_pwd')); 87attr.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 88attr.set(asset.Tag.ACCESSIBILITY, asset.Accessibility.DEVICE_FIRST_UNLOCKED); 89attr.set(asset.Tag.DATA_LABEL_NORMAL_1, stringToArray('demo_label')); 90asset.addAsUser(userId, attr).then(() => { 91 console.info(`Succeeded in adding Asset to user space.`); 92}); 93``` 94 95## asset.removeAsUser 96 97removeAsUser(userId: number, query: AssetMap): Promise\<void> 98 99从指定用户空间中删除符合条件的一条或多条关键资产。使用Promise异步回调。 100 101**系统接口：** 此接口为系统接口。 102 103**需要权限：** ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 104 105**系统能力：** SystemCapability.Security.Asset 106 107**参数：** 108 109| 参数名 | 类型 | 必填 | 说明 | 110| ------ | -------- | ---- | ------------------------------------------------------ | 111| userId | number | 是 | 用户ID。取值范围大于等于100。 | 112| query | [AssetMap](js-apis-asset.md#assetmap) | 是 | 待删除关键资产的搜索条件，如别名、访问控制属性、自定义数据等。 | 113 114**返回值：** 115 116| 类型 | 说明 | 117| ------------- | ----------------------- | 118| Promise\<void> | Promise对象，无返回结果。 | 119 120**错误码：** 121 122以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 123 124| 错误码ID | 错误信息 | 125| -------- | ---------------------------------------------------------- | 126| 201 | The caller doesn't have the permission. | 127| 202 | Non-system applications use system APIs. | 128| 401 | Parameter error. Possible causes: <br> 1. Incorrect parameter types. <br> 2. Parameter verification failed. | 129| 24000001 | The ASSET service is unavailable. | 130| 24000002 | The asset is not found. | 131| 24000006 | Insufficient memory. | 132| 24000007 | The asset is corrupted. | 133| 24000008 | The database operation failed. | 134| 24000010 | IPC failed. | 135| 24000011 | Calling the Bundle Manager service failed. | 136| 24000012 | Calling the OS Account service failed. | 137| 24000013 | Calling the Access Token service failed. | 138| 24000015 | Getting the system time failed. | 139 140**示例：** 141 142```typescript 143import { asset } from '@kit.AssetStoreKit'; 144import { util } from '@kit.ArkTS'; 145 146function stringToArray(str: string): Uint8Array { 147 let textEncoder = new util.TextEncoder(); 148 return textEncoder.encodeInto(str); 149} 150 151let userId: number = 100; 152let query: asset.AssetMap = new Map(); 153query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 154asset.removeAsUser(userId, query).then(() => { 155 console.info(`Succeeded in removing Asset from user space.`); 156}); 157``` 158 159## asset.updateAsUser 160 161updateAsUser(userId: number, query: AssetMap, attributesToUpdate: AssetMap): Promise\<void> 162 163在指定用户空间中更新符合条件的一条关键资产。使用Promise异步回调。 164 165**系统接口：** 此接口为系统接口。 166 167**需要权限：** ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 168 169**系统能力：** SystemCapability.Security.Asset 170 171**参数：** 172 173| 参数名 | 类型 | 必填 | 说明 | 174| ------------------ | -------- | ---- | ------------------------------------------------------------ | 175| userId | number | 是 | 用户ID。取值范围大于等于100。 | 176| query | [AssetMap](js-apis-asset.md#assetmap) | 是 | 待更新关键资产的搜索条件，如关键资产别名、访问控制属性、自定义数据等。 | 177| attributesToUpdate | [AssetMap](js-apis-asset.md#assetmap) | 是 | 待更新关键资产的属性集合，如关键资产明文和自定义数据等。 | 178 179**返回值：** 180 181| 类型 | 说明 | 182| ------------- | ----------------------- | 183| Promise\<void> | Promise对象，无返回结果。 | 184 185**错误码：** 186 187以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 188 189| 错误码ID | 错误信息 | 190| -------- | ---------------------------------------------------------- | 191| 201 | The caller doesn't have the permission. | 192| 202 | Non-system applications use system APIs. | 193| 401 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameter types. <br> 3. Parameter verification failed. | 194| 24000001 | The ASSET service is unavailable. | 195| 24000002 | The asset is not found. | 196| 24000005 | The screen lock status does not match. | 197| 24000006 | Insufficient memory. | 198| 24000007 | The asset is corrupted. | 199| 24000008 | The database operation failed. | 200| 24000009 | The cryptography operation failed. | 201| 24000010 | IPC failed. | 202| 24000011 | Calling the Bundle Manager service failed. | 203| 24000012 | Calling the OS Account service failed. | 204| 24000013 | Calling the Access Token service failed. | 205| 24000015 | Getting the system time failed. | 206 207**示例：** 208 209```typescript 210import { asset } from '@kit.AssetStoreKit'; 211import { util } from '@kit.ArkTS'; 212 213function stringToArray(str: string): Uint8Array { 214 let textEncoder = new util.TextEncoder(); 215 return textEncoder.encodeInto(str); 216} 217 218let userId: number = 100; 219let query: asset.AssetMap = new Map(); 220query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 221let attrsToUpdate: asset.AssetMap = new Map(); 222attrsToUpdate.set(asset.Tag.SECRET, stringToArray('demo_pwd_new')); 223asset.updateAsUser(userId, query, attrsToUpdate).then(() => { 224 console.info(`Succeeded in updating Asset in user space.`); 225}); 226``` 227 228## asset.preQueryAsUser 229 230preQueryAsUser(userId: number, query: AssetMap): Promise\<Uint8Array> 231 232在指定用户空间中查询的预处理，用于需要用户认证的关键资产。在用户认证成功后，应当随后调用[asset.queryAsUser](#assetqueryasuser)和[asset.postQueryAsUser](#assetpostqueryasuser)接口。使用Promise异步回调。 233 234**系统接口：** 此接口为系统接口。 235 236**需要权限：** ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 237 238**系统能力：** SystemCapability.Security.Asset 239 240**参数：** 241 242| 参数名 | 类型 | 必填 | 说明 | 243| ------ | -------- | ---- | ------------------------------------------------------ | 244| userId | number | 是 | 用户ID。取值范围大于等于100。 | 245| query | [AssetMap](js-apis-asset.md#assetmap) | 是 | 关键资产的查询条件，如别名、访问控制属性、自定义数据等。 | 246 247**返回值：** 248 249| 类型 | 说明 | 250| ------------------- | ----------------------------------------------------- | 251| Promise\<Uint8Array> | Promise对象，返回挑战值。<br>**说明：** 挑战值用于后续用户认证。 | 252 253**错误码：** 254 255以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 256 257| 错误码ID | 错误信息 | 258| -------- | ------------------------------------------------------------ | 259| 201 | The caller doesn't have the permission. | 260| 202 | Non-system applications use system APIs. | 261| 401 | Parameter error. Possible causes: <br> 1. Incorrect parameter types. <br> 2. Parameter verification failed. | 262| 24000001 | The ASSET service is unavailable. | 263| 24000002 | The asset is not found. | 264| 24000005 | The screen lock status does not match. | 265| 24000006 | Insufficient memory. | 266| 24000007 | The asset is corrupted. | 267| 24000008 | The database operation failed. | 268| 24000009 | The cryptography operation failed. | 269| 24000010 | IPC failed. | 270| 24000011 | Calling the Bundle Manager service failed. | 271| 24000012 | Calling the OS Account service failed. | 272| 24000013 | Calling the Access Token service failed. | 273| 24000016 | The cache exceeds the limit. | 274| 24000017 | The capability is not supported. | 275 276**示例：** 277 278```typescript 279import { asset } from '@kit.AssetStoreKit'; 280import { util } from '@kit.ArkTS'; 281 282function stringToArray(str: string): Uint8Array { 283 let textEncoder = new util.TextEncoder(); 284 return textEncoder.encodeInto(str); 285} 286 287let userId: number = 100; 288let query: asset.AssetMap = new Map(); 289query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 290asset.preQueryAsUser(userId, query).then((challenge: Uint8Array) => { 291 console.info(`Succeeded in pre-querying Asset from user space.`); 292}); 293``` 294 295## asset.queryAsUser 296 297queryAsUser(userId: number, query: AssetMap): Promise\<Array\<AssetMap>> 298 299在指定用户空间中查询一条或多条符合条件的关键资产。若查询需要用户认证的关键资产，则需要在本函数前调用[asset.preQueryAsUser](#assetprequeryasuser)接口，在本函数后调用[asset.postQueryAsUser](#assetpostqueryasuser)接口，开发步骤请参考[开发指导](../../security/AssetStoreKit/asset-js-query-auth.md)。使用Promise异步回调。 300 301**系统接口：** 此接口为系统接口。 302 303**需要权限：** ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 304 305**系统能力：** SystemCapability.Security.Asset 306 307**参数：** 308 309| 参数名 | 类型 | 必填 | 说明 | 310| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 311| userId | number | 是 | 用户ID。取值范围大于等于100。 | 312| query | [AssetMap](js-apis-asset.md#assetmap) | 是 | 关键资产的查询条件，如别名、访问控制属性、自定义数据等。 | 313 314**返回值：** 315 316| 类型 | 说明 | 317| ------------------------ | ------------------------------------- | 318| Promise\<Array\<AssetMap>> | Promise对象，返回查询结果列表。 | 319 320**错误码：** 321 322以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 323 324| 错误码ID | 错误信息 | 325| -------- | ---------------------------------------------------------- | 326| 201 | The caller doesn't have the permission. | 327| 202 | Non-system applications use system APIs. | 328| 401 | Parameter error. Possible causes: <br> 1. Incorrect parameter types. <br> 2. Parameter verification failed. | 329| 24000001 | The ASSET service is unavailable. | 330| 24000002 | The asset is not found. | 331| 24000004 | Access denied. | 332| 24000005 | The screen lock status does not match. | 333| 24000006 | Insufficient memory. | 334| 24000007 | The asset is corrupted. | 335| 24000008 | The database operation failed. | 336| 24000009 | The cryptography operation failed. | 337| 24000010 | IPC failed. | 338| 24000011 | Calling the Bundle Manager service failed. | 339| 24000012 | Calling the OS Account service failed. | 340| 24000013 | Calling the Access Token service failed. | 341| 24000017 | The capability is not supported. | 342 343**示例：** 344 345```typescript 346import { asset } from '@kit.AssetStoreKit'; 347import { util } from '@kit.ArkTS'; 348 349function stringToArray(str: string): Uint8Array { 350 let textEncoder = new util.TextEncoder(); 351 return textEncoder.encodeInto(str); 352} 353 354let userId: number = 100; 355let query: asset.AssetMap = new Map(); 356query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 357asset.queryAsUser(userId, query).then((res: Array<asset.AssetMap>) => { 358 for (let i = 0; i < res.length; i++) { 359 // 解析属性。 360 let accessibility: number = res[i].get(asset.Tag.ACCESSIBILITY) as number; 361 console.info(`Succeeded in getting accessibility, which is: ${accessibility}.`); 362 } 363 console.info(`Succeeded in querying Asset from user space.`); 364}); 365``` 366 367## asset.postQueryAsUser 368 369postQueryAsUser(userId: number, handle: AssetMap): Promise\<void> 370 371在指定用户空间中查询的后置处理，用于需要用户认证的关键资产（与[asset.preQueryAsUser](#assetprequeryasuser)函数成对出现）。使用Promise异步回调。 372 373**系统接口：** 此接口为系统接口。 374 375**需要权限：** ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 376 377**系统能力：** SystemCapability.Security.Asset 378 379**参数：** 380 381| 参数名 | 类型 | 必填 | 说明 | 382| ------ | -------- | ---- | ------------------------------------------------------------ | 383| userId | number | 是 | 用户ID。取值范围大于等于100。 | 384| handle | [AssetMap](js-apis-asset.md#assetmap) | 是 | 待处理的查询句柄，当前包含[asset.preQueryAsUser](#assetprequeryasuser)执行成功返回的挑战值。 | 385 386**返回值：** 387 388| 类型 | 说明 | 389| ------------- | ----------------------- | 390| Promise\<void> | Promise对象，无返回结果。 | 391 392**错误码：** 393 394以下错误码的详细介绍请参见[关键资产存储服务错误码](errorcode-asset.md) 395 396| 错误码ID | 错误信息 | 397| -------- | ---------------------------------------------------------- | 398| 201 | The caller doesn't have the permission. | 399| 202 | Non-system applications use system APIs. | 400| 401 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified. <br> 2. Incorrect parameter types. <br> 3. Parameter verification failed. | 401| 24000001 | The ASSET service is unavailable. | 402| 24000006 | Insufficient memory. | 403| 24000010 | IPC failed. | 404| 24000011 | Calling the Bundle Manager service failed. | 405| 24000012 | Calling the OS Account service failed. | 406| 24000013 | Calling the Access Token service failed. | 407 408**示例：** 409 410```typescript 411import { asset } from '@kit.AssetStoreKit'; 412 413let userId: number = 100; 414let handle: asset.AssetMap = new Map(); 415// 此处传入的new Uint8Array(32)仅作为示例，实际应传入asset.preQueryAsUser执行成功返回的挑战值 416handle.set(asset.Tag.AUTH_CHALLENGE, new Uint8Array(32)); 417asset.postQueryAsUser(userId, handle).then(() => { 418 console.info(`Succeeded in post-querying Asset from user space.`); 419}); 420```