文档模板：v0.4.2

本项目基于 react-native-secure-key-store 开发。

该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：@react-native-ohos/react-native-secure-key-store。版本所属关系如下：

| 三方库名称 | 三方库版本（npm地址） | 发布信息 | 支持RN版本 | 编译API版本 | 社区基线版本 | 源码地址 | | ------------ | ------------ | ------------------------------ | ------------- |------------------------ | ------------- | ------------- | | @react-native-ohos/react-native-secure-key-store | ~ 2.1.0 | Gitcode Releases | 0.77.* | API12+ | 2.0.10 | master | | @react-native-ohos/react-native-secure-key-store | <=2.0.11 | Gitcode Releases | 0.72.* | API12+ | 2.0.10 | br_rnoh0.72 |

简介

react-native-secure-key-store 是一个用于在 iOS、Android 和鸿蒙设备上安全存储密钥的 React Native 库，分别基于 KeyChain、KeyStore 和 HUKS 实现。

在鸿蒙平台上，密钥通过 HUKS（HarmonyOS Universal KeyStore）使用 AES-256-GCM 加密，密文经 preferences 持久化，提供设备级安全存储。

下载安装

进入到工程目录并输入以下命令：

npm

npm install @react-native-ohos/react-native-secure-key-store

yarn

yarn add @react-native-ohos/react-native-secure-key-store

Link

| | 是否支持autolink | RN框架版本 | |--------------------------------------|-----------------|------------| | ~2.1.0 | 否 | 0.77 |

首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony。

1. 在工程根目录的 oh-package.json5 添加 overrides 字段

{
  ...
  "overrides": {
    "@rnoh/react-native-openharmony" : "file:./../node_modules/react-native-harmony/react_native_openharmony.har"
  }
}

2. 引入原生端代码

方法（推荐）：通过 har 包引入。

[!TIP] har 包位于三方库安装路径下的 harmony 文件夹中。

打开 entry/oh-package.json5，添加以下依赖：

"dependencies": {
    "@rnoh/react-native-openharmony": "file:../../node_modules/react-native-harmony/react_native_openharmony.har",
    "@react-native-ohos/react-native-secure-key-store": "file:../../node_modules/@react-native-ohos/react-native-secure-key-store/harmony/secure_key_store.har"
}

点击右上角的 sync 按钮，或者在终端执行：

cd entry
ohpm install

3. 配置 CMakeLists 和引入 RTNSecureKeyStorePackage

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

# RNOH_BEGIN: manual_package_linking_1
+ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-secure-key-store/src/main/cpp" ./secure_key_store)
# RNOH_END: manual_package_linking_1

# RNOH_BEGIN: manual_package_linking_2
+ target_link_libraries(rnoh_app PUBLIC rnoh_secure_key_store)
# RNOH_END: manual_package_linking_2

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

#include "RNOH/PackageProvider.h"
#include "generated/RNOHGeneratedPackage.h"
+ #include "RTNSecureKeyStorePackage.h"

using namespace rnoh;

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

4. 在 ArkTs 侧引入 RNSecureKeyStorePackage

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

import type {RNPackageContext, RNPackage} from '@rnoh/react-native-openharmony/ts';
+ import {RNSecureKeyStorePackage} from '@react-native-ohos/react-native-secure-key-store/ts';

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

5. 运行

点击右上角的 sync 按钮

或者在终端执行：

cd entry
ohpm install

然后编译、运行即可。

约束与限制

兼容性

本文档内容基于以下环境验证通过：

1. RNOH: 0.77.18-1；SDK: HarmonyOS 5.0.0(12)；IDE: DevEco Studio；RN: 0.77.1；

权限要求

HUKS 与 preferences 在应用沙箱内运行，无需额外权限，仅需 ohos.permission.INTERNET（仅 Metro 热更新需要）。

使用示例

下面的代码展示了这个库的基本使用场景：

[!WARNING] 使用时 import 的库名不变（react-native-secure-key-store）。

import RNSecureKeyStore, {ACCESSIBLE} from "react-native-secure-key-store";

// 存储密钥
RNSecureKeyStore.set("key1", "value1", {accessible: ACCESSIBLE.ALWAYS_THIS_DEVICE_ONLY})
  .then((res) => {
    console.log(res);
  })
  .catch((err) => {
    console.log(err);
  });

