# 星盾机密风控引擎

#### 场景介绍

从26.0.0 版本开始，新增支持星盾机密风控引擎。

星盾机密风控引擎是一款基于端侧机密计算空间的风控解决方案，依托系统开放风险因子及App专属风险因子，在安全隔离的高安可信环境中，助力业务定制化配置风险识别策略与规则，高效完成风险研判。

依托机密计算环境，保障数据可算不可取、可知不可见、风控策略规则可用不泄露的安全环境。星盾机密风控引擎提供灵活、自主、丰富的策略规则配置能力，同时具备接入星盾机密风控引擎的App间联防联控协作机制。

例如在电信防诈场景下，应用使用星盾机密风控引擎识别支付/转账场景下的涉诈风险过程：

1.  在AGC上申请该特性权限，并构建防诈风控策略规则下发至端侧机密计算空间。
2.  在支付/转账环节调用Device Security Kit的getRiskControlResult接口获取自定义防诈风控策略结果。
3.  为增强检测能力，应用可通过调用Device Security Kit的importRiskFactors接口将App专属风险因子写入端侧机密计算空间，结合系统风险因子，综合设置风险识别规则，用于场景化风险检测。

#### 约束与限制

*   风控评分能力支持Phone、Tablet、PC/2in1设备。
*   每个应用在单台设备上，每天最多可以调用10次。

#### 业务流程

**流程说明：**

1.  **开发者应用获取nonce。**
    
    开发者应用在调用importRiskFactors和getRiskControlResult接口时，需传入随机生成的nonce值。返回的检测结果中将包含该nonce值，开发者可通过校验此值确认响应与请求的对应关系，并防范重放攻击。
    
    *   nonce值必须为16至66字节之间，有效值为base64编码范围。
        
    *   推荐的做法是，每次请求都从服务器随机生成新的nonce值。
        
    
2.  **开发者应用导入应用风险因子数据。**
    
    Device Security Kit收到请求后，会将应用风险因子数据写入星盾机密风控引擎，该数据可结合系统风险因子综合参与风控计算。
    
    开发者应用也可以跳过导入风险因子步骤，直接调用getRiskControlResult接口发起风控评分请求。
    
3.  **开发者应用发起风控评分请求。**
    
    Device Security Kit收到请求后，首先调用星盾机密风控引擎，风控引擎采集风控数据，计算风控评分，最后通过getRiskControlResult接口将完整的风控评分结果返回给开发者应用。
    
4.  **开发者应用服务器中验证检测结果。**
    
    当风控评分结果返回后，开发者应用通过解析JWS（JSON Web Signature）格式的返回值先进行签名验证，再根据Payload中的各风控因子项的结果进行相关风控处理。
    

#### 接口说明

以下是星盾机密风控引擎相关接口，更多接口及使用方法请参见API参考。

| 接口名 | 描述 |
| --- | --- |
| importRiskFactors(data: ImportData): Promise<void> | 导入应用风险因子数据。 |
| getRiskControlResult(params: RiskControlDetectionRequest): Promise<RiskControlDetectionResponse> | 风控评分结果。 |

#### 开发步骤

请确保已打开“星盾机密风控引擎”开关并申请Profile。

1.  导入Device Security Kit模块及相关公共模块。
    
    ```
    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';
    ```
    
2.  调用importRiskFactors接口导入应用风险因子数据。
    
    ```
    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: [
          // need to change factorName by your registered.
          { 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}d', e.code, e.message);
      }
    }
    ```
    
3.  调用getRiskControlResult接口获取风控评分结果。
    
    ```
    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 risk control detection request
      const request: riskControlEngine.RiskControlDetectionRequest = {
        // need to change policyName by your registered.
        policyName: 'antiFraudRiskEvaluation',
        nonce: base64.encodeToStringSync(randData.data)
      };
      try {
        // get risk control 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}d', e.code, e.message);
        return '';
      }
    }
    ```
    
4.  在开发者应用服务器中验证检测结果。
    
    风险控制接口响应结果，格式为JSON WEB签名（JWS），具体步骤如下：
    
    1.  解析JWS，获取风险控制评分结果的Header、Payload、Signature。
        
        **JWS的Header字段如下：**
        
        ```
        {
          "alg": "ES256",    // 数字签名算法，ES256表示为SHA256withECDSA
          "typ": "JWS",      // 固定值JWS
          "x5c": ["","",""]  // Device Security Kit服务器对JWS签名的证书链，包含3级证书。x5c[0]为给JWS签名的证书，x5c[1]为华为设备二级CA，x5c[2]为华为设备ROOT CA
        }
        ```
        
        **JWS的Payload字段如下：**
        
        ```
        {
          "nonce": "xxxxxxxxx",    // 调用getRiskControlResult接口时传入的nonce值Base64编码
          "RiskDetectionOutput": {
            "status": 0,        // 状态码
            "result": "1"      // 风控评分结果
          }
        }
        ```
        
    2.  从Header中获取证书链，使用Huawei CBG Device Attestation Root CA证书对其进行验证。
        
    3.  校验证书链中是否包含3级证书，并确认证书链中x5c\[0\]证书的Common Name是否为Harmony OS Device Attestation Service。
        
    4.  从Signature中获取签名，校验其签名。
        
    5.  从Payload中获取风控评分结果。