react-native-keychain-manager

Keychain/Keystore Access for React Native

• Keychain/Keystore Access for React Native
  • Installation
  • Usage
  • API
    • setGenericPassword(username, password, [{ accessControl, accessible, accessGroup, service, securityLevel }])
    • hasGenericPassword([{ service }])
    • getGenericPassword([{ authenticationPrompt, service, accessControl }])
    • resetGenericPassword([{ service }])
    • getAllGenericPasswordServices()
    • setInternetCredentials(server, username, password, [{ accessControl, accessible, accessGroup, securityLevel }])
    • hasInternetCredentials(server)
    • getInternetCredentials(server, [{ authenticationPrompt }])
    • resetInternetCredentials(server)
    • requestSharedWebCredentials() (iOS and visionOS only)
    • setSharedWebCredentials(server, username, password) (iOS and visionOS only)
    • canImplyAuthentication([{ authenticationType }]) (iOS and visionOS only)
    • getSupportedBiometryType()
    • getSecurityLevel([{ accessControl }]) (Android only)
    • Options
      • Data Structure Properties/Fields
        • authenticationPrompt Properties
      • Keychain.ACCESS_CONTROL enum
      • Keychain.ACCESSIBLE enum
      • Keychain.AUTHENTICATION_TYPE enum
      • Keychain.BIOMETRY_TYPE enum
      • Keychain.SECURITY_LEVEL enum (Android only)
      • Keychain.STORAGE_TYPE enum (Android only)
      • Keychain.SECURITY_RULES enum (Android only)
  • Important Behavior
    • Rule 1: Automatic Security Level
  • Manual Installation
    • iOS
      • Option: Manually
      • Option: With CocoaPods
      • Enable Keychain Sharing entitlement for iOS 10+
    • Android
      • Option: Manually
      • Proguard Rules
  • Unit Testing with Jest
    • Using a Jest __mocks__ Directory
    • Using a Jest Setup File
  • Notes
    • Android Notes
      • Configuring the Android-specific behavior
    • iOS Notes
    • macOS Catalyst
    • visionOS
    • Security

Installation

1. Run yarn add react-native-keychain-manager

   1 a. Only for React Native <= 0.59: $ react-native link react-native-keychain-manager and check MainApplication.java to verify the package was added. See manual installation below if you have issues with react-native link.

2. Run pod install in ios/ directory to install iOS dependencies.

3. If you want to support FaceID, add a NSFaceIDUsageDescription entry in your Info.plist.

4. Re-build your Android and iOS projects.

Usage

1import * as Keychain from 'react-native-keychain-manager';
2
3async () => {
4  const username = 'zuck';
5  const password = 'poniesRgr8';
6
7  // Store the credentials
8  await Keychain.setGenericPassword(username, password);
9
10  try {
11    // Retrieve the credentials
12    const credentials = await Keychain.getGenericPassword();
13    if (credentials) {
14      console.log(
15        'Credentials successfully loaded for user ' + credentials.username
16      );
17    } else {
18      console.log('No credentials stored');
19    }
20  } catch (error) {
21    console.log("Keychain couldn't be accessed!", error);
22  }
23  await Keychain.resetGenericPassword();
24};

See KeychainExample for fully working project example.

Both setGenericPassword and setInternetCredentials are limited to strings only, so if you need to store objects etc, please use JSON.stringify/JSON.parse when you store/access it.

API

setGenericPassword(username, password, [{ accessControl, accessible, accessGroup, service, securityLevel }])

Will store the username/password combination in the secure storage. Resolves to {service, storage} or rejects in case of an error. storage - is a name of used internal cipher for saving secret; service - name used for storing secret in internal storage (empty string resolved to valid default name).

hasGenericPassword([{ service }])

Will check if the username/password combination is available for service in the secure storage. Resolves to true if an entry exists or false if it doesn't.

getGenericPassword([{ authenticationPrompt, service, accessControl }])

Will retrieve the username/password combination from the secure storage. Resolves to { username, password, service, storage } if an entry exists or false if it doesn't. It will reject only if an unexpected error is encountered like lacking entitlements or permission.

