React Native Keychain 使用指南：安全存储与凭证管理-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00315/article/details/148578461

React Native Keychain 使用指南：安全存储与凭证管理

react-native-keychain :key: Keychain Access for React Native 项目地址: https://gitcode.com/gh_mirrors/re/react-native-keychain

前言

在现代移动应用开发中，安全存储用户凭证（如用户名、密码等敏感信息）是至关重要的基础功能。react-native-keychain 是一个专为 React Native 设计的原生模块，它提供了跨平台的安全凭证存储解决方案，能够充分利用 iOS 的 Keychain 服务和 Android 的 Keystore 系统。本文将深入解析该库的核心功能和使用方法。

基础使用

安装与导入

首先确保已正确安装该库，然后在代码中导入：

import * as Keychain from 'react-native-keychain';

基本操作流程

该库的核心功能围绕三个基本操作展开：

存储凭证：使用 setGenericPassword 方法
获取凭证：使用 getGenericPassword 方法
删除凭证：使用 resetGenericPassword 方法

// 存储凭证示例
const storeCredentials = async (username, password) => {
  try {
    await Keychain.setGenericPassword(username, password);
    console.log('凭证存储成功');
  } catch (error) {
    console.error('存储失败:', error);
  }
};

// 获取凭证示例
const retrieveCredentials = async () => {
  try {
    const credentials = await Keychain.getGenericPassword();
    if (credentials) {
      console.log('获取到的用户名:', credentials.username);
      return credentials;
    }
    console.log('无存储的凭证');
    return null;
  } catch (error) {
    console.error('获取失败:', error);
    throw error;
  }
};

// 删除凭证示例
const clearCredentials = async () => {
  try {
    await Keychain.resetGenericPassword();
    console.log('凭证已清除');
  } catch (error) {
    console.error('清除失败:', error);
  }
};

数据类型注意事项

重要提示：该库仅支持字符串类型的存储。如需存储复杂对象，需先进行序列化：

// 存储对象
const userData = { id: 123, token: 'abc123' };
await Keychain.setGenericPassword('user', JSON.stringify(userData));

// 读取对象
const credentials = await Keychain.getGenericPassword();
if (credentials) {
  const parsedData = JSON.parse(credentials.password);
  console.log(parsedData.token); // 输出: abc123
}

进阶功能

多凭证管理

对于需要存储多组凭证的场景，可以使用 server 参数作为区分标识：

// 存储不同服务的凭证
await Keychain.setInternetCredentials(
  'api.example.com',
  'user1',
  'password123'
);

await Keychain.setInternetCredentials(
  'auth.example.com',
  'user2',
  'password456'
);

// 获取特定服务的凭证
const apiCreds = await Keychain.getInternetCredentials('api.example.com');
const authCreds = await Keychain.getInternetCredentials('auth.example.com');

Android 平台特性

加密策略

该库会根据 Android 设备的 API 级别自动选择最佳加密方案：

API 16-22：使用 Facebook 的 Conceal 库
API 23+：使用 Android Keystore 系统

加密后的数据存储在 SharedPreferences 中。

性能优化

某些 Android 设备（特别是三星）的加密系统初始化较慢。库提供了预热机制：

// 默认启用预热（推荐）
new KeychainPackage();

// 如需禁用预热
new KeychainPackage(
  new KeychainModuleBuilder()
    .withoutWarmUp()
);

iOS 平台特性

应用间共享 Keychain

要在主应用和扩展（如 Share Extension）间共享 Keychain：

确保使用相同的 App Group 和 Keychain Sharing 组名
调用方法时指定相关参数：

// 设置共享凭证
await Keychain.setGenericPassword(username, password, {
  accessGroup: 'group.your.app',
  service: 'com.your.app.service'
});

// 获取共享凭证
const credentials = await Keychain.getGenericPassword({
  accessGroup: 'group.your.app',
  service: 'com.your.app.service'
});