React Native SSL Pinning: API-Kommunikation absichern

1. Warum HTTPS allein bei Mobile Apps nicht ausreicht

HTTPS verschlüsselt die Übertragung, aber die Vertrauensentscheidung liegt vollständig beim Trust Store des Betriebssystems. Jede der mehreren hundert vorinstallierten Root-CAs auf iOS und Android kann technisch ein gültiges Zertifikat für eine beliebige Domain ausstellen. Wird eine dieser CAs kompromittiert, fehlkonfiguriert oder zur Ausstellung eines missbräuchlichen Zertifikats überredet, akzeptiert jede App, die sich allein auf System-TLS-Validierung verlässt, die gefälschte Verbindung anstandslos. Genau an dieser Stelle setzt SSL Pinning an: Es ergänzt die Standard-Zertifikatsprüfung um eine zusätzliche, in der App fest hinterlegte Erwartung.

Auf verwalteten Firmengeräten (MDM) ist das Risiko besonders konkret. IT-Abteilungen installieren häufig ein zusätzliches Root-Zertifikat, damit ein Corporate-Proxy den gesamten TLS-Traffic entschlüsseln, protokollieren und filtern kann. Aus Unternehmenssicht ist das ein legitimer, gewollter Man-in-the-Middle. Für eine App mit sensiblen Daten, etwa im Banking- oder Gesundheitsbereich, bedeutet es aber, dass Zugangsdaten, Session-Tokens und API-Antworten im Klartext beim Proxy landen, sofern die App diesem erweiterten Trust Store ohne SSL Pinning vertraut.

Werkzeuge wie Charles Proxy oder mitmproxy machen das Problem greifbar: Sobald ein Root-Zertifikat auf dem Gerät installiert und der Traffic über den Proxy umgeleitet wird, lässt sich jede ungeschützte HTTPS-Verbindung vollständig mitlesen und manipulieren. Für React Native Apps kommt hinzu, dass Debug-Builds, Third-Party-SDKs und der Metro Bundler zusätzliche Angriffsflächen öffnen. Wer React Native SSL Pinning nicht einsetzt, verlässt sich implizit darauf, dass niemand im Netzwerkpfad ein zusätzliches Zertifikat installiert hat, eine Annahme, die auf öffentlichem WLAN oder verwalteten Geräten oft nicht zutrifft.

2. Certificate Pinning vs Public Key Pinning

Bei Certificate Pinning hinterlegt die App den kompletten Hash des Server-Zertifikats, meist als SHA-256 über die DER-kodierte Zertifikatsdatei. Läuft das Zertifikat ab oder wird es erneuert, ändert sich dieser Hash zwangsläufig, selbst wenn der zugrunde liegende Schlüssel unverändert bleibt. Jede Zertifikatserneuerung erzwingt damit ein App-Update mit neuem Pin, was in der Praxis zu genau den Ausfällen führt, die Sicherheitsteams eigentlich vermeiden wollen: Nutzer mit veralteter App-Version verlieren plötzlich jede API-Verbindung, sobald das Zertifikat auf dem Server rotiert wurde.

Public Key Pinning löst dieses Problem, indem nicht das Zertifikat selbst, sondern der SPKI-Hash gepinnt wird, also der SHA-256-Hash über die Subject Public Key Info, den öffentlichen Schlüssel im DER-Format. Solange bei einer Zertifikatserneuerung derselbe Schlüsselpaar weiterverwendet wird, was bei den meisten CAs Standardpraxis ist, bleibt der SPKI-Hash über mehrere Zertifikatsgenerationen hinweg stabil. Genau deshalb gilt Public Key Pinning im Jahr 2026 als empfohlener Standardansatz für SSL Pinning in mobilen Apps: Es bindet Vertrauen an den Schlüssel, nicht an ein Dokument mit begrenzter Gültigkeit.

Der Trade-off ist trotzdem real. Wird bei einer Zertifikatserneuerung auch der Schlüssel gewechselt, etwa weil ein neuer Provider, eine neue CA oder eine Sicherheitsrichtlinie das erzwingt, bricht auch Public Key Pinning genau wie Certificate Pinning. Der Unterschied liegt in der Häufigkeit: SPKI-Hashes überleben typische, jährliche Zertifikatserneuerungen fast immer, während reines Certificate Pinning bei jeder einzelnen Erneuerung ein neues App-Release erzwingt. Backup-Pins für einen zweiten, noch nicht aktiven Schlüssel entschärfen das verbleibende Risiko zusätzlich.

