@ohos.security.asset (关键资产存储服务)

关键资产存储服务提供了用户短敏感数据的安全存储及管理能力。其中，短敏感数据可以是密码类（账号/密码）、Token类（应用凭据）、其他关键明文（如银行卡号）等长度较短的用户敏感数据。

说明：

本模块首批接口从API version 11 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import { asset } from '@kit.AssetStoreKit';

asset.add

add(attributes: AssetMap): Promise<void>

新增一条关键资产，使用Promise方式异步返回结果。

设置IS_PERSISTENT属性时，需要申请ohos.permission.STORE_PERSISTENT_DATA权限。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

参数：

返回值：

错误码：

以下错误码的详细介绍请参见关键资产存储服务错误码

示例：

import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

function stringToArray(str: string): Uint8Array {
  let textEncoder = new util.TextEncoder();
  return textEncoder.encodeInto(str);
}

let attr: asset.AssetMap = new Map();
attr.set(asset.Tag.SECRET, stringToArray('demo_pwd'));
attr.set(asset.Tag.ALIAS, stringToArray('demo_alias'));
attr.set(asset.Tag.ACCESSIBILITY, asset.Accessibility.DEVICE_FIRST_UNLOCKED);
attr.set(asset.Tag.DATA_LABEL_NORMAL_1, stringToArray('demo_label'));
try {
  asset.add(attr).then(() => {
    console.info(`Asset added successfully.`);
  }).catch((err: BusinessError) => {
    console.error(`Failed to add Asset. Code is ${err.code}, message is ${err.message}`);
  })
} catch (error) {
  let err = error as BusinessError;
  console.error(`Failed to add Asset. Code is ${err.code}, message is ${err.message}`);
}

asset.addSync¹²⁺

addSync(attributes: AssetMap): void

新增一条关键资产，使用同步方式返回结果。

如果要设置IS_PERSISTENT属性，需要申请ohos.permission.STORE_PERSISTENT_DATA权限。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

参数：

错误码：

以下错误码的详细介绍请参见关键资产存储服务错误码

示例：

import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

function stringToArray(str: string): Uint8Array {
  let textEncoder = new util.TextEncoder();
  return textEncoder.encodeInto(str);
}

let attr: asset.AssetMap = new Map();
attr.set(asset.Tag.SECRET, stringToArray('demo_pwd'));
attr.set(asset.Tag.ALIAS, stringToArray('demo_alias'));
attr.set(asset.Tag.ACCESSIBILITY, asset.Accessibility.DEVICE_FIRST_UNLOCKED);
attr.set(asset.Tag.DATA_LABEL_NORMAL_1, stringToArray('demo_label'));
try {
  asset.addSync(attr);
} catch (error) {
  let err = error as BusinessError;
  console.error(`Failed to add Asset. Code is ${err.code}, message is ${err.message}`);
}

asset.remove

remove(query: AssetMap): Promise<void>

删除符合条件的一条或多条关键资产，使用Promise方式异步返回结果。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

参数：

返回值：

错误码：

以下错误码的详细介绍请参见关键资产存储服务错误码

示例：

import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

function stringToArray(str: string): Uint8Array {
  let textEncoder = new util.TextEncoder();
  return textEncoder.encodeInto(str);
}

let query: asset.AssetMap = new Map();
query.set(asset.Tag.ALIAS, stringToArray('demo_alias'));
try {
  asset.remove(query).then(() => {
    console.info(`Asset removed successfully.`);
  }).catch((err: BusinessError) => {
    console.error(`Failed to remove Asset. Code is ${err.code}, message is ${err.message}`);
  });
} catch (error) {
  let err = error as BusinessError;
  console.error(`Failed to remove Asset. Code is ${err.code}, message is ${err.message}`);
}

asset.removeSync¹²⁺

removeSync(query: AssetMap): void

删除符合条件的一条或多条关键资产，使用同步方式。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

参数：

错误码：

以下错误码的详细介绍请参见关键资产存储服务错误码

示例：

import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

function stringToArray(str: string): Uint8Array {
  let textEncoder = new util.TextEncoder();
  return textEncoder.encodeInto(str);
}

let query: asset.AssetMap = new Map();
query.set(asset.Tag.ALIAS, stringToArray('demo_alias'));
try {
  asset.removeSync(query);
} catch (error) {
  let err = error as BusinessError;
  console.error(`Failed to remove Asset. Code is ${err.code}, message is ${err.message}`);
}

asset.update

update(query: AssetMap, attributesToUpdate: AssetMap): Promise<void>

更新符合条件的一条关键资产，使用Promise方式异步返回结果。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

参数：

返回值：

错误码：

以下错误码的详细介绍请参见关键资产存储服务错误码

示例：

import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

function stringToArray(str: string): Uint8Array {
  let textEncoder = new util.TextEncoder();
  return textEncoder.encodeInto(str);
}

