HarmonyOS NEXT开发进阶（二十二）：＜network-security-config＞详解

文章目录

- 一、主要作用
- 二、配置文件位置
- 三、配置示例
- - 示例1：基础配置（允许HTTP明文通信）
  - 示例2：信任自定义CA证书
  - [示例3：证书固定（Certificate Pinning）](#示例3：证书固定（Certificate Pinning）)
  - 示例4：混合配置（生产环境推荐）
- 四、在应用中使用配置
- - [1. 修改 module.json5](#1. 修改 module.json5)
  - [2. 代码示例（使用HTTP连接）](#2. 代码示例（使用HTTP连接）)
- 五、注意事项
- 六、调试技巧

在 纯血鸿蒙（HarmonyOS NEXT） 应用开发中， <network-security-config> 是用于定义网络安全策略的配置文件，类似于Android中的同名机制。它允许开发者控制应用如何处理网络安全性，例如自定义证书信任、明文通信限制等。

一、主要作用

自定义可信证书
- 允许应用信任自定义CA证书或自签名证书，用于测试环境或内部服务器。
控制明文通信
- 配置是否允许HTTP明文传输（默认禁止），方便本地开发或测试。
证书固定（Certificate Pinning）
- 限制应用仅接受特定证书，防止中间人攻击。
调试覆盖
- 在开发阶段可临时放宽安全策略，便于调试。

二、配置文件位置

复制代码

项目目录/resources/base/profile/network_security_config.json

注意：HarmonyOS使用 JSON格式 而非Android的XML格式。

三、配置示例

示例1：基础配置（允许HTTP明文通信）

json 复制代码

{
  "networkSecurityConfig": {
    "cleartextTrafficPermitted": true,
    "domainConfigs": [
      {
        "domains": ["192.168.1.100", "localhost"],
        "cleartextTrafficPermitted": true
      }
    ]
  }
}

适用场景：开发环境连接本地HTTP服务器。

示例2：信任自定义CA证书

json 复制代码

{
  "networkSecurityConfig": {
    "trustAnchor": {
      "certificates": [
        {
          "src": "@raw/my_custom_ca"
        }
      ]
    },
    "domainConfigs": [
      {
        "domains": ["api.internal.company.com"],
        "trustAnchors": [
          {
            "certificates": [
              {
                "src": "@raw/internal_ca"
              }
            ]
          }
        ]
      }
    ]
  }
}

操作步骤：

将CA证书文件（如internal_ca.pem）放入 resources/rawfile/ 目录
在配置中通过 @raw/filename（不含扩展名）引用

示例3：证书固定（Certificate Pinning）

json 复制代码

{
  "networkSecurityConfig": {
    "domainConfigs": [
      {
        "domains": ["api.example.com"],
        "certificatePins": [
          {
            "sha256": "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
          },
          {
            "sha256": "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="
          }
        ],
        "enforcePinning": true
      }
    ]
  }
}

获取SHA256指纹命令：

bash 复制代码

openssl x509 -in certificate.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

示例4：混合配置（生产环境推荐）

json 复制代码

{
  "networkSecurityConfig": {
    "cleartextTrafficPermitted": false,
    "trustAnchors": [
      {
        "certificates": [
          {
            "src": "system"
          }
        ]
      }
    ],
    "domainConfigs": [
      {
        "domains": ["*.example.com"],
        "certificatePins": [
          {
            "sha256": "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
          }
        ]
      },
      {
        "domains": ["dev.test.com"],
        "cleartextTrafficPermitted": true,
        "trustAnchors": [
          {
            "certificates": [
              {
                "src": "@raw/dev_ca"
              }
            ]
          }
        ]
      }
    ]
  }
}

四、在应用中使用配置

1. 修改 module.json5

json 复制代码

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ],
    "securityConfiguration": {
      "path": "$profile:network_security_config"
    }
  }
}

2. 代码示例（使用HTTP连接）

typescript 复制代码

import http from '@ohos.net.http';

// 创建HTTP请求
let httpRequest = http.createHttp();
// 配置将自动应用网络安全策略

五、注意事项

生产环境安全
- 禁止开启 cleartextTrafficPermitted（除非必要）
- 使用证书固定增强关键域名安全性
证书格式
- 支持PEM格式证书
- 证书文件需为Base64编码的文本格式
域名匹配规则
- 支持通配符 *.example.com
- 子域名需单独配置
调试建议
- 为开发构建配置宽松策略
- 生产构建使用严格策略

六、调试技巧

检查配置是否生效：

typescript 复制代码

import { BusinessError } from '@ohos.base';
import http from '@ohos.net.http';

try {
  let response = await httpRequest.request('http://192.168.1.100/api');
  console.log('HTTP request successful');
} catch (error) {
  const err: BusinessError = error as BusinessError;
  console.error(`HTTP error code: ${err.code}, message: ${err.message}`);
  // 证书错误通常对应特定错误码
}

通过合理配置 <network-security-config>，可以在保证应用安全性的同时，灵活适应不同开发阶段和部署环境的需求。