react-native-ssl-manager

Production-ready SSL certificate pinning for React Native and Expo. Protects against MITM attacks with platform-native enforcement on both iOS and Android.

Features

• Platform-native pinning — TrustKit (iOS) + Network Security Config (Android)
• Single config — one ssl_config.json drives both platforms
• Runtime toggle — enable/disable pinning without rebuilding
• Expo + RN CLI — built-in Expo plugin, auto-setup for bare projects
• New Architecture — Fabric/TurboModules supported (RN 0.68+)
• Android NSC generation — auto-generates network_security_config.xml at build time, covering OkHttp, WebView, Coil, Glide, and HttpURLConnection

Installation

npm install react-native-ssl-manager
# or
yarn add react-native-ssl-manager

iOS:

cd ios && pod install

Expo

npx expo install react-native-ssl-manager

Add to app.json:

{
  "expo": {
    "plugins": [
      ["react-native-ssl-manager", { "sslConfigPath": "./ssl_config.json" }]
    ]
  }
}

Expo plugin options:

| Option | Default | Description | |--------|---------|-------------| | sslConfigPath | "ssl_config.json" | Path to config relative to project root | | enableAndroid | true | Enable Android NSC generation + manifest patching | | enableIOS | true | Enable iOS asset bundling |

Quick Start

1. Create ssl_config.json in your project root

{
  "sha256Keys": {
    "api.example.com": [
      "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
      "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="
    ]
  }
}

Always include at least 2 pins per domain (primary + backup) to avoid lockout during certificate rotation.

2. Use in your app

import { setUseSSLPinning, getUseSSLPinning } from 'react-native-ssl-manager';

// Enable SSL pinning (enabled by default)
await setUseSSLPinning(true);

// Check current state
const isEnabled = await getUseSSLPinning();

// Disable for development/debugging
await setUseSSLPinning(false);

Important: Toggling SSL pinning requires an app restart for changes to take effect. See Runtime Toggle below.

How It Works

iOS — TrustKit Swizzling

TrustKit is initialized with kTSKSwizzleNetworkDelegates: true, which swizzles URLSession delegates at the OS level. Most libraries using URLSession under the hood are automatically covered — no per-library configuration needed.

Each domain is configured with:

pinnedDomains[domain] = [
    kTSKIncludeSubdomains: true,
    kTSKEnforcePinning: true,
    kTSKPublicKeyHashes: pins  // SHA-256 base64
]

Android — Network Security Config + OkHttp CertificatePinner

Two layers of enforcement:

1. OkHttpClientFactory — Intercepts React Native's HTTP client creation, applies CertificatePinner from ssl_config.json. Covers fetch/axios calls from JS.

2. Network Security Config (NSC) — Auto-generated network_security_config.xml at build time from ssl_config.json. Enforced at OS level for all stacks using the platform default TrustManager.

Generated XML format:

<network-security-config>
  <domain-config cleartextTrafficPermitted="false">
    <domain includeSubdomains="true">api.example.com</domain>
    <pin-set expiration="2027-04-01">
      <pin digest="SHA-256">AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</pin>
    </pin-set>
  </domain-config>
</network-security-config>

Pin expiration defaults to 1 year from build date. If your app already has a network_security_config.xml, the library merges pin-set entries — existing configs (debug-overrides, base-config) are preserved.

Supported Networking Stacks

| Stack | Platform | Covered | Mechanism | |-------|----------|---------|-----------| | fetch / axios | iOS | Yes | TrustKit swizzling | | URLSession | iOS | Yes | TrustKit swizzling | | SDWebImage | iOS | Yes | TrustKit swizzling (uses URLSession) | | Alamofire | iOS | Yes | TrustKit swizzling (uses URLSession) | | Other URLSession-based libs | iOS | Yes* | TrustKit swizzling | | fetch / axios | Android | Yes | OkHttpClientFactory + NSC | | OkHttp (direct) | Android | Yes | NSC + CertificatePinner | | Android WebView | Android | Yes | NSC | | Coil / Ktor OkHttp engine | Android | Yes | NSC | | Glide / OkHttp3 | Android | Yes | NSC | | HttpURLConnection | Android | Yes | NSC | | Cronet | Android | Best-effort* | NSC (if using platform TrustManager) |

* Caveats:

• iOS URLSession: Apps with complex custom URLSessionDelegate implementations or other method-swizzling libraries may conflict with TrustKit. TrustKit docs note swizzling is designed for simple delegate setups.
• Android Cronet: No authoritative docs confirm Cronet always respects NSC <pin-set>. Cronet has its own pinning API — use CronetEngine.Builder.addPublicKeyPins() for guaranteed enforcement.
• Custom TrustManager: Any library (OkHttp, Cronet, etc.) that builds its own TrustManager bypassing the system default will not be covered by NSC.
• Custom TLS stacks: iOS libraries not using URLSession (e.g., OpenSSL bindings) and Android Ktor CIO engine are not covered. See Ktor CIO below.

PinnedOkHttpClient (Android)

For native module authors who need a pinned OkHttp client outside React Native's networking layer:

import com.usesslpinning.PinnedOkHttpClient

val client = PinnedOkHttpClient.getInstance(context)

• Singleton with double-checked locking
• Reads ssl_config.json and configures CertificatePinner when pinning is enabled
• Returns plain OkHttpClient when pinning is disabled
• Auto-invalidates when pinning state changes via setUseSSLPinning

Glide

@GlideModule
class MyAppGlideModule : AppGlideModule() {
    override fun registerComponents(context: Context, glide: Glide, registry: Registry) {
        registry.replace(
            GlideUrl::class.java,
            InputStream::class.java,
            OkHttpUrlLoader.Factory(PinnedOkHttpClient.getInstance(context))
        )
    }
}

Coil

val imageLoader = ImageLoader.Builder(context)
    .okHttpClient { PinnedOkHttpClient.getInstance(context) }
    .build()

Ktor OkHttp Engine

val httpClient = HttpClient(OkHttp) {
    engine {
        preconfigured = PinnedOkHttpClient.getInstance(context)
    }
}

Ktor CIO Engine

CIO uses its own TLS stack — not covered by NSC or PinnedOkHttpClient. Manual TrustManager required:

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import java.security.MessageDigest
import java.security.cert.X509Certificate
import javax.net.ssl.X509TrustManager

val httpClient = HttpClient(CIO) {
    engine {
        https {
            trustManager = object : X509TrustManager {
                override fun checkClientTrusted(chain: Array<X509Certificate>, authType: String) {}
                override fun checkServerTrusted(chain: Array<X509Certificate>, authType: String) {
                    val leafCert = chain[0]
                    val publicKeyHash = MessageDigest.getInstance("SHA-256")
                        .digest(leafCert.publicKey.encoded)
                    val pin = android.util.Base64.encodeToString(publicKeyHash, android.util.Base64.NO_WRAP)
                    val expectedPins = listOf("YOUR_PIN_HERE") // from ssl_config.json
                    if (pin !in expectedPins) {
                        throw javax.net.ssl.SSLPeerUnverifiedException("Certificate pin mismatch")
                    }
                }
                override fun getAcceptedIssuers(): Array<X509Certificate> = arrayOf()
            }
        }
    }
}

Runtime Toggle

Toggling SSL pinning requires a full app restart because pinning is enforced at the native level (TrustKit initialization on iOS, OkHttpClientFactory on Android).

import { setUseSSLPinning } from 'react-native-ssl-manager';
import RNRestart from 'react-native-restart'; // optional

await setUseSSLPinning(false);
RNRestart.Restart(); // apply change

Default state is enabled (true). State is persisted in:

• iOS: UserDefaults
• Android: SharedPreferences (context: AppSettings, key: useSSLPinning)

API Reference

setUseSSLPinning(usePinning: boolean): Promise<void>

Enable or disable SSL pinning. Requires app restart to take effect.

getUseSSLPinning(): Promise<boolean>

Returns current pinning state. Defaults to true if never explicitly set.

Types

interface SslPinningConfig {
  sha256Keys: {
    [domain: string]: string[];
  };
}

interface SslPinningError extends Error {
  code?: string;
  message: string;
}

Configuration Details

ssl_config.json

Must be named exactly ssl_config.json and placed in the project root.

{
  "sha256Keys": {
    "api.example.com": [
      "sha256/primary-cert-hash=",
      "sha256/backup-cert-hash="
    ]
  }
}

Pin format: sha256/ prefix + base64-encoded SHA-256 hash of the certificate's Subject Public Key Info (SPKI). The sha256/ prefix is stripped automatically when generating NSC XML.

How the config reaches each platform

| Platform | RN CLI | Expo | |----------|--------|------| | iOS | Podspec script phase copies to app bundle | Plugin copies to ios/ + adds to Xcode project | | Android (OkHttp) | Postinstall copies to assets/ | Plugin copies to app/src/main/assets/ | | Android (NSC) | Gradle task generates XML in res/xml/ | Plugin generates XML in res/xml/ | | Android (Manifest) | Gradle task patches manifest | Plugin patches manifest |

Verifying your setup

Android (RN CLI): After building, run:

./gradlew checkSslConfig

Testing with Proxyman/Charles: Enable pinning, then attempt to intercept traffic. Requests should fail with SSL handshake errors. Disable pinning to inspect traffic during development.

Platform Requirements

| | Minimum | |---|---------| | iOS | 13.0 | | Android | API 21 (5.0) | | React Native | 0.60+ (AutoLinking), 0.68+ (New Architecture) | | Expo | SDK 47+ | | Node | 16+ |

Roadmap

• Certificate rotation support and expiry notifications
• react-native-ssl-manager-glide — optional artifact with pre-configured AppGlideModule
• React Native Web support

Demo

| iOS | Android | |-----|---------| | | |

Contributing

git clone https://github.com/huytdps13400/react-native-ssl-manager.git
cd react-native-ssl-manager
yarn install
npm run build

# Example apps
npm run example:ios
npm run example:android
npm run example-expo:ios
npm run example-expo:android

See CONTRIBUTING.md for details.

License

MIT