let query: asset.AssetMap = new Map();
query.set(asset.Tag.ALIAS, stringToArray('demo_alias'));
let attrsToUpdate: asset.AssetMap = new Map();
attrsToUpdate.set(asset.Tag.SECRET, stringToArray('demo_pwd_new'));
try {
  asset.update(query, attrsToUpdate).then(() => {
    console.info(`Asset updated successfully.`);
  }).catch((err: BusinessError) => {
    console.error(`Failed to update Asset. Code is ${err.code}, message is ${err.message}`);
  });
} catch (error) {
  let err = error as BusinessError;
  console.error(`Failed to update Asset. Code is ${err.code}, message is ${err.message}`);
}

asset.updateSync¹²⁺

updateSync(query: AssetMap, attributesToUpdate: AssetMap): void

更新符合条件的一条关键资产，使用同步方式返回结果。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

参数：

错误码：

以下错误码的详细介绍请参见关键资产存储服务错误码

示例：

import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

function stringToArray(str: string): Uint8Array {
  let textEncoder = new util.TextEncoder();
  return textEncoder.encodeInto(str);
}

let query: asset.AssetMap = new Map();
query.set(asset.Tag.ALIAS, stringToArray('demo_alias'));
let attrsToUpdate: asset.AssetMap = new Map();
attrsToUpdate.set(asset.Tag.SECRET, stringToArray('demo_pwd_new'));
try {
  asset.updateSync(query, attrsToUpdate);
} catch (error) {
  let err = error as BusinessError;
  console.error(`Failed to update Asset. Code is ${err.code}, message is ${err.message}`);
}

asset.preQuery

preQuery(query: AssetMap): Promise<Uint8Array>

查询的预处理，用于需要用户认证的关键资产。在用户认证成功后，应当随后调用asset.query、asset.postQuery。使用Promise方式异步返回结果。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

参数：

返回值：

错误码：

以下错误码的详细介绍请参见关键资产存储服务错误码

示例：

import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

function stringToArray(str: string): Uint8Array {
  let textEncoder = new util.TextEncoder();
  return textEncoder.encodeInto(str);
}

let query: asset.AssetMap = new Map();
query.set(asset.Tag.ALIAS, stringToArray('demo_alias'));
try {
  asset.preQuery(query).then((challenge: Uint8Array) => {
    console.info(`Succeeded in pre-querying Asset.`);
  }).catch ((err: BusinessError) => {
    console.error(`Failed to pre-query Asset. Code is ${err.code}, message is ${err.message}`);
  });
} catch (error) {
  let err = error as BusinessError;
  console.error(`Failed to pre-query Asset. Code is ${err.code}, message is ${err.message}`);
}

asset.preQuerySync¹²⁺

preQuerySync(query: AssetMap): Uint8Array

查询的预处理，用于需要用户认证的关键资产。在用户认证成功后，应当随后调用asset.querySync、asset.postQuerySync。使用同步方式返回结果。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

参数：

返回值：

错误码：

以下错误码的详细介绍请参见关键资产存储服务错误码

示例：

import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

function stringToArray(str: string): Uint8Array {
  let textEncoder = new util.TextEncoder();
  return textEncoder.encodeInto(str);
}

let query: asset.AssetMap = new Map();
query.set(asset.Tag.ALIAS, stringToArray('demo_alias'));
try {
  let challenge: Uint8Array = asset.preQuerySync(query);
} catch (error) {
  let err = error as BusinessError;
  console.error(`Failed to pre-query Asset. Code is ${err.code}, message is ${err.message}`);
}

asset.query

query(query: AssetMap): Promise<Array<AssetMap>>

查询一条或多条符合条件的关键资产。若查询需要用户认证的关键资产，则需要在本函数前调用asset.preQuery，在本函数后调用asset.postQuery，开发步骤请参考开发指导。使用Promise回调异步返回结果。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

参数：

返回值：

错误码：

以下错误码的详细介绍请参见关键资产存储服务错误码

示例：

import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

function stringToArray(str: string): Uint8Array {
  let textEncoder = new util.TextEncoder();
  return textEncoder.encodeInto(str);
}

let query: asset.AssetMap = new Map();
query.set(asset.Tag.ALIAS, stringToArray('demo_alias'));
try {
  asset.query(query).then((res: Array<asset.AssetMap>) => {
    for (let i = 0; i < res.length; i++) {
      // parse the attribute.
      let accessibility: number = res[i].get(asset.Tag.ACCESSIBILITY) as number;
    }
    console.info(`Asset query succeeded.`);
  }).catch ((err: BusinessError) => {
    console.error(`Failed to query Asset. Code is ${err.code}, message is ${err.message}`);
  });
} catch (error) {
  let err = error as BusinessError;
  console.error(`Failed to query Asset. Code is ${err.code}, message is ${err.message}`);
}

asset.querySync¹²⁺

querySync(query: AssetMap): Array<AssetMap>

查询一条或多条符合条件的关键资产。若查询需要用户认证的关键资产，则需要在本函数前调用asset.preQuerySync，在本函数后调用asset.postQuerySync，开发步骤请参考开发指导。使用同步方式返回结果。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

参数：

返回值：

错误码：

以下错误码的详细介绍请参见关键资产存储服务错误码

示例：

import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

function stringToArray(str: string): Uint8Array {
  let textEncoder = new util.TextEncoder();
  return textEncoder.encodeInto(str);
}