resetGenericPassword([{ service }])

Will remove the username/password combination from the secure storage. Resolves to true in case of success.

getAllGenericPasswordServices()

Will retrieve all known service names for which a generic password has been stored (e.g., setGenericPassword).

Note: on iOS this will actully read the encrypted entries, so it will trigger an authentication UI if you have encrypted any entries with password/biometry.

setInternetCredentials(server, username, password, [{ accessControl, accessible, accessGroup, securityLevel }])

Will store the server/username/password combination in the secure storage. Resolves to { username, password, service, storage };

hasInternetCredentials(server)

Will check if the username/password combination for server is available in the secure storage. Resolves to true if an entry exists or false if it doesn't.

getInternetCredentials(server, [{ authenticationPrompt }])

Will retrieve the server/username/password combination from the secure storage. Resolves to { username, password } if an entry exists or false if it doesn't. It will reject only if an unexpected error is encountered like lacking entitlements or permission.

resetInternetCredentials(server)

Will remove the server/username/password combination from the secure storage.

requestSharedWebCredentials() (iOS and visionOS only)

Asks the user for a shared web credential. Requires additional setup both in the app and server side, see Apple documentation. Resolves to { server, username, password } if approved and false if denied and throws an error if not supported on platform or there's no shared credentials.

setSharedWebCredentials(server, username, password) (iOS and visionOS only)

Sets a shared web credential. Resolves to true when successful.

canImplyAuthentication([{ authenticationType }]) (iOS and visionOS only)

Inquire if the type of local authentication policy is supported on this device with the device settings the user chose. Should be used in combination with accessControl option in the setter functions. Resolves to true if supported.

getSupportedBiometryType()

On iOS and visionOS: Get what type of hardware biometry support the device can use for biometric encryption. Resolves to a Keychain.BIOMETRY_TYPE value when supported and enrolled, otherwise null.

On Android: Get what type of Class 3 (strong) biometry support the device has. Resolves to a Keychain.BIOMETRY_TYPE value when supported, otherwise null. In most devices this will return FINGERPRINT (except for Pixel 4 or similar where fingerprint sensor is not present).

This method returns null, if the device haven't enrolled into fingerprint/FaceId. Even though it has hardware for it.

getSecurityLevel([{ accessControl }]) (Android only)

Get security level that is supported on the current device with the current OS. Resolves to Keychain.SECURITY_LEVEL enum value.

Options

Data Structure Properties/Fields

Key	Platform	Description	Default
accessControl	All	This dictates how a keychain item may be used, see possible values in Keychain.ACCESS_CONTROL.	None
accessible	iOS, visionOS	This dictates when a keychain item is accessible, see possible values in Keychain.ACCESSIBLE.	Keychain.ACCESSIBLE.WHEN_UNLOCKED
accessGroup	iOS, visionOS	In which App Group to share the keychain. Requires additional setup with entitlements.	None
authenticationPrompt	All	What to prompt the user when unlocking the keychain with biometry or device password.	See authenticationPrompt Properties
authenticationType	iOS, visionOS	Policies specifying which forms of authentication are acceptable.	Keychain.AUTHENTICATION_TYPE.DEVICE_PASSCODE_OR_BIOMETRICS
service	All	Reverse domain name qualifier for the service associated with password.	App bundle ID
storage	Android only	Force specific cipher storage usage during saving the password	Select best available storage
rules	Android only	Force following to a specific security rules	Keychain.RULES.AUTOMATIC_UPGRADE

authenticationPrompt Properties

Key	Platform	Description	Default
title	All	Title of the authentication prompt when requesting a stored secret.	Authenticate to retrieve secret
subtitle	Android only	Subtitle of the Android authentication prompt when requesting a stored secret.	None. Optional
description	Android only	Description of the Android authentication prompt when requesting a stored secret.	None. Optional
cancel	Android only	Negative button text of the Android authentication prompt when requesting a stored secret.	Cancel

