RTCCertificateStats.fingerprint — Eigenschaft · JavaScript-Referenz

Signatur

RTCCertificateStats.fingerprint

Beschreibung

Die Eigenschaft fingerprint des Dictionaries RTCCertificateStats enthält den Fingerabdruck des zugehörigen Zertifikats als String. Dieses Zertifikat nutzt eine RTCPeerConnection für den DTLS-Handshake. Der Wert ist ein Hash über das DER-kodierte Zertifikat, geschrieben als Hexadezimal-Bytes in Großbuchstaben, getrennt durch Doppelpunkte (Format aus RFC 4572), z. B. "3C:4A:…:F1".

Solche Statistik-Objekte liefert RTCPeerConnection.getStats(). Sie haben den type "certificate". Normalerweise gibt es ein Objekt für das lokale und eines für das entfernte Zertifikat. Welches zu welcher Seite gehört, erfährst du über den Transport-Eintrag (type: "transport"): Dessen Felder localCertificateId und remoteCertificateId verweisen auf die id der Zertifikat-Einträge.

Den Fingerabdruck brauchst du vor allem bei der Fehlersuche und bei der Sicherheitsprüfung. Du kannst ihn mit der Zeile a=fingerprint im SDP vergleichen. Oder du lässt ihn über einen unabhängigen Kanal bestätigen, um einen Man-in-the-Middle am Signalisierungsserver auszuschließen. Welcher Hash-Algorithmus verwendet wurde, steht in der Eigenschaft fingerprintAlgorithm (meist "sha-256").

Rückgabewert

Typ

string

Beschreibung

Der Fingerabdruck des Zertifikats als Hex-Bytes in Großbuchstaben, getrennt durch Doppelpunkte (z. B. "AB:12:…"). Den verwendeten Algorithmus gibt fingerprintAlgorithm an.

Beispiele

Alle Zertifikat-Fingerabdrücke einer Verbindung ausgeben

// pc ist eine bestehende, verbundene RTCPeerConnection
const logCertificateFingerprints = async (pc) => {
  const stats = await pc.getStats();
  stats.forEach((report) => {
    if (report.type === 'certificate') {
      console.log(`${report.fingerprintAlgorithm}: ${report.fingerprint}`);
    }
  });
};

await logCertificateFingerprints(pc);

sha-256: 5B:9A:0E:…:C4:71 sha-256: 1F:D3:88:…:0A:2E

Lokales und entferntes Zertifikat über den Transport zuordnen

const getDtlsFingerprints = async (pc) => {
  const stats = await pc.getStats();
  const transport = [...stats.values()].find((r) => r.type === 'transport');
  if (!transport) return null;

  const local = stats.get(transport.localCertificateId);
  const remote = stats.get(transport.remoteCertificateId);
  return {
    local: local?.fingerprint ?? null,
    remote: remote?.fingerprint ?? null,
  };
};

console.log(await getDtlsFingerprints(pc));

{ local: "5B:9A:0E:…:C4:71", remote: "1F:D3:88:…:0A:2E" }

Entfernten Fingerabdruck mit dem SDP abgleichen

// Liest a=fingerprint aus der Remote-Beschreibung und vergleicht mit den Stats
const verifyRemoteFingerprint = async (pc) => {
  const sdp = pc.currentRemoteDescription?.sdp ?? '';
  const match = sdp.match(/^a=fingerprint:(\S+) (\S+)/m);
  if (!match) return false;
  const [, algo, sdpFingerprint] = match;

  const stats = await pc.getStats();
  const transport = [...stats.values()].find((r) => r.type === 'transport');
  const remoteCert = transport && stats.get(transport.remoteCertificateId);

  return (
    remoteCert?.fingerprintAlgorithm.toLowerCase() === algo.toLowerCase() &&
    remoteCert.fingerprint.toUpperCase() === sdpFingerprint.toUpperCase()
  );
};

console.log('Fingerabdruck stimmt:', await verifyRemoteFingerprint(pc));

Fingerabdruck stimmt: true

// Wichtig · Fallstricke

Erst nach dem DTLS-Handshake verfügbar: Solange die Verbindung nicht aufgebaut ist, liefert getStats() oft noch keine certificate-Einträge. Das gilt besonders für das entfernte Zertifikat. Frag die Werte daher erst ab, wenn connectionState === \"connected\" ist.
Nur lesbar: fingerprint ist ein reiner Messwert. Das Zertifikat selbst legst du über RTCPeerConnection.generateCertificate() und die Option certificates im Konstruktor fest.
Groß-/Kleinschreibung: Browser liefern die Hex-Werte in der Regel in Großbuchstaben. Im SDP ist auch Kleinschreibung zulässig. Normalisiere die Werte daher vor jedem Vergleich.
Sicherheit: Der Fingerabdruck schützt nur, wenn der Signalisierungskanal vertrauenswürdig ist oder der Wert unabhängig davon bestätigt wird. Wer das SDP manipulieren kann, kann auch den Fingerabdruck austauschen.
Kompatibilität: Chromium-Browser unterstützen die Eigenschaft seit Langem, Safari und Firefox erst in neueren Versionen. Ältere Firefox-Versionen liefern keine certificate-Stats. Prüfe daher, ob der Eintrag überhaupt vorhanden ist.
Bei Zertifikatsketten verweist issuerCertificateId auf den Stats-Eintrag des ausstellenden Zertifikats. In WebRTC sind die Zertifikate aber meist selbst signiert.

Siehe auch

RTCCertificateStats RTCCertificateStats.fingerprintAlgorithm RTCCertificateStats.base64Certificate RTCPeerConnection.getStats() RTCCertificate.getFingerprints() RTCTransportStats RTCCertificateStats.id