SSL-Pinning-Fehler: Leitfaden zur Sicherheit von mobilen Apps und APIs

Was ist SSL Pinning?

SSL Pinning (Certificate Pinning) ist ein Sicherheitsmechanismus, der dafür sorgt, dass eine Anwendung nur einem bestimmten SSL-Zertifikat oder Public Key vertraut. Bei der normalen SSL-Prüfung vertraut der Browser allen vertrauenswürdigen CAs; mit Pinning akzeptiert die Anwendung nur Verbindungen mit dem festgelegten Zertifikat bzw. Key.

Dieser Mechanismus wird vor allem in mobilen Apps und in der API-Kommunikation eingesetzt, um Man-in-the-Middle-Angriffe (MITM) zu verhindern.

Arten des Pinnings

Häufige Fehler beim SSL Pinning

Fehler 1: Zertifikat erneuert, Pin aber nicht aktualisiert

Das häufigste Problem. Wird beim Einsatz von Certificate Pinning das SSL-Zertifikat erneuert, stimmt der Pin des neuen Zertifikats nicht mehr mit dem im Anwendungscode hinterlegten überein.

Symptome

• Die App kann keine API-Aufrufe ausführen: „SSL Handshake Error“ oder „Certificate verification failed“
• Die Website funktioniert im Browser, aber die App kann keine Verbindung herstellen
• Nach der Zertifikatserneuerung sind schlagartig alle Nutzer betroffen

Lösung

• Public Key Pinning verwenden: Auch wenn das Zertifikat wechselt, kann dasselbe Key Pair weiterverwendet werden
• Backup-Pin hinzufügen: Pinnen Sie immer mindestens 2 Pins (aktiv + Reserve)
• App-Update: Veröffentlichen Sie ein Update, das den neuen Pin enthält

Fehler 2: Zertifikatswechsel bei Proxy/CDN

CDN-Dienste wie Cloudflare verwenden eigene SSL-Zertifikate. Wechselt das CDN-Zertifikat, passt der Pin nicht mehr.

Lösung

• Vermeiden Sie Pinning hinter einem CDN oder pinnen Sie die Root-CA

Fehler 3: Fehler in der Android Network Security Config

<!-- Android: res/xml/network_security_config.xml -->
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">api.example.com</domain>
        <pin-set expiration="2026-06-01">
            <!-- Aktiver Pin -->
            <pin digest="SHA-256">base64EncodedSHA256Hash=</pin>
            <!-- Backup-Pin (mit anderem Key) -->
            <pin digest="SHA-256">backupBase64Hash=</pin>
        </pin-set>
    </domain-config>
</network-security-config>

⚠️ Das Datum in expiration ist wichtig — nach Ablauf wird das Pinning automatisch deaktiviert und die App funktioniert weiter.

Fehler 4: Konflikte mit iOS ATS

// iOS: Pinning mit URLSession
func urlSession(_ session: URLSession,
                didReceive challenge: URLAuthenticationChallenge,
                completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void) {
    guard let serverTrust = challenge.protectionSpace.serverTrust,
          let serverCert = SecTrustGetCertificateAtIndex(serverTrust, 0) else {
        completionHandler(.cancelAuthenticationChallenge, nil)
        return
    }
    // Public-Key-Hash vergleichen
}

Wie wird der Pin-Hash berechnet?

# SPKI-Pin-Hash aus dem Zertifikat berechnen
openssl x509 -in certificate.crt -pubkey -noout | \
  openssl pkey -pubin -outform der | \
  openssl dgst -sha256 -binary | \
  openssl enc -base64

# Pin von einem laufenden Server abrufen
openssl s_client -connect api.example.com:443 -servername api.example.com | \
  openssl x509 -pubkey -noout | \
  openssl pkey -pubin -outform der | \
  openssl dgst -sha256 -binary | \
  openssl enc -base64

Strategien für sicheres SSL Pinning

1. Public Key Pinning bevorzugen: Bei einer Zertifikatserneuerung können Sie das neue Zertifikat mit demselben Key Pair beziehen
2. Backup-Pin hinzufügen: Pinnen Sie stets einen zusätzlichen Public-Key-Pin als Reserve
3. Ablaufdatum für Pins festlegen: Unter Android bietet das Attribut expiration Schutz im Notfall
4. Remote-Aktualisierung der Pins: Richten Sie einen Mechanismus ein, mit dem sich die Pin-Liste aus der Ferne aktualisieren lässt
5. Root-CA pinnen: Die flexibelste Methode — solange die CA nicht wechselt, bleiben Zertifikatserneuerungen ohne Auswirkung

HTTP Public Key Pinning (HPKP) — nicht mehr in Gebrauch

HPKP war ein HTTP-Header, mit dem sich Public Key Pinning in Webbrowsern umsetzen ließ. Weil eine fehlerhafte Konfiguration eine Website dauerhaft unerreichbar machen konnte, wurde er jedoch bis 2020 aus den gängigen Browsern entfernt. An seine Stelle ist Certificate Transparency getreten.

Fazit

SSL Pinning ist eine starke MITM-Schutzschicht für mobile Apps und die API-Sicherheit. Es muss jedoch im Einklang mit den Prozessen der Zertifikatserneuerung verwaltet werden. Public Key Pinning, der Einsatz von Backup-Pins und ein festgelegtes Ablaufdatum — diese drei Maßnahmen sind der wirksamste Weg, durch Pinning verursachte Ausfälle zu vermeiden.