@ohos.deviceAttest (Device Attestation) (System API)

The deviceAttest module provides attestation of devices in OpenHarmony by comparing the device information with that stored in the cloud.

You can use the APIs provided by the deviceAttest module to obtain the device attestation result.

NOTE

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.

The APIs provided by this module are system APIs.

Modules to Import

import { deviceAttest } from '@kit.BasicServicesKit';

deviceAttest.getAttestStatus

getAttestStatus(callback: AsyncCallback<AttestResultInfo>) : void

Obtains details about the device attestation result from the cloud. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.XTS.DeviceAttest

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<AttestResultInfo>	Yes	Callback used to return the result. If the operation is successful, error is undefined, and result is the obtained AttestResultInfo. Otherwise, error is an error object.

Error codes For details about error codes, see Device Attestation Error Codes and Universal Error Codes.

ID	Error Message
202	This api is system api, Please use the system application to call this api.
401	Input parameters wrong, the number of parameters is incorrect, or the type of parameters is incorrect.
20000001	System service exception, please try again or reboot your device.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
    deviceAttest.getAttestStatus((error: BusinessError, value: deviceAttest.AttestResultInfo) => {
    if (typeof error != 'undefined') {
        console.error("error code:" + error.code + " message:" + error.message);
    } else {
        console.info("auth:" + value.authResult + " software:" + value.softwareResult + " ticket:" + value.ticket);
        console.info("versionIdResult:" + value.softwareResultDetail[0],
        " patchLevelResult:" + value.softwareResultDetail[1],
        " rootHashResult:" + value.softwareResultDetail[2],
        " PCIDResult:" + value.softwareResultDetail[3],
        " reserver:" + value.softwareResultDetail[4]);
    }
    })
} catch (error) {
    let code: number = (error as BusinessError).code;
    let message: string = (error as BusinessError).message;
    console.error("error code:" + code + " message:" + message);
}

deviceAttest.getAttestStatus

getAttestStatus() : Promise<AttestResultInfo>

Obtains details about the device attestation result from the cloud. This API uses a promise to return the result.

System capability: SystemCapability.XTS.DeviceAttest

Return value

Type	Description
Promise<AttestResultInfo>	Promise used to return the device attestation information obtained.

Error codes For details about error codes, see Device Attestation Error Codes and Universal Error Codes.

ID	Error Message
202	This api is system api, Please use the system application to call this api.
401	Input parameters wrong, the number of parameters is incorrect, or the type of parameters is incorrect.
20000001	System service exception, please try again or reboot your device.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
    deviceAttest.getAttestStatus().then((value: deviceAttest.AttestResultInfo) => {
    console.info("auth:" + value.authResult + " software:" + value.softwareResult + " ticket:" + value.ticket);
    console.info("versionIdResult:" + value.softwareResultDetail[0],
        " patchLevelResult:" + value.softwareResultDetail[1],
        " rootHashResult:" + value.softwareResultDetail[2],
        " PCIDResult:" + value.softwareResultDetail[3],
        " reserver:" + value.softwareResultDetail[4]);
    }).catch((error: BusinessError) => {
        console.error("error code:" + error.code + " message:" + error.message);
    });
} catch (error) {
    let code: number = (error as BusinessError).code;
    let message: string = (error as BusinessError).message;
    console.error("error code:" + code + " message:" + message);
}

deviceAttest.getAttestStatusSync

getAttestStatusSync() : AttestResultInfo

Obtains details about the device attestation result from the cloud synchronously.

System capability: SystemCapability.XTS.DeviceAttest

Return value

Type	Description
AttestResultInfo	Returns the device attestation information obtained.

Error codes For details about error codes, see Device Attestation Error Codes and Universal Error Codes.

ID	Error Message
202	This api is system api, Please use the system application to call this api.
401	Input parameters wrong, the number of parameters is incorrect, or the type of parameters is incorrect.
20000001	System service exception, please try again or reboot your device.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
    let value: deviceAttest.AttestResultInfo = deviceAttest.getAttestStatusSync();
    console.info("auth:" + value.authResult + " software:" + value.softwareResult + " ticket:" + value.ticket);
    console.info("versionIdResult:" + value.softwareResultDetail[0],
    " patchLevelResult:" + value.softwareResultDetail[1],
    " rootHashResult:" + value.softwareResultDetail[2],
    " PCIDResult:" + value.softwareResultDetail[3],
    " reserver:" + value.softwareResultDetail[4]);
} catch (error) {
    let code: number = (error as BusinessError).code;
    let message: string = (error as BusinessError).message;
    console.error("error code:" + code + " message:" + message);
}

AttestResultInfo

Defines the device attestation result information.

System capability: SystemCapability.XTS.DeviceAttest

Name	Type	Read-Only	Optional	Description
authResult	number	No	No	Device hardware attestation result.
softwareResult	number	No	No	Device software attestation result.
softwareResultDetail	Array<number>	No	No	Detailed information about the device software attestation result. - softwareResultDetail[0]: attestation result of version ID. - softwareResultDetail[1]: attestation result of the security patch label. - softwareResultDetail[2]: attestation result of version hash. - softwareResultDetail[3]: attestation result of the system capability set. - softwareResultDetail[4]: reserved.
ticket	string	No	No	Soft certificate delivered by the cloud. If the device hardware attestation is successful, a value is returned. If the attestation fails, this parameter is empty.

NOTE

The attestation result of device hardware and software information can be any of the following:
- -2: No attestation is performed.
- -1: The attestation fails.
- 0: The attestation is successful.