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```