@avieldr/react-native-rsa

High-performance native RSA cryptography for React Native. Uses platform-native crypto libraries (Android KeyPairGenerator, iOS Security framework) for fast, secure operations.

Features

• Native RSA key generation on both iOS and Android
• Encrypt/Decrypt with OAEP or PKCS#1 padding
• Sign/Verify with PSS or PKCS#1 padding
• Key sizes: 1024, 2048, 4096 bit
• Hash algorithms: SHA-1, SHA-256, SHA-384, SHA-512
• Output formats: PKCS#1 and PKCS#8 (private key), SPKI/X.509 (public key)
• Key format conversion between PKCS#1 and PKCS#8
• Public key extraction from private key
• Key validation (JS-only, no bridge call)
• Turbo Module (New Architecture required)

Why This Package?

Performance

Uses platform-native crypto APIs (KeyPairGenerator on Android, Security.framework on iOS) instead of JavaScript implementations or slow bridge calls:

| Operation | Native (this package) | | --------------- | --------------------- | | 2048-bit keygen | ~200ms | | Encrypt/Decrypt | < 10ms | | Sign/Verify | < 10ms |

Note: Pure JS implementations are significantly less efficient for RSA operations.

Security

• Uses OS-hardened cryptographic APIs — battle-tested implementations maintained by Apple and Google
• No bundled crypto libraries that could become outdated or vulnerable
• Supports modern padding schemes (OAEP, PSS) recommended by security standards

Lightweight

Zero runtime dependencies — only peer dependencies on React and React Native.

Flexibility

• Multiple padding modes: OAEP/PKCS#1 for encryption, PSS/PKCS#1 for signatures
• Multiple hash algorithms: SHA-1, SHA-256, SHA-384, SHA-512
• Multiple key formats: PKCS#1 and PKCS#8, with conversion between them
• Full TypeScript support with typed errors and options

Compatibility

• Requires New Architecture (Turbo Modules) — React Native 0.71+
• Android API 24+ (Android 7.0)
• iOS 13.4+
• Expo — Supported with development builds (npx expo prebuild). Not compatible with Expo Go.

Installation

npm install @avieldr/react-native-rsa
# or
yarn add @avieldr/react-native-rsa

For iOS:

cd ios && pod install

💡 Tip: Check out the example/ app in this repository for complete working demonstrations of all features, including key generation, encryption, signing, and error handling.

Quick Start

import RSA, { base64ToUtf8 } from '@avieldr/react-native-rsa';

// Generate a key pair
const { publicKey, privateKey } = await RSA.generateKeyPair(2048);

// Encrypt and decrypt
const encrypted = await RSA.encrypt('Hello, World!', publicKey);
const decryptedBase64 = await RSA.decrypt(encrypted, privateKey);
const decrypted = base64ToUtf8(decryptedBase64); // "Hello, World!"

// Sign and verify
const signature = await RSA.sign('Message to sign', privateKey);
const isValid = await RSA.verify('Message to sign', signature, publicKey); // true

API

generateKeyPair(keySize?, options?)

Generate an RSA key pair using native platform crypto.

import RSA from '@avieldr/react-native-rsa';

const { publicKey, privateKey } = await RSA.generateKeyPair(2048);

// With PKCS#8 format
const { publicKey, privateKey } = await RSA.generateKeyPair(2048, {
  format: 'pkcs8',
});

| Parameter | Type | Default | Description | | ---------------- | -------------------- | --------- | --------------------------------------- | | keySize | number | 2048 | RSA key size in bits (1024, 2048, 4096) | | options.format | 'pkcs1' \| 'pkcs8' | 'pkcs1' | Private key output format |

Returns: Promise<RSAKeyPair>

interface RSAKeyPair {
  publicKey: string; // PEM (SPKI/X.509): -----BEGIN PUBLIC KEY-----
  privateKey: string; // PEM (PKCS#1): -----BEGIN RSA PRIVATE KEY-----
  // or (PKCS#8): -----BEGIN PRIVATE KEY-----
}

encrypt(data, publicKeyPEM, options?)

Encrypt data with an RSA public key.

// Basic encryption (UTF-8 text)
const encrypted = await RSA.encrypt('Hello, World!', publicKey);

// With options
const encrypted = await RSA.encrypt('Hello, World!', publicKey, {
  padding: 'oaep', // or 'pkcs1'
  hash: 'sha256', // or 'sha1', 'sha384', 'sha512'
});

// Binary data (already base64-encoded)
const encrypted = await RSA.encrypt(binaryDataBase64, publicKey, {
  encoding: 'base64',
});

