React Native Secure Storage: Using Keychain and Keystore

Why it exists

Apps often handle sensitive data like authentication tokens or private keys. Storing this data in plaintext using a simple key-value store like AsyncStorage is a major security risk. On a rooted or jailbroken device, this data can be easily extracted. Secure storage exists to protect this data using the operating system's built-in, hardware-backed security features.

The mental model

Think of it as a specialized, secure vault provided by the operating system, not as a general-purpose database. On iOS, this is the Keychain; on Android, it's the Keystore. A library like react-native-keychain acts as a bridge, giving your JavaScript code a unified API to access these native vaults. You hand a secret to the OS, and it locks it away, often tying access to biometrics or the device passcode.

How it works

When you use a library to save a credential, it makes native calls to the underlying OS. These native services encrypt the data and store it in a protected area of the device's memory, which is often backed by a hardware security module (like the Secure Enclave on iPhones). The library abstracts away the platform-specific differences, so you can write one piece of code for both iOS and Android. To retrieve the data, the OS may require user authentication, such as a fingerprint or Face ID scan.

When to use it

Use it for small, highly sensitive pieces of information that need to be persisted securely across app sessions. This is the correct place for user authentication tokens (JWTs), refresh tokens, API keys, and cryptographic private keys. It's for anything you wouldn't want an attacker to read if they gained access to the device's file system.

When not to use it

Do not use it as a general-purpose database. It is not designed for storing large amounts of data, application state, user preferences, or cached API responses. The encryption and decryption overhead makes it significantly slower than other storage options like AsyncStorage or a local database. Using it for bulk data will harm your app's performance.

One canonical example

A wallet app like MetaMask Mobile needs to store the user's private keys. Storing them in AsyncStorage would be catastrophic. Instead, it uses react-native-keychain to save the keys to the device's native secure storage. When the user needs to sign a transaction, the app retrieves the key, and the OS may first prompt for Face ID before releasing it. This ensures the key remains protected even if the phone is lost or stolen.