RTCPeerConnection.generateCertificate() — Methode · JavaScript-Referenz

Signatur

RTCPeerConnection.generateCertificate(keygenAlgorithm)

Beschreibung

RTCPeerConnection.generateCertificate() ist eine statische Methode. Sie wird direkt über die Klasse aufgerufen, nicht über eine Instanz. Sie erzeugt ein selbstsigniertes X.509-Zertifikat mit dazugehörigem Schlüsselpaar. Mit diesem Zertifikat authentifiziert sich eine WebRTC-Verbindung beim DTLS-Handshake. Der private Schlüssel bleibt im Browser und lässt sich nicht auslesen.

Normalerweise erzeugt jede RTCPeerConnection ihr Zertifikat automatisch. Selbst erzeugen lohnt sich, wenn Sie den Schlüsselalgorithmus festlegen wollen (z. B. ECDSA P-256 statt RSA, das ist schneller und kleiner), wenn Sie die Gültigkeitsdauer steuern möchten (expires) oder wenn Sie ein Zertifikat für mehrere Verbindungen wiederverwenden wollen. Beim Wiederverwenden bleibt der DTLS-Fingerprint gleich. Das ist praktisch für Identitätsprüfung oder Signalisierungs-Caching.

Das zurückgegebene RTCCertificate übergeben Sie im Konfigurationsobjekt unter certificates an den Konstruktor new RTCPeerConnection(). RTCCertificate-Objekte sind serialisierbar. Deshalb können Sie sie in IndexedDB speichern und später wieder laden, ohne dass der private Schlüssel offengelegt wird.

Parameter

Name	Typ	Default	Beschreibung
$keygenAlgorithm Pflicht	string \| AlgorithmIdentifier \| RsaHashedKeyGenParams \| EcKeyGenParams		Beschreibt den Schlüsselalgorithmus im Format der Web Crypto API. Alle Browser müssen zwei Varianten unterstützen: `{ name: 'ECDSA', namedCurve: 'P-256' }` und `{ name: 'RSASSA-PKCS1-v1_5', modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: 'SHA-256' }`. Optional kann das Objekt die Eigenschaft `expires` enthalten: die Gültigkeit in Millisekunden ab jetzt (Standard sind meist 30 Tage). Es kann auch nur ein Algorithmusname als String übergeben werden.

Rückgabewert

Typ

Promise<RTCCertificate>

Beschreibung

Ein Promise, das mit dem neu erzeugten RTCCertificate erfüllt wird. Wenn der Algorithmus nicht unterstützt wird, wird das Promise mit einem NotSupportedError (DOMException) abgelehnt.

Beispiele

ECDSA-Zertifikat erzeugen und an eine Verbindung übergeben

const createPeer = async () => {
  const cert = await RTCPeerConnection.generateCertificate({
    name: 'ECDSA',
    namedCurve: 'P-256'
  });

  console.log('Gültig bis:', new Date(cert.expires).toISOString());

  const pc = new RTCPeerConnection({
    iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
    certificates: [cert]
  });
  return pc;
};

createPeer().then((pc) => console.log('Verbindung erstellt:', pc.signalingState));

Gültig bis: 2025-...T...Z Verbindung erstellt: stable

RSA-Zertifikat mit eigener Gültigkeitsdauer (7 Tage)

const SIEBEN_TAGE = 7 * 24 * 60 * 60 * 1000;

const cert = await RTCPeerConnection.generateCertificate({
  name: 'RSASSA-PKCS1-v1_5',
  modulusLength: 2048,
  publicExponent: new Uint8Array([1, 0, 1]),
  hash: 'SHA-256',
  expires: SIEBEN_TAGE
});

// Fingerprints ausgeben (sofern vom Browser unterstützt)
const fps = cert.getFingerprints?.() ?? [];
fps.forEach(({ algorithm, value }) => console.log(algorithm, value));

sha-256 AB:CD:EF:...

Zertifikat in IndexedDB speichern und wiederverwenden

const openDb = () => new Promise((resolve, reject) => {
  const req = indexedDB.open('webrtc', 1);
  req.onupgradeneeded = () => req.result.createObjectStore('certs');
  req.onsuccess = () => resolve(req.result);
  req.onerror = () => reject(req.error);
});

const getCertificate = async () => {
  const db = await openDb();
  const stored = await new Promise((resolve) => {
    const r = db.transaction('certs').objectStore('certs').get('main');
    r.onsuccess = () => resolve(r.result);
    r.onerror = () => resolve(undefined);
  });

  // Noch gültig? Dann wiederverwenden
  if (stored && stored.expires > Date.now()) return stored;

  const cert = await RTCPeerConnection.generateCertificate({
    name: 'ECDSA', namedCurve: 'P-256'
  });
  db.transaction('certs', 'readwrite').objectStore('certs').put(cert, 'main');
  return cert;
};

const pc = new RTCPeerConnection({ certificates: [await getCertificate()] });

Fehlerbehandlung bei nicht unterstütztem Algorithmus

try {
  await RTCPeerConnection.generateCertificate({ name: 'Ed25519' });
} catch (err) {
  console.warn(err.name, '– Rückfall auf ECDSA');
  await RTCPeerConnection.generateCertificate({ name: 'ECDSA', namedCurve: 'P-256' });
}

NotSupportedError – Rückfall auf ECDSA

// Wichtig · Fallstricke

Statischer Aufruf: pc.generateCertificate() auf einer Instanz ist undefined. Rufen Sie die Methode immer über RTCPeerConnection.generateCertificate() auf.
Abgelaufene Zertifikate: Wenn Sie ein abgelaufenes Zertifikat (expires liegt in der Vergangenheit) an den Konstruktor übergeben, wirft er einen InvalidAccessError. Prüfen Sie daher gespeicherte Zertifikate vor der Wiederverwendung.
Zertifikate sind unveränderlich: Nach dem Erzeugen der Verbindung lassen sich die Zertifikate nicht mehr tauschen, auch nicht über setConfiguration().
Algorithmen: Verlässlich funktionieren nur ECDSA P-256 und RSASSA-PKCS1-v1_5 mit SHA-256. ECDSA ist deutlich schneller zu erzeugen als RSA-2048. Browser begrenzen expires teils auf höchstens etwa ein Jahr.
Datenschutz: Ein dauerhaft wiederverwendetes Zertifikat hat einen gleichbleibenden Fingerprint. Darüber lässt sich ein Nutzer wiedererkennen. Verwenden Sie Zertifikate deshalb nur wieder, wenn Sie das bewusst wollen.
Sicherer Kontext: WebRTC erfordert in der Praxis HTTPS oder localhost. RTCCertificate.getFingerprints() gibt es erst in neueren Browsern (Safari/Firefox mit Einschränkungen).

Siehe auch

new RTCPeerConnection() RTCCertificate RTCPeerConnection.prototype.getConfiguration() SubtleCrypto.generateKey() new RTCPeerConnectionIceErrorEvent()