react-native-keychain

react-native-keychain

react-native-keychain provides secure access to the keychain (iOS) and keystore (Android) for React Native applications. It is used to securely store and retrieve sensitive information like passwords, internet credentials, and tokens using native encryption.

Key Features:

• Biometric authentication (Face ID, Touch ID, Fingerprint)
• Passcode authentication
• Secure storage levels
• Customizable access and storage options

On iOS, values are stored using keychain services as kSecClassGenericPassword.

Key behaviors:

• Persistence: For standalone iOS apps, data stored with react-native-keychain can persist even after the app is uninstalled.
• Accessibility: You can control when a value is available to be fetched by setting the kSecAttrAccessible attribute.

Data stored via react-native-keychain survives app restarts and updates. However, be aware of the following lifecycle behaviors:

• App Uninstallation: On most platforms, stored data is erased when the app is uninstalled.
• iOS Exception: On iOS, stored data may persist even after the app is uninstalled and reinstalled due to how iOS manages keychain storage.
• Critical Data Warning: Do not use react-native-keychain as the sole source of truth for irreplaceable or critical data, as it is primarily intended for secure credential storage rather than general-purpose database persistence.

Before attempting to retrieve or overwrite credentials, use hasGenericPassword or hasInternetCredentials to verify if data is already stored. This prevents unnecessary error handling or logic for missing data.

• Use hasGenericPassword with a service identifier to check for generic credentials.
• Use hasInternetCredentials with a server identifier to check for internet-based credentials.

import Keychain from 'react-native-keychain';

const isGenericPasswordAvailable = await Keychain.hasGenericPassword({
  service: 'service_key'
});

const isInternetCredentialAvailable = await Keychain.hasInternetCredentials({
  server: 'https://google.com'
});

To use react-native-keychain in your React Native project, follow these steps:

1. Install the package using yarn:

   yarn add react-native-keychain

2. Install iOS dependencies:

   cd ios && pod install

3. Re-build your Android and iOS projects.

Note for FaceID support: If you intend to use FaceID, you must add a NSFaceIDUsageDescription entry to your Info.plist file.

On Android, react-native-keychain uses Jetpack DataStore encrypted with the Android Keystore system. You can choose between different security levels based on your sensitivity requirements:

1. High Security (with Biometric Authentication): Uses AES_GCM (symmetric) or RSA (asymmetric) encryption. This requires biometric protection and is best for passwords, personal data, or sensitive keys.
2. Medium Security (without Authentication): Uses AES_GCM_NO_AUTH (symmetric) encryption. This does not require biometric requirements and is suitable for cached or non-sensitive encrypted data.
3. Legacy/Deprecated: AES_CBC is available but is not recommended for new implementations.

To mock the entire module for all tests automatically, use the Jest __mocks__ directory pattern:

1. Create a __mocks__ directory in your project root.
2. Create a react-native-keychain folder inside __mocks__.
3. Create an index.js (or index.ts) file inside that folder containing the keychainMock object and export it using module.exports = keychainMock;.

// index.ts or index.js inside __mocks__/react-native-keychain

const keychainMock = {
  SECURITY_LEVEL: {
    SECURE_SOFTWARE: 'MOCK_SECURITY_LEVEL_SECURE_SOFTWARE',
    SECURE_HARDWARE: 'MOCK_SECURITY_LEVEL_SECURE_HARDWARE',
    ANY: 'MOCK_SECURITY_LEVEL_ANY',
  },
  // ... rest of the keychainMock object ...
};

module.exports = keychainMock;

Encryption Upgrades

The library automatically uses the highest possible encryption level when storing a secret. However, it will not automatically upgrade the encryption of an existing secret if a higher standard becomes available. To upgrade, you must re-save the secret.

Encryption Downgrades

Automatic downgrading of encryption is not supported by the library as it is considered a "loss of trust" from a security standpoint. If your application requires the ability to downgrade encryption levels, you must implement that logic manually within your application code.

Install react-native-keychain using your preferred Node.js package manager to enable secure keychain/keystore access in your React Native application.

npm install react-native-keychain

To mock the module via a global setup file:

1. In your jest.config.js, add the path to your setup file in the setupFiles array:

module.exports = {
  setupFiles: ['<rootDir>/jest.setup.js'],
};

2. In your jest.setup.js file, import your mock object and call jest.mock():

import keychainMock from './path/to/keychainMock';

jest.mock('react-native-keychain', () => keychainMock);

// jest.config.js
module.exports = {
  // ... other configurations ...
  setupFiles: ['<rootDir>/jest.setup.js'],
};

// jest.setup.js
import keychainMock from './path/to/keychainMock';

jest.mock('react-native-keychain', () => keychainMock);