let query: asset.AssetMap = new Map();
query.set(asset.Tag.ALIAS, stringToArray('demo_alias'));
try {
  let res: Array<asset.AssetMap> = asset.querySync(query);
  let accessibility: number;
  for (let i = 0; i < res.length; i++) {
    // parse the attribute.
    if (res[i] != null) {
      accessibility = res[i].get(asset.Tag.ACCESSIBILITY) as number;
    }
  }
} catch (error) {
  let err = error as BusinessError;
  console.error(`Failed to query Asset. Code is ${err.code}, message is ${err.message}`);
}

asset.postQuery

postQuery(handle: AssetMap): Promise<void>

查询的后置处理，用于需要用户认证的关键资产。需与asset.preQuery函数成对出现。使用Promise方式异步返回结果。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

参数：

返回值：

错误码：

以下错误码的详细介绍请参见关键资产存储服务错误码

示例：

import { asset } from '@kit.AssetStoreKit';
import { BusinessError } from '@kit.BasicServicesKit';

let handle: asset.AssetMap = new Map();
// 此处传入的new Uint8Array(32)仅作为示例，实际应传入asset.preQuery执行成功返回的挑战值。
handle.set(asset.Tag.AUTH_CHALLENGE, new Uint8Array(32));
try {
  asset.postQuery(handle).then(() => {
    console.info(`Succeeded in post-querying Asset.`);
  }).catch ((err: BusinessError) => {
    console.error(`Failed to post-query Asset. Code is ${err.code}, message is ${err.message}`);
  });
} catch (error) {
  let err = error as BusinessError;
  console.error(`Failed to post-query Asset. Code is ${err.code}, message is ${err.message}`);
}

asset.postQuerySync¹²⁺

postQuerySync(handle: AssetMap): void

查询的后置处理，用于需要用户认证的关键资产。需与asset.preQuerySync函数成对出现。使用同步方式返回结果。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

参数：

错误码：

以下错误码的详细介绍请参见关键资产存储服务错误码

示例：

import { asset } from '@kit.AssetStoreKit';
import { BusinessError } from '@kit.BasicServicesKit';

let handle: asset.AssetMap = new Map();
// 此处传入的new Uint8Array(32)仅作为示例，实际应传入asset.preQuerySync执行成功返回的挑战值。
handle.set(asset.Tag.AUTH_CHALLENGE, new Uint8Array(32));
try {
  asset.postQuerySync(handle)
} catch (error) {
  let err = error as BusinessError;
  console.error(`Failed to post-query Asset. Code is ${err.code}, message is ${err.message}`);
}

asset.querySyncResult²⁰⁺

querySyncResult(query: AssetMap): Promise<SyncResult>

执行同步操作后，查询同步执行结果。使用Promise异步回调。

系统能力： SystemCapability.Security.Asset

参数：

返回值：

错误码：

以下错误码的详细介绍请参见关键资产存储服务错误码。

示例：

import { asset } from '@kit.AssetStoreKit';
import { BusinessError } from '@kit.BasicServicesKit';

let query: asset.AssetMap = new Map();
asset.querySyncResult(query).then((res: asset.SyncResult) => {
  console.info(`sync result: ${JSON.stringify(res)}`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to query sync result of Asset. Code is ${err.code}, message is ${err.message}`);
});

TagType

枚举，关键资产属性支持的数据类型。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

Tag

枚举，关键资产支持的属性名称类型，用作AssetMap的键。

系统能力： SystemCapability.Security.Asset

说明：

以下为Tag类型的全量枚举值，每个接口可传的Tag枚举及对应的Value取值范围不同，详见各个场景的开发指导。

Value

type Value = boolean|number|Uint8Array

关键资产属性的内容，用作AssetMap的值。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

AssetMap

type AssetMap = Map<Tag, Value>

关键资产属性的键-值对集合。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

Accessibility

枚举，关键资产基于锁屏状态的访问控制类型。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

AuthType

枚举，关键资产支持的用户认证类型。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

SyncType

枚举，关键资产支持的同步类型。

说明：

本字段是能力预埋，当前不支持同步。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

ReturnType

枚举，关键资产查询返回的结果类型。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

ConflictResolution

枚举，新增关键资产时的冲突（如：别名相同）处理策略。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Security.Asset

OperationType¹²⁺

枚举，附属的操作类型。

系统能力： SystemCapability.Security.Asset

WrapType¹⁸⁺

枚举，关键资产支持的加密导入导出类型。

系统能力： SystemCapability.Security.Asset

SyncResult²⁰⁺

关键资产同步的结果。

系统能力： SystemCapability.Security.Asset

ErrorCode

表示错误码的枚举。

系统能力： SystemCapability.Security.Asset

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Asset Store Kit（关键资产存储服务）

harmony 鸿蒙asset_api.h

harmony 鸿蒙Asset_Attr

harmony 鸿蒙Asset_Blob

harmony 鸿蒙Asset_Result

harmony 鸿蒙Asset_ResultSet

harmony 鸿蒙Asset_SyncResult

harmony 鸿蒙asset_type.h

harmony 鸿蒙Asset_Value

harmony 鸿蒙AssetApi