• Home
Name Date Size #Lines LOC

..--

common_lib/12-May-2024-3,0382,234

default_config/12-May-2024-9276

deps_adapter/12-May-2024-7,4385,888

figures/12-May-2024-

frameworks/12-May-2024-22,79218,561

interfaces/innerkits/12-May-2024-811538

services/12-May-2024-35,82629,499

test/12-May-2024-12,5849,040

.gitattributesD12-May-2024631 1615

BUILD.gnD12-May-20242.7 KiB7063

LICENSED12-May-202410.1 KiB177150

README.mdD12-May-202410.6 KiB141115

README_zh.mdD12-May-202410.2 KiB142117

bundle.jsonD12-May-20242.3 KiB7776

deviceauth_env.gniD12-May-20241.5 KiB4035

hisysevent.yamlD12-May-20241,013 239

README.md

1# deviceauth<a name="EN-US_TOPIC_0000001150002727"></a>
2
3-   [Introduction](#section11660541593)
4-   [Directory Structure](#section161941989596)
5-   [Usage](#section1312121216216)
6    -   [Available APIs](#section1551164914237)
7
8-   [Repositories Involved](#section1371113476307)
9
10## Introduction<a name="section11660541593"></a>
11
12The device authentication module belongs to the security subsystem of OpenHarmony. It manages the entire lifecycle of trust relationships between devices, including establishment, maintenance, use, and cancellation, and implements authentication and secure session key exchange between trusted devices. It provides basic capabilities for trusted interconnections between devices that run OpenHarmony.
13
14The device authentication module provides the following capabilities:
15
16-   Device trust relationship management: manages the establishment, maintenance, and cancellation of trust relationships between devices in a unified manner; allows the isolation and controllable sharing of trust relationships created by different services.
17-   Device trust relationship authentication: authenticates trust relationships between devices, allows trusted devices to exchange secure session keys with each other, and sets up connections between trusted devices through the DSoftBus.
18
19The device authentication module consists of three submodules: device group management, device group authentication, and account-irrelevant P2P device authentication. The following figure shows the logical architecture of the device authentication module.
20
21**Figure  1**  Architecture of the device authentication module<a name="fig4460722185514"></a>
22
23
24![](figures/en-us_deviceauth_architecture.png)
25
26In the architecture:
27
28-   Device group management: allows you to manage the trust relationships between the local device and other devices created by different services in a unified manner, create trust relationships between devices using the provided APIs, create an account-irrelevant device group, add trusted devices to the group, and create a trust relationship between isolated devices.
29-   Device group authentication: allows devices to authenticate the trust relationships that have been established between them and exchange session keys.
30-   Account-irrelevant P2P device authentication: allows two devices to establish a trust relationship based on a shared secret, and exchange a session key for secure communication based on the trusted relationship.
31
32## Directory Structure<a name="section161941989596"></a>
33
34```
35/base/security/device_auth
36├── frameworks                   # Device authentication framework code
37├── hals                         # HAL code for the tool library
38│   ├── inc                      # Tool library header files
39│   └── src                      # Tool library source files
40├── interfaces                   # APIs exposed externally
41└── services                     # Device authentication services
42    ├── common                   # Common code
43    ├── group_auth               # Device group authentication
44    ├── group_manager            # Device group management
45    ├── module                   # Authenticator module (including the account-irrelevant P2P device authenticator)
46    └── session                  # Scheduling and session management module
47```
48
49## Usage<a name="section1312121216216"></a>
50
51### Available APIs<a name="section1551164914237"></a>
52
53The device group management sub-module abstracts trust relationships established by different services between devices into trust groups and provides unified APIs for creating, deleting, and querying groups. The device group authentication sub-module provides trusted device authentication and end-to-end session key exchange based on the trust groups.
54
55**Table  1**  APIs in DeviceGroupManager
56
57<a name="table1731550155318"></a>
58<table><thead align="left"><tr id="row4419501537"><th class="cellrowborder" valign="top" width="57.38999999999999%" id="mcps1.2.3.1.1"><p id="p54150165315"><a name="p54150165315"></a><a name="p54150165315"></a>API</p>
59</th>
60<th class="cellrowborder" valign="top" width="42.61%" id="mcps1.2.3.1.2"><p id="p941150145313"><a name="p941150145313"></a><a name="p941150145313"></a>Description</p>
61</th>
62</tr>
63</thead>
64<tbody><tr id="row34145016535"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p1487722894416"><a name="p1487722894416"></a><a name="p1487722894416"></a>const DeviceGroupManager *GetGmInstance()</p>
65</td>
66<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p13562171015712"><a name="p13562171015712"></a><a name="p13562171015712"></a>Obtains a <strong id="b4999346135811"><a name="b4999346135811"></a><a name="b4999346135811"></a>DeviceGroupManager</strong> instance.</p>
67</td>
68</tr>
69<tr id="row1027292610453"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p1227312634518"><a name="p1227312634518"></a><a name="p1227312634518"></a>int32_t RegCallback(const char *appId, const DeviceAuthCallback *callback)</p>
70</td>
71<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p7488141134613"><a name="p7488141134613"></a><a name="p7488141134613"></a>Registers a callback.</p>
72</td>
73</tr>
74<tr id="row1746172917474"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p9758144610285"><a name="p9758144610285"></a><a name="p9758144610285"></a>int32_t CreateGroup(int64_t requestId, const char *appId, const char *createParams)</p>
75</td>
76<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p2431455765"><a name="p2431455765"></a><a name="p2431455765"></a>Creates a group of trusted devices.</p>
77</td>
78</tr>
79<tr id="row10992232154714"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p1310363994713"><a name="p1310363994713"></a><a name="p1310363994713"></a>int32_t DeleteGroup(int64_t requestId, const char *appId, const char *disbandParams)</p>
80</td>
81<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p126575774517"><a name="p126575774517"></a><a name="p126575774517"></a>Deletes a group of trusted devices.</p>
82</td>
83</tr>
84<tr id="row1440154863415"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p19702122715481"><a name="p19702122715481"></a><a name="p19702122715481"></a>int32_t AddMemberToGroup(int64_t requestId, const char *appId, const char *addParams)</p>
85</td>
86<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p240224817343"><a name="p240224817343"></a><a name="p240224817343"></a>Adds a member to a specified group.</p>
87</td>
88</tr>
89<tr id="row495164812345"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p1872417515488"><a name="p1872417515488"></a><a name="p1872417515488"></a>int32_t DeleteMemberFromGroup(int64_t requestId, const char *appId, const char *deleteParams);</p>
90</td>
91<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p1995144893411"><a name="p1995144893411"></a><a name="p1995144893411"></a>Deletes a member from a specified group.</p>
92</td>
93</tr>
94<tr id="row4107114933418"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p794617473016"><a name="p794617473016"></a><a name="p794617473016"></a>int32_t ProcessData(int64_t requestId, const uint8_t *data, uint32_t dataLen)</p>
95</td>
96<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p11107849113418"><a name="p11107849113418"></a><a name="p11107849113418"></a>Processes data that is bound or unbound.</p>
97</td>
98</tr>
99<tr id="row3270349193419"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p179130216514"><a name="p179130216514"></a><a name="p179130216514"></a>int32_t GetGroupInfo(const char *appId, const char *queryParams, char **returnGroupVec, uint32_t *groupNum)</p>
100</td>
101<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p12701049183411"><a name="p12701049183411"></a><a name="p12701049183411"></a>Obtains information about a trusted group of devices.</p>
102</td>
103</tr>
104</tbody>
105</table>
106
107**Table  2**  APIs in GroupAuthManager
108
109<a name="table12330133114308"></a>
110<table><thead align="left"><tr id="row15330631193013"><th class="cellrowborder" valign="top" width="57.38999999999999%" id="mcps1.2.3.1.1"><p id="p73319319302"><a name="p73319319302"></a><a name="p73319319302"></a>API</p>
111</th>
112<th class="cellrowborder" valign="top" width="42.61%" id="mcps1.2.3.1.2"><p id="p133312317305"><a name="p133312317305"></a><a name="p133312317305"></a>Description</p>
113</th>
114</tr>
115</thead>
116<tbody><tr id="row15331183193010"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p19743328133620"><a name="p19743328133620"></a><a name="p19743328133620"></a>const GroupAuthManager *GetGaInstance()</p>
117</td>
118<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p16742028153611"><a name="p16742028153611"></a><a name="p16742028153611"></a>Obtains a <strong id="b13399173415119"><a name="b13399173415119"></a><a name="b13399173415119"></a>GroupAuthManager</strong> instance.</p>
119</td>
120</tr>
121<tr id="row7331133163017"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p118111117133514"><a name="p118111117133514"></a><a name="p118111117133514"></a>int32_t AuthDevice(int64_t authReqId, const char *authParams, const DeviceAuthCallback *gaCallback)</p>
122</td>
123<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p151481335193817"><a name="p151481335193817"></a><a name="p151481335193817"></a>Authenticates a peer device.</p>
124</td>
125</tr>
126<tr id="row633283153012"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p12534111115352"><a name="p12534111115352"></a><a name="p12534111115352"></a>int32_t ProcessData(int64_t authReqId, const uint8_t *data, uint32_t dataLen,</p>
127<p id="p16534181113358"><a name="p16534181113358"></a><a name="p16534181113358"></a>const DeviceAuthCallback *gaCallback)</p>
128</td>
129<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p1633173173012"><a name="p1633173173012"></a><a name="p1633173173012"></a>Processes authentication data.</p>
130</td>
131</tr>
132</tbody>
133</table>
134
135## Repositories Involved<a name="section1371113476307"></a>
136
137**Security subsystem**
138
139[security\_device\_auth](https://gitee.com/openharmony/security_device_auth)
140
141

README_zh.md

1# 设备互信认证<a name="ZH-CN_TOPIC_0000001150002727"></a>
2
3-   [简介](#section11660541593)
4-   [目录](#section161941989596)
5-   [说明](#section1312121216216)
6    -   [接口说明](#section1551164914237)
7
8-   [相关仓](#section1371113476307)
9
10## 简介<a name="section11660541593"></a>
11
12在OpenHarmony中，设备互信认证模块作为安全子系统的子模块，负责设备间可信关系的建立、维护、使用、撤销等全生命周期的管理，实现可信设备间的互信认证和安全会话密钥协商，是搭载OpenHarmony的设备进行可信互联的基础平台能力。
13
14设备互信认证模块当前提供如下功能：
15
16-   设备互信关系管理功能：统一管理设备互信关系的建立、维护、撤销过程；支持各个业务创建的设备互信关系的隔离和可控共享。
17-   设备互信关系认证功能：提供认证设备间互信关系、进行安全会话密钥协商的能力，支持分布式软总线实现互信设备间的组网。
18
19为实现上述功能，设备互信认证模块当前包含设备群组管理、设备群组认证和帐号无关点对点认证三个子模块，其部署逻辑如下图：
20
21**图 1**  子系统架构图<a name="fig4460722185514"></a>
22
23
24![](figures/zh-cn_deviceauth_architecture.png)
25
26其中，
27
28-   设备群组管理服务：统一管理不同业务建立的本设备与其他设备间的互信关系，并对外提供设备互信关系的创建入口 ，完成信任建立后创建帐号无关设备群组，并将信任对象设备添加进群组；OpenHarmony上各业务可独立创建相互隔离的设备间可信关系。
29-   设备群组认证服务：支持已建立可信关系的设备间完成互信关系的认证及会话密钥的协商。
30-   帐号无关点对点设备互信认证：提供设备间基于共享秘密建立一对一互信关系的功能，并支持基于这种互信关系的认证密钥协商。
31
32## 目录<a name="section161941989596"></a>
33
34```
35/base/security/device_auth
36├── frameworks                   # 设备互信认证IPC代码
37├── interfaces                   # 对外接口目录
38├── test                         # 设备互信认证的接口测试用例
39├── common_lib                   # C语言公共基础库
40├── deps_adapter                 # 依赖组件适配器代码
41│   ├── key_management_adapter   # 秘钥及算法适配层
42│   └── os_adapter               # 系统能力适配层
43└── services                     # 设备互信认证服务层代码
44    ├── frameworks               # 设备互信认证框架层代码
45    ├── data_manager             # 设备互信群组信息管理模块
46    ├── group_auth               # 设备群组认证服务
47    ├── group_manager            # 设备群组管理服务
48    ├── authenticators           # 认证执行模块（包括帐号无关点对点认证器）
49    └── protocol                 # 认证协议库
50```
51
52## 说明<a name="section1312121216216"></a>
53
54### 接口说明<a name="section1551164914237"></a>
55
56设备互信认证组件中，设备群组管理服务负责将不同业务建立的设备间可信关系抽象成一个个可信群组，对外提供统一的接口，包含群组创建、删除、查询等功能；设备群组认证服务基于已经建立过可信关系的设备群组，提供设备可信认证与端到端会话密钥协商功能。
57
58**表 1**  设备群组管理服务提供的API接口\(DeviceGroupManager\)功能介绍
59
60<a name="table1731550155318"></a>
61<table><thead align="left"><tr id="row4419501537"><th class="cellrowborder" valign="top" width="57.38999999999999%" id="mcps1.2.3.1.1"><p id="p54150165315"><a name="p54150165315"></a><a name="p54150165315"></a>接口名</p>
62</th>
63<th class="cellrowborder" valign="top" width="42.61%" id="mcps1.2.3.1.2"><p id="p941150145313"><a name="p941150145313"></a><a name="p941150145313"></a>描述</p>
64</th>
65</tr>
66</thead>
67<tbody><tr id="row34145016535"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p1487722894416"><a name="p1487722894416"></a><a name="p1487722894416"></a>const DeviceGroupManager *GetGmInstance()</p>
68</td>
69<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p13562171015712"><a name="p13562171015712"></a><a name="p13562171015712"></a>获取设备群组管理的实例。</p>
70</td>
71</tr>
72<tr id="row1027292610453"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p1227312634518"><a name="p1227312634518"></a><a name="p1227312634518"></a>int32_t RegCallback(const char *appId, const DeviceAuthCallback *callback)</p>
73</td>
74<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p7488141134613"><a name="p7488141134613"></a><a name="p7488141134613"></a>注册业务的监听回调。</p>
75</td>
76</tr>
77<tr id="row1746172917474"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p9758144610285"><a name="p9758144610285"></a><a name="p9758144610285"></a>int32_t CreateGroup(int32_t osAccountId, int64_t requestId, const char *appId, const char *createParams)</p>
78</td>
79<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p2431455765"><a name="p2431455765"></a><a name="p2431455765"></a>创建一个可信设备群组。</p>
80</td>
81</tr>
82<tr id="row10992232154714"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p1310363994713"><a name="p1310363994713"></a><a name="p1310363994713"></a>int32_t DeleteGroup(int32_t osAccountId, int64_t requestId, const char *appId, const char *disbandParams)</p>
83</td>
84<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p126575774517"><a name="p126575774517"></a><a name="p126575774517"></a>删除一个可信设备群组。</p>
85</td>
86</tr>
87<tr id="row1440154863415"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p19702122715481"><a name="p19702122715481"></a><a name="p19702122715481"></a>int32_t AddMemberToGroup(int32_t osAccountId, int64_t requestId, const char *appId, const char *addParams)</p>
88</td>
89<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p240224817343"><a name="p240224817343"></a><a name="p240224817343"></a>添加成员到指定群组ID的可信设备群组。</p>
90</td>
91</tr>
92<tr id="row495164812345"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p1872417515488"><a name="p1872417515488"></a><a name="p1872417515488"></a>int32_t DeleteMemberFromGroup(int32_t osAccountId, int64_t requestId, const char *appId, const char *deleteParams);</p>
93</td>
94<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p1995144893411"><a name="p1995144893411"></a><a name="p1995144893411"></a>从指定可信设备群组里删除可信成员。</p>
95</td>
96</tr>
97<tr id="row4107114933418"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p794617473016"><a name="p794617473016"></a><a name="p794617473016"></a>int32_t ProcessData(int64_t requestId, const uint8_t *data, uint32_t dataLen)</p>
98</td>
99<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p11107849113418"><a name="p11107849113418"></a><a name="p11107849113418"></a>处理绑定或者解绑的数据。</p>
100</td>
101</tr>
102<tr id="row3270349193419"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p179130216514"><a name="p179130216514"></a><a name="p179130216514"></a>int32_t GetGroupInfo(int32_t osAccountId, const char *appId, const char *queryParams, char **returnGroupVec, uint32_t *groupNum)</p>
103</td>
104<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p12701049183411"><a name="p12701049183411"></a><a name="p12701049183411"></a>查询可信设备群组信息。</p>
105</td>
106</tr>
107</tbody>
108</table>
109
110**表 2**  设备群组认证模块提供的API接口\(GroupAuthManager\)功能介绍
111
112<a name="table12330133114308"></a>
113<table><thead align="left"><tr id="row15330631193013"><th class="cellrowborder" valign="top" width="57.38999999999999%" id="mcps1.2.3.1.1"><p id="p73319319302"><a name="p73319319302"></a><a name="p73319319302"></a>接口名</p>
114</th>
115<th class="cellrowborder" valign="top" width="42.61%" id="mcps1.2.3.1.2"><p id="p133312317305"><a name="p133312317305"></a><a name="p133312317305"></a>描述</p>
116</th>
117</tr>
118</thead>
119<tbody><tr id="row15331183193010"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p19743328133620"><a name="p19743328133620"></a><a name="p19743328133620"></a>const GroupAuthManager *GetGaInstance()</p>
120</td>
121<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p16742028153611"><a name="p16742028153611"></a><a name="p16742028153611"></a>获取设备群组认证的实例。</p>
122</td>
123</tr>
124<tr id="row7331133163017"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p118111117133514"><a name="p118111117133514"></a><a name="p118111117133514"></a>int32_t AuthDevice(int32_t osAccountId, int64_t authReqId, const char *authParams, const DeviceAuthCallback *gaCallback)</p>
125</td>
126<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p151481335193817"><a name="p151481335193817"></a><a name="p151481335193817"></a>认证可信设备。</p>
127</td>
128</tr>
129<tr id="row633283153012"><td class="cellrowborder" valign="top" width="57.38999999999999%" headers="mcps1.2.3.1.1 "><p id="p12534111115352"><a name="p12534111115352"></a><a name="p12534111115352"></a>int32_t ProcessData(int64_t authReqId, const uint8_t *data, uint32_t dataLen, const DeviceAuthCallback *gaCallback)</p>
130</td>
131<td class="cellrowborder" valign="top" width="42.61%" headers="mcps1.2.3.1.2 "><p id="p1633173173012"><a name="p1633173173012"></a><a name="p1633173173012"></a>处理认证的数据。</p>
132</td>
133</tr>
134</tbody>
135</table>
136
137## 相关仓<a name="section1371113476307"></a>
138
139**安全子系统**
140
141[security\_device\_auth](https://gitee.com/openharmony/security_device_auth)
142