文档模板：v0.4.2

react-native-secure-key-store

本项目基于 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

ManualLink：此步骤为手动配置原生依赖项的指导

首先需要使用 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 包引入。

打开 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 热更新需要）。

使用示例

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

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);

接口说明

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，请自由地享受和参与开源。