openharmony/security_asset
1
0
Fork 0
mirror of https://gitee.com/openharmony/security_asset synced 2024-11-26 17:40:37 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

add doc

Browse Source 
Change-Id: Ia0d0224382337365fa9fa00e260481f6091c0fc8

Match-id-e3353bf27e598578bb600460afdf20d91ccf9977
This commit is contained in:
authName 2023-11-25 09:39:52 +08:00 committed by userName
parent d709849a9c
commit 31f5302caa
31 changed files with 1456 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Cargo.toml
View File

@ -9,7 +9,6 @@ members = [
"services/core_service",
"services/crypto_manager",
"services/db_operator",
"services/os_dependency",
"test/unittest/inner_api_rust",
"test/unittest/module_test"
]

177
LICENSE Executable file
View File

@ -0,0 +1,177 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS

64
README_zh.md Executable file
View File

@ -0,0 +1,64 @@
# 关键资产存储服务（ASSET）
[toc]
## 简介
关键资产存储服务（ASSET），提供了用户短敏感数据的安全存储及管理能力。其中，短敏感数据可以是密码类（账号/密码）、Token类（应用凭据）、其他关键明文（如银行卡号）等长度较短的用户敏感数据。
关键资产存储服务的架构如下图所示。
![ASSET架构图](figures/asset_architecture.png)
应用接入关键资产存储服务后，可以进行如下操作：
- 调用关键资产新增接口，ASSET 首先为应用生成独属于它的密钥，然后使用该密钥对关键资产进行加密，最后将关键资产密文及其附加属性，一起存储到数据库。
- 调用关键资产更新接口，ASSET 使用新增阶段生成的密钥，对新的关键资产进行加密，并覆盖数据库中的相应记录。
- 调用关键资产查询接口，ASSET 首先根据应用指定的查询条件，从数据库中读取关键资产密文，然后校验应用的访问控制权限，验证通过后，使用新增阶段生成的密钥，对关键资产密文进行解密，最后将明文数据返回给应用。
- 调用关键资产删除接口，ASSET 根据应用指定的删除条件，从数据库中查找并删除符合条件的关键资产记录。
关键资产的安全存储，依赖底层的通用密钥库系统。具体来说，关键资产的加/解密操作以及访问控制校验，都由通用密钥库系统在安全环境（如可信执行环境）完成，即使系统被攻破，也能保证用户敏感数据不发生泄露。
针对安全性要求更高的场景，ASSET 支持应用存储需要用户身份认证通过才允许访问的关键资产。具体来说，应用在读取此类关键资产时，需要先拉起统一用户认证服务，提示用户通过锁屏密码、指纹、人脸等方式进行身份认证；应用将用户身份认证结果传递给 ASSET 后，ASSET 会请求通用密钥库系统，在安全环境校验认证结果，验证通过后才继续在安全环境解密关键资产。
使用关键资产存储服务提供的接口，开发者可以快速集成平台级别、面向短敏感数据的加密存储和访问控制机制，帮助用户方便、安全地管理密码等数据。
## 目录
```bash
├── frameworks # 关键资产存储框架层代码
│ ├── definition # 通用数据类型定义
│ ├── ipc # IPC接口定义
│ ├── js # JS-Native交互模块
│ ├── os_dependency # 通用系统能力适配模块
│ └── utils # 工具方法
├── interfaces # 关键资产存储对外提供的接口
│ ├── inner_api # 提供给系统服务调用的接口
│ └── kits # 提供给应用调用的接口
├── sa_profile # 系统服务配置文件
└── services # 关键资产存储服务层代码
├── constants # 服务层数据结构定义
├── core_service # 核心处理模块
├── crypto_manager # 数据加密模块
├── db_operator # 数据管理模块
└── os_dependency # 系统能力适配模块
```
## 说明
### 接口说明
[API说明文档](./docs/js-apis-asset.md)
### 使用说明
[ArkTS开发指导](./docs/asset-js-guidelines.md)
[Native开发指导](./docs/asset-native-guidelines.md)
## 相关仓
**安全子系统**
**[通用密钥库系统（HUKS）](https://gitee.com/openharmony/security_huks)**
**[统一用户认证（UserIAM）](https://gitee.com/openharmony/useriam_user_auth_framework)**

881
docs/reference/apis/js-apis-asset.md Executable file
View File

@ -0,0 +1,881 @@
# @ohos.security.asset (关键资产存储)
关键资产存储提供了用户短敏感数据的安全存储及管理能力。其中，短敏感数据可以是密码类（账号/密码）、Token类（应用凭据）、其他关键明文（如银行卡号）等长度较短的用户敏感数据。
> **说明：**
>
> 本模块首批接口从API version 11 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
## 导入模块
```typescript
import asset from '@ohos.security.asset';
```
## asset.add
function add(attributes: AssetMap, callback: AsyncCallback<void>): void
写入关键资产，使用Callback回调异步返回结果。
**需要权限**：ohos.permission.STORE_PERSISTENT_DATA
**系统能力：** SystemCapability.Security.Asset
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | -------------------- | ---- | ------------------------------------------------------------ |
| attributes | AssetMap | 是 | 待写入关键资产及其属性，包括关键资产明文、访问控制属性、自定义数据等。 |
| callback | AsyncCallback\<void> | 是 | 关键资产写入结果的回调，未捕获到error代表关键资产写入成功，若捕获到error，则代表关键资产写入失败。 |
**错误码：**
以下错误码的详细介绍请参见[关键资产存储错误码](../errorcodes/errorcode-asset.md)
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------------------------- |
| 201 | The caller doesn't have permission to operate. |
| 401 | The argument is invalid. |
| 24000001 | The Asset service is unavailable. |
| 24000003 | The added Asset already exists. |
| 24000005 | The screen lock status mismatches. |
| 24000006 | Insufficient memory. |
| 24000007 | The Asset is corrupted. |
| 24000008 | The database operation is failed. |
| 24000009 | The cryptography operation is failed. |
| 24000010 | IPC communication is failed |
| 24000011 | The operation of calling bundle manager service is failed. |
| 24000012 | The operation of calling OS account service is failed. |
| 24000013 | The operation of calling access token service is failed. |
| 24000014 | The operation of file is failed. |
| 24000015 | The operation of getting system time is failed. |
**示例代码：**
```typescript
import asset from '@ohos.security.asset';
import util from '@ohos.util';
import { BusinessError } from '@ohos.base';
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, (error: BusinessError) => {
if (error) {
console.error(`Failed to add Asset.`);
} else {
console.info(`Asset added successfully.`);
}
});
} catch (error) {
console.error(`Failed to add Asset.`);
}
```
## asset.add
function add(attributes: AssetMap): Promise<void>
写入关键资产，使用Promise方式异步返回结果。
**需要权限**：ohos.permission.STORE_PERSISTENT_DATA
**系统能力：** SystemCapability.Security.Asset
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | -------- | ---- | ------------------------------------------------------------ |
| attributes | AssetMap | 是 | 待写入关键资产及其属性，包括关键资产明文、访问控制属性、自定义数据等。 |
**返回值：**
| 类型 | 说明 |
| ------------- | ----------------------- |
| Promise<void> | Promise对象，无返回值。 |
**错误码：**
以下错误码的详细介绍请参见[关键资产存储错误码](../errorcodes/errorcode-asset.md)
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------------------------- |
| 201 | The caller doesn't have permission to operate. |
| 401 | The argument is invalid. |
| 24000001 | The Asset service is unavailable. |
| 24000003 | The added Asset already exists. |
| 24000005 | The screen lock status mismatches. |
| 24000006 | Insufficient memory. |
| 24000007 | The Asset is corrupted. |
| 24000008 | The database operation is failed. |
| 24000009 | The cryptography operation is failed. |
| 24000010 | IPC communication is failed |
| 24000011 | The operation of calling bundle manager service is failed. |
| 24000012 | The operation of calling OS account service is failed. |
| 24000013 | The operation of calling access token service is failed. |
| 24000014 | The operation of file is failed. |
| 24000015 | The operation of getting system time is failed. |
**示例代码：**
```typescript
import asset from '@ohos.security.asset';
import util from '@ohos.util';
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(() => {
console.error(`Failed to add Asset.`);
})
} catch (error) {
console.error(`Failed to add Asset.`);
}
```
## asset.remove
function remove(query: AssetMap, callback: AsyncCallback<void>): void
销毁关键资产，使用Callback回调异步返回结果。
**系统能力：** SystemCapability.Security.Asset
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| query | AssetMap | 是 | 关键资产删除条件，如别名、访问控制属性、自定义数据等。 |
| callback | AsyncCallback\<void> | 是 | 关键资产删除结果的回调，未捕获到error代表关键资产销毁成功，若捕获到error，则代表关键资产销毁失败。 |
**错误码：**
以下错误码的详细介绍请参见[关键资产存储错误码](../errorcodes/errorcode-asset.md)
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------------------------- |
| 401 | The argument is invalid. |
| 24000001 | The Asset service is unavailable. |
| 24000002 | The queried Asset can not be found. |
| 24000006 | Insufficient memory. |
| 24000007 | The Asset is corrupted. |
| 24000008 | The database operation is failed. |
| 24000009 | The cryptography operation is failed. |
| 24000010 | IPC communication is failed |
| 24000011 | The operation of calling bundle manager service is failed. |
| 24000012 | The operation of calling OS account service is failed. |
| 24000013 | The operation of calling access token service is failed. |
**示例代码：**
```typescript
import asset from '@ohos.security.asset';
import util from '@ohos.util';
import { BusinessError } from '@ohos.base';
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, (error: BusinessError) => {
if (error) {
console.error(`Failed to remove Asset.`);
} else {
console.info(`Asset removed successfully.`);
}
});
} catch (error) {
console.error(`Failed to remove Asset.`);
}
```
## asset.remove
function remove(query: AssetMap): Promise<void>
销毁关键资产，使用Promise方式异步返回结果。
**系统能力：** SystemCapability.Security.Asset
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | -------- | ---- | ------------------------------------------------------ |
| query | AssetMap | 是 | 关键资产删除条件，如别名、访问控制属性、自定义数据等。 |
**返回值：**
| 类型 | 说明 |
| ------------- | ----------------------- |
| Promise<void> | Promise对象，无返回值。 |
**错误码：**
以下错误码的详细介绍请参见[关键资产存储错误码](../errorcodes/errorcode-asset.md)
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------------------------- |
| 401 | The argument is invalid. |
| 24000001 | The Asset service is unavailable. |
| 24000002 | The queried Asset can not be found. |
| 24000006 | Insufficient memory. |
| 24000007 | The Asset is corrupted. |
| 24000008 | The database operation is failed. |
| 24000009 | The cryptography operation is failed. |
| 24000010 | IPC communication is failed |
| 24000011 | The operation of calling bundle manager service is failed. |
| 24000012 | The operation of calling OS account service is failed. |
| 24000013 | The operation of calling access token service is failed. |
**示例代码：**
```typescript
import asset from '@ohos.security.asset';
import util from '@ohos.util';
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(() => {
console.error(`Failed to remove Asset.`);
});
} catch (error) {
console.error(`Failed to remove Asset.`);
}
```
## asset.update
function update(query: AssetMap, attributesToUpdate: AssetMap, callback: AsyncCallback<void>): void
更新关键资产，使用Callback回调异步返回结果。
**系统能力：** SystemCapability.Security.Asset
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------------------ | -------------------- | ---- | ------------------------------------------------------------ |
| query | AssetMap | 是 | 待更新关键资产的查询条件，如关键资产别名、访问控制属性、自定义数据等。 |
| attributesToUpdate | AssetMap | 是 | 待更新关键资产及其属性，如关键资产明文、自定义数据等。 |
| callback | AsyncCallback\<void> | 是 | 关键资产更新结果的回调，未捕获到error代表关键资产更新成功，若捕获到error，则代表关键资产更新失败。 |
**错误码：**
以下错误码的详细介绍请参见[关键资产存储错误码](../errorcodes/errorcode-asset.md)
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------------------------- |
| 401 | The argument is invalid. |
| 24000001 | The Asset service is unavailable. |
| 24000002 | The queried Asset can not be found. |
| 24000005 | The screen lock status mismatches. |
| 24000006 | Insufficient memory. |
| 24000007 | The Asset is corrupted. |
| 24000008 | The database operation is failed. |
| 24000009 | The cryptography operation is failed. |
| 24000010 | IPC communication is failed |
| 24000011 | The operation of calling bundle manager service is failed. |
| 24000012 | The operation of calling OS account service is failed. |
| 24000013 | The operation of calling access token service is failed. |
| 24000015 | The operation of getting system time is failed. |
**示例代码：**
```typescript
import asset from '@ohos.security.asset';
import util from '@ohos.util';
import { BusinessError } from '@ohos.base';
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, (error: BusinessError) => {
if (error) {
console.error(`Failed to update Asset.`);
} else {
console.info(`Asset updated successfully.`);
}
});
} catch (error) {
console.error(`Failed to update Asset.`);
}
```
## asset.update
function update(query: AssetMap, attributesToUpdate: AssetMap): Promise<void>
更新关键资产，使用Promise方式异步返回结果。
**系统能力：** SystemCapability.Security.Asset
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------------------ | -------- | ---- | ------------------------------------------------------------ |
| query | AssetMap | 是 | 待更新关键资产的查询条件，如关键资产别名、访问控制属性、自定义数据等。 |
| attributesToUpdate | AssetMap | 是 | 待更新关键资产及其属性，如关键资产明文、自定义数据等。 |
**返回值：**
| 类型 | 说明 |
| ------------- | ----------------------- |
| Promise<void> | Promise对象，无返回值。 |
**错误码：**
以下错误码的详细介绍请参见[关键资产存储错误码](../errorcodes/errorcode-asset.md)
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------------------------- |
| 401 | The argument is invalid. |
| 24000001 | The Asset service is unavailable. |
| 24000002 | The queried Asset can not be found. |
| 24000005 | The screen lock status mismatches. |
| 24000006 | Insufficient memory. |
| 24000007 | The Asset is corrupted. |
| 24000008 | The database operation is failed. |
| 24000009 | The cryptography operation is failed. |
| 24000010 | IPC communication is failed |
| 24000011 | The operation of calling bundle manager service is failed. |
| 24000012 | The operation of calling OS account service is failed. |
| 24000013 | The operation of calling access token service is failed. |
| 24000015 | The operation of getting system time is failed. |
**示例代码：**
```typescript
import asset from '@ohos.security.asset';
import util from '@ohos.util';
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(() => {
console.error(`Failed to update Asset.`);
});
} catch (error) {
console.error(`Failed to update Asset.`);
}
```
## asset.preQuery
function preQuery(query: AssetMap, callback: AsyncCallback<Uint8Array>): void
预查询关键资产，返回安全随机数，仅查询需要用户认证的关键资产时需要调用。在用户认证成功后，应当随后调用asset.query、asset.postQuery。使用Callback回调异步返回结果。
**系统能力：** SystemCapability.Security.Asset
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------- | ---- | ------------------------------------------------------------ |
| query | AssetMap | 是 | 关键资产查询条件，如别名、访问控制属性、自定义数据等。 |
| callback | AsyncCallback\<Uint8Array> | 是 | 关键资产预查询结果的回调，未捕获到error时，返回安全随机数，表示预查询成功，若捕获到error，则代表关键资产预查询失败。 |
**错误码：**
以下错误码的详细介绍请参见[关键资产存储错误码](../errorcodes/errorcode-asset.md)
| 错误码ID | 错误信息 |
| -------- | ------------------------------------------------------------ |
| 401 | The argument is invalid. |
| 24000001 | The Asset service is unavailable. |
| 24000002 | The queried Asset can not be found. |
| 24000005 | The screen lock status mismatches. |
| 24000006 | Insufficient memory. |
| 24000007 | The Asset is corrupted. |
| 24000008 | The database operation is failed. |
| 24000009 | The cryptography operation is failed. |
| 24000010 | IPC communication is failed |
| 24000011 | The operation of calling bundle manager service is failed. |
| 24000012 | The operation of calling OS account service is failed. |
| 24000013 | The operation of calling access token service is failed. |
| 24000016 | The amount of map element or other limited quotas exceed the limit. |
| 24000017 | The capability is not supported. |
**示例代码：**
```typescript
import asset from '@ohos.security.asset';
import util from '@ohos.util';
import { BusinessError } from '@ohos.base';
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, (error: BusinessError) => {
if (error) {
console.error(`Failed to pre-query Asset.`);
} else {
console.info(`Succeeded in pre-querying Asset.`);
}
});
} catch (error) {
console.error(`Failed to pre-query Asset.`);
}
```
## asset.preQuery
function preQuery(query: AssetMap): Promise<Uint8Array>
预查询关键资产，返回安全随机数，仅查询需要用户认证的关键资产时需要调用。在用户认证成功后，应当随后调用asset.query、asset.postQuery。使用Promist方式异步返回结果。
**系统能力：** SystemCapability.Security.Asset
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | -------- | ---- | ------------------------------------------------------ |
| query | AssetMap | 是 | 关键资产查询条件，如别名、访问控制属性、自定义数据等。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ----------------------------------------------------- |
| Promise<Uint8Array> | Promise对象，返回安全随机数，作为用户认证时的挑战值。 |
**错误码：**
以下错误码的详细介绍请参见[关键资产存储错误码](../errorcodes/errorcode-asset.md)
| 错误码ID | 错误信息 |
| -------- | ------------------------------------------------------------ |
| 401 | The argument is invalid. |
| 24000001 | The Asset service is unavailable. |
| 24000002 | The queried Asset can not be found. |
| 24000005 | The screen lock status mismatches. |
| 24000006 | Insufficient memory. |
| 24000007 | The Asset is corrupted. |
| 24000008 | The database operation is failed. |
| 24000009 | The cryptography operation is failed. |
| 24000010 | IPC communication is failed |
| 24000011 | The operation of calling bundle manager service is failed. |
| 24000012 | The operation of calling OS account service is failed. |
| 24000013 | The operation of calling access token service is failed. |
| 24000016 | The amount of map element or other limited quotas exceed the limit. |
| 24000017 | The capability is not supported. |
**示例代码：**
```typescript
import asset from '@ohos.security.asset';
import util from '@ohos.util';
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(() => {
console.info(`Succeeded in pre-querying Asset.`);
}).catch (() => {
console.error(`Failed to pre-query Asset.`);
});
} catch (error) {
console.error(`Failed to pre-query Asset.`);
}
```
## asset.query
function query(query: AssetMap, callback: AsyncCallback<Array<AssetMap>>): void
查询关键资产。若查询需要用户认证的关键资产，则需要在本函数前调用asset.preQuery，在本函数户后调用asset.postQuery。使用Callback回调异步返回结果。
**系统能力：** SystemCapability.Security.Asset
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------- | ---- | ------------------------------------------------------------ |
| query | AssetMap | 是 | 关键资产查询条件，如别名、访问控制属性、自定义数据等。 |
| callback | AsyncCallback\<Uint8Array> | 是 | 关键资产查询结果的回调，未捕获到error时，返回关键资产明文或属性，表示查询成功，若捕获到error，则代表关键资产查询失败。 |
**错误码：**
以下错误码的详细介绍请参见[关键资产存储错误码](../errorcodes/errorcode-asset.md)
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------------------------- |
| 401 | The argument is invalid. |
| 24000001 | The Asset service is unavailable. |
| 24000002 | The queried Asset can not be found. |
| 24000004 | The access to Asset is denied. |
| 24000005 | The screen lock status mismatches. |
| 24000006 | Insufficient memory. |
| 24000007 | The Asset is corrupted. |
| 24000008 | The database operation is failed. |
| 24000009 | The cryptography operation is failed. |
| 24000010 | IPC communication is failed |
| 24000011 | The operation of calling bundle manager service is failed. |
| 24000012 | The operation of calling OS account service is failed. |
| 24000013 | The operation of calling access token service is failed. |
| 24000017 | The capability is not supported. |
**示例代码：**
```typescript
import asset from '@ohos.security.asset';
import util from '@ohos.util';
import { BusinessError } from '@ohos.base';
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, (error: BusinessError) => {
if (error) {
console.error(`Failed to query Asset.`);
} else {
console.info(`Asset query succeeded.`);
}
});
} catch (error) {
console.error(`Failed to query Asset.`);
}
```
## asset.query
function query(query: AssetMap): Promise<Array<AssetMap>>
查询关键资产。若查询需要用户认证的关键资产，则需要在本函数前调用asset.preQuery，在本函数户后调用asset.postQuery。使用Promise回调异步返回结果。
**系统能力：** SystemCapability.Security.Asset
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------- | ---- | ------------------------------------------------------------ |
| query | AssetMap | 是 | 关键资产查询条件，如别名、访问控制属性、自定义数据等。 |
| callback | AsyncCallback\<Array<AssetMap>> | 是 | 关键资产查询结果的回调，未捕获到error时，返回关键资产明文或属性，表示查询成功，若捕获到error，则代表关键资产查询失败。 |
**返回值：**
| 类型 | 说明 |
| ------------------------ | ------------------------------------- |
| Promise<Array<AssetMap>> | Promise对象，返回关键资产明文或属性。 |
**错误码：**
以下错误码的详细介绍请参见[关键资产存储错误码](../errorcodes/errorcode-asset.md)
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------------------------- |
| 401 | The argument is invalid. |
| 24000001 | The Asset service is unavailable. |
| 24000002 | The queried Asset can not be found. |
| 24000004 | The access to Asset is denied. |
| 24000005 | The screen lock status mismatches. |
| 24000006 | Insufficient memory. |
| 24000007 | The Asset is corrupted. |
| 24000008 | The database operation is failed. |
| 24000009 | The cryptography operation is failed. |
| 24000010 | IPC communication is failed |
| 24000011 | The operation of calling bundle manager service is failed. |
| 24000012 | The operation of calling OS account service is failed. |
| 24000013 | The operation of calling access token service is failed. |
| 24000017 | The capability is not supported. |
**示例代码：**
```typescript
import asset from '@ohos.security.asset';
import util from '@ohos.util';
import { BusinessError } from '@ohos.base';
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(() => {
console.info(`Asset query succeeded.`);
}).catch (() => {
console.error(`Failed to query Asset.`);
});
} catch (error) {
console.error(`Failed to query Asset.`);
}
```
## asset.postQuery
function postQuery(handle: AssetMap, callback: AsyncCallback<void>): void
关键资产查询后的资源释放。仅查询需要用户认证的关键资产，且在本函数前asset.preQuery调用成功后需要调用。使用Callback回调异步返回结果。
**系统能力：** SystemCapability.Security.Asset
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| handle | AssetMap | 是 | 待释放的资源句柄，即asset.preQuery执行成功返回的安全随机数。 |
| callback | AsyncCallback\<void> | 是 | 资源释放的回调，未捕获到error代表处理成功，若捕获到error，则代表处理失败。 |
**错误码：**
以下错误码的详细介绍请参见[关键资产存储错误码](../errorcodes/errorcode-asset.md)
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------------------------- |
| 401 | The argument is invalid. |
| 24000001 | The Asset service is unavailable. |
| 24000006 | Insufficient memory. |
| 24000010 | IPC communication is failed |
| 24000011 | The operation of calling bundle manager service is failed. |
| 24000012 | The operation of calling OS account service is failed. |
| 24000013 | The operation of calling access token service is failed. |
**示例代码：**
```typescript
import asset from '@ohos.security.asset';
import { BusinessError } from '@ohos.base';
let handle: asset.AssetMap = new Map();
// 此处传入的new Uint8Array(32)仅作为示例，实际应传入asset.preQuery执行成功返回的安全随机数
handle.set(asset.Tag.AUTH_CHALLENGE, new Uint8Array(32));
try {
asset.postQuery(handle, (error: BusinessError) => {
if (error) {
console.error(`Failed to post-query Asset.`);
} else {
console.info(`Succeeded in post-querying Asset.`);
}
});
} catch (error) {
console.error(`Failed to post-query Asset.`);
}
```
## asset.postQuery
function postQuery(handle: AssetMap, callback: AsyncCallback<void>): void
关键资产查询后的资源释放。仅查询需要用户认证的关键资产，且在本函数前asset.preQuery调用成功后需要调用。使用Promise方式异步返回结果。
**系统能力：** SystemCapability.Security.Asset
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | -------- | ---- | ------------------------------------------------------------ |
| handle | AssetMap | 是 | 待释放的资源句柄，即asset.preQuery执行成功返回的安全随机数。 |
**返回值：**
| 类型 | 说明 |
| ------------- | ----------------------- |
| Promise<void> | Promise对象，无返回值。 |
**错误码：**
以下错误码的详细介绍请参见[关键资产存储错误码](../errorcodes/errorcode-asset.md)
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------------------------- |
| 401 | The argument is invalid. |
| 24000001 | The Asset service is unavailable. |
| 24000006 | Insufficient memory. |
| 24000010 | IPC communication is failed |
| 24000011 | The operation of calling bundle manager service is failed. |
| 24000012 | The operation of calling OS account service is failed. |
| 24000013 | The operation of calling access token service is failed. |
**示例代码：**
```typescript
import asset from '@ohos.security.asset';
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 (() => {
console.error(`Failed to post-query Asset.`);
});
} catch (error) {
console.error(`Failed to post-query Asset.`);
}
```
## asset.AssetMap
type AssetMap = Map<Tag, Value>
描述关键资产属性的键-值对集合，每个键最多传入一次。
**系统能力：** SystemCapability.Security.Asset
| 名称 | 值 | 说明 |
| ----------- | ----------------------------- | ------------------ |
| asset.Tag | 见[asset.Tag](#asset.Tag) | 关键资产属性名称 |
| asset.Value | 见[asset.Value](#asset.Value) | 关键资产属性对应值 |
## asset.Tag
关键资产属性名称，用作[asset.AssetMap](#asset.AssetMap)的键。
**系统能力：** SystemCapability.Security.Asset
## asset.Value
type Value = boolean | number | Uint8Array;
关键资产属性值，用作[asset.AssetMap](#asset.AssetMap)的值。
**系统能力：** SystemCapability.Security.Asset
**asset.AssetMap参数：**
| 属性名（类型：asset.Tag） | 属性值（类型：asset.Value） | 说明 |
| ------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| SECRET | 类型为Uint8Array，长度为1-1024字节 | 关键资产明文 |
| ALIAS | 类型为Uint8Array，长度为1-256字节 | 关键资产别名，每条关键资产的唯一索引 |
| ACCESSIBILITY | 类型为number，取值范围详见[asset.Accessibility](#asset.Accessibility) | 访问控制属性 |
| REQUIRE_PASSWORD_SET | 类型为bool | 关键资产是否仅在设置了锁屏密码的情况下可访问 |
| AUTH_TYPE | 类型为number，详见[asset.AuthType](#asset.AuthType) | 访问关键资产所需的用户认证类型 |
| AUTH_VALIDITY_PERIOD | 类型为number，取值范围：1-600 | 用户认证的有效期 |
| AUTH_CHALLENGE | 类型为Uint8Array，长度为32字节 | 用户认证使用的挑战值 |
| AUTH_TOKEN | 类型为Uint8Array，长度为148字节 | 认证通过的授权令牌 |
| SYNC_TYPE | 类型为number，取值范围详见[asset.SyncType](#asset.SyncType) | 关键资产支持的同步类型 |
| IS_PERSISTENT | 类型为bool | 关键资产在应用卸载时是否需要保留 |
| DATA_LABEL_CRITICAL_1 | 类型为Uint8Array，长度为1-512字节 | 关键资产附属信息，内容由业务自定义且有完整性保护 |
| DATA_LABEL_CRITICAL_2 | 类型为Uint8Array，长度为1-512字节 | 关键资产附属信息，内容由业务自定义且有完整性保护 |
| DATA_LABEL_CRITICAL_3 | 类型为Uint8Array，长度为1-512字节 | 关键资产附属信息，内容由业务自定义且有完整性保护 |
| DATA_LABEL_CRITICAL_4 | 类型为Uint8Array，长度为1-512字节 | 关键资产附属信息，内容由业务自定义且有完整性保护 |
| DATA_LABEL_NORMAL_1 | 类型为Uint8Array，长度为1-512字节 | 关键资产附属信息，内容由业务自定义且无完整性保护 |
| DATA_LABEL_NORMAL_2 | 类型为Uint8Array，长度为1-512字节 | 关键资产附属信息，内容由业务自定义且无完整性保护 |
| DATA_LABEL_NORMAL_3 | 类型为Uint8Array，长度为1-512字节 | 关键资产附属信息，内容由业务自定义且无完整性保护 |
| DATA_LABEL_NORMAL_4 | 类型为Uint8Array，长度为1-512字节 | 关键资产附属信息，内容由业务自定义且无完整性保护 |
| RETURN_TYPE | 类型为number，取值范围详见[asset.ReturnType](#asset.ReturnType) | 关键资产查询结果类型 |
| RETURN_LIMIT | 类型为number | 关键资产查询结果数量 |
| RETURN_OFFSET | 类型为number，取值范围：1-65536 | 满足查询条件的关键资产偏移量 |
| RETURN_ORDERED_BY | 类型为number，取值范围：asset.Tag.DATA_LABEL_xxx | 关键资产查询结果排序依据，仅支持指定按照附属信息排序，不指定的情况下，默认按照关键资产写入的顺序排序。 |
| CONFLICT_RESOLUTION | 类型为number，取值范围详见[asset.ConflictResolution](#asset.ConflictResolution) | 写入同别名的关键资产时的处理策略 |
## asset.Accessibility
关键资产的访问控制属性。
**系统能力：** SystemCapability.Security.Asset
| 名称 | 值 | 说明 |
| --------------------- | ---- | ------------------------------------------------------------ |
| DEVICE_POWER_ON | 0 | 关键资产在设备开机后可访问 |
| DEVICE_FIRST_UNLOCKED | 1 | 关键资产在设备首次解锁后可访问<br>**备注：**设备未设置锁屏密码时，等同于设备开机后可访问 |
| DEVICE_UNLOCKED | 2 | 关键资产在设备处于解锁状态时可访问<br/>**备注：**设备未设置锁屏密码时，等同于设备开机后可访问 |
## asset.AuthType
关键资产支持的用户认证类型。
**系统能力：** SystemCapability.Security.Asset
| 名称 | 值 | 说明 |
| ---- | ---- | ------------------------------------------------------------ |
| NONE | 0 | 访问关键资产前无需用户认证 |
| ANY | 255 | 任意一种用户认证方式（PIN码、人脸、指纹等）通过后，均可访问关键资产 |
## asset.SyncType
关键资产支持的同步类型。本字段属于能力预埋，当前不支持同步。
**系统能力：** SystemCapability.Security.Asset
| 名称 | 值 | 说明 |
| -------------- | ---- | ------------------------------------------------ |
| NEVER | 0 | 不允许同步关键资产 |
| THIS_DEVICE | 1 | 只在本设备进行同步，如PC备份场景，仅在设备还原。 |
| TRUSTED_DEVICE | 2 | 只在可信设备间进行同步，如克隆场景。 |
## asset.ReturnType
关键资产查询结果类型。
**系统能力：** SystemCapability.Security.Asset
| 名称 | 值 | 说明 |
| ---------- | ---- | ------------------------------------------------------------ |
| ALL | 0 | 返回关键资产明文及属性<br/>**备注：**仅支持查询单条关键资产明文 |
| ATTRIBUTES | 1 | 返回关键资产属性，不含关键资产明文<br>**备注：**无需解密，可批量查询多条关键资产 |
## asset.ConflictResolution
写入同别名的关键资产时的处理策略。
**系统能力：** SystemCapability.Security.Asset
| 名称 | 值 | 说明 |
| ----------- | ---- | ---------------------------- |
| OVERWRITE | 0 | 覆盖同别名的关键资产数据 |
| THROW_ERROR | 1 | 抛出异常，由业务进行后续处理 |

37
docs/reference/asset-js-guidelines.md Executable file
View File

@ -0,0 +1,37 @@
# 开发指导
## 用户场景1（存储密码流程图）
## 用户场景2（二次访问控制）
### 使用场景
### 流程图/架构框图
### sample示例
- 界面图
- sample链接
## 写入关键资产
- 使用场景
- 接口和必选参数介绍（参数名、参数类型、参数限制）
- 代码示例
- 可选参数介绍（
___________________________________________________________________
| 可选参数（所有可设置的属性） | API链接 | 拓展链接 |
| RequiredPasswordSet | xxxx | - |
| AuthType.ANY | xxxx | 跳转到访问控制专门章节 |
| ... | ... | ... |
___________________________________________________________________
- 约束限制（会话？？性能？？并发？？存储数量？？）
## 读取关键资产更新关键资产
## 删除关键资产

214
docs/reference/errorcodes/errorcode-asset.md Executable file
View File

@ -0,0 +1,214 @@
# 关键资产存储错误码
> **说明：**
>
> 以下仅介绍本模块特有错误码，通用错误码请参考[通用错误码说明文档](errorcode-universal.md)。
## 24000001
**错误信息**
The Asset service is unavailable.
**可能原因**
关键资产进程崩溃。
**处理步骤**
重试，
## 24000002
**错误信息**
The queried Asset can not be found.
**可能原因**
关键资产未写入过，或已经删除。
**处理步骤**
1. 在关键资产写入成功、删除成功后加日志，确认在查询关键资产前是否已写入或删除过数据。
2. 重新写入关键资产，再查询该关键资产。
## 24000003
**错误信息**
The added Asset already exists.
**可能原因**
业务正写入同别名的关键资产，即asset.Tag.ALIAS属性相同的关键资产。
**处理步骤**
请先确认写入同别名的关键资产是否符合预期，如果不符合需排查别名是否错误，如果符合则可通过以下任意一种方式处理
1. 先调用asset.remove销毁该别名的关键资产，再调用asset.add重新写入。
2. 调用asset.add时，需要指定参数asset.Tag.CONFLICT_RESOLUTION的值为asset.ConflictResolution.OVERWRITE
## 24000004
**错误信息**
The access to Asset is denied.
**可能原因**
1. 业务在调用asset.query查询关键资产前，没有调用asset.preQuery预查询关键资产。
2. 用户在访问需要用户认证的关键资产前，没有进行用户认证。
**处理步骤**
1. 业务在调用asset.query查询关键资产前，先调用asset.preQuery预查询关键资产。
2. 用户在访问需要用户认证的关键资产前，先进行用户认证。
## 24000005
**错误信息**
The screen lock status mismatches.
**可能原因**
1. 在设备处于未设置锁屏密码的状态下，访问仅设备设置密码时才允许访问的关键资产。
2. 在设备未完成首次解锁的状态下，访问仅设备首次解锁才允许访问的关键资产。
3. 在设备未处于解锁状态下，访问仅设备处于解锁才允许访问的关键资产。
**处理步骤**
给设备设置锁屏密码或解锁后，再访问关键资产。
## 24000006
**错误信息**
Insufficient memory.
**可能原因**
系统内存不足。
**处理步骤**
清理后台，重新发起处理请求。
## 24000007
**错误信息**
The Asset is corrupted.
**可能原因**
因设备掉电导致关键资产损坏。
**处理步骤**
调试阶段：删除data/service/el1/public/asset_service/asset.db目录后重试
发布阶段：
## 24000008
**错误信息**
The database operation is failed.
**可能原因**
**处理步骤**
## 24000009
**错误信息**
The cryptography operation is failed.
**可能原因**
**处理步骤**
## 24000010
**错误信息**
IPC communication is failed.
**可能原因**
**处理步骤**
## 24000011
**错误信息**
The operation of calling bundle manager service is failed.
**可能原因**
**处理步骤**
## 24000012
**错误信息**
The operation of calling OS account service is failed.
**可能原因**
**处理步骤**
## 24000013
**错误信息**
The operation of calling access token service is failed.
**可能原因**
**处理步骤**
## 24000014
**错误信息**
The operation of file is failed.
**可能原因**
**处理步骤**
## 24000015
**错误信息**
The operation of getting system time is failed.
**可能原因**
**处理步骤**
## 24000016
**错误信息**
The amount of map element or other limited quotas exceed the limit.
**可能原因**
**处理步骤**
## 24000017
**错误信息**
The capability is not supported.
**可能原因**
**处理步骤**

39
docs/security/asset-js-guidelines.md Executable file
View File

@ -0,0 +1,39 @@
# 开发指导
## 用户场景1（存储密码流程图）
## 用户场景2（二次访问控制）
### 使用场景
### 流程图/架构框图
### sample示例
- 界面图
- sample链接
## 写入关键资产
- 使用场景
- 接口和必选参数介绍（参数名、参数类型、参数限制）
- 代码示例
- 可选参数介绍（
___________________________________________________________________
| 可选参数（所有可设置的属性） | API链接 | 拓展链接 |
| RequiredPasswordSet | xxxx | - |
| AuthType.ANY | xxxx | 跳转到访问控制专门章节 |
| ... | ... | ... |
___________________________________________________________________
- 约束限制（会话？？性能？？并发？？存储数量？？）
## 读取关键资产
## 更新关键资产
## 删除关键资产

0
docs/security/asset-native-guidelines.md Executable file
View File

0
docs/security/asset-overview.md Executable file
View File

BIN
figures/asset_architecture.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 230 KiB

6
frameworks/definition/src/lib.rs
View File

@ -154,9 +154,6 @@ impl_enum_trait! {
/// The error code indicates that the argument is invalid.
InvalidArgument = 401,
/// The error code indicates that the capability is not supported.
NotSupport = 801,
/// The error code indicates that the Asset service is unavailable.
ServiceUnavailable = 24000001,
@ -204,6 +201,9 @@ impl_enum_trait! {
/// The error code indicates that the amount of map element or other limited quotas exceed the limit.
LimitExceeded = 24000016,
/// The error code indicates that the capability is not supported.
Unsupported = 24000017,
}
}

32
frameworks/js/@ohos.security.asset.d.ts vendored
View File

@ -32,16 +32,15 @@ declare namespace asset {
* @param { AsyncCallback<void> } callback - the callback function for add operation.
* @throws { BusinessError } 201 - Permission denied.
* @throws { BusinessError } 401 - Invalid argument.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 24000001 - Service unavailable.
* @throws { BusinessError } 24000003 - Data already exists.
* @throws { BusinessError } 24000005 - Device status mismatch.
* @throws { BusinessError } 24000006 - Out of memory.
* @throws { BusinessError } 24000007 - Data corrupted.
* @throws { BusinessError } 24000008 - Database operation failed.
* @throws { BusinessError } 24000009 - Key manager is abnormal.
* @throws { BusinessError } 24000010 - IPC communication is abnormal.
* @throws { BusinessError } 24000011 - Bundle framework is abnormal.
* @throws { BusinessError } 24000011 - Key manager is abnormal.
* @throws { BusinessError } 24000012 - Account manager is abnormal.
* @throws { BusinessError } 24000013 - Access token manager is abnormal.
* @throws { BusinessError } 24000014 - File operation failed.
@ -59,7 +58,6 @@ declare namespace asset {
* @returns { Promise<void> } the promise object returned by the function.
* @throws { BusinessError } 201 - Permission denied.
* @throws { BusinessError } 401 - Invalid argument.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 24000001 - Service unavailable.
* @throws { BusinessError } 24000003 - Data already exists.
* @throws { BusinessError } 24000005 - Device status mismatch.
@ -84,7 +82,6 @@ declare namespace asset {
* @param { AssetMap } query - a map object containing attributes of the Asset to be removed.
* @param { AsyncCallback<void> } callback - the callback function for remove operation.
* @throws { BusinessError } 401 - Invalid argument.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 24000001 - Service unavailable.
* @throws { BusinessError } 24000002 - Data not found.
* @throws { BusinessError } 24000006 - Out of memory.
@ -106,7 +103,6 @@ declare namespace asset {
* @param { AssetMap } query - a map object containing attributes of the Asset to be removed.
* @returns { Promise<void> } the promise object returned by the function.
* @throws { BusinessError } 401 - Invalid argument.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 24000001 - Service unavailable.
* @throws { BusinessError } 24000002 - Data not found.
* @throws { BusinessError } 24000006 - Out of memory.
@ -128,7 +124,6 @@ declare namespace asset {
* @param { AssetMap } attributesToUpdate - a map object containing attributes with new values.
* @param { AsyncCallback<void> } callback - the callback function for update operation.
* @throws { BusinessError } 401 - Invalid argument.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 24000001 - Service unavailable.
* @throws { BusinessError } 24000002 - Data not found.
* @throws { BusinessError } 24000005 - Device status mismatch.
@ -153,7 +148,6 @@ declare namespace asset {
* @param { AssetMap } attributesToUpdate - a map object containing attributes with new values.
* @returns { Promise<void> } the promise object returned by the function.
* @throws { BusinessError } 401 - Invalid argument.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 24000001 - Service unavailable.
* @throws { BusinessError } 24000002 - Data not found.
* @throws { BusinessError } 24000005 - Device status mismatch.
@ -177,7 +171,6 @@ declare namespace asset {
* @param { AssetMap } query - a map object containing attributes of the Asset to be queried.
* @param { AsyncCallback<Uint8Array> } callback - the callback function for pre-query operation.
* @throws { BusinessError } 401 - Invalid argument.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 24000001 - Service unavailable.
* @throws { BusinessError } 24000002 - Data not found.
* @throws { BusinessError } 24000005 - Device status mismatch.
@ -190,6 +183,7 @@ declare namespace asset {
* @throws { BusinessError } 24000012 - Account manager is abnormal.
* @throws { BusinessError } 24000013 - Access token manager is abnormal.
* @throws { BusinessError } 24000016 - Capacity exceeds the limit.
* @throws { BusinessError } 24000017 - Capability not supported.
* @syscap SystemCapability.Security.Asset
* @since 11
*/
@ -201,7 +195,6 @@ declare namespace asset {
* @param { AssetMap } query - a map object containing attributes of the Asset to be queried.
* @returns { Promise<Uint8Array> } the promise object returned by the function.
* @throws { BusinessError } 401 - Invalid argument.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 24000001 - Service unavailable.
* @throws { BusinessError } 24000002 - Data not found.
* @throws { BusinessError } 24000005 - Device status mismatch.
@ -214,6 +207,7 @@ declare namespace asset {
* @throws { BusinessError } 24000012 - Account manager is abnormal.
* @throws { BusinessError } 24000013 - Access token manager is abnormal.
* @throws { BusinessError } 24000016 - Capacity exceeds the limit.
* @throws { BusinessError } 24000017 - Capability not supported.
* @syscap SystemCapability.Security.Asset
* @since 11
*/
@ -225,7 +219,6 @@ declare namespace asset {
* @param { AssetMap } query - a map object containing attributes of the Asset to be queried.
* @param { AsyncCallback<Array<AssetMap>> } callback - the callback function for query operation.
* @throws { BusinessError } 401 - Invalid argument.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 24000001 - Service unavailable.
* @throws { BusinessError } 24000002 - Data not found.
* @throws { BusinessError } 24000004 - Access denied.
@ -238,6 +231,7 @@ declare namespace asset {
* @throws { BusinessError } 24000011 - Bundle framework is abnormal.
* @throws { BusinessError } 24000012 - Account manager is abnormal.
* @throws { BusinessError } 24000013 - Access token manager is abnormal.
* @throws { BusinessError } 24000017 - Capability not supported.
* @syscap SystemCapability.Security.Asset
* @since 11
*/
@ -249,7 +243,6 @@ declare namespace asset {
* @param { AssetMap } query - a map object containing attributes of the Asset to be queried.
* @returns { Promise<Array<AssetMap>> } the promise object returned by the function.
* @throws { BusinessError } 401 - Invalid argument.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 24000001 - Service unavailable.
* @throws { BusinessError } 24000002 - Data not found.
* @throws { BusinessError } 24000004 - Access denied.
@ -262,6 +255,7 @@ declare namespace asset {
* @throws { BusinessError } 24000011 - Bundle framework is abnormal.
* @throws { BusinessError } 24000012 - Account manager is abnormal.
* @throws { BusinessError } 24000013 - Access token manager is abnormal.
* @throws { BusinessError } 24000017 - Capability not supported.
* @syscap SystemCapability.Security.Asset
* @since 11
*/
@ -273,7 +267,6 @@ declare namespace asset {
* @param { AssetMap } handle - a map object contains the handle returned by {@link preQuery}.
* @param { AsyncCallback<void> } callback - the callback function for post-query operation.
* @throws { BusinessError } 401 - Invalid argument.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 24000001 - Service unavailable.
* @throws { BusinessError } 24000006 - Out of memory.
* @throws { BusinessError } 24000010 - IPC communication is abnormal.
@ -291,7 +284,6 @@ declare namespace asset {
* @param { AssetMap } handle - a map object contains the handle returned by {@link preQuery}.
* @returns { Promise<void> } the promise object returned by the function.
* @throws { BusinessError } 401 - Invalid argument.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 24000001 - Service unavailable.
* @throws { BusinessError } 24000006 - Out of memory.
* @throws { BusinessError } 24000010 - IPC communication is abnormal.
@ -677,13 +669,6 @@ declare namespace asset {
* @since 11
*/
INVALID_ARGUMENT = 401,
/**
* The error code indicates that the capability is not supported.
*
* @syscap SystemCapability.Security.Asset
* @since 11
*/
NOT_SUPPORTED = 801,
/**
* The error code indicates that the Asset service is unavailable.
*
@ -796,6 +781,13 @@ declare namespace asset {
* @since 11
*/
LIMIT_EXCEEDED = 24000016,
/**
* The error code indicates that the capability is not supported.
*
* @syscap SystemCapability.Security.Asset
* @since 11
*/
UNSUPPORTED = 24000017,
}
}

4
frameworks/js/napi/inc/asset_napi_error_code.h
View File

@ -37,10 +37,10 @@ const std::unordered_map<int32_t, const char *> ERR_MSGS = {
{ ASSET_STATUS_MISMATCH, "The screen lock status mismatches." },
{ ASSET_OUT_OF_MEMRORY, "Insufficient memory." },
{ ASSET_DATA_CORRUPTED, "The Asset is corrupted." },
{ ASSET_IPC_ERROR, "Ipc communication is failed" },
{ ASSET_DATABASE_ERROR, "The database operation is failed." },
{ ASSET_BMS_ERROR, "The operation of calling bundle manager service is failed." },
{ ASSET_CRYPTO_ERROR, "The cryptography operation is failed." },
{ ASSET_IPC_ERROR, "IPC communication is failed." },
{ ASSET_BMS_ERROR, "The operation of calling bundle manager service is failed." },
{ ASSET_ACCOUNT_ERROR, "The operation of calling OS account service is failed." },
{ ASSET_ACCESS_TOKEN_ERROR, "The operation of calling access token service is failed." },
{ ASSET_FILE_OPERATION_ERROR, "The operation of file is failed." },

2
frameworks/os_dependency/log/inc/asset_log.h
View File

@ -26,7 +26,7 @@
#define LOG_TAG "Asset"
#undef LOG_DOMAIN
#define LOG_DOMAIN 0xD002F70 // Security Domain ID: 0xD002F00 - 0xD002FFF
#define LOG_DOMAIN 0xD002F08
#define LOGD(fmt, arg...) \
HILOG_DEBUG(LOG_CORE, "%" LOG_PUBLIC "s[%" LOG_PUBLIC "u]: " fmt "\n", __func__, __LINE__, ##arg)

6
frameworks/os_dependency/log/src/lib.rs
View File

@ -23,7 +23,7 @@ use hilog_rust::hilog;
pub fn log_func_i(log: &str) {
let log_label = hilog_rust::HiLogLabel {
log_type: hilog_rust::LogType::LogCore,
domain: 0xD002F70, // Security Domain ID: 0xD002F00 - 0xD002FFF
domain: 0xD002F08,
tag: "Asset",
};
hilog_rust::info!(log_label, "{}", @public(log));
@ -33,7 +33,7 @@ pub fn log_func_i(log: &str) {
pub fn log_func_w(log: &str) {
let log_label = hilog_rust::HiLogLabel {
log_type: hilog_rust::LogType::LogCore,
domain: 0xD002F70, // Security Domain ID: 0xD002F00 - 0xD002FFF
domain: 0xD002F08,
tag: "Asset",
};
hilog_rust::warn!(log_label, "{}", @public(log));
@ -43,7 +43,7 @@ pub fn log_func_w(log: &str) {
pub fn log_func_e(log: &str) {
let log_label = hilog_rust::HiLogLabel {
log_type: hilog_rust::LogType::LogCore,
domain: 0xD002F70, // Security Domain ID: 0xD002F00 - 0xD002FFF
domain: 0xD002F08,
tag: "Asset",
};
hilog_rust::error!(log_label, "{}", @public(log));

2
frameworks/os_dependency/samgr/BUILD.gn
View File

@ -18,7 +18,7 @@ ohos_static_library("asset_samgr") {
include_dirs = [ "../log/inc" ]
external_deps = [
"hilog:libhilog",
"ipc:ipc_core",
"ipc:ipc_single",
"samgr:samgr_proxy",
]
subsystem_name = "security"

1
interfaces/inner_api/rs/BUILD.gn
View File

@ -19,7 +19,6 @@ ohos_rust_shared_library("asset_sdk") {
"../../../frameworks/definition:asset_definition",
"../../../frameworks/ipc:asset_ipc",
"../../../frameworks/os_dependency/log:asset_log",
"../../../frameworks/os_dependency/samgr:asset_samgr",
]
external_deps = [

8
interfaces/kits/c/inc/asset_type.h
View File

@ -186,10 +186,6 @@ typedef enum {
* The error code indicates that the argument is invalid.
*/
ASSET_INVALID_ARGUMENT = 401,
/**
* The error code indicates that the capability is not supported.
*/
ASSET_NOT_SUPPORTED = 801,
/**
* The error code indicates that the Asset service is unavailable.
*/
@ -254,6 +250,10 @@ typedef enum {
* The error code indicates that the amount of map element or other limited quotas exceed the limit.
*/
ASSET_LIMIT_EXCEEDED = 24000016,
/**
* The error code indicates that the capability is not supported.
*/
ASSET_UNSUPPORTED = 24000017,
} Asset_ResultCode;
/**

2
services/constants/src/calling_info.rs
View File

@ -35,7 +35,6 @@ enum ResultCode {
InvalidArgument = 1,
BmsError = 2,
AccessTokenError = 3,
Unsupported = 4,
}
extern "C" {
@ -89,7 +88,6 @@ impl CallingInfo {
ResultCode::AccessTokenError => {
log_throw_error!(ErrCode::AccessTokenError, "[FATAL]Get process info failed.")
},
ResultCode::Unsupported => log_throw_error!(ErrCode::NotSupport, "[FATAL]Unsupported calling type."),
}
}

2
services/core_service/BUILD.gn
View File

@ -24,7 +24,7 @@ ohos_rust_shared_library("asset_service") {
"../constants:asset_constants",
"../crypto_manager:asset_crypto_manager",
"../db_operator:asset_db_operator",
"../os_dependency:asset_system_ability",
"../os_dependency:asset_os_dependency",
]
external_deps = [

1
services/core_service/Cargo.toml
View File

@ -27,4 +27,3 @@ asset_file_operator = { path = "../../frameworks/os_dependency/file" }
asset_utils = { path = "../../frameworks/utils" }
asset_ipc = { path = "../../frameworks/ipc" }
asset_log = { path = "../../frameworks/os_dependency/log" }
asset_system_ability = { path = "../os_dependency" }

6
services/core_service/src/lib.rs
View File

@ -29,8 +29,8 @@ use asset_constants::CallingInfo;
use asset_definition::{log_throw_error, AssetMap, ErrCode, Result};
use asset_ipc::{IAsset, SA_ID};
use asset_log::{loge, logi};
use asset_system_ability::{subscribe_system_abillity, unsubscribe_system_ability};
mod listener;
mod operations;
mod stub;
mod sys_event;
@ -57,7 +57,7 @@ fn start_service<T: ISystemAbility + IMethod>(ability: &T) -> Result<()> {
ability.publish(&obj, SA_ID);
logi!("[INFO]Asset service on_start");
thread::spawn(subscribe_system_abillity);
thread::spawn(listener::subscribe);
Ok(())
}
@ -71,7 +71,7 @@ fn on_start<T: ISystemAbility + IMethod>(ability: &T) {
fn on_stop<T: ISystemAbility + IMethod>(_ability: &T) {
logi!("[INFO]Asset service on_stop");
unsubscribe_system_ability();
listener::unsubscribe();
}
#[used]

6
services/os_dependency/src/lib.rs → services/core_service/src/listener.rs
View File

@ -13,7 +13,7 @@
* limitations under the License.
*/
//! This module is used to adapt to the functions on which assets depend.
//! This module is used to subscribe common event and system ability.
use std::slice;
@ -63,7 +63,7 @@ extern "C" {
}
/// Subscribe to the add and remove events of system abilities.
pub fn subscribe_system_abillity() {
pub(crate) fn subscribe() {
unsafe {
if SubscribeSystemEvent(delete_data_by_owner, delete_dir_by_user, delete_crypto_need_unlock) {
logi!("Subscribe system event success.");
@ -80,7 +80,7 @@ pub fn subscribe_system_abillity() {
}
/// Unsubscribe to the add and remove events of system abilities.
pub fn unsubscribe_system_ability() {
pub(crate) fn unsubscribe() {
unsafe {
if !UnSubscribeSystemAbility() {
loge!("Unsubscribe system ability failed.")

2
services/core_service/src/operations/operation_pre_query.rs
View File

@ -58,7 +58,7 @@ fn query_key_attrs(calling_info: &CallingInfo, db_data: &DbMap) -> Result<(Acces
Ok((access_type, require_password_set))
},
_ => log_throw_error!(
ErrCode::NotSupport,
ErrCode::Unsupported,
"[FATAL][SA]Data of multiple access control types cannot be accessed at the same time."
),
}

2
services/core_service/src/operations/operation_query.rs
View File

@ -151,7 +151,7 @@ pub(crate) fn query(query: &AssetMap, calling_info: &CallingInfo) -> Result<Vec<
match query.get(&Tag::ReturnType) {
Some(Value::Number(return_type)) if *return_type == (ReturnType::All as u32) => {
if !query.contains_key(&Tag::Alias) {
log_throw_error!(ErrCode::NotSupport, "[FATAL]Batch secret query is not supported.")
log_throw_error!(ErrCode::Unsupported, "[FATAL]Batch secret query is not supported.")
} else {
query_all(calling_info, &mut db_data, query)
}

9
services/db_operator/src/database.rs
View File

@ -158,19 +158,22 @@ impl Database {
}
/// Update the database version for database upgrade.
pub fn set_version(&self, ver: u32) -> Result<()> {
#[allow(dead_code)]
pub(crate) fn set_version(&self, ver: u32) -> Result<()> {
let sql = format!("pragma user_version = {}", ver);
self.exec(sql.as_str())
}
/// Upgrade database to new version.
pub fn upgrade(&self, ver: u32, callback: UpgradeDbCallback) -> Result<()> {
#[allow(dead_code)]
pub(crate) fn upgrade(&self, ver: u32, callback: UpgradeDbCallback) -> Result<()> {
let version_old = self.get_version()?;
callback(self, version_old, ver)
}
/// Delete database file.
pub fn delete(user_id: i32) -> Result<()> {
#[allow(dead_code)]
pub(crate) fn delete(user_id: i32) -> Result<()> {
let path = fmt_db_path(user_id);
let _backup_path = fmt_backup_path(&path);
if let Err(e) = fs::remove_file(path) {

2
services/db_operator/src/table.rs
View File

@ -346,7 +346,7 @@ impl<'a> Table<'a> {
/// let exits = table
/// .is_data_exists(&DbMap::from([("id", Value::Number(3)), ("alias", Value::Bytes(b"alias"))]));
/// ```
pub fn is_data_exists(&self, cond: &DbMap) -> Result<bool> {
pub(crate) fn is_data_exists(&self, cond: &DbMap) -> Result<bool> {
let ret = self.count_datas(cond);
match ret {
Ok(count) => Ok(count > 0),

18
services/os_dependency/BUILD.gn
View File

@ -39,21 +39,3 @@ ohos_static_library("asset_os_dependency") {
subsystem_name = "security"
part_name = "asset"
}
ohos_rust_static_library("asset_system_ability") {
sources = [ "src/lib.rs" ]
deps = [
":asset_os_dependency",
"../../frameworks/definition:asset_definition",
"../../frameworks/os_dependency/file:asset_file_operator",
"../../frameworks/os_dependency/log:asset_log",
"../constants:asset_constants",
"../crypto_manager:asset_crypto_manager",
"../db_operator:asset_db_operator",
]
external_deps = [ "hilog:libhilog" ]
crate_name = "asset_system_ability"
crate_type = "rlib"
subsystem_name = "security"
part_name = "asset"
}

27
services/os_dependency/Cargo.toml
View File

@ -1,27 +0,0 @@
# Copyright (C) 2023 Huawei Device Co., Ltd.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
[package]
name = "asset_system_ability"
version = "0.1.0"
edition = "2021"
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
[dependencies]
asset_constants = { path = "../constants" }
asset_crypto_manager = { path = "../../services/crypto_manager" }
asset_definition = { path = "../../frameworks/definition" }
asset_db_operator = { path = "../../services/db_operator" }
asset_file_operator = { path = "../../frameworks/os_dependency/file" }
asset_log = { path = "../../frameworks/os_dependency/log" }

1
services/os_dependency/inc/bms_wrapper.h
View File

@ -32,7 +32,6 @@ enum ResultCode {
INVALID_ARGUMENT = 1,
BMS_ERROR = 2,
ACCESS_TOKEN_ERROR = 3,
UNSUPPORTED = 4,
};
ResultCode GetOwnerInfo(int32_t userId, uint64_t uid, OwnerType *ownerType, uint8_t *ownerInfo, uint32_t *infoLen);

4
services/os_dependency/src/bms_wrapper.cpp
View File

@ -84,8 +84,8 @@ ResultCode GetOwnerInfo(int32_t userId, uint64_t uid, OwnerType *ownerType, uint
code = GetProcessInfo(tokenId, uid, info);
break;
default:
LOGE("[FATAL]Unsupported calling type: %{public}d", tokenType);
code = UNSUPPORTED;
LOGE("[FATAL]Invalid calling type: %{public}d", tokenType);
code = INVALID_ARGUMENT;
}
if (code != SUCCESS) {