@bingtang-rn/react-native-ssl-public-key-pinning for HarmonyOS

本项目基于 react-native-ssl-public-key-pinning 开发，为 React Native 鸿蒙（OpenHarmony）适配版本。如果在使用过程中有任何问题，可以在GitCode提Issue，会及时跟进。issue地址：issues。

版本对应关系

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 见发布记录 | 1.2.6 | 0.72+ | 是 | API17+ |

安装

npm install @bingtang-rn/react-native-ssl-public-key-pinning

使用

import {
  initializeSslPinning,
  disableSslPinning,
  addSslPinningErrorListener,
  isSslPinningAvailable,
} from 'react-native-ssl-public-key-pinning';

// 1. 初始化 pinning（域名 + 其 CA 公钥的 base64 SHA-256 哈希）
await initializeSslPinning({
  'google.com': {
    includeSubdomains: true,
    publicKeyHashes: [
      'hxqRlPTu1bMS/0DITB1SSu0vd4u/8l8TjPgfaAp63Gc=', // GTS Root R1
      'Vfd95BwDeSQo+NUYxVEEIlvkOlWY2SalKK1lPhzOx78=', // GTS Root R2
    ],
  },
});

// 2. 监听 pinning 失败事件（pin 不匹配时触发）
const subscription = addSslPinningErrorListener((error) => {
  console.warn(`Pinning failed for ${error.serverHostname}: ${error.message}`);
});

// 3. 正常发起 fetch / XMLHttpRequest，自动走 pinning 校验
const response = await fetch('https://www.google.com');

// 4. 禁用 pinning
await disableSslPinning();
subscription.remove();

import 时使用原库名 'react-native-ssl-public-key-pinning'，而非鸿蒙包名。RNOH 通过 alias 自动映射到 @bingtang-rn/react-native-ssl-public-key-pinning。

宿主配置（必须）：HarmonyOS 的 httpClient 在 RN 实例创建时注入，pinning 配置运行时由 TurboModule 设置。需在宿主 EntryAbility 中注入库导出的 SslPinningHttpClient：

import { SslPinningHttpClient } from '@bingtang-rn/react-native-ssl-public-key-pinning';

// 在 EntryAbility 中
protected override onCreateDefaultHttpClient(): HttpClient {
  return new SslPinningHttpClient();
}

平台差异：

• iOS TrustKit 强制每域至少 2 个 pin，HarmonyOS 无此限制（与 Android OkHttp 一致）
• pinning 失败事件通过 emitDeviceEvent('pinning-error', payload) 发送，payload = { serverHostname: string, message?: string }

权限要求：

• 需在 module.json5 声明 ohos.permission.INTERNET（system_grant，安装时自动授予）
• certificatePinning 功能需 HarmonyOS API17+

Link

| 版本 | 是否支持 Autolink | |------|------------------| | 当前版本 | 是 |

如使用版本支持 Autolink 且工程已接入，可跳过手动配置。

说明：本模块需要同时在 C++ 侧和 ETS 侧注册 Package。

1. Overrides RN SDK

在工程根目录 oh-package.json5 添加：

{
  "overrides": {
    "@rnoh/react-native-openharmony": "./react_native_openharmony"
  }
}

2. 引入原生端依赖

打开 entry/oh-package.json5，添加：

"dependencies": {
  "@bingtang-rn/react-native-ssl-public-key-pinning": "file:../../node_modules/@bingtang-rn/react-native-ssl-public-key-pinning/harmony/ssl_public_key_pinning.har"
}

执行 ohpm install。

3. 配置 CMakeLists

打开 entry/src/main/cpp/CMakeLists.txt，添加：

set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

add_subdirectory("${OH_MODULES}/@bingtang-rn/react-native-ssl-public-key-pinning/src/main/cpp" ./ssl_public_key_pinning)

target_link_libraries(rnoh_app PUBLIC ssl_public_key_pinning)

4. 注册 Package（C++ 侧）

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "SslPublicKeyPinningPackage.h"

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<SslPublicKeyPinningPackage>(ctx),
    };
}

5. 注册 Package（ETS 侧）

打开 entry/src/main/ets/RNPackagesFactory.ets，添加：

import { SslPublicKeyPinningPackage } from '@bingtang-rn/react-native-ssl-public-key-pinning/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new SslPublicKeyPinningPackage(ctx),
  ];
}

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | isSslPinningAvailable() | 检查 SSL Pinning 模块是否可用 | 无 | boolean | ✅ 完全支持 | | initializeSslPinning(options) | 初始化并启用 SSL 公钥绑定 | options: PinningOptions | Promise<void> | ✅ 完全支持 | | disableSslPinning() | 禁用 SSL 公钥绑定 | 无 | Promise<void> | ✅ 完全支持 | | addSslPinningErrorListener(callback) | 订阅 pinning 失败事件 | callback: (error: PinningError) => void | EmitterSubscription | ✅ 完全支持 |

平台差异

• iOS TrustKit 强制每个 pinned domain 至少 2 个 pin，HarmonyOS 无此原生限制（与 Android 一致），单 pin 也可用
• pinning 失败识别：Android 用 SSLPeerUnverifiedException + message 含 "Certificate pinning failure"，iOS 用 TSKTrustEvaluationFailedNoMatchingPin；HarmonyOS 用 @ohos.net.http 错误码 2300060 / 2300058 / 2300077 识别 SSL 证书校验失败并发送 pinning-error 事件

使用限制

• 需 HarmonyOS API17+（HttpRequestOptions.certificatePinning 自 API 12 起支持）
• 需在宿主 EntryAbility.onCreateDefaultHttpClient 注入 SslPinningHttpClient，否则 pinning 配置虽写入全局状态但不生效
• pin 格式为 base64 编码的 SHA-256 SPKI 哈希（与原库一致，无需 sha256/ 前缀，hashAlgorithm 字段已指定算法）

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18 | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 17+ |

运行步骤

1. 克隆仓库

git clone <仓库地址>
cd <仓库目录>

2. 安装依赖并构建

npm install --legacy-peer-deps
npm pack           # 生成 tgz 包（会自动触发 prepare 构建 JS 产物）

3. 进入 example 目录，安装依赖

cd example
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。

约束与限制

兼容性

• RNOH: 0.72+
• HarmonyOS SDK: API 17+
• DevEco Studio: 5.0+

遗留问题

无（或列出已知问题）

开源协议

本项目基于 MIT License，详见 LICENSE 文件。