RTCTransportStats.dtlsCipher — Eigenschaft · JavaScript-Referenz

Signatur

RTCTransportStats.dtlsCipher

Beschreibung

Die Eigenschaft dtlsCipher gehört zum Dictionary RTCTransportStats. Solche Objekte liefert RTCPeerConnection.getStats() für Einträge mit type === "transport". Der Wert ist der beschreibende Name der Cipher Suite, die beim DTLS-Handshake ausgehandelt wurde. Die Schreibweise folgt dem IANA-Register der TLS-Cipher-Suites, zum Beispiel "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256" oder bei DTLS 1.3 "TLS_AES_128_GCM_SHA256".

DTLS schützt in WebRTC den Schlüsselaustausch für SRTP (Audio/Video) und bildet die Sicherheitsschicht unter SCTP für RTCDataChannel. Mit dtlsCipher lässt sich also prüfen, welches Verschlüsselungsverfahren eine Verbindung tatsächlich nutzt. Das ist nützlich für Sicherheits-Audits, Diagnose-Dashboards und die Fehlersuche, wenn Gegenstellen mit unterschiedlichen Browsern oder SFUs arbeiten.

Die Eigenschaft ist erst vorhanden, wenn der DTLS-Handshake abgeschlossen ist, also wenn dtlsState den Wert "connected" hat. Vorher fehlt sie im Statistikobjekt oder ist undefined. Die Cipher Suite für die Medienpakete selbst (SRTP) steht in einer eigenen Eigenschaft, srtpCipher.

Rückgabewert

Typ

string | undefined

Beschreibung

Name der ausgehandelten DTLS-Cipher-Suite nach IANA-Schreibweise. undefined, solange der DTLS-Handshake nicht abgeschlossen ist oder der Browser die Eigenschaft nicht unterstützt.

Beispiele

DTLS-Cipher einer bestehenden Verbindung auslesen

// pc ist eine verbundene RTCPeerConnection
const logDtlsCipher = async (pc) => {
  const stats = await pc.getStats();
  stats.forEach((report) => {
    if (report.type === 'transport') {
      console.log(`DTLS-Status: ${report.dtlsState}`);
      console.log(`DTLS-Cipher: ${report.dtlsCipher ?? 'noch nicht ausgehandelt'}`);
    }
  });
};

await logDtlsCipher(pc);

DTLS-Status: connected DTLS-Cipher: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

Auf abgeschlossenen Handshake warten

const waitForDtlsCipher = (pc) =>
  new Promise((resolve) => {
    const check = async () => {
      const stats = await pc.getStats();
      for (const report of stats.values()) {
        if (report.type === 'transport' && report.dtlsState === 'connected' && report.dtlsCipher) {
          pc.removeEventListener('connectionstatechange', check);
          resolve(report.dtlsCipher);
          return;
        }
      }
    };
    pc.addEventListener('connectionstatechange', check);
    check();
  });

const cipher = await waitForDtlsCipher(pc);
console.log('Ausgehandelt:', cipher);

Ausgehandelt: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

Sicherheits-Audit: nur AEAD-Cipher-Suites zulassen

const isAeadCipher = (name = '') => /_GCM_|CHACHA20_POLY1305/.test(name);

const auditTransport = async (pc) => {
  const stats = await pc.getStats();
  const transport = [...stats.values()].find((r) => r.type === 'transport');
  if (!transport?.dtlsCipher) {
    return { ok: false, reason: 'Keine DTLS-Informationen verfügbar' };
  }
  return {
    ok: isAeadCipher(transport.dtlsCipher),
    dtls: transport.dtlsCipher,
    srtp: transport.srtpCipher,
    tlsVersion: transport.tlsVersion
  };
};

console.log(await auditTransport(pc));

{ ok: true, dtls: 'TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256', srtp: 'AEAD_AES_128_GCM', tlsVersion: 'FEFD' }

// Wichtig · Fallstricke

Nur nach dem Handshake verfügbar: Solange dtlsState nicht "connected" ist, fehlt dtlsCipher. Prüfen Sie den Wert daher immer auf undefined, z. B. mit ?? oder optionaler Verkettung.
Browser-Unterstützung: Die Eigenschaft ist relativ neu (Chrome/Edge ab ca. 111, Firefox ab ca. 125, Safari ab ca. 17.4). Ältere Browser liefern sie nicht mit aus. Für eine robuste Auswertung sollten Sie Ersatzwerte vorsehen.
Nicht verwechseln: dtlsCipher beschreibt die DTLS-Cipher-Suite. Die Verschlüsselung der Medienpakete steht in srtpCipher (z. B. "AEAD_AES_128_GCM").
Mehrere Transporte: Bei bundlePolicy: "max-compat" oder ohne BUNDLE kann es mehrere transport-Einträge geben, jeder mit eigenem dtlsCipher.
Datenschutz: Der Wert ist rein informativ und lässt sich nicht beeinflussen. Welche Cipher Suite ausgehandelt wird, entscheiden Browser und Gegenstelle. Statistikdaten können zum Fingerprinting beitragen. Senden Sie sie deshalb nur anonymisiert an Telemetrie-Server.

Siehe auch

RTCTransportStats RTCTransportStats.srtpCipher RTCTransportStats.dtlsState RTCTransportStats.tlsVersion RTCPeerConnection.prototype.getStats() RTCDtlsTransport MediaTrackSupportedConstraints.logicalSurface