应用通过调用Device Security Kit的checkSysIntegrityEnhanced接口获取系统完整性增强检测结果,用于判断设备环境是否安全,比如是否被越狱、非真实设备等。
应用可以根据检测结果评估如何进行业务操作。

流程说明:
在调用checkSysIntegrityEnhanced接口时,您必须传入一个随机生成的nonce值。在检测结果中会包含这个nonce值,您可以通过校验这个nonce值来确定返回结果能够对应您的请求,并且没有被重放攻击。
开发者应用调用checkSysIntegrityEnhanced接口,发起系统完整性增强检测请求。
Device Security Kit收到请求后,首先采集系统完整性增强检测数据,然后将检测数据与nonce一起发送到Device Security服务器做检测,最后通过checkSysIntegrityEnhanced接口的返回值将检测结果传递给开发者应用。
当开发者应用发起业务请求时,在您的应用服务器中验证系统完整性增强检测结果。
当系统完整性增强检测结果为false时,请进一步判断detail中的具体风险分类,您可以根据风险分类以及自身功能对安全的要求决定是否提醒用户。
以下是系统完整性增强检测相关接口,包括ArkTS API,更多接口及使用方法请参见API参考。
| 接口名 | 描述 |
|---|---|
| checkSysIntegrityEnhanced(req: SysIntegrityRequest): Promise<SysIntegrityResponse> | 增强检测系统完整性 |
导入Device Security Kit模块及相关公共模块。
import { safetyDetect } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit'; 调用checkSysIntegrityEnhanced接口获取系统完整性增强检测结果。
该接口涉及端云协同,需要联网等耗时操作,因此不要在UI线程中执行,避免阻塞UI线程。
const TAG = 'SafetyDetectJsTest';
// 请求系统完整性增强检测,并处理结果
let req : safetyDetect.SysIntegrityRequest = {
nonce : 'imEe1PCRcjGkBCAhOCh6ImADztOZ8ygxlWRs' // 从服务器生成的随机的nonce值
};
try {
hilog.info(0x0000, TAG, 'CheckSysIntegrityEnhanced begin.');
const data: safetyDetect.SysIntegrityResponse = await safetyDetect.checkSysIntegrityEnhanced(req);
hilog.info(0x0000, TAG, 'Succeeded in checkSysIntegrityEnhanced: %{public}s', data.result);
} catch (err) {
let e: BusinessError = err as BusinessError;
hilog.error(0x0000, TAG, 'CheckSysIntegrityEnhanced failed: %{public}d %{public}s', e.code, e.message);
} 系统完整性增强检测结果是一个格式为JSON WEB Signature(JWS)的字符串。包括三个部分:
这三个部分使用Base64URL编码后通过“.”进行连接。其中Signature为通过Header中指定的算法对Header与Payload拼接的字符串签名生成的字符串。
示例
eyAgICAiYW**.**.*Jxse eyAgICAiYW**.**.*JodHxx
更多JWS的相关知识请参见 JSON Web Signature。
JWS的Header字段如下:
{
"alg": "ES256",
"typ":"JWS",
"x5c": ["","",""]
}
"alg":签名算法名称,ES256表示使用ECDSA进行签名。
"typ":固定值JWS。
"x5c":Device Security服务对JWS签名的证书链,包含3级证书。其中,x5c[0]为给JWS签名的证书,x5c[1]为二级CA,x5c[2]为ROOT CA。
JWS的Payload字段如下:
{
"hapCertificateSha256": "xxx",
"hapBundleName": "xxx",
"appId": "xxx",
"basicIntegrity": false,
"version": xxx,
"detail": [
"attack",
"jailbreak",
"emulator",
"unlock"
],
"nonce": "xxx",
"timestamp": 1604098577327
}
nonce:调用checkSysIntegrityEnhanced接口时传入的nonce字符串。
timestamp:服务器生成的时间戳。
hapBundleName:您应用的包名。
hapCertificateSha256:您应用的签名证书SHA256摘要。
basicIntegrity:系统完整性增强检测的结果,true表示检测结果完整,false表示存在风险。
version:检测服务的版本,数字类型,便于比较,首版本为1。
appId:您应用的appId。
detail:可选字段,当basicIntegrity结果为false时,该字段将提供存在风险的原因,App开发者可以根据不同风险做出不同的决策,详情如下:
验证检测结果的步骤如下:
请按照上述步骤校验证书与签名,确保检测结果的完整性,防止检测结果被篡改。