RTCDtlsTransport.state — Eigenschaft · JavaScript-Referenz

Signatur

RTCDtlsTransport.state

Beschreibung

Die Eigenschaft state eines RTCDtlsTransport-Objekts gibt an, in welchem Zustand sich die verschlüsselte DTLS-Schicht (Datagram Transport Layer Security) einer WebRTC-Verbindung gerade befindet. Über DTLS werden die Schlüssel für SRTP (Audio/Video) ausgehandelt, und der SCTP-Verkehr der Datenkanäle wird darüber abgesichert. Ein Transport erreicht nur dann "connected", wenn die Gegenseite ihre Identität über ihr Zertifikat nachgewiesen hat.

Mögliche Werte:

"new" – Die DTLS-Aushandlung hat noch nicht begonnen.
"connecting" – Der DTLS-Handshake läuft gerade (Zertifikate und Schlüssel werden ausgetauscht).
"connected" – Der Handshake ist abgeschlossen, der Fingerabdruck des Zertifikats wurde geprüft, der Kanal ist gesichert.
"closed" – Der Transport wurde ordnungsgemäß geschlossen, z. B. durch eine close_notify-Nachricht oder RTCPeerConnection.close().
"failed" – Der Transport ist durch einen Fehler dauerhaft ausgefallen, etwa durch eine Fehler-Nachricht (Alert) oder weil der Zertifikats-Fingerabdruck nicht mit dem aus dem SDP übereinstimmt.

Auf den Transport greift man über RTCRtpSender.transport, RTCRtpReceiver.transport oder RTCSctpTransport.transport zu. Änderungen des Zustands meldet das Ereignis statechange (bzw. die Eigenschaft onstatechange). Das eignet sich gut zur Fehlersuche oder um in der Oberfläche gezielt anzuzeigen, dass es beim Verschlüsseln ein Problem gibt, während die ICE-Verbindung selbst noch funktioniert.

Rückgabewert

Typ

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

Beschreibung

Ein String (Aufzählungstyp RTCDtlsTransportState), der den aktuellen DTLS-Zustand beschreibt.

Beispiele

DTLS-Zustand eines Senders abfragen

const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const sender = pc.addTrack(stream.getAudioTracks()[0], stream);

// transport ist erst nach setLocalDescription/setRemoteDescription gesetzt
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

console.log(sender.transport?.state);

new

Zustandsänderungen per statechange überwachen

const watchDtls = (transport) => {
  if (!transport) return;
  const log = () => console.log(`DTLS-Zustand: ${transport.state}`);
  log();
  transport.addEventListener('statechange', () => {
    log();
    if (transport.state === 'failed') {
      console.error('DTLS-Handshake fehlgeschlagen – Zertifikat prüfen!');
    }
  });
};

// nach erfolgreicher Verhandlung
pc.getSenders().forEach((s) => watchDtls(s.transport));

DTLS-Zustand: new DTLS-Zustand: connecting DTLS-Zustand: connected

Status aller Transporte zusammenfassen (z. B. für eine Diagnoseseite)

const dtlsStates = (pc) => {
  const transports = new Set([
    ...pc.getSenders().map((s) => s.transport),
    ...pc.getReceivers().map((r) => r.transport),
    pc.sctp?.transport,
  ].filter(Boolean));
  return [...transports].map((t) => t.state);
};

const states = dtlsStates(pc);
const allSecure = states.length > 0 && states.every((s) => s === 'connected');
console.log(states, allSecure ? 'gesichert' : 'nicht (vollständig) gesichert');

["connected"] gesichert

Über die on-Property reagieren

const transport = pc.getReceivers()[0]?.transport;
if (transport) {
  transport.onstatechange = () => {
    document.querySelector('#status').textContent =
      transport.state === 'connected' ? '🔒 Verschlüsselt' : `DTLS: ${transport.state}`;
  };
}

// Wichtig · Fallstricke

Transport ist anfangs null: RTCRtpSender.transport bzw. RTCRtpReceiver.transport ist erst gesetzt, wenn eine lokale oder entfernte Beschreibung angewendet wurde. Optional Chaining (?.) verwenden.
Gebündelte Transporte: Mit bundlePolicy: "max-bundle" (Standard in modernen Browsern) teilen sich meist alle Sender, Empfänger und der SCTP-Transport ein RTCDtlsTransport-Objekt. Deshalb nicht mehrfach Listener registrieren, sondern vorher mit einem Set doppelte Einträge entfernen.
Endzustände: "closed" und "failed" sind endgültig. Ein fehlgeschlagener Transport erholt sich nicht von selbst, nötig ist ein ICE-Neustart (pc.restartIce()) bzw. eine Neuverhandlung oder eine neue Verbindung.
Abgrenzung: RTCIceTransport.state beschreibt die Netzwerk-Konnektivität, RTCDtlsTransport.state die Verschlüsselungsschicht darüber. Einen Gesamtüberblick bietet RTCPeerConnection.connectionState, der beide zusammenfasst.
Kompatibilität: Wird von Chrome/Edge (ab 72), Firefox (ab 82) und Safari (ab 15) unterstützt. Ältere Browser liefern kein transport-Attribut. Deshalb vor dem Zugriff prüfen, ob es existiert.

Siehe auch

RTCDtlsTransport RTCDtlsTransport.iceTransport RTCDtlsTransport.getRemoteCertificates() RTCIceTransport.state RTCPeerConnection.connectionState RTCRtpSender.transport