README.md
1# xts_device_attest_lite module<a name="EN-CN_TOPIC_001"></a>
2
3- [Introduction](#section100)
4- [Directory Structure](#section200)
5- [Architecture diagram](#section300)
6- [Constraints](#section400)
7- [Integration guidance](#section500)
8 - [Terminology](#section501)
9 - [Partner completes information registration](#section502)
10 - [Dependent interface adaptation](#section503)
11 - [External interface](#section504)
12 - [Compilation instruction](#section505)
13 - [mini](#section5051)
14 - [small](#section5052)
15- [Repositories Involved](#section600)
16
17
18## Introduction<a id="section100"></a>
19
20xts_device_attest_lite module：
21
22- The basic function of the xts_device_attest_lite module is to take care of the OpenHarmony ecological device attest results, and achieve the goal of counting the number of OH ecological devices through the cloud of end data. The purpose is to count the number of OH equipment. xts_device_attest_lite module applies to mini system and small system.
23
24## Directory Structure<a id="section200"></a>
25
26```
27/test/xts
28├── device_attest_lite
29│ └── build # Compile configuration
30│ └── figures
31│ └── framework # System capability service framework
32│ └── mini # Mini system service framework
33│ └── small # Small system service framework
34│ └── interfaces # External interface
35│ └── services # Service subject and business logic code
36│ └── core # Business logic code
37│ └── test
38│ └── startup # Small system startup example
39│ └── unittest # Test case
40```
41
42## Architecture diagram<a id="section300"></a>
43
44
45
46## Constraints<a id="section400"></a>
47
48The integration dependency library is shown in the following table:
49
50| Library | Version | Function description | Note |
51| --------- | ---------------- | ----------------------------------------------- | ---------------------------------------- |
52| mbedtls | 2.16.11 | A lightweight implementation library of TLS protocol for embedded devices. | Library path..\third_party\mbedtls |
53| cJSON | 1.7.15 | JSON file resolution library. | Library path..\third_party\cJSON\third_party |
54| libsec | 1.1.10 | Security function library. | Library path..\bounds_checking_function |
55| parameter | OpenHarmony 1.0+ | System interface for obtaining device information. | Library path ..\base\startup\init\interfaces\innerkits\include\syspara\parameter.h |
56
57
58## Integration guidance<a id="section500"></a>
59
60### Terminology<a id="section501"></a>
61
62**table 1**
63| Term | Explain |
64| ---------- | ------------------------------------------------------------ |
65| partners | Enterprises applying for OpenHarmony compatibility evaluation are hereinafter collectively referred to as "partners". It is required to integrate xts_device_attest_lite module. |
66| manuKey | The secret key obtained by partners from the official website of the [OpenHarmony compatibility platform](https://openatom.cn/atomavatar/#/login?redirect=%2Fauthorize%3Fresponse_type%3Dcode%26client_id%3D6bdacef0a8bd11ec938bd9550d2decfd%26redirect_uri%3Dhttps%3A%2F%2Fcompatibility.openharmony.cn%2Fconsole%26appName%3DOpenHarmony%E8%AE%A4%E8%AF%81%E5%B9%B3%E5%8F%B0%26scope%3D0,1,2,3%26state%3D%2Fpersonal). It is used to encrypt and protect relevant data in the product. To ensure the compatibility of multiple products, manuKey should remain unchanged during the life cycle of all products. |
67| productId | When a partner applies for compatibility evaluation from the official website of the OpenHarmony compatibility platform, the platform assigns a unique product identifier to the evaluation product. The productId must remain unchanged throughout the product life cycle. |
68| productKey | When partners apply for compatibility evaluation from the official website of the OpenHarmony compatibility platform, the platform assigns the unique product secret key to the evaluation product. It corresponds to the productId one by one, and is used to encrypt and protect product level data. It is also necessary to ensure that it remains unchanged throughout the product life cycle. |
69| token | The partner obtains the device credentials allocated by the platform from the official website of the OpenHarmony compatibility platform, one for each device, to identify the device identity. It needs to be stored in the security partition, and cannot be cleared when the factory settings are restored or the image is upgraded. |
70
71
72### Partner completes information registration <a id="section502"></a>
73
74Partners need to register a series of basic information about product equipment on the [OpenHarmony compatibility platform](https://openatom.cn/atomavatar/#/login?redirect=%2Fauthorize%3Fresponse_type%3Dcode%26client_id%3D6bdacef0a8bd11ec938bd9550d2decfd%26redirect_uri%3Dhttps%3A%2F%2Fcompatibility.openharmony.cn%2Fconsole%26appName%3DOpenHarmony%E8%AE%A4%E8%AF%81%E5%B9%B3%E5%8F%B0%26scope%3D0,1,2,3%26state%3D%2Fpersonal), such as 公司简称（英文）, 品牌英文名称, 设备型号, etc.
75In the equipment certification processing process, the equipment certification module reads the equipment information and reports it to the foundation cloud, which verifies it. Therefore, partners are required to complete product information registration on the official website of the OpenHarmony compatibility platform in advance, including the following two steps:
76
771）Partners complete device information registration on the official website of OpenHarmony compatibility platform.
782）Partners write the device information registered on the official website of the OpenHarmony compatibility platform to the device.
79
801. Partners complete information registration on the OpenHarmony compatibility platform
81
82 Partners need to register relevant equipment certification data on the OpenHarmony compatibility platform, please follow the registration process on the official website.
83
842. Partners writes the registered OS information to the device
85
86 For the information registered by partners on the OpenHarmony compatibility platform, the version package provides relevant interfaces for partners to fill in.
87 When calling the xts_device_attest_lite function, the value filled in by the partner will be reported to the foundation cloud, which will compare and verify the information registered in the previous section with the information reported by the device.
88 xts_device_attest module depends on some device information and needs to be adapted and modified by partners.
89 Device information is located in the startup subsystem file: base/startup/init/services/etc_lite/param/ohos_const/ohos.para.The device OS information is shown in the following table：
90
91**table 2**
92| Device information | ohos.para configuration parameter | Note |
93| --------------- | ------------------------------------------------------------ | ---------------------------- |
94| 发布类型 | const.ohos.releasetype=Beta | Use default |
95| api版本 | const.ohos.apiversion=6 | Use default |
96| 安全补丁标签 | const.ohos.version.security_patch=2021-09-01 | 2021-09-01 replace with real value |
97| 软件版本号 | const.ohos.fullname=OpenHarmony-1.0.1.0 | Use default |
98
99Device product information is located in the vendor subsystem file: vendor/hisilicon/hispark_pegasus/hals/utils/sys_param/vendor.para.The device product information is shown in the following table：
100
101**table 3**
102| Device information | vendor.para configuration parameter | Note |
103| ---------------- | ------------------------------------------------- | ---------------------------- |
104| 企业简称（英文） | const.product.manufacturer=**** | **** replace with real value |
105| 品牌英文名 | const.product.brand=**** | **** replace with real value |
106| 设备型号 | const.product.model=**** | **** replace with real value |
107| 软件版本号 | \# const.product.software.version="OpenHarmony 1.0.1" const.product.software.version=OpenHarmony 3.3.3.3 | "OpenHarmony 1.0.1" replace with real value |
108| 版本 id | | No partner operation is required, and the system automatically generates |
109| 版本 Hash | const.ohos.buildroothash=default | default replace with real value|
110
111
112Note：版本 id needs to be obtained through equipment, Fill in the OpenHarmony compatibility platform, 版本 id consists of：
113VersionId = deviceType/manufacture/brand/productSeries/OSFullName/productModel/softwareModel/OHOS_SDK_API_VERSION/incrementalVersion/buildType
114
115Get 版本 id:
116 1) OS information and product information writing device
117 2) Release encrypted log(Modify the modification of PrintDevSysInfo in the following figure)
118 3) Burn
119 4) View 版本 ID through logs
120
121
122
123View 版本 ID through logs
124
125
126
127
128### Dependent interface adaptation <a id="section503"></a>
129
130In order to shield the differences in the underlying implementations of different modules, vendor defines token related APIs, which are implemented by partners through adaptation. The interface definitions are shown in the following table：
131
132**table 4**
133|
134Function | Interface definition | Parameters definition | Return value | Belong to |
135| ----------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ | --------------------- | ------------------------- |
136| Read manuKey | int32_t HalGetManufactureKey(char\* manuKey, uint32_t len) | acKey：Secret key storage memory len：memory length | 0：success -1：fail | ..\hal_token.h |
137| Read ProductId | int32_t HalGetProdId(char\* productId, uint32_t len) | productId：Product model identification len：memory length | 0：success 1：fail | ..\hal_token.h |
138| Read token | int32_t HalReadToken(char\* token, uint32_t len); | token：Token storage memory len：memory length | 0：success 1：fail | ..\hal_token.h |
139| Write token | int32_t HalWriteToken(char\* token, uint32_t len); | token：Token storage memory len：memory length | 0：success 1：fail | ..\hal_token.h |
140|Read ProductKey（Reserved interface） | int32_t HalGetProdKey(char\* productKey, uint32_t len) | productKey：Product (Unique) Secret Key len：memory length | 0：success 1：fail | ..\hal_token.h |
141
142
143 1. HalGetManufactureKey
144 manuKey is a parameter used to generate AES secret key in combination with the token, which is downloaded from the OpenHarmony compatibility platform.
145
146
147
148 Convert ASCII code to hexadecimal through tools.
149
150
151
152
153
154
155 Preset in the return value of HalGetManufactureKey interface.
156
157
158
159 2. HalGetProdId
160 ProductId is a parameter that is used to generate AES secret key together with the token, which can be viewed on the OpenHarmony platform.
161
162
163
164 Preset in the return value of HalGetProductId interface
165
166
167
168 3. HalReadToken 和 HalWriteToken
169 The manufacturer needs to implement the token read and write interface, write the token in the security partition of the device, and the partition will not be erased when the device is restarted or initialized.
170
171 4. HalGetProdKey
172 Reserved interface, which does not need to be implemented temporarily.
173
174
175### External interface<a id="section504"></a>
176
177xts_device_attest_lite module external interface, the following table：
178
179| **Interface Name** | **Description** |
180| ------------------------------------------------------- | ------------ |
181| int32_t StartDevAttestTask(void); | Start the main process of xts_device_attest_lite |
182| int32_t GetAttestStatus(AttestResultInfo* attestResultInfo); | Get attest result |
183
184After the network connection is successful, the manufacturer needs to actively call the StartDevAttestTask function to enter the process of xts_device_attest_lite. By querying the GetAttestStatus interface, you can get the results of device attest.
185
186### Compilation instruction<a id="section505"></a>
187#### mini<a id="section5051"></a>
188
189```c
190hb set
191hb build --gn-args build_xts=true
192```
193#### small<a id="section5052"></a>
194LiteOS：
195```c
196hb set
197hb build --gn-args build_xts=true
198```
199Linux:
200```c
201hb set
202hb build --gn-args build_xts=true
203```
204## Repositories Involved<a id="section600"></a>
205
206[xts\_device\_attest](https://gitee.com/openharmony-sig/xts_device_attest/)
207
208**xts\_device\_attest\_lite**
209
