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