• Home
Name Date Size #Lines LOC

..--

build/07-Sep-2024-10281

common/07-Sep-2024-206126

figures/07-Sep-2024-

interfaces/07-Sep-2024-1,6451,073

sample/client/07-Sep-2024-7853

services/07-Sep-2024-13,22010,374

test/07-Sep-2024-2,1451,460

LICENSED07-Sep-202411.3 KiB202169

OAT.xmlD07-Sep-20242.2 KiB4930

README.mdD07-Sep-202413.5 KiB198136

README_zh.mdD07-Sep-20245.1 KiB7760

bundle.jsonD07-Sep-20241.6 KiB6968

README.md

1# 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-   [Repositories Involved](#section600)
14
15
16## Introduction<a id="section100"></a>
17
18xts_device_attest module:
19
20-   The basic function of the xts_device_attest 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 module applies to standard system.
21
22## Directory Structure<a id="section200"></a>
23
24```
25/test/xts
26├── device_attest
27│   └── build                   # Compile configuration
28│   └── common                  # Public basic capacity
29│   └── figures
30│   └── interfaces              # External interface
31│   └── sample                  # External interface example
32│   └── services                # Service subject and business logic code
33│       └── core                # Business logic code
34│       └── devattest_ability   # Service framework
35│       └── etc                 # Startup configuration
36│       └── sa_profile          # Process configuration
37│   └── test
38│       └── unittest            # Test case
39```
40
41## Architecture diagram<a id="section300"></a>
42
43![](figures/image_010.png)
44
45## Constraints<a id="section400"></a>
46
47The integration dependency library is shown in the following table::
48
49| Library    | Version           | Function description                                        | Note                                     |
50| --------- | ---------------- | ----------------------------------------------- | ---------------------------------------- |
51| mbedtls   | 2.16.11          | A lightweight implementation library of TLS protocol for embedded devices. | Library path..\third_party\mbedtls           |
52| OpenSSL   | 1.1.1          | TLS protocal(include SSLv3)and common password library. | Library path..\third_party\openssl           |
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.                    |
56
57
58## Integration guidance<a id="section500"></a>
59
60### Terminology<a id="section501"></a>
61
62**table 1**
63**table 1**
64| Term       | Explain                                                         |
65| ---------- | ------------------------------------------------------------ |
66| partners       | Enterprises applying for OpenHarmony compatibility evaluation are hereinafter collectively referred to as "partners". It is required to integrate xts_device_attest module. |
67| 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. |
68| 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. |
69| 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. |
70| 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. |
71
72
73### Partner completes information registration <a id="section502"></a>
74
75Partners 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.
76In 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:
77
781)Partners complete device information registration on the official website of OpenHarmony compatibility platform.
792)Partners write the device information registered on the official website of the OpenHarmony compatibility platform to the device.
80
81
821.  Partners complete information registration on the OpenHarmony compatibility platform
83
84    Partners need to register relevant equipment certification data on the OpenHarmony compatibility platform, please follow the registration process on the official website.
85
862.  Partners writes the registered OS information to the device
87
88    For the information registered by partners on the OpenHarmony compatibility platform, the version package provides relevant interfaces for partners to fill in.
89    When calling the xts_device_attest 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.
90    xts_device_attest module depends on some device information and needs to be adapted and modified by partners.
91    Device information is located in the startup subsystem file: base/startup/init/services/etc/param/ohos_const/ohos.para.The device OS information is shown in the following table:
92
93**table 2**
94| Device information         | ohos.para configuration parameter                                           | Note                         |
95| --------------- | ------------------------------------------------------------ | ---------------------------- |
96| 发布类型         | const.ohos.releasetype=Beta                                 | Use default    |
97| api版本          | const.ohos.apiversion=6                                     | Use default    |
98| 安全补丁标签     | const.ohos.version.security_patch=2021-09-01                | 2021-09-01 replace with real value   |
99| 软件版本号       | const.ohos.fullname=OpenHarmony-1.0.1.0                      | Use default |
100
101Device product information is located in the vendor subsystem file: base/startup/init/services/etc/param/ohos.para. The device product information is shown in the following table:
102
103**table 3**
104| Device information         | vendor.para configuration parameter                                | Note                         |
105| ---------------- | ------------------------------------------------- | ---------------------------- |
106| 企业简称(英文)  | const.product.manufacturer=****                  | **** replace with real value |
107| 品牌英文名        | const.product.brand=****                         | **** replace with real value |
108| 设备型号         | const.product.model=****                            | **** replace with real value    |
109| 软件版本号       | \# 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 |
110| 版本 id          |                                                     | No partner operation is required, and the system automatically generates |
111| 版本 Hash        | const.ohos.buildroothash=default                    | 添加该数据 defaultreplace with real value|
112
113Note:版本 id needs to be obtained through equipment,Fill in the OpenHarmony compatibility platform,版本 id consists of:
114VersionId = deviceType/manufacture/brand/productSeries/OSFullName/productModel/softwareModel/OHOS_SDK_API_VERSION/incrementalVersion/buildType
115
116Get 版本 id:
117    1) OS information and product information writing device
118    2) Release encrypted log(Modify the modification of PrintDevSysInfo in the following figure)
119    3) Burn
120    4) View 版本 ID through logs
121
122![](figures/image_002.png)
123
124View 版本 ID through logs
125
126![](figures/image_003.png)
127
128
129### Dependent interface adaptation <a id="section503"></a>
130
131In 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:
132
133**table 4**
134|
135Function                                            | Interface definition                                                   | Parameters definition                                                     | Return value                | Belong to                  |
136| ----------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ | --------------------- | ------------------------- |
137| 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 |
138| Read ProductId                                  | int32_t HalGetProdId(char\* productId, uint32_t len)    | productId:Product model identification len:memory length                     | 0:success      1:fail    | ..\hal_token.h |
139| Read token                                     | int32_t HalReadToken(char\* token, uint32_t len);          | token:Token storage memory len:memory length                 | 0:success      1:fail   | ..\hal_token.h |
140| Write token                                      | int32_t HalWriteToken(char\* token, uint32_t len);         | token:Token storage memory len:memory length                 | 0:success      1:fail    | ..\hal_token.h |
141|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 |
142
143
144    1. HalGetManufactureKey
145    manuKey is a parameter used to generate AES secret key in combination with the token, which is downloaded from the OpenHarmony compatibility platform.
146![](figures/image_004.png)
147
148
149    Convert ASCII code to hexadecimal through tools.
150![](figures/image_005.png)
151
152
153![](figures/image_006.png)
154
155
156    Preset in the return value of HalGetManufactureKey interface.
157![](figures/image_007.png)
158
159
160    2. HalGetProdId
161    ProductId is a parameter that is used to generate AES secret key together with the token, which can be viewed on the OpenHarmony platform.
162![](figures/image_008.png)
163
164
165    Preset in the return value of HalGetProductId interface
166![](figures/image_009.png)
167
168
169    3. HalReadToken 和 HalWriteToken
170    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.
171
172    4. HalGetProdKey
173    Reserved interface, which does not need to be implemented temporarily.
174
175
176### External interface<a id="section504"></a>
177
178xts_device_attest module external interface,the following table:
179
180| **Interface Name**                                              | **Description**     |
181| ------------------------------------------------------- | ------------ |
182| int32_t  GetAttestStatus(AttestResultInfo* attestResultInfo); | Get attest result |
183
184The service of xts_device_attest starts automatically when device is started. After the network connection is successful, it will enter the process of xts_device_attest. By querying the GetAttestStatus interface, you can get the results of device attest.
185Call to view sample example.
186
187### Compilation instruction<a id="section505"></a>
188
189Take rk3568 as an example
190```c
191./build.sh --product-name=rk3568 system_size=standard
192```
193
194## Repositories Involved<a id="section600"></a>
195
196**xts\_device\_attest**
197
198[xts\_device\_attest\_lite](https://gitee.com/openharmony-sig/xts_device_attest_lite/)

README_zh.md

1# device_attest部件<a name="ZH-CN_TOPIC_001"></a>
2
3## 简介<a id="section100"></a>
4
5device_attest,设备证明部件,是一个系统服务(SystemAbility), 是OpenHarmony compatibility agreement约定需要设备厂商在产品中集成的部件,用于支撑生态伙伴完成产品的兼容性测试。其基本功能是看护OpenHarmony生态设备认证结果,通过端云校验机制,支撑OpenHarmony南北向生态统一,保障用户体验。该部件用于标准系统(standard system)。
6生态伙伴(即设备厂商)兼容性测试工作流程:
71、设备厂商在[OpenHarmony兼容性平台](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)注册企业账号,完成设备信息登记,将登记的设备信息写入设备,并完成依赖接口适配;
82、设备厂商启动认证测试,上传xts测试报告;
93、OpenHarmony认证云认证通过设备厂商产品信息,发放token到OpenHarmony兼容性平台;
104、设备厂商从OpenHarmony兼容性平台获取token;
115、设备厂商经三方产线将token烧录到OpenHarmony设备;
126、设备证明部件与OpenHarmony认证云通信,对设备进行激活/认证,设备从OpenHarmony认证云获取认证结果,存储到本地;
137、系统服务、系统应用等可通过设备证明部件提供的接口获取认证结果,并基于认证结果进行业务设计。
14
15工作流程图:
16![](figures/image_002.png)
17
18## 目录<a id="section200"></a>
19
20```
21/test/xts
22├── device_attest               # 设备证明部件代码存放目录
23│   └── build                   # 编译配置存放目录
24│   └── common                  # 公共基础能力
25│   └── figures
26│   └── interfaces              # 对外接口
27│   └── sample                  # 对外接口示例
28│   └── services                # 服务主体和业务逻辑代码
29│       └── core                # 业务逻辑代码
30│       └── devattest_ability   # 服务框架
31│       └── etc                 # 启动配置文件存放目录
32│       └── oem_adapter         # 设备厂商适配接口存放目录
33│       └── sa_profile          # 进程配置文件存放目录
34```
35
36## 架构图<a id="section300"></a>
37
381、设备启动过程中,设备证明部件被init进程拉起,监控网络状态,设备联网后,读取token和系统参数,发起设备认证端云通信;
392、端云通信采用https协议,设备证明部件将token和系统参数上传到OpenHarmony认证云,并获取认证结果和新token;
403、设备证明部件将认证结果存储到沙箱目录,并更新token;
414、设备证明部件对外提供认证结果查询接口,供其他模块判定设备是否已通过认证,比如系统服务、系统应用等。
42
43![](figures/image_001.png)
44
45## 约束<a id="section400"></a>
46
47**表 1 设备证明部件集成依赖库**
48| 库名称    | 版本号           | 功能描述                                        | 仓库路径                                     |
49| --------- | ---------------- | ----------------------------------------------- | ---------------------------------------- |
50| mbedtls   | 2.16.11          | 供嵌入式设备使用的一个 TLS 协议的轻量级实现库。 | third_party\mbedtls           |
51| OpenSSL   | 1.1.1          | 传输层安全(TLS)协议(包括SSLv3)以及通用密码库。 | third_party\openssl           |
52| cJSON     | 1.7.15           | JSON 文件解析库。                               | third_party\cJSON |
53| libsec    | 1.1.10           | 安全函数库。                                    | bounds_checking_function      |
54| parameter | OpenHarmony 1.0 release及之后版本 | 获取设备信息的系统接口。                        | base\startup\init\interfaces\innerkits\include\syspara\parameter.h                    |
55
56## 对外接口<a id="section500"></a>
57
58**表 2 设备证明部件对外接口**
59| **接口名**                                              | **描述**     |
60| ------------------------------------------------------- | ------------ |
61| int32_t  GetAttestStatus(AttestResultInfo* attestResultInfo); | 获取设备认证结果 |
62
63设备证明部件开机自启动,网络连接成功后,会进入设备证明部件主流程。通过调用GetAttestStatus接口,获取设备认证结果。
64调用可查看sample示例
65
66## 编译指令<a id="section600"></a>
67以rk3568为例
68```sh
69./build.sh --product-name=rk3568 system_size=standard
70```
71编译成功后会在out/rk3568/packages/phone/system/lib路径下生成libdevattest_core.z.solibdevattest_sdk.z.solibdevattest_service.z.solibdevice_attest_oem_adapter.z.so四个动态库
72
73## 相关仓<a id="section700"></a>
74
75**xts\_device\_attest**
76
77[xts\_device\_attest\_lite](https://gitee.com/openharmony-sig/xts_device_attest_lite/)