README.md
1# appverify<a name="EN-US_TOPIC_0000001096592945"></a>
2
3- [Introduction](#section11660541593)
4- [Architecture](#section9498162413412)
5- [Directory Structure](#section161941989596)
6- [Constraints](#section119744591305)
7- [Usage](#section1312121216216)
8 - [Available APIs](#section1551164914237)
9 - [Usage Guidelines](#section129654513264)
10
11- [Repositories Involved](#section1371113476307)
12
13## Introduction<a name="section11660541593"></a>
14
15To ensure the integrity and trustworthiness of the applications to be installed in OpenHarmony, the applications must be signed and their signatures must be verified.
16
17- **In application development**: After developing an application, you need to sign its installation package to ensure that the installation package is not tampered with when it is released on devices. To sign the application package, you can use the signature tools and the public key certificates and follow the signing certificate generation specifications provided by the application integrity verification module. For your convenience, a public key certificate and a corresponding private key are preset in OpenHarmony. You need to replace the public key certificate and private key in your commercial version of OpenHarmony.
18
19- **In application installation**: The Application Framework subsystem of OpenHarmony installs applications. Upon receiving an application installation package, the Application Framework subsystem parses the signature of the installation package, and verifies the signature using the application integrity verification APIs. The application can be installed only after the verification succeeds. During the verification, the application integrity verification module uses the preset public key certificate to verify the signature.
20
21## Architecture<a name="section9498162413412"></a>
22
23**Figure 1** Application integrity verification architecture<a name="fig78941174427"></a>
24
25
26- **APIs between subsystems**: APIs provided by the application integrity verification module for other modules
27
28- **Integrity verification**: ensures the integrity of application bundles and prevents tampering through signature verification.
29
30- **Application source identification**: identifies the application source by matching the signature certificate chain with the trusted source list.
31
32## Directory Structure<a name="section161941989596"></a>
33
34```
35/base/security/appverify
36├── interfaces/innerkits/appverify # Application integrity verification module
37│ ├── config # Application signature root certificates and configuration files for the trusted source list
38│ ├── include # Header files
39│ ├── src # Source code
40│ ├── test # Automated test cases
41├── test/resource # Test resources
42```
43
44## Constraints<a name="section119744591305"></a>
45
46The certificates used for application integrity verification are specific to OpenHarmony. The corresponding public key certificates and private keys are preset in the open-source code repositories of OpenHarmony to provide offline signing and verification capabilities for the open-source community. The public key certificates and the corresponding private keys need to be replaced in commercial versions that are based on OpenHarmony.
47
48## Usage<a name="section1312121216216"></a>
49
50The application integrity verification module provides an inter-subsystem API, which is called by the Bundle Manager Service \(BMS\) during application installation.
51
52### Available APIs<a name="section1551164914237"></a>
53
54<a name="table775715438253"></a>
55<table><thead align="left"><tr id="row12757154342519"><th class="cellrowborder" valign="top" width="50.22%" id="mcps1.1.3.1.1"><p id="p1075794372512"><a name="p1075794372512"></a><a name="p1075794372512"></a>API</p>
56</th>
57<th class="cellrowborder" valign="top" width="49.78%" id="mcps1.1.3.1.2"><p id="p375844342518"><a name="p375844342518"></a><a name="p375844342518"></a>Description</p>
58</th>
59</tr>
60</thead>
61<tbody><tr id="row1348165765318"><td class="cellrowborder" valign="top" width="50.22%" headers="mcps1.1.3.1.1 "><p id="p154855755315"><a name="p154855755315"></a><a name="p154855755315"></a>int32_t HapVerify(const std::string& filePath, HapVerifyResult& hapVerifyResult)</p>
62</td>
63<td class="cellrowborder" valign="top" width="49.78%" headers="mcps1.1.3.1.2 "><p id="p64845775315"><a name="p64845775315"></a><a name="p64845775315"></a>Verifies application integrity and identifies the application source.</p>
64</td>
65</tr>
66</tbody>
67</table>
68
69### Usage Guidelines<a name="section129654513264"></a>
70
71The **HapVerify\(\)** API provided by the application integrity verification module is an inter-subsystem API. This API can be called with the HAP file path passed to verify the integrity of an application, and the verification result can be obtained from the return value. The signature of the application can be obtained from the input parameter **hapVerifyResult**.
72
73```
74Security::Verify::HapVerifyResult verifyResult;
75int32_t res = Security::Verify::HapVerify(hapPath, verifyResult);
76if (res != Security::Verify::HapVerifyResultCode::VERIFY_SUCCESS) {
77 // processing error
78}
79```
80
81## Repositories Involved<a name="section1371113476307"></a>
82
83Security subsystem
84
85hmf/security/appverify
86
87
README_zh.md
1# 应用完整性校验<a name="ZH-CN_TOPIC_0000001096592945"></a>
2
3- [简介](#section11660541593)
4- [系统架构图](#section9498162413412)
5- [目录](#section161941989596)
6- [约束](#section119744591305)
7- [说明](#section1312121216216)
8 - [接口说明](#section1551164914237)
9 - [使用说明](#section129654513264)
10
11- [相关仓](#section1371113476307)
12
13## 简介<a name="section11660541593"></a>
14
15为了确保应用的完整性和来源可靠，OpenHarmony需要对应用进行签名和验签。
16
17- **应用开发阶段：** 开发者完成开发并生成安装包后，需要开发者对安装包进行签名，以证明安装包发布到设备的过程中没有被篡改。OpenHarmony的应用完整性校验模块提供了签名工具、签名证书生成规范，以及签名所需的公钥证书等完整的机制，支撑开发者对应用安装包签名。为了方便开源社区开发者，版本中预置了公钥证书和对应的私钥，为开源社区提供离线签名和校验能力；在OpenHarmony商用版本中应替换此公钥证书和对应的私钥。
18
19- **应用安装阶段：** OpenHarmony用户程序框架子系统负责应用的安装。在接收到应用安装包之后，应用程序框架子系统需要解析安装包的签名数据，然后使用应用完整性校验模块的API对签名进行验证，只有校验成功之后才允许安装此应用. 应用完整性校验模块在校验安装包签名数据时，会使用系统预置的公钥证书进行验签。
20
21## 系统架构图<a name="section9498162413412"></a>
22
23**图 1** 应用完整性校验架构图<a name="fig78941174427"></a>
24
25
26
27- **子系统间接口：** 应用完整性校验模块给其他模块提供的接口；
28
29- **完整性校验：** 通过验签，保障应用包完整性，防篡改；
30
31- **应用来源识别：** 通过匹配签名证书链与可信源列表，识别应用来源。
32
33## 目录<a name="section161941989596"></a>
34
35```
36/base/security/appverify
37├── interfaces/innerkits/appverify # 应用完整性校验模块代码
38│ ├── config # 应用签名根证书和可信源列表配置文件存放目录
39│ ├── include # 头文件存放目录
40│ ├── src # 源代码存放目录
41│ ├── test # 模块自动化测试用例存放目录
42├── test/resource # 测试资源存放目录
43```
44
45## 约束<a name="section119744591305"></a>
46
47应用完整性校验在OpenHarmony中使用的证书，是专为OpenHarmony生成的，涉及的公钥证书和对应的私钥均预置在OpenHarmony开源代码仓中，为开源社区提供离线签名和校验能力；在商用版本中应替换此公钥证书和对应的私钥。
48
49## 说明<a name="section1312121216216"></a>
50
51应用完整性校验模块提供一个子系统间接口，由包管理服务在安装应用时调用。
52
53### 接口说明<a name="section1551164914237"></a>
54
55<a name="table775715438253"></a>
56<table><thead align="left"><tr id="row12757154342519"><th class="cellrowborder" valign="top" width="50.22%" id="mcps1.1.3.1.1"><p id="p1075794372512"><a name="p1075794372512"></a><a name="p1075794372512"></a>接口名</p>
57</th>
58<th class="cellrowborder" valign="top" width="49.78%" id="mcps1.1.3.1.2"><p id="p375844342518"><a name="p375844342518"></a><a name="p375844342518"></a>说明</p>
59</th>
60</tr>
61</thead>
62<tbody><tr id="row1348165765318"><td class="cellrowborder" valign="top" width="50.22%" headers="mcps1.1.3.1.1 "><p id="p154855755315"><a name="p154855755315"></a><a name="p154855755315"></a>int32_t HapVerify(const std::string& filePath, HapVerifyResult& hapVerifyResult)</p>
63</td>
64<td class="cellrowborder" valign="top" width="49.78%" headers="mcps1.1.3.1.2 "><p id="p64845775315"><a name="p64845775315"></a><a name="p64845775315"></a>校验应用完整性，识别应用来源</p>
65</td>
66</tr>
67</tbody>
68</table>
69
70### 使用说明<a name="section129654513264"></a>
71
72应用完整性校验提供的是子系统间接口，仅提供底层能力，不对开发者开放。以应用文件路径作为输入，调用HapVerify接口即可校验应用完整性，通过接口返回值可以获取校验结果，通过引用传参hapVerifyResult获取签名相关信息。
73
74```
75Security::Verify::HapVerifyResult verifyResult;
76int32_t res = Security::Verify::HapVerify(hapPath, verifyResult);
77if (res != Security::Verify::HapVerifyResultCode::VERIFY_SUCCESS) {
78 // processing error
79}
80```
81
82## 相关仓<a name="section1371113476307"></a>
83
84安全子系统
85
86hmf/security/appverify
87
88