Keychain.ACCESS_CONTROL enum

Key	Description
USER_PRESENCE	Constraint to access an item with either Touch ID or passcode.
BIOMETRY_ANY	Constraint to access an item with Touch ID for any enrolled fingers.
BIOMETRY_CURRENT_SET	Constraint to access an item with Touch ID for currently enrolled fingers.
DEVICE_PASSCODE	Constraint to access an item with a passcode.
APPLICATION_PASSWORD	Constraint to use an application-provided password for data encryption key generation.
BIOMETRY_ANY_OR_DEVICE_PASSCODE	Constraint to access an item with Touch ID for any enrolled fingers or passcode.
BIOMETRY_CURRENT_SET_OR_DEVICE_PASSCODE	Constraint to access an item with Touch ID for currently enrolled fingers or passcode.

Note #1: BIOMETRY_ANY, BIOMETRY_CURRENT_SET, BIOMETRY_ANY_OR_DEVICE_PASSCODE, BIOMETRY_CURRENT_SET_OR_DEVICE_PASSCODE - recognized by Android as a requirement for Biometric enabled storage (Till we got a better implementation);

Note #2: For Android we support only two states: None (default) and Fingerprint (use only biometric protected storage); Face recognition fails with "User not authenticated" exception, see issue #318

Refs:

• https://developer.apple.com/documentation/security/secaccesscontrolcreateflags?language=objc

Keychain.ACCESSIBLE enum

Key	Description
WHEN_UNLOCKED	The data in the keychain item can be accessed only while the device is unlocked by the user.
AFTER_FIRST_UNLOCK	The data in the keychain item cannot be accessed after a restart until the device has been unlocked once by the user.
ALWAYS	The data in the keychain item can always be accessed regardless of whether the device is locked.
WHEN_PASSCODE_SET_THIS_DEVICE_ONLY	The data in the keychain can only be accessed when the device is unlocked. Only available if a passcode is set on the device. Items with this attribute never migrate to a new device.
WHEN_UNLOCKED_THIS_DEVICE_ONLY	The data in the keychain item can be accessed only while the device is unlocked by the user. Items with this attribute do not migrate to a new device.
AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY	The data in the keychain item cannot be accessed after a restart until the device has been unlocked once by the user. Items with this attribute never migrate to a new device.

Refs:

• https://developer.apple.com/documentation/security/ksecattraccessiblewhenunlocked

Keychain.AUTHENTICATION_TYPE enum

Key	Description
DEVICE_PASSCODE_OR_BIOMETRICS	Device owner is going to be authenticated by biometry or device passcode.
BIOMETRICS	Device owner is going to be authenticated using a biometric method (Touch ID or Face ID).

Refs:

• https://developer.apple.com/documentation/localauthentication/lapolicy

Keychain.BIOMETRY_TYPE enum

Key	Description
TOUCH_ID	Device supports authentication with Touch ID. (iOS only)
FACE_ID	Device supports authentication with Face ID. (iOS only)
OPTIC_ID	Device supports authentication with Optic ID. (visionOS only)
FINGERPRINT	Device supports authentication with Fingerprint. (Android only)
FACE	Device supports authentication with Face Recognition. (Android only)
IRIS	Device supports authentication with Iris Recognition. (Android only)

Refs:

• https://developer.apple.com/documentation/localauthentication/labiometrytype?language=objc

Keychain.SECURITY_LEVEL enum (Android only)

If set, securityLevel parameter specifies minimum security level that the encryption key storage should guarantee for storing credentials to succeed.

Key	Description
ANY	no security guarantees needed (default value); Credentials can be stored in FB Secure Storage;
SECURE_SOFTWARE	requires for the key to be stored in the Android Keystore, separate from the encrypted data;
SECURE_HARDWARE	requires for the key to be stored on a secure hardware (Trusted Execution Environment or Secure Environment). Read this article for more information.

Keychain.STORAGE_TYPE enum (Android only)

Key	Description
FB	Facebook compatibility cipher
AES	Encryptions without human interaction.
RSA	Encryption with biometrics.

