RTCTransportStats.tlsVersion — Eigenschaft · JavaScript-Referenz

Signatur

RTCTransportStats.tlsVersion

Beschreibung

Die schreibgeschützte Eigenschaft tlsVersion gehört zum Wörterbuch RTCTransportStats. Solche Statistik-Objekte mit dem type "transport" erhältst du über RTCPeerConnection.getStats(). Die Eigenschaft zeigt, welche Protokollversion der DTLS-Handshake zwischen den beiden Endpunkten tatsächlich ausgehandelt hat.

Der Wert ist ein String mit der Versionsnummer, wie sie im Handshake übertragen wird: zwei Bytes, geschrieben als vier Hexadezimalziffern in Großbuchstaben. DTLS zählt seine Versionen rückwärts. "FEFF" steht für DTLS 1.0, "FEFD" für DTLS 1.2 und "FEFC" für DTLS 1.3.

Die Eigenschaft ist erst vorhanden, wenn die DTLS-Aushandlung abgeschlossen ist, also wenn dtlsState den Wert "connected" hat. Vorher fehlt sie im Statistik-Objekt ganz und ist dann undefined. Typische Einsatzzwecke sind:

Fehlersuche bei Verbindungen
Sicherheitsprüfungen, etwa ob mindestens DTLS 1.2 verwendet wird
Telemetrie in WebRTC-Anwendungen

Rückgabewert

Typ

string | undefined

Beschreibung

Die ausgehandelte Version als vier Hexadezimalziffern in Großbuchstaben, z. B. "FEFD" (DTLS 1.2) oder "FEFC" (DTLS 1.3). Solange der Handshake nicht abgeschlossen ist, fehlt die Eigenschaft (undefined).

Beispiele

TLS-Version aus den Transport-Statistiken auslesen

// pc ist eine bestehende, verbundene RTCPeerConnection
const logTlsVersion = async (pc) => {
  const report = await pc.getStats();
  report.forEach((stats) => {
    if (stats.type === 'transport') {
      console.log('DTLS-Status:', stats.dtlsState);
      console.log('TLS-Version:', stats.tlsVersion ?? '(noch nicht ausgehandelt)');
    }
  });
};

logTlsVersion(pc);

DTLS-Status: connected TLS-Version: FEFD

Hex-Wert in lesbare Versionsbezeichnung umwandeln

const DTLS_VERSIONS = {
  FEFF: 'DTLS 1.0',
  FEFD: 'DTLS 1.2',
  FEFC: 'DTLS 1.3'
};

const describeTlsVersion = (hex) =>
  hex ? (DTLS_VERSIONS[hex.toUpperCase()] ?? `Unbekannt (${hex})`) : 'nicht verfügbar';

console.log(describeTlsVersion('FEFD'));
console.log(describeTlsVersion('FEFC'));
console.log(describeTlsVersion(undefined));

DTLS 1.2 DTLS 1.3 nicht verfügbar

Nach dem Verbindungsaufbau Mindestversion prüfen

const MIN_VERSION_BYTE = 0xfd; // DTLS 1.2 (kleinerer Wert = neuere Version)

pc.addEventListener('connectionstatechange', async () => {
  if (pc.connectionState !== 'connected') return;

  const report = await pc.getStats();
  const transport = [...report.values()].find((s) => s.type === 'transport');

  if (!transport?.tlsVersion) {
    console.warn('tlsVersion wird von diesem Browser nicht geliefert.');
    return;
  }

  // Unteres Byte vergleichen: FEFD (1.2) und FEFC (1.3) sind in Ordnung
  const minor = parseInt(transport.tlsVersion.slice(2), 16);
  if (minor > MIN_VERSION_BYTE) {
    console.warn('Veraltete DTLS-Version:', transport.tlsVersion);
  } else {
    console.log('DTLS-Version in Ordnung:', transport.tlsVersion);
  }
});

DTLS-Version in Ordnung: FEFD

// Wichtig · Fallstricke

Nur nach dem Handshake verfügbar: Solange dtlsState nicht "connected" ist, fehlt die Eigenschaft. Prüfe den Wert deshalb immer auf undefined, z. B. mit ?. oder ??.
Rückwärts zählende Versionsnummern: Bei DTLS bedeutet ein kleinerer Hex-Wert eine neuere Version (FEFC ist neuer als FEFD). Einfache String-Vergleiche wie „größer ist neuer“ führen hier zu falschen Ergebnissen.
Browser-Kompatibilität: Chromium-basierte Browser liefern tlsVersion zuverlässig. Firefox und Safari liefern Transport-Statistiken nur eingeschränkt oder gar nicht. Prüfe also vorher, ob die Eigenschaft vorhanden ist.
Datenschutz und Fingerprinting: Die Statistiken sind nur lokal über die eigene RTCPeerConnection zugänglich. Wenn du sie als Telemetrie an einen Server schickst, solltest du das in der Datenschutzerklärung erwähnen.
Mehrere Transport-Einträge sind möglich, wenn kein BUNDLE verwendet wird. In dem Fall musst du alle Einträge mit type === "transport" auswerten.

Siehe auch

RTCTransportStats RTCTransportStats.dtlsState RTCTransportStats.dtlsCipher RTCTransportStats.srtpCipher RTCPeerConnection.getStats() RTCDtlsTransport MediaTrackSupportedConstraints.echoCancellation