• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.deviceAttest (Device Attestation) (System API)
2
3The **deviceAttest** module provides attestation of devices in OpenHarmony by comparing the device information with that stored in the cloud.
4You can use the APIs provided by the **deviceAttest** module to obtain the device attestation result.
5
6> **NOTE**
7>
8> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
9>
10> - The APIs provided by this module are system APIs.
11
12## Modules to Import
13
14```ts
15import deviceAttest from '@ohos.deviceAttest';
16```
17
18## deviceAttest.getAttestStatus
19
20getAttestStatus(callback: AsyncCallback<AttestResultInfo>) : void
21
22Obtains details about the device attestation result from the cloud. This API uses an asynchronous callback to return the result.
23
24**System capability**: SystemCapability.XTS.DeviceAttest
25
26**Parameters**
27
28| Name  | Type                                                       | Mandatory| Description                                                        |
29| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ |
30| callback | AsyncCallback<[AttestResultInfo](#attestresultinfo)> | Yes  | Callback used to return the result. If the operation is successful, **error** is **undefined**, and **result** is the obtained [AttestResultInfo](#attestresultinfo). Otherwise, **error** is an error object.|
31
32**Error codes**
33For details about error codes, see [Device Attestation Error Codes](./errorcode-deviceAttest.md) and [Universal Error Codes](../errorcode-universal.md).
34| ID | Error Message            |
35|----------|----------------------|
36| 202     | This api is system api, Please use the system application to call this api. |
37| 401     | Input parameters wrong, the number of parameters is incorrect, or the type of parameters is incorrect. |
38| 20000001 | System service exception, please try again or reboot your device. |
39
40**Example**
41
42```ts
43import base from '@ohos.base';
44
45try {
46    deviceAttest.getAttestStatus((error: base.BusinessError, value: deviceAttest.AttestResultInfo) => {
47    if (typeof error != 'undefined') {
48        console.error("error code:" + error.code + " message:" + error.message);
49    } else {
50        console.info("auth:" + value.authResult + " software:" + value.softwareResult + " ticket:" + value.ticket);
51        console.info("versionIdResult:" + value.softwareResultDetail[0],
52        " patchLevelResult:" + value.softwareResultDetail[1],
53        " rootHashResult:" + value.softwareResultDetail[2],
54        " PCIDResult:" + value.softwareResultDetail[3],
55        " reserver:" + value.softwareResultDetail[4]);
56    }
57    })
58} catch (error) {
59    let code: number = (error as base.BusinessError).code;
60    let message: string = (error as base.BusinessError).message;
61    console.error("error code:" + code + " message:" + message);
62}
63```
64
65## deviceAttest.getAttestStatus
66
67getAttestStatus() : Promise<AttestResultInfo>
68
69Obtains details about the device attestation result from the cloud. This API uses a promise to return the result.
70
71**System capability**: SystemCapability.XTS.DeviceAttest
72
73**Return value**
74
75| Type                                                 | Description                           |
76| ----------------------------------------------------- | ------------------------------- |
77| Promise<[AttestResultInfo](#attestresultinfo)> | Promise used to return the device attestation information obtained.|
78
79**Error codes**
80For details about error codes, see [Device Attestation Error Codes](./errorcode-deviceAttest.md) and [Universal Error Codes](../errorcode-universal.md).
81| ID | Error Message            |
82|----------|----------------------|
83| 202     | This api is system api, Please use the system application to call this api. |
84| 401     | Input parameters wrong, the number of parameters is incorrect, or the type of parameters is incorrect. |
85| 20000001 | System service exception, please try again or reboot your device. |
86
87**Example**
88
89```ts
90import base from '@ohos.base';
91
92try {
93    deviceAttest.getAttestStatus().then((value: deviceAttest.AttestResultInfo) => {
94    console.info("auth:" + value.authResult + " software:" + value.softwareResult + " ticket:" + value.ticket);
95    console.info("versionIdResult:" + value.softwareResultDetail[0],
96        " patchLevelResult:" + value.softwareResultDetail[1],
97        " rootHashResult:" + value.softwareResultDetail[2],
98        " PCIDResult:" + value.softwareResultDetail[3],
99        " reserver:" + value.softwareResultDetail[4]);
100    }).catch((error: base.BusinessError) => {
101        console.error("error code:" + error.code + " message:" + error.message);
102    });
103} catch (error) {
104    let code: number = (error as base.BusinessError).code;
105    let message: string = (error as base.BusinessError).message;
106    console.error("error code:" + code + " message:" + message);
107}
108```
109
110## deviceAttest.getAttestStatusSync
111
112getAttestStatusSync() : AttestResultInfo
113
114Obtains details about the device attestation result from the cloud synchronously.
115
116**System capability**: SystemCapability.XTS.DeviceAttest
117
118**Return value**
119
120| Type                                                 | Description                           |
121| ----------------------------------------------------- | ------------------------------- |
122| [AttestResultInfo](#attestresultinfo) | Returns the device attestation information obtained.|
123
124**Error codes**
125For details about error codes, see [Device Attestation Error Codes](./errorcode-deviceAttest.md) and [Universal Error Codes](../errorcode-universal.md).
126| ID | Error Message            |
127|----------|----------------------|
128| 202     | This api is system api, Please use the system application to call this api. |
129| 401     | Input parameters wrong, the number of parameters is incorrect, or the type of parameters is incorrect. |
130| 20000001 | System service exception, please try again or reboot your device. |
131
132**Example**
133
134```ts
135import base from '@ohos.base';
136
137try {
138    let value: deviceAttest.AttestResultInfo = deviceAttest.getAttestStatusSync();
139    console.info("auth:" + value.authResult + " software:" + value.softwareResult + " ticket:" + value.ticket);
140    console.info("versionIdResult:" + value.softwareResultDetail[0],
141    " patchLevelResult:" + value.softwareResultDetail[1],
142    " rootHashResult:" + value.softwareResultDetail[2],
143    " PCIDResult:" + value.softwareResultDetail[3],
144    " reserver:" + value.softwareResultDetail[4]);
145} catch (error) {
146    let code: number = (error as base.BusinessError).code;
147    let message: string = (error as base.BusinessError).message;
148    console.error("error code:" + code + " message:" + message);
149}
150```
151
152## AttestResultInfo
153
154Defines the device attestation result information.
155
156**System capability**: SystemCapability.XTS.DeviceAttest
157
158| Name                 | Type                 | Read-Only| Optional| Description                  |
159| --------------------- | --------------------- | ---- | ---- | ---------------------- |
160| authResult            | number               | No  | No  | Device hardware attestation result.   |
161| softwareResult        | number               | No  | No  | Device software attestation result.   |
162| softwareResultDetail  | Array&lt;number&gt;  | No  | No  | Detailed information about the device software attestation result.<br> - **softwareResultDetail[0]**: attestation result of version ID.<br>- **softwareResultDetail[1]**: attestation result of the security patch label.<br>- **softwareResultDetail[2]**: attestation result of version hash.<br>- **softwareResultDetail[3]**: attestation result of the system capability set.<br>- **softwareResultDetail[4]**: reserved. |
163| ticket                | string               | No  | No  | Soft certificate delivered by the cloud.<br>If the device hardware attestation is successful, a value is returned. If the attestation fails, this parameter is empty.       |
164
165> **NOTE**
166>
167> - The attestation result of device hardware and software information can be any of the following:<br> - **-2**: No attestation is performed.<br>- **-1**: The attestation fails.<br>- **0**: The attestation is successful.
168