Keychain.SECURITY_RULES enum (Android only)

Key	Description
NONE	No rules. Be dummy, developer control everything
AUTOMATIC_UPGRADE	Upgrade secret to the best available storage as soon as it is available and user request secret extraction. Upgrade not applied till we request the secret. This rule only applies to secrets stored with FacebookConseal.

Important Behavior

Rule 1: Automatic Security Level

As a rule the library will try to apply the best possible encryption for storing secrets. Once the secret is stored however its does not try to upgrade it unless FacebookConseal was used and the option 'SECURITY_RULES' is set to 'AUTOMATIC_UPGRADE'

---

Q: What will happen if user disables/drops biometric usage?

A: User will lose ability to extract secret from storage. On re-enable biometric access to the secret will be possible again.

---

Q: Is it possible to implement automatic downgrading?

A: From security perspective any Automatic downgrading is treated as "a loss of the trust" point. Developer should implement own logic to allow downgrade and deal with "security loss". (My recommendation - never do that!)

---

Q: How to enable automatic upgrade for FacebookConseal?

A: Do call getGenericPassword({ ...otherProps, rules: "AUTOMATIC_UPGRADE" }) with extra property rules set to AUTOMATIC_UPGRADE string value.

---

Q: How to force a specific level of encryption during saving the secret?

A: Do call setGenericPassword({ ...otherProps, storage: "AES" }) with forced storage.

Note: attempt to force storage RSA when biometrics is not available will force code to reject call with errors specific to device biometric configuration state.

Manual Installation

iOS

Option: Manually

• Right click on Libraries, select Add files to "…" and select node_modules/react-native-keychain-manager/RNKeychainManager.xcodeproj
• Select your project and under Build Phases -> Link Binary With Libraries, press the + and select libRNKeychainManager.a.
• make sure pod 'RNKeychainManager' is not in your Podfile

Option: With CocoaPods

Add the following to your Podfile and run pod update:

pod 'RNKeychainManager', :path => '../node_modules/react-native-keychain-manager'

Enable Keychain Sharing entitlement for iOS 10+

For iOS 10 you'll need to enable the Keychain Sharing entitlement in the Capabilities section of your build target. (See screenshot). Otherwise you'll experience the error shown below.

Error: {
  code = "-34018";
  domain = NSOSStatusErrorDomain;
  message = "The operation couldn\U2019t be completed. (OSStatus error -34018.)";
}

Android

Option: Manually

• Edit android/settings.gradle to look like this (without the +):

1rootProject.name = 'MyApp'
2
3include ':app'
4
5+ include ':react-native-keychain-manager'
6+ project(':react-native-keychain-manager').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-keychain-manager/android')

• Edit android/app/build.gradle (note: app folder) to look like this:

1apply plugin: 'com.android.application'
2
3android {
4  ...
5}
6
7dependencies {
8  implementation fileTree(dir: 'libs', include: ['*.jar'])
9  implementation 'com.android.support:appcompat-v7:23.0.1'
10  implementation 'com.facebook.react:react-native:0.19.+'
11+ implementation project(':react-native-keychain-manager')
12}

• Edit your MainApplication.java (deep in android/app/src/main/java/...) to look like this (note two places to edit):

1package com.myapp;
2
3+ import com.dorianmazur.keychain.KeychainPackage;
4
5....
6
7public class MainActivity extends extends ReactActivity {
8
9  @Override
10  protected List<ReactPackage> getPackages() {
11      return Arrays.<ReactPackage>asList(
12              new MainReactPackage(),
13+             new KeychainPackage()
14      );
15  }
16  ...
17}

Proguard Rules

On Android builds that use proguard (like release), you may see the following error:

RNKeychainManager: no keychain entry found for service:
JNI DETECTED ERROR IN APPLICATION: JNI FindClass called with pending exception java.lang.NoSuchFieldError: no "J" field "mCtxPtr" in class "Lcom/facebook/crypto/cipher/NativeGCMCipher;" or its superclasses