3. SSL Pinning unter iOS implementieren

Unter iOS greift SSL Pinning typischerweise über die Server Trust Evaluation von NSURLSession, entweder mit eigenem URLSessionDelegate und manueller SPKI-Prüfung in urlSession(_:didReceive:completionHandler:), oder deklarativ über die Bibliothek TrustKit, die genau diese Logik kapselt. TrustKit swizzled die Netzwerk-Delegates der App und vergleicht bei jedem TLS-Handshake den SPKI-Hash des präsentierten Zertifikats gegen eine Liste konfigurierter Pins pro Domain, inklusive optionaler Backup-Pins für den Rollover-Fall.

Wichtig ist das Zusammenspiel mit App Transport Security (ATS). ATS erzwingt standardmäßig moderne TLS-Versionen und verbietet unverschlüsselte Verbindungen, ersetzt aber kein SSL Pinning. Wer für eine einzelne Domain eine ATS-Ausnahme in der Info.plist unter NSAppTransportSecurity definiert, etwa für einen Legacy-Endpunkt, sollte diese Ausnahme so eng wie möglich fassen und trotzdem TrustKit für die produktiven API-Hosts aktiv halten. ATS und Pinning ergänzen sich: ATS sichert die Transportparameter ab, SSL Pinning sichert die Identität des Servers gegen jede im Trust Store akzeptierte, aber falsche CA ab.

4. SSL Pinning unter Android implementieren

Auf Android läuft der Netzwerk-Stack von React Native standardmäßig über OkHttp, das mit CertificatePinner.Builder() eine native, gut dokumentierte API für SSL Pinning mitbringt. Ein Aufruf wie CertificatePinner.Builder().add(hostname, "sha256/BASE64HASH") reicht aus, um für einen Host einen oder mehrere SPKI-Pins zu registrieren. Alternativ, und für viele Projekte bevorzugt, weil es ohne Code-Änderung im OkHttp-Client auskommt, lässt sich Pinning deklarativ über network_security_config.xml konfigurieren, mit einem <pin-set>-Element und mehreren <pin digest="SHA-256">-Einträgen pro Domain.

Für React-Native-Projekte ist die Community-Bibliothek react-native-ssl-pinning der pragmatischste Weg, weil sie eine fetch-ähnliche API bereitstellt und intern sowohl den OkHttp-CertificatePinner unter Android als auch die NSURLSession-Validierung unter iOS anspricht. Damit muss SSL Pinning nicht getrennt für beide Plattformen in nativem Code gepflegt werden, sondern lässt sich zentral über die JavaScript-Schicht konfigurieren, während die eigentliche kryptografische Prüfung weiterhin nativ und damit performant abläuft.

5. Code-Walkthrough: react-native-ssl-pinning

Der erste Schritt ist die Extraktion des SPKI-Hashes vom produktiven Server, bevor überhaupt Code geschrieben wird. Mit einer Kette aus openssl s_client, openssl x509, openssl pkey und openssl dgst lässt sich der Base64-kodierte SHA-256-Hash des öffentlichen Schlüssels direkt aus der laufenden TLS-Verbindung ziehen, ganz ohne Zugriff auf den privaten Schlüssel oder die Serverkonfiguration.

# Extract the SPKI (Subject Public Key Info) pin for SSL Pinning
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null \
  | openssl x509 -pubkey -noout \
  | openssl pkey -pubin -outform der \
  | openssl dgst -sha256 -binary \
  | base64

Auf iOS-Seite registriert TrustKit den ermittelten Pin beim App-Start, üblicherweise im AppDelegate, zusammen mit einem zweiten, noch nicht aktiven Backup-Pin für die spätere Rotation.

// AppDelegate.swift - TrustKit configuration for SSL pinning on iOS
import TrustKit

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let trustKitConfig: [String: Any] = [
        kTSKSwizzleNetworkDelegates: true,
        kTSKPinnedDomains: [
            "api.example.com": [
                kTSKPublicKeyHashes: [
                    "AbCdEf1234567890PrimaryPinBase64==",
                    "ZyXwVu0987654321BackupPinBase64=="
                ],
                kTSKEnforcePinning: true,
                kTSKIncludeSubdomains: true
            ]
        ]
    ]
    TrustKit.initSharedInstance(withConfiguration: trustKitConfig)
    return true
}

Auf Android-Seite wird derselbe Pin (und der Backup-Pin) im OkHttp-Client registriert, entweder im nativen Modul, das React Native beim Networking verwendet, oder direkt über network_security_config.xml. Der Code unten zeigt die programmatische Variante mit CertificatePinner.Builder().

