@capgo/capacitor-ssl-pinning

Capgo SSL Pinning brings certificate pinning to Capacitor 8 apps by integrating with CapacitorHttp on Android and iOS.

The implementation follows the Ionic SSL pinning install flow and uses the same plugins.SSLPinning configuration shape documented at ionic.io.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/ssl-pinning/

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ |

Install

bun add @capgo/capacitor-ssl-pinning
bunx cap sync

Configure

Enable Capacitor HTTP interception and declare the certificate files relative to your app root:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorHttp: {
      enabled: true,
    },
    SSLPinning: {
      certs: ['sslCerts/production/primary.cer', 'sslCerts/production/backup.cer'],
      excludedDomains: ['https://analytics.google.com'],
    },
  },
};

export default config;

During bunx cap sync, the plugin copies the configured certificates into webDir/certs, which lets both native implementations load them from the bundled app assets.

Usage

Make HTTPS calls with CapacitorHttp:

import { CapacitorHttp } from '@capacitor/core';

const response = await CapacitorHttp.get({
  url: 'https://api.example.com/health',
});

If the server certificate does not match one of the pinned certificates, the native request fails.

Behavior

• Android injects a pinned SSLSocketFactory into Capacitor HTTP requests unless the URL matches excludedDomains.
• iOS swaps the default Capacitor HTTP handler with a pinned URLSession delegate and also answers WebView authentication challenges through the Capacitor plugin hook.
• Web exposes inspection helpers only; browsers do not support this native pinning behavior.

API

• getConfiguration()
• getPluginVersion()
• Interfaces

Capacitor API for inspecting SSL pinning configuration.

Native enforcement is applied automatically to CapacitorHttp requests when:

1. plugins.CapacitorHttp.enabled is true
2. plugins.SSLPinning.certs contains at least one certificate

getConfiguration()

getConfiguration() => Promise<SSLPinningConfigurationState>

Returns the active native configuration visible to the plugin.

Returns: Promise<SSLPinningConfigurationState>

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the native implementation version marker.

Returns: Promise<PluginVersionResult>

Interfaces

SSLPinningConfigurationState

Static SSL pinning configuration currently visible to the plugin.

| Prop | Type | Description | | --------------------- | --------------------- | --------------------------------------------------------------------- | | configured | boolean | Whether at least one certificate is configured for native pinning. | | certs | string[] | Certificate paths from capacitor.config.* relative to the app root. | | excludedDomains | string[] | Fully-qualified URLs that should bypass SSL pinning. |

PluginVersionResult

Plugin version payload.

| Prop | Type | Description | | ------------- | ------------------- | ----------------------------------------------------------- | | version | string | Version identifier returned by the platform implementation. |