// 获取密钥
RNSecureKeyStore.get("key1")
  .then((res) => {
    console.log(res);
  })
  .catch((err) => {
    console.log(err);
  });

// 删除密钥
RNSecureKeyStore.remove("key1")
  .then((res) => {
    console.log(res);
  })
  .catch((err) => {
    console.log(err);
  });

// 关闭应用卸载时重置存储
RNSecureKeyStore.setResetOnAppUninstallTo(false);

接口说明

[!TIP] "Platform"列表示该属性在原三方库上支持的平台。

[!TIP] "鸿蒙平台支持"列为 yes 表示鸿蒙平台支持该属性；no 则表示不支持。使用方法跨平台一致，效果对标 iOS / Android 的效果。

API

| 名称 | 类型 | 参数类型 | 返回值 | 必填 | 平台 | 鸿蒙平台支持 | 描述 | |--------|---------|-----|-------|-------|--------|-----|-----------------| | set | function | key: string, value: string, options?: { accessible?: ACCESSIBLE } | Promise<string> | 是 | iOS,Android | yes | 加密并存储键值对。accessible 为 iOS 专属属性，鸿蒙侧为接口对齐保留（实际无效）。 | | get | function | key: string | Promise<string> | 是 | iOS,Android | yes | 取回并解密指定键的值。键不存在时以 code 404 reject。 | | remove | function | key: string | Promise<string> | 是 | iOS,Android | yes | 删除已存储的键。无法删除时以 code 6 reject。 | | setResetOnAppUninstallTo | function | enabled: boolean | void | 否 | iOS | yes | 设置应用卸载时是否重置安全存储。在鸿蒙侧镜像 iOS Keychain 卸载重置行为。 |

ACCESSIBLE 枚举

| 键 | 描述 | | --- | --- | | WHEN_UNLOCKED | 数据仅在设备解锁时可访问。 | | AFTER_FIRST_UNLOCK | 重启后首次解锁前不可访问。 | | ALWAYS | 无论设备是否锁定均可访问。 | | WHEN_PASSCODE_SET_THIS_DEVICE_ONLY | 仅解锁时可访问；需设密码；不迁移到新设备。 | | WHEN_UNLOCKED_THIS_DEVICE_ONLY | 仅解锁时可访问；不迁移到新设备。 | | AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY | 首次解锁后可访问；不迁移到新设备。 | | ALWAYS_THIS_DEVICE_ONLY | 始终可访问；不迁移到新设备。 |

注：ACCESSIBLE 取值为 iOS 专属属性，用于接口对齐。在鸿蒙侧所有取值行为一致（基于 HUKS 的安全存储）。

遗留问题

其他

无

目录结构

/react-native-secure-key-store        # 项目根目录
├── harmony                           # 鸿蒙适配代码
│   ├─ secure_key_store.har           # har 包
│   └─ secure_key_store               # 鸿蒙适配核心代码
│         ├─ BuildProfile.ets          # 构建配置
│         ├─ ts.ts                    # 类型导出
│         ├─ oh-package.json5         # 鸿蒙模块包配置
│         ├─ build-profile.json5      # 鸿蒙模块构建配置
│         ├─ hvigorfile.ts            # 鸿蒙模块构建脚本
│         └─ src/main
│             ├─ module.json5         # 鸿蒙模块声明
│             ├─ cpp
│             │   ├─ CMakeLists.txt   # C++ 构建配置
│             │   ├─ RTNSecureKeyStorePackage.h  # 包封装头文件
│             │   └─ generated        # Codegen 生成
│             ├─ ets
│             │   ├─ index.ets               # 鸿蒙适配代码入口
│             │   ├─ RNSecureKeyStorePackage.ts   # ArkTS 包封装
│             │   └─ RNSecureKeyStoreTurboModule.ts # 原生 TurboModule（HUKS）
├── src                               # RN 源码 / TurboModule 规格
│   └─ NativeRNSecureKeyStore.ts      # TurboModule 规格
├── example                           # 鸿蒙示例工程
├── README_en.md                      # 英文说明文档
└── README.md                         # 中文说明文档

贡献代码

使用过程中发现任何问题都可以提交 Issue，当然，也非常欢迎提交 PR。

开源协议

本项目基于 ISC License，请自由地享受和参与开源。