// NetworkModule.kt - OkHttp CertificatePinner for Android SSL pinning
val certificatePinner = CertificatePinner.Builder()
    .add("api.example.com", "sha256/AbCdEf1234567890PrimaryPinBase64==")
    .add("api.example.com", "sha256/ZyXwVu0987654321BackupPinBase64==")
    .build()

val client = OkHttpClient.Builder()
    .certificatePinner(certificatePinner)
    .build()

Auf der JavaScript-Seite kapselt react-native-ssl-pinning beide nativen Implementierungen hinter einer fetch-kompatiblen API. Die sslPinning-Option referenziert dabei gebündelte Zertifikatsdateien im App-Paket, nicht die rohen Hash-Strings, was bedeutet, dass die passenden .cer-Dateien vorab in die iOS- und Android-Projekte kopiert werden müssen.

// api/client.js - fetch wrapper using react-native-ssl-pinning
import { fetch } from 'react-native-ssl-pinning';

export async function fetchOrders(token) {
  const response = await fetch('https://api.example.com/v1/orders', {
    method: 'GET',
    timeoutInterval: 15000,
    headers: {
      Authorization: `Bearer ${token}`,
    },
    // sslPinning references bundled certificate files, not raw hash strings
    sslPinning: {
      certs: ['api-example-com-primary', 'api-example-com-backup'],
    },
  });

  if (response.status !== 200) {
    throw new Error(`Request failed with status ${response.status}`);
  }

  return response.json();
}

6. Zertifikatsrotation und Pin-Rollover-Strategie

Ein einzelner, hartkodierter Pin ist ein handfestes Ausfallrisiko. Läuft das Serverzertifikat oder der zugrunde liegende Schlüssel aus, ohne dass ein passender Backup-Pin bereits in der ausgelieferten App-Version vorhanden ist, verlieren alle Nutzer mit dieser Version augenblicklich jede API-Verbindung, und zwar ohne dass ein Server-seitiger Fehler vorliegt. Deshalb gehört zu jedem seriösen SSL Pinning-Setup mindestens ein zweiter, noch inaktiver Pin, der bereits Monate vor der geplanten Rotation ausgeliefert wird.

Der bewährte Ablauf für Pin-Rollover sieht so aus: Der neue Schlüssel beziehungsweise das neue Zertifikat wird serverseitig vorbereitet, aber noch nicht aktiviert. Der zugehörige SPKI-Hash wird als Backup-Pin in ein neues App-Release aufgenommen und ausgerollt, mit ausreichend Vorlauf, damit ein möglichst großer Anteil der aktiven Installationen das Update erhält, bevor der alte Pin abläuft. Erst wenn Monitoring zeigt, dass die überwiegende Mehrheit der Clients den Backup-Pin kennt, wird der Server auf das neue Zertifikat umgestellt, und der alte Pin kann in einem folgenden Release entfernt werden.

OTA-Update-Mechanismen wie EAS Update oder CodePush sind in dieser Rollover-Kette ein wichtiges Sicherheitsnetz, weil sie erlauben, JavaScript-seitige Pin-Konfigurationen ohne vollständige App-Store-Review auszurollen, wenn ein Pin-Ablauf kurzfristig droht. Sie ersetzen aber keine native Neu-Kompilierung, sobald die Pins fest im nativen TrustKit- oder OkHttp-Code verankert sind, weshalb Teams, die auf schnelle Pin-Updates angewiesen sind, die Pin-Liste bewusst so weit wie möglich in konfigurierbaren, per OTA aktualisierbaren Code auslagern sollten.

7. SSL Pinning testen und verifizieren

Ob SSL Pinning tatsächlich greift, lässt sich zuverlässig nur mit einem aktiven MITM-Proxy überprüfen. Mit mitmproxy, Charles Proxy oder Proxyman wird ein eigenes Root-Zertifikat auf dem Testgerät installiert und der gesamte App-Traffic über den Proxy umgeleitet. Eine korrekt implementierte SSL Pinning-Konfiguration erkennt, dass das vom Proxy präsentierte Zertifikat nicht zum hinterlegten Pin passt, und bricht die Verbindung sofort ab, meist mit einem expliziten Verbindungsfehler statt einer erfolgreichen, aber manipulierten Antwort.

