RiskControlEngine

Use Cases

Since version 26.0.0, the RiskControlEngine is supported.

The RiskControlEngine is a risk control solution running in the on-device confidential computing space. Based on the system open risk factors and app-specific risk factors, the engine helps customize risk identification policies and rules in a securely isolated high-security trusted environment, efficiently completing risk analysis.

The confidential computing environment ensures that data is calculable but not retrievable, knowable but not visible, and that risk control policies and rules are available but not disclosed. The RiskControlEngine provides flexible, autonomous, and rich policy rule configuration capabilities, as well as an inter-app collaborative defense and control mechanism for apps connected to the StarShield confidential risk control engine.

For example, in telecom anti-fraud scenarios, an app can use the StarShield confidential risk control engine to identify fraud risks in payment/bank transfer scenarios. The process is as follows:

Apply for the permission for this feature in AppGallery Connect, create anti-fraud risk control policies, and deliver them to the on-device confidential computing space.
Call the getRiskControlResult API of Device Security Kit to obtain the result of the custom anti-fraud risk control policies during payment or bank transfer.
Call the importRiskFactors API of Device Security Kit in your app to write app-specific risk factors into the confidential computing space on the device to enhance the detection capability. Set risk identification rules based on the system risk factors for scenario-based risk detection.

Constraints

The risk control scoring capability is supported on mobile phones, tablets, and PCs/2-in-1 devices.
Each app can call the API for up to 10 times per day on each device.

Service Process

Process description:

Your app obtains the nonce value.

When calling the importRiskFactors and getRiskControlResult APIs, your app needs to pass a randomly generated nonce value. The returned detection result contains the nonce value. You can verify this value to confirm the mapping between the response and the request, and prevent 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 imports the app risk factor data.

After receiving the request, Device Security Kit writes the app risk factor data into the RiskControlEngine. The data can be used together with system risk factors for risk control calculation.

Your app can also skip the step of importing risk factors and directly call the getRiskControlResult API to initiate a risk control scoring request.
Your app initiates a risk control scoring request.

After receiving the request, Device Security Kit calls the RiskControlEngine. The risk control engine collects risk control data, calculates the risk control score, and returns the comprehensive risk control score to your app through the getRiskControlResult API.
**Your app verifies the check result on the app server. **

After receiving the risk control scoring result, your app parses the return value in JSON Web Signature (JWS) format to verify the signature, and then performs risk control based on the result of each risk control factor in the payload.

API Description

The following table lists the APIs related to the RiskControlEngine. For more information about the APIs, please refer to API Reference.

API	Description
importRiskFactors(data: ImportData): Promise<void>	Imports app risk factor data.
getRiskControlResult(params: RiskControlDetectionRequest): Promise<RiskControlDetectionResponse>	Risk control scoring result.

Development Procedure

Ensure that you have enabled the RiskControlEngine and requested the profile.

Import the Device Security Kit module and related public modules.

import { riskControlEngine } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { cryptoFramework } from '@kit.CryptoArchitectureKit';
import { util } from '@kit.ArkTS';

Call the importRiskFactors API to import app risk factor data.

const TAG: string = '[RiskControlEngineGetModel]';

async function importRiskFactors(): Promise<void> {
  let rand = cryptoFramework.createRandom();
  let len = 32;
  let randData = rand.generateRandomSync(len);
  let base64 = new util.Base64Helper();
  // Import risk factors.
  let data: riskControlEngine.ImportData = {
    appFactorData: [
      // Change factorName to the name registered by the developer.
      { factorName: 'isFirstTransfer', factorValue: true }
    ],
    nonce: base64.encodeToStringSync(randData.data)
  };
  try {
    await riskControlEngine.importRiskFactors(data);
  } catch (error) {
    let e: BusinessError = error as BusinessError;
    hilog.error(0x0000, TAG, 'ImportRiskFactors failed: %{public}d %{public}s', e.code, e.message);
  }
}

Call the getRiskControlResult API to obtain the risk control score.

const TAG: string = '[RiskControlEngineGetModel]';
// ...

async function getRiskControlResult(): Promise<string> {
  let rand = cryptoFramework.createRandom();
  let len = 32;
  let randData = rand.generateRandomSync(len);
  let base64 = new util.Base64Helper();
  // Prepare the request parameters for risk control scoring.
  const request: riskControlEngine.RiskControlDetectionRequest = {
    // Change policyName to the name registered by the developer.
    policyName: 'antiFraudRiskEvaluation',
    nonce: base64.encodeToStringSync(randData.data)
  };
  try {
    // Obtain the risk control scoring result.
    let res:riskControlEngine.RiskControlDetectionResponse = await riskControlEngine.getRiskControlResult(request);
    return res.result;
  } catch (error) {
    let e: BusinessError = error as BusinessError;
    hilog.error(0x0000, TAG, 'GetRiskControlResult failed: %{public}d %{public}s', e.code, e.message);
    return '';
  }
}

Verify the check result on your app server.

The result returned by the risk control API is a JWS string. The procedure is as follows:

Parse the JWS string to obtain the header, payload, and signature of the risk control scoring result.

Fields in JWS-format Header are as follows:

{
  "alg": "ES256", // Digital signature algorithm. ES256 indicates SHA256withECDSA.
  "typ": "JWS", // The value is fixed to JWS.
  "x5c": ["","",""] // Certificate chain signed by the Device Security Kit server for the JWS, which contains three levels of certificates. x5c[0] is the certificate signed for the JWS, x5c[1] is the level-2 CA certificate for Huawei devices, and x5c[2] is the root CA certificate for Huawei devices.
}

Fields in JWS-format Payload are as follows:

{
  "nonce": "xxxxxxxxx",    // Nonce value encoded in Base64 format and transferred when the getRiskControlResult API is called
  "RiskDetectionOutput": {
    "status": 0,        // Status code
    "result": "1"      // Risk control scoring result
  }
}