System Integrity Check

Use Cases

An app calls the checkSysIntegrity API of Device Security Kit to obtain the system integrity check result and determine whether the device environment is secure, for example, whether the device environment has been jailbroken or the device is a non-real device.

An app can warn users of security risks, prompt users to exercise caution when performing service operations, or block operations as needed based on check results.

Constraints

The system integrity check capability is supported on phones, tablets, and PCs/2-in-1 devices. Starting from version 5.1.0(18), it's also supported on wearables.
Each app can call the API for up to 10,000 times per day and five times per minute on each device. A maximum of five concurrent calls are supported on each device.

Service Process

Process description:

Your app obtains the nonce value.

When calling the checkSysIntegrity API, you must pass a randomly generated nonce value. which will be contained in the check result. You can check the nonce value to verify that the returned result corresponds to your request and does not encounter replay attacks.
- A nonce value must contain 16 to 66 bytes and be encoded using Base64.
- It is recommended that a new nonce value be randomly generated by the server for each request.
Your app calls the checkSysIntegrity API to send a system integrity check request.

After receiving the request, Device Security Kit collects the system integrity data, sends the data and nonce to the Device Security server for verification, and then returns the verification result to your app through the checkSysIntegrity API.
When your app initiates a service request, your app server verifies the check result of the checkSysIntegrity API.

If the check result is false, you need to check the risk type in detail and determine whether to notify the user based on the risk type and your app's security requirements.
- The current solution has combined the server and client to mitigate security risks. However, the checkSysIntegrity API cannot mitigate all security risks.
- The system integrity check result can be used as one of the system security proofs. You should consider relevant risks caused by possibly incorrect check results and the impacts to users. You are advised not to use the check result as the only proof to determine whether the current device is secure. It's better to take extra measures to further reduce risks.
- To improve user experience when notifying users within the app, consider using friendly messages like:
  
  Your device might be at risk or running in an insecure environment. Please exercise caution when using the XXX feature.

API Description

The following table lists the system integrity check API, which is an ArkTS API. For more information about the API, please refer to API Reference.

API	Description
checkSysIntegrity(req: SysIntegrityRequest): Promise<SysIntegrityResponse>	Checks system integrity.

Development Procedure

Ensure that you have enabled SafetyDetect and requested the profile.

Import the Device Security Kit module and related public modules.

import { safetyDetect } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

Call the checkSysIntegrity API to obtain the system integrity check result.

This API involves device-cloud synergy and time-consuming operations such as network connection. Therefore, do not execute this API in the UI thread, in order to avoid UI thread blocking.

const TAG = 'SafetyDetectJsTest';

// Request system integrity check and process the result.
let req : safetyDetect.SysIntegrityRequest = {
  nonce : 'imEe1PCRcjGkBCAhOCh6ImADztOZ8ygxlWRs' // Random nonce value generated by the server.
};
try {
  hilog.info(0x0000, TAG, 'CheckSysIntegrity begin.');
  const data: safetyDetect.SysIntegrityResponse = await safetyDetect.checkSysIntegrity(req);
  hilog.info(0x0000, TAG, 'Succeeded in checkSysIntegrity: %{public}s', data.result);
  // ...
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, TAG, 'CheckSysIntegrity failed: %{public}d %{public}s', e.code, e.message);
  // ...
}