• Home
Name Date Size #Lines LOC

..--

figures/12-May-2024-

libhvb/12-May-2024-3,4072,371

test/12-May-2024-250198

tools/12-May-2024-1,2841,011

BUILD.gnD12-May-2024711 2219

LICENSED12-May-202410.1 KiB177150

OAT.xmlD12-May-20245.5 KiB8236

README.mdD12-May-20241.1 KiB4020

README_zh.mdD12-May-20246.4 KiB16091

bundle.jsonD12-May-2024648 3232

README.md

1# OpenHarmony Verified Boot<a name="ZH-CN_TOPIC_0000001129033057"></a>
2
3## Introduction<a name="section469617221261"></a>
4
5Open**H**armony **V**erified **B**oot (HVB) component is used to verify and authenticate system images to make sure OpenHarmony is running system images:
6
7- from authenticated sources
8- without tampering
9- can not roll back to old versions with vulnerabilities
10
11![](figures/usage-en.png)
12
13
14
15HVB is composed of three modules as shown below：
16
17![](figures/hvb-arch.png)
18
19- libhvb is the verifying utility library. It will be integrated by Bootloader to verify initial images, and integrated by init to verify system images.
20- hvbtool is used to sign system images, it will be integrated by Building system.
21
22
23
24## Directory Structure<a name="section15884114210197"></a>
25
26The structure of the repository directory is as follows:
27
28```
29base/startup/hvb/
30├── libhvb         # source code for libhvb module
31└── tools          # source code for hvbtool module
32```
33
34
35
36##  Repositories Involved<a name="section641143415335"></a>
37
38**[startup\_init\_lite](https://gitee.com/openharmony/startup_init_lite)**
39
40

README_zh.md

1# 安全启动<a name="ZH-CN_TOPIC_0000001129033057"></a>
2
3## 简介<a name="section469617221261"></a>
4
5Open**H**armony **V**erified **B**oot (HVB)部件用于校验设备启动过程对系统镜像的完整性以及合法性；确保OpenHarmony设备启动的镜像包：
6
7- 来源合法
8- 不被篡改
9- 无法回滚到有漏洞的历史版本
10
11![](figures/usage.png)
12
13HVB安全启动使用到的基础安全算法包括以下两类：
14
15- **完整性算法**
16
17编译时为系统镜像计算完整性摘要数据，启动时执行相同的完整性算法计算出摘要进行对比，从而确定镜像的完整性。
18
19- **签名算法**
20
21通过对摘要信息进行签名校验，确保镜像的来源可信。此过程依赖设备OEM厂商在初始的bootloader启动时通过安全运行环境提供可行根，从而建立完整的信任链。
22
23## 系统架构
24
25### 基本概念
26
27HVB主要用于校验系统镜像，根据镜像的类型分为整包校验和分块校验两种方式：
28
29- 整包校验（hash）
30
31整包校验适用于一次性加载的镜像，这种镜像只需要生成一个hash值即可，加载镜像时对整个镜像进行hash计算，与编译时的hash值进行对比确保完整性。
32
33此校验方式的弊端是镜像过大时影响开机校验时间。
34
35- 按需校验（hashtree）
36
37按需校验适用于大的文件系统镜像包，由内核在访问存储块时进行完整性校验。由于是按存储块进行hash值计算的，因此需要在编译时构造哈希树（hashtree）加快校验速度。此方案可以不用在开机时对整个进行进行完整性校验，而只对hashtree进行校验，加快系统启动速度。
38
39>  此方案依赖内核开启[dm-verity](https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/verity.html)特性。
40
41#### verity校验信息
42
43为了实现安全启动，每个系统镜像都需要在末尾追加校验信息（verity），根据校验方式为两类，如下图所示：
44
45![](figures/verity.png)
46
47verity校验信息主要包括
48
49| **字段名称**   | **说明**                                                     |
50| -------------- | ------------------------------------------------------------ |
51| signature_info | verity信息的签名内容。verity签名内容可包含多份pubkey，signature值信息，以兼容老的bootloader产品。 |
52| hash_info      | hash_info存放镜像的完整性信息，根据镜像校验类型可以是hash或hashtree信息。 |
53
54#### Root Verity Table根校验信息列表
55
56对于有多个镜像的系统，可以增加根校验信息列表（RVT, Root Verity Table）分区用于统一存放各个镜像verity信息的pubkey，如下图所示：
57
58![](figures/rvt.png)
59
60上游的bootloader只需要校验root_verity_table（**RVT**）的合法性，就可以通过该分区的pubkey列表逐个校验每个分区镜像的verity信息。
61
62### 部件结构
63
64如下图所示，HVB部件主要包括以下几个模块：
65
66![](figures/hvb-arch.png)
67
68- libhvb是安全启动的校验库，工作在设备侧。该模块可供bootloader集成，完成初始的安全镜像校验；也会被系统init调用，完成dm-verity使能。
69- hvbtool用于构造安全校验信息，由编译工具集成使用。
70
71
72
73## 目录<a name="section15884114210197"></a>
74仓目录结构如下：
75```
76base/startup/hvb/
77├── libhvb         # libhvb模块代码
78└── tools          # hvbtool工具代码
79```
80
81
82## 约束<a name="section12212842173518"></a>
83
84目前仅支持标准系统设备。
85
86## 说明<a name="section837771600"></a>
87
88hvb特性的完整使能依赖以下几方面的适配：
89
90### Bootloader适配
91
92Bootloader中安全启动校验流程示例如下：
93
94![](figures/bootloader.png)
95
96如上图所示，Bootloader中可判断：
97
98- 设备是否解锁
99
100Bootloader可通过可信的存储器来存放解锁标记。一般可通过可信信任根对解锁标记进行完整性校验，确保合法。
101
102设备是否支持解锁以及解锁方式由厂商实现。
103
104- 镜像是否可信
105
106Bootloader通过可信根信息对RVT内容进行可信认证。同时，需要对镜像中的rollback_index进行安全存放；防止回滚到有安全漏洞的版本。
107
108
109
110OEM厂商在Bootloader中可使用libhvb中的接口对单个镜像的verity信息进行校验；也可根据rvt信息对多个镜像的verity信息进行校验。
111
112且需要适配[hvb_sysdeps.h](libhvb/include/hvb_sysdeps.h)中平台相关的函数。
113
114
115
116Bootloader校验通过后，通过bootargs传递校验信息给内核，具体的参数定义如下：
117
118| bootargs名称            | **说明**                                                     |
119| ----------------------- | ------------------------------------------------------------ |
120| ohos.boot.hvb.enable    | hvb使能开关：<br>false：不需要使能hvb<br>true：需使能HVB；使能时，bootloader需传递以下hvb详细参数： |
121| ohos.boot.hvb.version   | 当前只支持1.0版本                                            |
122| ohos.boot.hvb.hash_algo | 当前只支持sha256                                             |
123| ohos.boot.hvb.digest    | HVB保护的所有用户态镜像以及RVT的verity信息摘要               |
124
125[init](https://gitee.com/openharmony/startup_init_lite)部件启动时会根据上述参数使能内核dm-verity，从而实现对system.img等镜像的安全校验。
126
127### Kernel适配
128
129Kernel需要使能dm-verity功能，默认需要开启以下内核宏：
130
131```shell
132CONFIG_MD=y
133CONFIG_BLK_DEV_DM_BUILTIN=y
134CONFIG_BLK_DEV_DM=y
135CONFIG_DM_BUFIO=y
136CONFIG_DM_ZERO=y
137CONFIG_DM_DELAY=m
138CONFIG_DM_INIT=y
139CONFIG_DM_UEVENT=y
140CONFIG_DM_VERITY=y
141CONFIG_DM_VERITY_VERIFY_ROOTHASH_SIG=y
142CONFIG_DM_VERITY_FEC=y
143```
144
145### fstab适配
146
147[init](https://gitee.com/openharmony/startup_init_lite)部件在挂载系统镜像时，会根据fstab配置的fs_mgr_flags选项决定哪些系统镜像需要使能hvb安全校验。如下所示，fs_mgr_flags添加上hvb表示该分区需要使能hvb安全校验：
148
149```
150#<src>                                                  <mnt_point> <type>   <mnt_flags and options>  <fs_mgr_flags>
151/dev/block/platform/f8300000.ufs/by-name/system         /usr        ext4     ro,barrier=1             wait,required,hvb
152```
153
154
155
156## 相关仓<a name="section641143415335"></a>
157
158**[startup\_init\_lite](https://gitee.com/openharmony/startup_init_lite)**
159
160