| Parameter | Type | Default | Description | | ------------------ | -------------------- | ---------- | ---------------------------------------- | | data | string | — | Data to encrypt (UTF-8 string or base64) | | publicKeyPEM | string | — | Public key in SPKI PEM format | | options.padding | 'oaep' \| 'pkcs1' | 'oaep' | Padding mode (OAEP recommended) | | options.hash | HashAlgorithm | 'sha256' | Hash algorithm (used with OAEP) | | options.encoding | 'utf8' \| 'base64' | 'utf8' | How to interpret the input string |

Returns: Promise<string> — Base64-encoded ciphertext

decrypt(encrypted, privateKeyPEM, options?)

Decrypt ciphertext with an RSA private key.

import RSA, { base64ToUtf8 } from '@avieldr/react-native-rsa';

const decryptedBase64 = await RSA.decrypt(encrypted, privateKey);
const plaintext = base64ToUtf8(decryptedBase64); // Convert back to UTF-8

// With options (must match encryption options)
const decryptedBase64 = await RSA.decrypt(encrypted, privateKey, {
  padding: 'oaep',
  hash: 'sha256',
});

| Parameter | Type | Default | Description | | ----------------- | ------------------- | ---------- | ----------------------------------------- | | encrypted | string | — | Base64-encoded ciphertext | | privateKeyPEM | string | — | Private key in PEM format (PKCS#1/PKCS#8) | | options.padding | 'oaep' \| 'pkcs1' | 'oaep' | Padding mode (must match encryption) | | options.hash | HashAlgorithm | 'sha256' | Hash algorithm (must match encryption) |

Returns: Promise<string> — Base64-encoded plaintext (use base64ToUtf8() to convert)

sign(data, privateKeyPEM, options?)

Sign data with an RSA private key.

const signature = await RSA.sign('Message to sign', privateKey);

// With options
const signature = await RSA.sign('Message to sign', privateKey, {
  padding: 'pss', // or 'pkcs1'
  hash: 'sha256',
});

| Parameter | Type | Default | Description | | ------------------ | -------------------- | ---------- | ----------------------------------------- | | data | string | — | Data to sign (UTF-8 string or base64) | | privateKeyPEM | string | — | Private key in PEM format (PKCS#1/PKCS#8) | | options.padding | 'pss' \| 'pkcs1' | 'pss' | Padding mode (PSS recommended) | | options.hash | HashAlgorithm | 'sha256' | Hash algorithm | | options.encoding | 'utf8' \| 'base64' | 'utf8' | How to interpret the input string |

Returns: Promise<string> — Base64-encoded signature

verify(data, signature, publicKeyPEM, options?)

Verify a signature against data using an RSA public key.

const isValid = await RSA.verify('Message to sign', signature, publicKey);
// true if signature is valid, false otherwise

// With options (must match signing options)
const isValid = await RSA.verify('Message to sign', signature, publicKey, {
  padding: 'pss',
  hash: 'sha256',
});

| Parameter | Type | Default | Description | | ------------------ | -------------------- | ---------- | ----------------------------------- | | data | string | — | Original data that was signed | | signature | string | — | Base64-encoded signature | | publicKeyPEM | string | — | Public key in SPKI PEM format | | options.padding | 'pss' \| 'pkcs1' | 'pss' | Padding mode (must match signing) | | options.hash | HashAlgorithm | 'sha256' | Hash algorithm (must match signing) | | options.encoding | 'utf8' \| 'base64' | 'utf8' | How to interpret the input string |

Returns: Promise<boolean> — true if valid, false otherwise

getPublicKeyFromPrivate(privateKeyPEM)

Extract the public key from an RSA private key.

const publicKey = await RSA.getPublicKeyFromPrivate(privateKey);

Accepts both PKCS#1 and PKCS#8 private key formats.

Returns: Promise<string> — Public key in SPKI PEM format

convertPrivateKey(pem, targetFormat)

Convert a private key between PKCS#1 and PKCS#8 formats.

// Convert PKCS#1 to PKCS#8
const pkcs8Key = await RSA.convertPrivateKey(pkcs1Key, 'pkcs8');

// Convert PKCS#8 to PKCS#1
const pkcs1Key = await RSA.convertPrivateKey(pkcs8Key, 'pkcs1');

| Parameter | Type | Description | | -------------- | -------------------- | ---------------------------- | | pem | string | Private key in PEM format | | targetFormat | 'pkcs1' \| 'pkcs8' | Target format for conversion |

Returns: Promise<string> — Private key in the target format

getKeyInfo(keyString)

Analyze a PEM key string and return metadata. Runs entirely in JS — no native bridge call.

import { getKeyInfo } from '@avieldr/react-native-rsa';

const info = getKeyInfo(privateKey);
// {
//   isValid: true,
//   format: 'pkcs1',
//   keyType: 'private',
//   pemLineCount: 13,
//   derByteLength: 609,
//   errors: []
// }

Returns: RSAKeyInfo

interface RSAKeyInfo {
  isValid: boolean;
  format: 'pkcs1' | 'pkcs8' | 'public' | 'unknown';
  keyType: 'private' | 'public' | 'unknown';
  pemLineCount: number;
  derByteLength: number;
  errors: string[];
}

Encoding Utilities

The library provides pure-JS encoding utilities that work in all React Native JS engines.

import { utf8ToBase64, base64ToUtf8 } from '@avieldr/react-native-rsa';

// Encode UTF-8 text to base64
const encoded = utf8ToBase64('Hello, 世界! 🎉');

// Decode base64 back to UTF-8
const decoded = base64ToUtf8(encoded);

These are useful for:

• Converting decrypted data back to readable text
• Preparing binary data for encryption
• Handling Unicode and emoji correctly

Error Handling

The library throws RsaError for invalid inputs and native failures with specific error codes:

import RSA, { RsaError } from '@avieldr/react-native-rsa';

try {
  await RSA.encrypt('data', 'invalid-key');
} catch (error) {
  if (error instanceof RsaError) {
    console.log(error.code); // 'INVALID_KEY'
    console.log(error.message); // Detailed error message
    console.log(error.cause); // Original error (if from native layer)
  }
}

Validation Errors

These are thrown before calling native code when inputs are invalid:

| Error Code | Description | | ------------------ | ----------------------------------------- | | INVALID_INPUT | Required parameter is missing or empty | | INVALID_KEY | Key format is wrong or key type mismatch | | INVALID_KEY_SIZE | Unsupported key size (not 1024/2048/4096) | | INVALID_PADDING | Unknown padding mode | | INVALID_HASH | Unknown hash algorithm | | INVALID_FORMAT | Unknown key format | | INVALID_ENCODING | Unknown encoding type |

Native Operation Errors

These are thrown when the platform crypto operation fails:

| Error Code | Description | | ----------------------- | ---------------------------------------------- | | KEY_GENERATION_FAILED | Native key generation failed | | KEY_EXTRACTION_FAILED | Failed to extract public key from private key | | KEY_CONVERSION_FAILED | Failed to convert key between formats | | ENCRYPTION_FAILED | Encryption failed (e.g., data too large) | | DECRYPTION_FAILED | Decryption failed (e.g., wrong key or padding) | | SIGNING_FAILED | Signing operation failed | | VERIFICATION_FAILED | Signature verification failed |

TypeScript Support

The error code type is exported for TypeScript users:

import type { RsaErrorCode } from '@avieldr/react-native-rsa';

function handleError(code: RsaErrorCode) {
  switch (code) {
    case 'INVALID_KEY':
      // Handle invalid key
      break;
    case 'DECRYPTION_FAILED':
      // Handle decryption failure
      break;
    // ...
  }
}

Types

All types are exported for TypeScript users:

import type {
  RSAKeyPair,
  RSAKeyInfo,
  GenerateKeyPairOptions,
  KeyFormat,
  EncryptOptions,
  DecryptOptions,
  SignOptions,
  VerifyOptions,
  EncryptionPadding,
  SignaturePadding,
  HashAlgorithm,
  InputEncoding,
  RsaErrorCode,
} from '@avieldr/react-native-rsa';

| Type | Values | | ------------------- | -------------------------------------------- | | KeyFormat | 'pkcs1' \| 'pkcs8' | | RsaErrorCode | See Error Handling | | EncryptionPadding | 'oaep' \| 'pkcs1' | | SignaturePadding | 'pss' \| 'pkcs1' | | HashAlgorithm | 'sha1' \| 'sha256' \| 'sha384' \| 'sha512' | | InputEncoding | 'utf8' \| 'base64' |

Benchmarks

Typical key generation times on modern devices:

| Key Size | Time | | -------- | -------- | | 1024-bit | ~50ms | | 2048-bit | ~200ms | | 4096-bit | ~2,000ms |

Times vary by device. Measured on mid-range Android and iPhone devices.

Security Recommendations

• Use OAEP padding for encryption (default) — PKCS#1 v1.5 is vulnerable to padding oracle attacks
• Use PSS padding for signatures (default) — more secure than PKCS#1 v1.5
• Use SHA-256 or higher — SHA-1 is deprecated for new applications
• Use 2048-bit keys minimum — 1024-bit is considered weak

License

MIT