Der häufigste False Negative entsteht, wenn ausschließlich auf Debug-Builds getestet wird. Manche Entwickler-Setups und einige Pinning-Bibliotheken deaktivieren die Pin-Prüfung standardmäßig in Debug-Konfigurationen, um lokales Debugging über einen Proxy nicht zu blockieren. Wer SSL Pinning ausschließlich im Debug-Build testet, sieht möglicherweise gar keinen Effekt und schließt fälschlich, dass etwas kaputt ist, obwohl der Release-Build korrekt schützt, oder umgekehrt hält eine kaputte Konfiguration für funktionsfähig, weil der Debug-Build sie ohnehin umgeht.

Der verlässliche Testablauf ist deshalb immer ein Release-Build oder mindestens ein release-nahes Build-Profil, installiert auf einem physischen Gerät mit aktivem MITM-Proxy und installiertem Proxy-Root-Zertifikat. Erst wenn dieser Testfall zuverlässig zu einem Verbindungsabbruch führt, während dieselbe App ohne aktiven Proxy normal funktioniert, gilt SSL Pinning als korrekt verifiziert.

8. Zusammenspiel mit anderen Sicherheitsebenen

SSL Pinning ist eine Kontrolle auf Netzwerkebene und ersetzt keine Authentifizierung oder Autorisierung auf API-Ebene. Kurzlebige JWTs mit Ablaufzeiten von wenigen Minuten begrenzen den Schaden, falls ein Token trotz allem abgegriffen wird, während Refresh-Tokens serverseitig invalidiert werden können. Diese beiden Schutzmechanismen ergänzen sich: SSL Pinning verhindert, dass ein Angreifer den Traffic überhaupt entschlüsseln kann, kurzlebige Tokens begrenzen den Schaden, falls eine andere Schwachstelle, etwa auf einem kompromittierten Gerät, Tokens dennoch offenlegt.

Request Signing, bei dem jeder API-Aufruf zusätzlich mit einem geheimen, gerätespezifischen Schlüssel signiert wird, adressiert wiederum ein drittes Risiko: Manipulation von Requests durch eine App-interne Schwachstelle, unabhängig vom Transportkanal. Wichtig ist, diese Ebenen klar zu trennen und keine als Ersatz für eine andere zu betrachten. SSL Pinning löst ausschließlich das Problem einer vertrauenswürdigen Transportverbindung, während Authentifizierung und Request Signing dafür sorgen, dass auch bei intakter Transportverbindung nur autorisierte, unveränderte Requests akzeptiert werden.

9. Pinning-Strategien im direkten Vergleich

Die Wahl zwischen keinem Pinning, Certificate Pinning, Public Key Pinning und einer Kombination aus Public Key Pinning mit Backup-Pins hat direkte Auswirkungen auf Schutzwirkung, Renewal-Robustheit und operatives Risiko. Die folgende Tabelle stellt die vier Ansätze entlang dieser Dimensionen gegenüber.

In der Praxis ist die Kombination aus Public Key Pinning und mindestens einem Backup-Pin der Ansatz mit dem besten Verhältnis aus Schutzwirkung und operativer Sicherheit. Reines Certificate Pinning ohne Rollover-Plan verschiebt das Risiko lediglich von einem Sicherheitsproblem zu einem selbstverursachten Ausfallproblem, was in der Bewertung häufig übersehen wird.

10. Zusammenfassung

SSL Pinning schließt die Lücke, die reines HTTPS bei mobilen Apps offen lässt: das blinde Vertrauen in den gesamten Trust Store des Betriebssystems, inklusive rogue CAs und Corporate-Proxies. Public Key Pinning auf Basis des SPKI-Hashes ist dabei die robustere Wahl gegenüber klassischem Certificate Pinning, weil es Zertifikatserneuerungen mit gleichbleibendem Schlüsselpaar übersteht. Unter iOS läuft die Implementierung typischerweise über TrustKit, unter Android über OkHttps CertificatePinner oder network_security_config.xml, und react-native-ssl-pinning vereint beide Plattformen hinter einer gemeinsamen fetch-API.

Ohne durchdachte Rollover-Strategie mit Backup-Pins wird SSL Pinning selbst zum Ausfallrisiko, sobald ein Zertifikat oder Schlüssel ausläuft. Getestet werden muss zwingend auf Release-Builds mit einem aktiven MITM-Proxy wie mitmproxy oder Charles Proxy, weil Debug-Builds die Pin-Prüfung häufig umgehen. Und SSL Pinning bleibt eine Kontrolle auf Netzwerkebene, die kurzlebige Tokens, Request Signing und API-Autorisierung sinnvoll ergänzt, aber nicht ersetzt.

11. FAQ: React Native SSL Pinning