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