react-native-crypto-vault

react-native-crypto-vault is a secure, cross-platform library for managing cryptographic keys, encrypting/decrypting sensitive data, and handling vault-based key policies in React Native.

It is designed to provide developer-friendly APIs while enforcing best security practices.

Motivation

Mobile applications often need to store highly sensitive data, including:

• Authentication tokens and API keys
• Payment or banking credentials
• User passwords, PINs, or personal secrets

Existing solutions are often:

• Exposing keys in memory or logs
• Requiring complex, unsafe handling of keys
• Platform-specific with no unified API

We built react-native-crypto-vault to provide a secure, cross-platform, and developer-friendly interface for handling cryptographic operations in React Native.

Security Design

Cryptographic Choices

| Algorithm | Purpose | | ----------------- | ----------------------------------------------------------------------------------------------- | | AES-GCM (256-bit) | Fast symmetric encryption with authenticated encryption, protecting confidentiality & integrity | | HMAC-SHA256 | Ensures message integrity and authenticity when combined with AES-GCM or used independently | | SHA-256 | Secure one-way hash for passwords, PINs, or sensitive string data | | SecureRandom | Cryptographically secure generation of salts, IVs, and random keys |

Design Principles

• Keys are never exported in plaintext
• AES-GCM uses random IVs per encryption
• HMAC ensures authenticated encryption (detects tampering)
• Each key has a unique alias, preventing accidental overwrites
• Vault supports PIN or biometric unlocking (future enhancements)

Features

Key Management

• Generate and store AES keys securely in Android Keystore / iOS Keychain
• Retrieve stored keys via a unique alias
• Automatic key generation if key does not exist
• Future support for backup and restore

Encryption / Decryption

• AES-GCM encryption using 256-bit keys
• AES-GCM decryption returns original plaintext securely
• Optional combination with HMAC for authenticated encryption

Hashing & Signing

• SHA-256 hashing for strings or messages
• HMAC-SHA256 signing using secure keys for message integrity

Random Data Generation

• Generate cryptographically secure random bytes
• Generate UUIDs for unique identifiers

Vault Policies (Future Features)

• Lock/unlock vault with PIN, biometric, or none
• Auto-lock after inactivity
• Backup & restore vault securely

Installation

npm install react-native-crypto-vault
# or
yarn add react-native-crypto-vault

Compatibility: React Native >=0.70 and New Architecture (TurboModules)

** Android

Uses Android Keystore automatically

No extra configuration required

iOS

Uses iOS Keychain

Enable Keychain entitlements if necessary **

1. Generate a Secure Key

import CryptoVault from 'react-native-crypto-vault';

const alias = 'my_app_aes_key';

// Generates key if not exists, returns key alias
await CryptoVault.generateSecureKey(alias);
console.log('Secure key generated:', alias);

2. AES-GCM Encryption / Decryption

const plainText = 'Hello Secret';

// Encrypt
const cipherText = await CryptoVault.aesGcmEncrypt(plainText, alias);
console.log('Encrypted:', cipherText);

// Decrypt
const decrypted = await CryptoVault.aesGcmDecrypt(cipherText, alias);
console.log('Decrypted:', decrypted); // "Hello Secret"

Security Note: AES-GCM uses random IV per encryption to prevent repeated patterns.

3. SHA-256 Hashing

const hash = await CryptoVault.hashString('my secret');
console.log('SHA-256 Hash:', hash);
Use Case: Storing hashed passwords or verifying message integrity.

4. HMAC-SHA256 Signing

const message = 'message-to-sign';
const hmac = await CryptoVault.hmacSHA256(message, alias);
console.log('HMAC:', hmac);
Security Purpose: Authenticate messages and prevent tampering.

5. AES-GCM + HMAC (Authenticated Encryption)

const randomKey = await CryptoVault.getRandomBytes(32);
const encrypted = await CryptoVault.aesGcmEncryptWithHmac('secure-message', randomKey);
const decryptedMessage = await CryptoVault.aesGcmDecryptWithHmac(encrypted, randomKey);

console.log('Decrypted Message:', decryptedMessage); // "secure-message"
Benefit: Ensures both confidentiality and integrity in one operation.

6. Vault Utilities

// Get unique device ID
const deviceId = await CryptoVault.getDeviceInfo();
console.log('Device ID:', deviceId);

// Generate random UUID
const uuid = await CryptoVault.getRandomId();
console.log('Random UUID:', uuid);

7. Encrypt / Decrypt Data

