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 invoked 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**
33
34| ID | Error Message            |
35|----------|----------------------|
36| 20000001 | system service exception. |
37
38**Example**
39
40```ts
41import base from '@ohos.base';
42
43try {
44    deviceAttest.getAttestStatus((error: base.BusinessError, value: deviceAttest.AttestResultInfo) => {
45    if (typeof error != 'undefined') {
46        console.info("error code:" + error.code + " message:" + error.message);
47    } else {
48        console.info("auth:" + value.authResult + " software:" + value.softwareResult + " ticket:" + value.ticket);
49        console.info("versionIdResult:" + value.softwareResultDetail[0],
50        " patchLevelResult:" + value.softwareResultDetail[1],
51        " rootHashResult:" + value.softwareResultDetail[2],
52        " PCIDResult:" + value.softwareResultDetail[3],
53        " reserver:" + value.softwareResultDetail[4]);
54    }
55    })
56} catch (error) {
57    let code: number = (error as base.BusinessError).code;
58    let message: string = (error as base.BusinessError).message;
59    console.info("error code:" + code + " message:" + message);
60}
61```
62
63## deviceAttest.getAttestStatus
64
65getAttestStatus() : Promise<AttestResultInfo>
66
67Obtains details about the device attestation result from the cloud. This API uses a promise to return the result.
68
69**System capability**: SystemCapability.XTS.DeviceAttest
70
71**Return value**
72
73| Type                                                 | Description                           |
74| ----------------------------------------------------- | ------------------------------- |
75| Promise<[AttestResultInfo](#attestresultinfo)> | Promise used to return the device attestation information obtained.|
76
77**Error codes**
78
79| ID | Error Message            |
80|----------|----------------------|
81| 20000001 | system service exception. |
82
83**Example**
84
85```ts
86import base from '@ohos.base';
87
88try {
89    deviceAttest.getAttestStatus().then((value: deviceAttest.AttestResultInfo) => {
90    console.info("auth:" + value.authResult + " software:" + value.softwareResult + " ticket:" + value.ticket);
91    console.info("versionIdResult:" + value.softwareResultDetail[0],
92        " patchLevelResult:" + value.softwareResultDetail[1],
93        " rootHashResult:" + value.softwareResultDetail[2],
94        " PCIDResult:" + value.softwareResultDetail[3],
95        " reserver:" + value.softwareResultDetail[4]);
96    }).catch((error: base.BusinessError) => {
97        console.info("error code:" + error.code + " message:" + error.message);
98    });
99} catch (error) {
100    let code: number = (error as base.BusinessError).code;
101    let message: string = (error as base.BusinessError).message;
102    console.info("error code:" + code + " message:" + message);
103}
104```
105
106## deviceAttest.getAttestStatusSync
107
108getAttestStatusSync() : AttestResultInfo
109
110Obtains details about the device attestation result from the cloud synchronously.
111
112**System capability**: SystemCapability.XTS.DeviceAttest
113
114**Return value**
115
116| Type                                                 | Description                           |
117| ----------------------------------------------------- | ------------------------------- |
118| [AttestResultInfo](#attestresultinfo) | Returns the device attestation information obtained.|
119
120**Error codes**
121
122| ID | Error Message            |
123|----------|----------------------|
124| 20000001 | system service exception. |
125
126**Example**
127
128```ts
129import base from '@ohos.base';
130
131try {
132    let value: deviceAttest.AttestResultInfo = deviceAttest.getAttestStatusSync();
133    console.info("auth:" + value.authResult + " software:" + value.softwareResult + " ticket:" + value.ticket);
134    console.info("versionIdResult:" + value.softwareResultDetail[0],
135    " patchLevelResult:" + value.softwareResultDetail[1],
136    " rootHashResult:" + value.softwareResultDetail[2],
137    " PCIDResult:" + value.softwareResultDetail[3],
138    " reserver:" + value.softwareResultDetail[4]);
139} catch (error) {
140    let code: number = (error as base.BusinessError).code;
141    let message: string = (error as base.BusinessError).message;
142    console.info("error code:" + code + " message:" + message);
143}
144```
145
146## AttestResultInfo
147
148Defines the device attestation result information.
149
150**System capability**: SystemCapability.XTS.DeviceAttest
151
152| Name                 | Type                 | Readable| Writable| Description                  |
153| --------------------- | --------------------- | ---- | ---- | ---------------------- |
154| authResult            | number               | Yes  | No  | Device hardware attestation result.   |
155| softwareResult        | number               | Yes  | No  | Device software attestation result.   |
156| softwareResultDetail  | Array&lt;number&gt;  | Yes  | No  | Detailed information about the device software attestation result.<br> - **softwareResultDetail[0]**: version ID attestation result.<br>- **softwareResultDetail[1]**: attestation result of the security patch label.<br>- **softwareResultDetail[2]**: version hash attestation result.<br>- **softwareResultDetail[3]**: attestation result of the system capability set.<br>- **softwareResultDetail[4]**: reserved. |
157| ticket                | string               | Yes  | 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.       |
158
159> **NOTE**
160>
161> - 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.
162