From a45acf2f66de55936680468779438b8264f1f533 Mon Sep 17 00:00:00 2001 From: Annie_wang Date: Wed, 21 Jun 2023 14:28:43 +0800 Subject: [PATCH] update docs Signed-off-by: Annie_wang --- .../reference/apis/Readme-EN.md | 1 + .../reference/apis/js-apis-deviceAttest.md | 154 ++++++++++++++++++ 2 files changed, 155 insertions(+) create mode 100644 en/application-dev/reference/apis/js-apis-deviceAttest.md diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index 3bfa03c8e9..37bf36f22b 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -421,6 +421,7 @@ - Test - [@ohos.application.testRunner (TestRunner)](js-apis-application-testRunner.md) + - [@ohos.deviceAttest (Device Attestation)](js-apis-deviceAttest.md) - [@ohos.uitest (UiTest)](js-apis-uitest.md) - APIs No Longer Maintained diff --git a/en/application-dev/reference/apis/js-apis-deviceAttest.md b/en/application-dev/reference/apis/js-apis-deviceAttest.md new file mode 100644 index 0000000000..06cc480a91 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-deviceAttest.md @@ -0,0 +1,154 @@ +# @ohos.deviceAttest (Device Attestation) + +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 + +```js +import deviceAttest from '@ohos.deviceAttest'; +``` + +## 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](#attestresultinfo)> | Yes | Callback invoked to return the result.
If the operation is successful, **error** is **undefined**, and **result** is the [AttestResultInfo](#attestresultinfo) obtained. Otherwise, **error** is an error object. | + +**Error codes** + +| ID | Error Message | +|----------|----------------------| +| 20000001 | system service exception. | + +**Example** + +```js +try { + deviceAttest.getAttestStatus((error, value) => { + if (typeof error != 'undefined') { + console.info("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) { + console.info("error code:" + error.code + " message:" + error.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](#attestresultinfo)> | Promise used to return the device attestation information obtained.| + +**Error codes** + +| ID | Error Message | +|----------|----------------------| +| 20000001 | system service exception. | + +**Example** + +```js +try { + deviceAttest.getAttestStatus().then((value) => { + 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) => { + console.info("error code:" + error.code + " message:" + error.message); + }); +} catch (error) { + console.info("error code:" + error.code + " message:" + error.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](#attestresultinfo) | Returns the device attestation information obtained.| + +**Error codes** + +| ID | Error Message | +|----------|----------------------| +| 20000001 | system service exception. | + +**Example** + +```js +try { + let value = 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) { + console.info("error code:" + error.code + " message:" + error.message); +} +``` + +## AttestResultInfo + +Defines the device attestation result information. + +**System capability**: SystemCapability.XTS.DeviceAttest + +| Name | Type | Readable| Writable| Description | +| --------------------- | --------------------- | ---- | ---- | ---------------------- | +| authResult | number | Yes | No | Device hardware attestation result. | +| softwareResult | number | Yes | No | Device software attestation result. | +| softwareResultDetail | Array<number> | Yes | No | Detailed information about the device software attestation result.
- **softwareResultDetail[0]**: version ID attestation result.
- **softwareResultDetail[1]**: attestation result of the security patch label.
- **softwareResultDetail[2]**: version hash attestation result.
- **softwareResultDetail[3]**: attestation result of the system capability set.
- **softwareResultDetail[4]**: reserved. | +| ticket | string | Yes | 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. + -- GitLab