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