//Use AES-GCM (with optional HMAC) to encrypt sensitive data:
const cipherText = await CryptoVault.aesGcmEncrypt('Hello', alias);
const plainText = await CryptoVault.aesGcmDecrypt(cipherText, alias);

8. Backup & Restore Keys

///You can export keys securely in Base64 and restore them later:

const backup = await CryptoVault.backupKey(alias);
await CryptoVault.restoreKey(alias + '_restored', backup);

9. Vault Locking / Unlocking

///Depending on policy, lock or unlock the vault:
await CryptoVault.lockVault();
const locked = await CryptoVault.isVaultLocked();
await CryptoVault.unlockVault(''); // policy NONE does not require data

7. Simple Connectivity

console.log(await CryptoVault.ping()); // "pong"
console.log(await CryptoVault.echo('hello')); // "hello"

API Reference (Detailed)

| Method | Parameters | Returns | Description & Flow Notes | | | | | ---------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | --------------- | ----------------------------------------------- | | generateSecureKey(alias) | alias: string | Promise<string> | Generates or retrieves a secure key. Must call before encryption/decryption | | | | | aesGcmEncrypt(plainText, alias) | plainText: string, alias: string | Promise<string> | AES-GCM encrypts plaintext. Requires key generated | | | | | aesGcmDecrypt(cipherText, alias) | cipherText: string, alias: string | Promise<string> | AES-GCM decrypts ciphertext. Requires key generated | | | | | aesGcmEncryptWithHmac(plainText, keyBase64) | plainText: string, keyBase64 | Promise<string> | Authenticated encryption. Requires Base64 key | | | | | aesGcmDecryptWithHmac(cipherTextBase64, keyBase64) | cipherTextBase64: string, keyBase64 | Promise<string> | Authenticated decryption. Requires Base64 key | | | | | backupKey(alias) | alias: string | Promise<string> | Exports key as Base64; key must exist | | | | | restoreKey(alias, backupBlob) | alias: string, backupBlob: string | Promise<void> | Restores key from Base64 backup | | | | | lockVault() | - | Promise<void> | Locks vault; only affects methods if policy != NONE | | | | | unlockVault(authData) | authData: string | Promise<void> | Unlocks vault; authData used if policy requires | | | | | isVaultLocked() | - | Promise<boolean> | Check if vault is currently locked | | | | | setVaultPolicy(policy, timeoutMs?) | `policy: 'NONE' | 'PIN' | 'BIOMETRIC' | 'TIMEOUT', timeoutMs?: number` | Promise<void> | Sets vault policy; affects lock/unlock behavior | | hashString(message) | message: string | Promise<string> | SHA-256 hash; independent method | | | | | hmacSHA256(message, alias) | message: string, alias: string | Promise<string> | HMAC; key must exist | | | | | getRandomBytes(length) | length: number | Promise<string> | Independent; cryptographically secure | | | | | getRandomId() | - | Promise<string> | Generates UUID | | | | | getDeviceInfo() | - | Promise<string> | Returns unique device ID | | | | | ping() | - | string | Test connectivity | | | | | echo(message) | message: string | string | Returns the same message | | | | | Method | Parameters | Returns | Description & Flow Notes | | ---------------------------------------------------------------- | --------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | generateSecureKeyWithAuth(alias, authValiditySeconds?) | alias: string, authValiditySeconds?: number | Promise<string> | Generates a key protected by biometrics. authValiditySeconds defines how long the key remains usable after authentication (default: -1 = one-time auth). Requires device fingerprint enrolled | | aesGcmEncryptWithAuth(plainText, alias, authValiditySeconds?) | plainText: string, alias: string, authValiditySeconds?: number | Promise<string> | Encrypts data using a key protected with biometric authentication. User must authenticate to use the key. | | aesGcmDecryptWithAuth(cipherText, alias, authValiditySeconds?) | cipherText: string, alias: string, authValiditySeconds?: number | Promise<string> | Decrypts data using a key protected with biometric authentication. User must authenticate to access the key. |

Security Notes

Keys are never exported from Keystore / Keychain

AES-GCM uses random IV per encryption

HMAC ensures authenticated encryption to detect tampering

Always use unique aliases to avoid overwriting keys

Sensitive data should never be logged or exposed in memory

Future Features

IOS Soon

Biometric-based key access (Face ID)

Contributing

Fork the repo

Use TypeScript + TurboModules architecture

Follow existing code style and naming conventions

Add tests for any new feature

License

MIT © [thtRajasthaniGuy]