1 # @ohos.deviceAttest (Device Attestation) 2 3 The **deviceAttest** module provides attestation of devices in OpenHarmony by comparing the device information with that stored in the cloud. 4 You 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 15 import deviceAttest from '@ohos.deviceAttest'; 16 ``` 17 18 ## deviceAttest.getAttestStatus 19 20 getAttestStatus(callback: AsyncCallback<AttestResultInfo>) : void 21 22 Obtains 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.<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 41 import base from '@ohos.base'; 42 43 try { 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 65 getAttestStatus() : Promise<AttestResultInfo> 66 67 Obtains 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 86 import base from '@ohos.base'; 87 88 try { 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 108 getAttestStatusSync() : AttestResultInfo 109 110 Obtains 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 129 import base from '@ohos.base'; 130 131 try { 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 148 Defines 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<number> | 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: 162 > 163 > - **-2**: No attestation is performed. 164 > - **-1**: The attestation fails. 165 > - **0**: The attestation is successful. 166