安全检测模块提供设备环境安全检测能力,包括系统完整性检测、恶意URL检测、统一风控凭证等安全评估功能。开发者应用可基于检测结果评估设备安全风险并采取相应防护措施。
起始版本: 5.0.0(12)
系统完整性检测的请求参数。
元服务API: 从API版本5.0.2(14)开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Security.SafetyDetect
模型约束: 此接口仅可在Stage模型下使用。
起始版本: 5.0.0(12)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| nonce | string | 否 | 否 | 开发者应用传入的一个随机生成的nonce值,用于防重放攻击,每个请求应具有唯一性,在检测结果中会包含该值。nonce必须是长度16至66字节之间,有效值为base64编码范围。 |
系统完整性检测返回值。
元服务API: 从API版本5.0.2(14)开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Security.SafetyDetect
模型约束: 此接口仅可在Stage模型下使用。
起始版本: 5.0.0(12)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| result | string | 否 | 否 | JWS格式的系统完整性检测结果。JWS内容详见系统完整性检测开发步骤。 |
URL检测请求参数。
元服务API: 从API版本5.0.2(14)开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Security.SafetyDetect
模型约束: 此接口仅可在Stage模型下使用。
起始版本: 5.0.0(12)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| urls | Array<string> | 否 | 否 | 被检测的URL列表。URL数量最多10个并且每个URL长度不大于4096字节。 |
URL检测返回值。
元服务API: 从API版本5.0.2(14)开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Security.SafetyDetect
模型约束: 此接口仅可在Stage模型下使用。
起始版本: 5.0.0(12)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| results | Array<UrlCheckResult> | 否 | 否 | URL检测返回的检测结果。每个结果包含被检查的URL及其威胁类型。 |
URL检测结果详情。
元服务API: 从API版本5.0.2(14)开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Security.SafetyDetect
模型约束: 此接口仅可在Stage模型下使用。
起始版本: 5.0.0(12)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| url | string | 否 | 否 | 对应到输入参数中被检测的URL。 |
| threat | UrlThreatType | 否 | 否 | URL的威胁类型。 |
枚举URL威胁类型。
元服务API: 从API版本5.0.2(14)开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Security.SafetyDetect
模型约束: 此接口仅可在Stage模型下使用。
起始版本: 5.0.0(12)
| 名称 | 值 | 说明 |
|---|---|---|
| NORMAL | 0 | 未发现威胁。 |
| MALWARE | 1 | 恶意类型的URL。 |
| PHISHING | 2 | 钓鱼类型的URL。 |
| OTHERS | 3 | 其他威胁类型的URL。 |
checkSysIntegrity(req: SysIntegrityRequest): Promise<SysIntegrityResponse>
获取本设备的系统完整性的在线检测结果。使用Promise异步回调。
该接口涉及端云协同,需要联网等耗时操作,因此不要在UI线程中执行,避免阻塞UI线程。
元服务API: 从API版本5.0.2(14)开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Security.SafetyDetect
模型约束: 此接口仅可在Stage模型下使用。
起始版本: 5.0.0(12)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| req | SysIntegrityRequest | 是 | 请求参数,包含nonce。 nonce长度必须16至66字节之间,有效值为base64编码范围。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<SysIntegrityResponse> | Promise对象,返回系统完整性检测结果。 |
错误码:
以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。
| 错误码ID | 错误信息 |
|---|---|
| 201 | Permission verification failed. The application does not have the permission. |
| 401 | [Sync] Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. |
| 801 | Capability not supported. Possible causes: 1. The hardware does not support the capability; 2. The chip does not support the capability; 3. A dependent service feature is not supported. 适用版本:5.1.0(18)+ |
| 1010800001 | Internal error. |
| 1010800002 | The network is unreachable. |
| 1010800003 | Access cloud server fail. |
| 1010800005 | The number of calls exceeds the parallel threshold. 适用版本:5.1.0(18)+ |
| 1010800006 | The invoking frequency exceeds the threshold. 适用版本:5.1.0(18)+ |
| 1010800007 | Operation timeout. 适用版本:5.1.0(18)+ |
| 1010800008 | The cloud service traffic exceeds the threshold. 适用版本:5.1.0(18)+ |
示例:
import { safetyDetect } from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
const TAG = 'SafetyDetectJsTest';
// 请求系统完整性检测,并处理结果
let req : safetyDetect.SysIntegrityRequest = {
nonce : 'imEe1PCRcjGkBCAhOCh6ImADztOZ8ygxlWRs' // 从服务器生成的随机的nonce值
};
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);
} checkUrlThreat(req: UrlCheckRequest): Promise<UrlCheckResponse>
检测URL是否为恶意网址。使用Promise异步回调。
该接口涉及端云协同,需要联网等耗时操作,因此不要在UI线程中执行,避免阻塞UI线程。
元服务API: 从API版本5.0.2(14)开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Security.SafetyDetect
模型约束: 此接口仅可在Stage模型下使用。
起始版本: 5.0.0(12)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| req | UrlCheckRequest | 是 | 请求参数,包含被检测的URL列表。 传入的URL数量最多10个并且每个URL长度不大于4096字节。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<UrlCheckResponse> | Promise对象,返回URL检测结果。 |
错误码:
以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。
| 错误码ID | 错误信息 |
|---|---|
| 201 | Permission verification failed. The application does not have the permission. |
| 401 | [Sync] Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. |
| 801 | Capability not supported. Possible causes: 1. The hardware does not support the capability; 2. The chip does not support the capability; 3. A dependent service feature is not supported. 适用版本:5.1.0(18)+ |
| 1010800001 | Internal error. |
| 1010800002 | The network is unreachable. |
| 1010800003 | Access cloud server fail. |
| 1010800005 | The number of calls exceeds the parallel threshold. 适用版本:5.1.0(18)+ |
| 1010800006 | The invoking frequency exceeds the threshold. 适用版本:5.1.0(18)+ |
| 1010800007 | Operation timeout. 适用版本:5.1.0(18)+ |
| 1010800008 | The cloud service traffic exceeds the threshold. 适用版本:5.1.0(18)+ |
示例:
import { safetyDetect } from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
const TAG = 'SafetyDetectJsTest';
// 请求URL检测,并处理结果
let req : safetyDetect.UrlCheckRequest = {
urls : ['https://test1.com']
};
try {
hilog.info(0x0000, TAG, 'CheckUrlThreat begin.');
const data: safetyDetect.UrlCheckResponse = await safetyDetect.checkUrlThreat(req);
hilog.info(0x0000, TAG, 'Succeeded in checkUrlThreat: %{public}s %{public}d', data.results[0].url, data.results[0].threat);
} catch (err) {
let e: BusinessError = err as BusinessError;
hilog.error(0x0000, TAG, 'CheckUrlThreat failed: %{public}d %{public}s', e.code, e.message);
} checkSysIntegrityOnLocal(): Promise<string>
获取本设备的系统完整性的本地检测结果。使用Promise异步回调。
元服务API: 从API版本5.1.0(18)开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Security.SafetyDetect
模型约束: 此接口仅可在Stage模型下使用。
起始版本: 5.1.0(18)
返回值:
| 类型 | 说明 |
|---|---|
| Promise<string> | Promise对象,返回JSON格式的本地系统完整性检测结果,格式详见本地系统完整性检测结果JSON结构说明。 |
本地系统完整性检测结果JSON结构说明:
| 字段名 | 类型 | 说明 |
|---|---|---|
| basicIntegrity | boolean | 本地系统完整性检测的结果。true表示检测结果完整,false表示存在风险。 |
| detail | Array<string> | 可选字段,当basicIntegrity结果为false时,该字段将提供存在风险的原因。取值见detail字段取值说明。 |
detail字段取值说明:
| 值 | 说明 |
|---|---|
| jailbreak | 设备被越狱。 |
| emulator | 非真实设备。 |
| attack | 设备被攻击。 |
| unlock | 设备被解锁。 |
示例(返回值):
{
"basicIntegrity": false,
"detail": [
"attack",
"jailbreak",
"emulator"
]
} 错误码:
以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。
| 错误码ID | 错误信息 |
|---|---|
| 801 | Capability not supported. Possible causes: 1. The hardware does not support the capability; 2. The chip does not support the capability; 3. A dependent service feature is not supported. |
| 1010800001 | Internal error. |
| 1010800004 | Verify capability fail. |
| 1010800005 | The number of calls exceeds the parallel threshold. |
| 1010800006 | The invoking frequency exceeds the threshold. |
| 1010800007 | Operation timeout. |
示例:
import { safetyDetect } from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
const TAG = 'SafetyDetectJsTest';
// 请求本地系统完整性检测,并处理结果
try {
hilog.info(0x0000, TAG, 'CheckSysIntegrityOnLocal begin.');
const result: string = await safetyDetect.checkSysIntegrityOnLocal();
hilog.info(0x0000, TAG, 'Succeeded in checkSysIntegrityOnLocal: %{public}s', result);
} catch (err) {
let e: BusinessError = err as BusinessError;
hilog.error(0x0000, TAG, 'CheckSysIntegrityOnLocal failed: %{public}d %{public}s', e.code, e.message);
} checkSysIntegrityEnhanced(req: SysIntegrityRequest): Promise<SysIntegrityResponse>
获取本设备的系统完整性的在线增强检测结果。使用Promise异步回调。
该接口涉及端云协同,需要联网等耗时操作,因此不要在UI线程中执行,避免阻塞UI线程。
元服务API: 从API版本6.0.0(20)开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Security.SafetyDetect
模型约束: 此接口仅可在Stage模型下使用。
起始版本: 6.0.0(20)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| req | SysIntegrityRequest | 是 | 请求参数,包含nonce。 nonce长度必须16至66字节之间,有效值为base64编码范围。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<SysIntegrityResponse> | Promise对象,返回系统完整性增强检测结果。 |
错误码:
以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。
| 错误码ID | 错误信息 |
|---|---|
| 801 | Capability not supported. Possible causes: 1. The hardware does not support the capability; 2. The chip does not support the capability; 3. A dependent service feature is not supported. |
| 1010800001 | Internal error. |
| 1010800002 | The network is unreachable. |
| 1010800003 | Access cloud server fail. |
| 1010800004 | Verify capability fail. |
| 1010800005 | The number of calls exceeds the parallel threshold. |
| 1010800006 | The invoking frequency exceeds the threshold. |
| 1010800007 | Operation timeout. |
| 1010800008 | The cloud service traffic exceeds the threshold. |
示例:
import { safetyDetect } from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
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);
} 枚举风险因子类型。
元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Security.SafetyDetect
模型约束: 此接口仅可在Stage模型下使用。
设备行为差异: 本接口实际支持的设备类型范围(Phone、PC/2in1、Tablet)小于其所属系统能力支持的设备类型范围(Phone、PC/2in1、Tablet、Wearable)。因设备能力受限,该接口在Wearable设备中调用将返回801错误码。
起始版本: 26.0.0
| 名称 | 值 | 说明 |
|---|---|---|
| HDC_DEBUG_STATE | "hdcDebugState" | HDC调试状态。 |
| IS_DEVELOPER_MODE | "isDeveloperMode" | 开发者模式状态。 |
| IS_VPN_STATUS | "isVpnStatus" | VPN状态。 |
| IS_NET_PROXY_STATUS | "isNetProxyStatus" | 网络代理状态。 |
| SIM_CNT | "simCnt" | 插入的SIM卡数量。 |
| OOBE_CNT | "oobeCnt" | OOBE操作次数。 |
| ODID_RESET_CNT | "odidResetCnt" | ODID重置次数。 |
| ODID | "odid" | 当前ODID值。 |
| IS_DISPLAY_CAPTURED | "isDisplayCaptured" | 屏幕录制状态。 |
| GLOBAL_WINDOW_STATE | "globalWindowState" | 前台窗口模式。 |
| BATTERY_CHARGE_STATE | "batteryChargeState" | 电池充电状态。 |
| BATTERY_HEALTH_STATE | "batteryHealthState" | 电池健康状态。 |
| ON_CALL_STATE | "onCallState" | 通话状态。 |
风险因子查询请求参数。
元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Security.SafetyDetect
模型约束: 此接口仅可在Stage模型下使用。
设备行为差异: 本接口实际支持的设备类型范围(Phone、PC/2in1、Tablet)小于其所属系统能力支持的设备类型范围(Phone、PC/2in1、Tablet、Wearable)。因设备能力受限,该接口在Wearable设备中调用将返回801错误码。
起始版本: 26.0.0
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| nonce | string | 否 | 否 | 开发者应用传入的一个随机生成的nonce值,用于防重放攻击,每个请求应具有唯一性,在检测结果中会包含该值。nonce必须是长度16至66字节之间,有效值为base64编码范围。 |
| queries | Array<FactorQuery> | 否 | 否 | 要查询的风险因子列表。最大长度为20且不能为空。 |
风险因子查询项。
元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Security.SafetyDetect
模型约束: 此接口仅可在Stage模型下使用。
设备行为差异: 本接口实际支持的设备类型范围(Phone、PC/2in1、Tablet)小于其所属系统能力支持的设备类型范围(Phone、PC/2in1、Tablet、Wearable)。因设备能力受限,该接口在Wearable设备中调用将返回801错误码。
起始版本: 26.0.0
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| factor | RiskFactorType | 否 | 否 | 要查询的风险因子类型。 |
风险因子查询返回值。
元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Security.SafetyDetect
模型约束: 此接口仅可在Stage模型下使用。
设备行为差异: 本接口实际支持的设备类型范围(Phone、PC/2in1、Tablet)小于其所属系统能力支持的设备类型范围(Phone、PC/2in1、Tablet、Wearable)。因设备能力受限,该接口在Wearable设备中调用将返回801错误码。
起始版本: 26.0.0
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| result | string | 否 | 否 | JWS格式的风险因子查询结果。JWS内容详见统一风控凭证开发步骤。 |
queryRiskFactors(req: RiskFactorRequest): Promise<RiskFactorResponse>
查询系统级风险因子数据。使用Promise异步回调。
元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Security.SafetyDetect
模型约束: 此接口仅可在Stage模型下使用。
设备行为差异: 本接口实际支持的设备类型范围(Phone、PC/2in1、Tablet)小于其所属系统能力支持的设备类型范围(Phone、PC/2in1、Tablet、Wearable)。因设备能力受限,该接口在Wearable设备中调用将返回801错误码。
起始版本: 26.0.0
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| req | RiskFactorRequest | 是 | 风险因子查询请求参数。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<RiskFactorResponse> | Promise对象,返回风险因子查询结果。 |
错误码:
以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。
| 错误码ID | 错误信息 |
|---|---|
| 801 | Capability not supported. Possible causes: 1. The hardware does not support the capability; 2. The chip does not support the capability; 3. A dependent service feature is not supported. |
| 1010800004 | Verify capability fail. |
| 1010800005 | The number of calls exceeds the parallel threshold. |
| 1010800006 | The invoking frequency exceeds the threshold. |
| 1010800007 | Operation timeout. |
| 1010800011 | Failed to query the risk factor. |
示例:
import { safetyDetect } from '@kit.DeviceSecurityKit';
import { BusinessError} from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
const TAG = 'SafetyDetectJsTest';
// 请求风控因子数据,并处理结果
const request: safetyDetect.RiskFactorRequest = {
nonce: 'a1b2c3d4e5f6g7hfsdfxvsdae8', // 16-66字节的防重放随机数
queries: [
{ factor: safetyDetect.RiskFactorType.HDC_DEBUG_STATE },
{ factor: safetyDetect.RiskFactorType.IS_DEVELOPER_MODE },
{ factor: safetyDetect.RiskFactorType.ODID_RESET_CNT }
]
};
try {
hilog.info(0x0000, TAG, 'QueryRiskFactors begin.');
const response: safetyDetect.RiskFactorResponse = await safetyDetect.queryRiskFactors(request);
hilog.info(0x0000, TAG, 'Succeeded in QueryRiskFactors: %{public}s', response.result);
} catch (err) {
let e: BusinessError = err as BusinessError;
hilog.error(0x0000, TAG, 'QueryRiskFactors failed: %{public}d %{public}s', e.code, e.message);
}