RTCTransportStats.dtlsState — Eigenschaft · JavaScript-Referenz

Signatur

RTCTransportStats.dtlsState

Beschreibung

Die Eigenschaft dtlsState gehört zu einem RTCTransportStats-Objekt. Solche Objekte liefert RTCPeerConnection.getStats() als Einträge mit type === "transport". Der Wert zeigt, in welchem Zustand sich der DTLS-Handshake des Transports gerade befindet. Über DTLS werden die Schlüssel für SRTP (Audio/Video) und die Verschlüsselung von SCTP (DataChannels) ausgehandelt.

Mögliche Werte entsprechen der Enumeration RTCDtlsTransportState:

"new": Der DTLS-Handshake hat noch nicht begonnen.
"connecting": Der Handshake läuft gerade, einschließlich der Prüfung des Fingerabdrucks.
"connected": Der Handshake ist abgeschlossen und der Fingerabdruck wurde bestätigt.
"closed": Der Transport wurde ordnungsgemäß geschlossen (close_notify).
"failed": Fehler beim Handshake, eine Fatal-Alert-Meldung oder eine falsche Prüfung des Fingerabdrucks.

Nützlich ist die Eigenschaft vor allem für Diagnose und Monitoring. Mit ihr lässt sich unterscheiden, ob eine Verbindung auf ICE-Ebene (iceState) oder erst bei der Verschlüsselung (DTLS) scheitert. Neben dtlsState geben die Transport-Statistiken oft auch tlsVersion, dtlsCipher, srtpCipher und dtlsRole an.

Rückgabewert

Typ

"new" | "connecting" | "connected" | "closed" | "failed"

Beschreibung

Ein String aus der Enumeration RTCDtlsTransportState, der den DTLS-Zustand zum Zeitpunkt der Statistik-Abfrage beschreibt.

Beispiele

DTLS-Zustand aus getStats() auslesen

const logDtlsState = async (pc) => {
  const report = await pc.getStats();
  report.forEach((stats) => {
    if (stats.type === "transport") {
      console.log(`Transport ${stats.id}: DTLS = ${stats.dtlsState}`);
    }
  });
};

// Aufruf nach erfolgreichem Verbindungsaufbau
await logDtlsState(peerConnection);

Transport T01: DTLS = connected

Verbindungsdiagnose: ICE vs. DTLS unterscheiden

const diagnose = async (pc) => {
  const report = await pc.getStats();
  const transport = [...report.values()].find((s) => s.type === "transport");
  if (!transport) return "Kein Transport vorhanden";

  if (transport.dtlsState === "failed") {
    return "DTLS-Handshake fehlgeschlagen – Zertifikat/Fingerabdruck prüfen";
  }
  if (transport.dtlsState === "connected") {
    return `Verschlüsselt: ${transport.tlsVersion ?? "?"}, SRTP: ${transport.srtpCipher ?? "?"}`;
  }
  return `DTLS noch im Zustand "${transport.dtlsState}"`;
};

console.log(await diagnose(peerConnection));

Verschlüsselt: FEFD, SRTP: AES_CM_128_HMAC_SHA1_80

Periodisches Monitoring mit Zustandswechsel-Erkennung

const watchDtls = (pc, intervalMs = 2000) => {
  let last;
  const timer = setInterval(async () => {
    if (pc.connectionState === "closed") return clearInterval(timer);
    const report = await pc.getStats();
    for (const s of report.values()) {
      if (s.type === "transport" && s.dtlsState !== last) {
        console.log(`DTLS: ${last ?? "-"} → ${s.dtlsState}`);
        last = s.dtlsState;
      }
    }
  }, intervalMs);
  return () => clearInterval(timer);
};

const stop = watchDtls(peerConnection);

DTLS: - → connecting DTLS: connecting → connected

// Wichtig · Fallstricke

Nur eine Momentaufnahme: Der Wert gilt nur für den Zeitpunkt, zu dem getStats() aufgerufen wurde. Wer auf Änderungen sofort reagieren will, verwendet stattdessen das Ereignis statechange von RTCDtlsTransport (erreichbar über sender.transport) oder connectionstatechange der RTCPeerConnection.
Mehrere Transporte: Ohne Bundling (bundlePolicy ≠ "max-bundle") kann es mehrere transport-Einträge geben. Deshalb immer alle Einträge durchlaufen und nicht nur den ersten nehmen.
Browser-Kompatibilität: Wie die Transport-Statistiken umgesetzt sind, unterscheidet sich zwischen den Engines. Firefox hat transport-Einträge lange nicht oder nur unvollständig geliefert. Prüfe deshalb vor der Nutzung, ob die Eigenschaft vorhanden ist (stats.dtlsState ?? "unbekannt").
Fehlersuche bei "failed": Häufige Ursachen sind ein falscher a=fingerprint in der SDP (etwa weil die SDP unterwegs verändert wurde), abgelaufene Zertifikate aus RTCPeerConnection.generateCertificate() oder Middleboxen, die UDP-Pakete verwerfen.

Siehe auch

RTCTransportStats RTCDtlsTransport RTCDtlsTransport.state RTCPeerConnection.getStats() RTCTransportStats.iceState MediaTrackSupportedConstraints.displaySurface