If so, add a proguard rule in proguard-rules.pro:

-keep class com.facebook.crypto.** {
   *;
}

Unit Testing with Jest

The keychain manager relies on interfacing with the native application itself. As such, it does not successfully compile and run in the context of a Jest test, where there is no underlying app to communicate with. To be able to call the JS functions exposed by this module in a unit test, you should mock them in one of the following two ways:

First, let's create a mock object for the module:

1const keychainMock = {
2  SECURITY_LEVEL_ANY: "MOCK_SECURITY_LEVEL_ANY",
3  SECURITY_LEVEL_SECURE_SOFTWARE: "MOCK_SECURITY_LEVEL_SECURE_SOFTWARE",
4  SECURITY_LEVEL_SECURE_HARDWARE: "MOCK_SECURITY_LEVEL_SECURE_HARDWARE",
5  setGenericPassword: jest.fn().mockResolvedValue(),
6  getGenericPassword: jest.fn().mockResolvedValue(),
7  resetGenericPassword: jest.fn().mockResolvedValue(),
8  ...
9}

Using a Jest __mocks__ Directory

1. Read the jest docs for initial setup

2. Create a react-native-keychain-manager folder in the __mocks__ directory and add index.js file in it. It should contain the following code:

1export default keychainMock;

Using a Jest Setup File

1. In your Jest config, add a reference to a setup file

2. Inside your setup file, set up mocking for this package:

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

Now your tests should run successfully, though note that writing and reading to the keychain will be effectively a no-op.

Notes

Android Notes

The module will automatically use the appropriate CipherStorage implementation based on API level:

• API level 16-22 will en/de crypt using Facebook Conceal
• API level 23+ will en/de crypt using Android Keystore

Encrypted data is stored in DataStore Preferences.

The setInternetCredentials(server, username, password) call will be resolved as call to setGenericPassword(username, password, server). Use the server argument to distinguish between multiple entries.

Configuring the Android-specific behavior

Android implementation has behavioural specifics incurred by existing inconsistency between implementations by different vendors. E.g., some Samsung devices show very slow startup of crypto system. To alleviate this, a warm-up strategy is introduced in Android implementation of this library.

Using default constructor you get default behaviour, i.e. with the warming up on.

1    private List<ReactPackage> createPackageList() {
2      return Arrays.asList(
3        ...
4        new KeychainPackage(),  // warming up is ON
5        ...
6      )
7

Those who want finer control are required to use constructor with a builder which can be configured as they like:

1    private List<ReactPackage> createPackageList() {
2      return Arrays.asList(
3        ...
4        new KeychainPackage(
5                new KeychainModuleBuilder()
6                        .withoutWarmUp()),   // warming up is OFF
7        ...
8      )

iOS Notes

If you need Keychain Sharing in your iOS extension, make sure you use the same App Group and Keychain Sharing group names in your Main App and your Share Extension. To then share the keychain between the Main App and Share Extension, use the accessGroup and service option on setGenericPassword and getGenericPassword, like so: getGenericPassword({ accessGroup: 'group.appname', service: 'com.example.appname' })

Refs:

• https://developer.apple.com/documentation/localauthentication
• https://developer.apple.com/documentation/security

macOS Catalyst

This package supports macOS Catalyst.

visionOS

This package supports visionOS.

Security

On API levels that do not support Android keystore, Facebook Conceal is used to en/decrypt stored data. The encrypted data is then stored in DataStore Preferences. Since Conceal itself stores its encryption key in DataStore Preferences, it follows that if the device is rooted (or if an attacker can somehow access the filesystem), the key can be obtained and the stored data can be decrypted. Therefore, on such a device, the conceal encryption is only an obscurity. On API level 23+ the key is stored in the Android Keystore, which makes the key non-exportable and therefore makes the entire process more secure. Follow best practices and do not store user credentials on a device. Instead use tokens or other forms of authentication and re-ask for user credentials before performing sensitive operations.

• Android authentication
• Android Cipher
• Android Protected Confirmation