TLS (SSL)

[Stabil: 2 - Stabil]

Stabil: 2 Stabilität: 2 - Stabil

Quellcode: lib/tls.js

Das node:tls-Modul bietet eine Implementierung der Transport Layer Security (TLS)- und Secure Socket Layer (SSL)-Protokolle, die auf OpenSSL aufbaut. Auf das Modul kann wie folgt zugegriffen werden:

ESM

import tls from 'node:tls'

CJS

const tls = require('node:tls')

Feststellen, ob keine Krypto-Unterstützung verfügbar ist

Es ist möglich, dass Node.js ohne Unterstützung für das node:crypto-Modul erstellt wird. In solchen Fällen führt der Versuch, von tls zu importieren oder require('node:tls') aufzurufen, zu einem Fehler.

Bei Verwendung von CommonJS kann der ausgelöste Fehler mit try/catch abgefangen werden:

let tls
try {
  tls = require('node:tls')
} catch (err) {
  console.error('tls-Unterstützung ist deaktiviert!')
}

Bei Verwendung des lexikalischen ESM-Schlüsselworts import kann der Fehler nur abgefangen werden, wenn ein Handler für process.on('uncaughtException') registriert wird, bevor ein Versuch unternommen wird, das Modul zu laden (z. B. mit einem Preload-Modul).

Wenn Sie ESM verwenden und die Möglichkeit besteht, dass der Code auf einem Build von Node.js ausgeführt wird, bei dem die Krypto-Unterstützung nicht aktiviert ist, sollten Sie die Funktion import() anstelle des lexikalischen Schlüsselworts import verwenden:

let tls
try {
  tls = await import('node:tls')
} catch (err) {
  console.error('tls-Unterstützung ist deaktiviert!')
}

TLS/SSL-Konzepte

TLS/SSL ist eine Reihe von Protokollen, die auf einer Public-Key-Infrastruktur (PKI) basieren, um eine sichere Kommunikation zwischen einem Client und einem Server zu ermöglichen. In den meisten Fällen muss jeder Server einen privaten Schlüssel haben.

Private Schlüssel können auf verschiedene Arten generiert werden. Das folgende Beispiel veranschaulicht die Verwendung der OpenSSL-Befehlszeilenschnittstelle, um einen 2048-Bit-RSA-Privatschlüssel zu generieren:

openssl genrsa -out ryans-key.pem 2048

Mit TLS/SSL müssen alle Server (und einige Clients) ein Zertifikat haben. Zertifikate sind öffentliche Schlüssel, die einem privaten Schlüssel entsprechen und entweder von einer Zertifizierungsstelle oder vom Eigentümer des privaten Schlüssels digital signiert werden (solche Zertifikate werden als "selbstsigniert" bezeichnet). Der erste Schritt zum Erhalt eines Zertifikats ist die Erstellung einer Certificate Signing Request (CSR)-Datei.

Die OpenSSL-Befehlszeilenschnittstelle kann verwendet werden, um eine CSR für einen privaten Schlüssel zu generieren:

openssl req -new -sha256 -key ryans-key.pem -out ryans-csr.pem

Sobald die CSR-Datei generiert ist, kann sie entweder an eine Zertifizierungsstelle zur Signierung gesendet oder zur Generierung eines selbstsignierten Zertifikats verwendet werden.

Das Erstellen eines selbstsignierten Zertifikats mit der OpenSSL-Befehlszeilenschnittstelle wird im folgenden Beispiel veranschaulicht:

openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem

Sobald das Zertifikat generiert wurde, kann es verwendet werden, um eine .pfx- oder .p12-Datei zu generieren:

openssl pkcs12 -export -in ryans-cert.pem -inkey ryans-key.pem \
      -certfile ca-cert.pem -out ryans.pfx

Wobei:

• in: das signierte Zertifikat ist
• inkey: der zugehörige private Schlüssel ist
• certfile: eine Verkettung aller Zertifizierungsstellen-Zertifikate (CA) in einer einzigen Datei ist, z. B. cat ca1-cert.pem ca2-cert.pem \> ca-cert.pem

Perfekte Vorwärtsgeheimhaltung

Der Begriff Vorwärtsgeheimhaltung oder perfekte Vorwärtsgeheimhaltung beschreibt eine Eigenschaft von Schlüsselvereinbarungs- (d. h. Schlüsselaustausch-) Verfahren. Das heißt, die Server- und Client-Schlüssel werden verwendet, um neue temporäre Schlüssel auszuhandeln, die speziell und nur für die aktuelle Kommunikationssitzung verwendet werden. Praktisch bedeutet dies, dass die Kommunikation, selbst wenn der private Schlüssel des Servers kompromittiert wurde, von Lauscher nur dann entschlüsselt werden kann, wenn der Angreifer das speziell für die Sitzung generierte Schlüsselpaar erhalten kann.

Die perfekte Vorwärtsgeheimhaltung wird erreicht, indem bei jedem TLS/SSL-Handshake ein zufälliges Schlüsselpaar für die Schlüsselvereinbarung generiert wird (im Gegensatz zur Verwendung desselben Schlüssels für alle Sitzungen). Methoden, die diese Technik implementieren, werden als "ephemeral" bezeichnet.

Derzeit werden zwei Methoden häufig verwendet, um eine perfekte Vorwärtsgeheimhaltung zu erreichen (beachten Sie den Buchstaben "E", der an die traditionellen Abkürzungen angehängt wird):

• ECDHE: Eine ephemere Version des Elliptic Curve Diffie-Hellman Key-Agreement-Protokolls.
• DHE: Eine ephemere Version des Diffie-Hellman-Key-Agreement-Protokolls.

Die perfekte Vorwärtsgeheimhaltung mit ECDHE ist standardmäßig aktiviert. Die Option ecdhCurve kann beim Erstellen eines TLS-Servers verwendet werden, um die Liste der unterstützten zu verwendenden ECDH-Kurven anzupassen. Weitere Informationen finden Sie unter tls.createServer().

DHE ist standardmäßig deaktiviert, kann aber zusammen mit ECDHE aktiviert werden, indem die Option dhparam auf 'auto' gesetzt wird. Benutzerdefinierte DHE-Parameter werden ebenfalls unterstützt, sind aber zugunsten von automatisch ausgewählten, bekannten Parametern nicht empfehlenswert.

Die perfekte Vorwärtsgeheimhaltung war bis TLSv1.2 optional. Ab TLSv1.3 wird (EC)DHE immer verwendet (mit Ausnahme von PSK-Only-Verbindungen).

ALPN und SNI

ALPN (Application-Layer Protocol Negotiation Extension) und SNI (Server Name Indication) sind TLS-Handshake-Erweiterungen:

• ALPN: Ermöglicht die Verwendung eines TLS-Servers für mehrere Protokolle (HTTP, HTTP/2).
• SNI: Ermöglicht die Verwendung eines TLS-Servers für mehrere Hostnamen mit unterschiedlichen Zertifikaten.

Pre-shared Keys

TLS-PSK-Unterstützung ist als Alternative zur normalen zertifikatsbasierten Authentifizierung verfügbar. Es verwendet einen vorabgeteilten Schlüssel anstelle von Zertifikaten, um eine TLS-Verbindung zu authentifizieren und eine gegenseitige Authentifizierung zu ermöglichen. TLS-PSK und Public-Key-Infrastruktur schließen sich nicht gegenseitig aus. Clients und Server können beides unterstützen und während des normalen Cipher-Aushandlungsschritts eine von beiden auswählen.

TLS-PSK ist nur dann eine gute Wahl, wenn es Mittel gibt, um einen Schlüssel sicher mit jedem verbindenden Rechner zu teilen, sodass es die Public-Key-Infrastruktur (PKI) für den Großteil der TLS-Anwendungen nicht ersetzt. Die TLS-PSK-Implementierung in OpenSSL hat in den letzten Jahren viele Sicherheitslücken aufgewiesen, hauptsächlich weil sie nur von einer Minderheit von Anwendungen verwendet wird. Bitte ziehen Sie alle alternativen Lösungen in Betracht, bevor Sie zu PSK-Ciphers wechseln. Bei der Generierung von PSK ist es von entscheidender Bedeutung, ausreichend Entropie zu verwenden, wie in RFC 4086 beschrieben. Die Ableitung eines gemeinsamen Geheimnisses aus einem Passwort oder anderen Quellen mit geringer Entropie ist nicht sicher.

PSK-Ciphers sind standardmäßig deaktiviert, und die Verwendung von TLS-PSK erfordert daher die explizite Angabe einer Cipher-Suite mit der Option ciphers. Die Liste der verfügbaren Ciphers kann über openssl ciphers -v 'PSK' abgerufen werden. Alle TLS 1.3 Ciphers sind für PSK geeignet und können über openssl ciphers -v -s -tls1_3 -psk abgerufen werden. Bei der Client-Verbindung sollte eine benutzerdefinierte checkServerIdentity übergeben werden, da die Standardeinstellung in Abwesenheit eines Zertifikats fehlschlägt.

Gemäß RFC 4279 müssen PSK-Identitäten mit einer Länge von bis zu 128 Byte und PSKs mit einer Länge von bis zu 64 Byte unterstützt werden. Ab OpenSSL 1.1.0 beträgt die maximale Identitätsgröße 128 Byte und die maximale PSK-Länge 256 Byte.

Die aktuelle Implementierung unterstützt aufgrund der Einschränkungen der zugrunde liegenden OpenSSL-API keine asynchronen PSK-Callbacks.

Um TLS-PSK zu verwenden, müssen Client und Server die Option pskCallback angeben, eine Funktion, die den zu verwendenden PSK zurückgibt (der mit dem Digest des ausgewählten Ciphers kompatibel sein muss).

Es wird zuerst auf dem Client aufgerufen:

• hint: <string> optionale Nachricht, die vom Server gesendet wird, um dem Client bei der Entscheidung zu helfen, welche Identität während der Verhandlung verwendet werden soll. Immer null, wenn TLS 1.3 verwendet wird.
• Returns: <Object> in der Form { psk: \<Buffer|TypedArray|DataView\>, identity: \<string\> } oder null.

Dann auf dem Server:

• socket: <tls.TLSSocket> die Server-Socket-Instanz, die this entspricht.
• identity: <string> vom Client gesendeter Identitätsparameter.
• Returns: <Buffer> | <TypedArray> | <DataView> der PSK (oder null).

Ein Rückgabewert von null stoppt den Verhandlungsprozess und sendet eine unknown_psk_identity-Alert-Nachricht an die andere Partei. Wenn der Server die Tatsache verbergen möchte, dass die PSK-Identität nicht bekannt war, muss der Callback einige zufällige Daten als psk bereitstellen, damit die Verbindung mit decrypt_error fehlschlägt, bevor die Verhandlung abgeschlossen ist.

Abschwächung von clientseitigen Neuverhandlungsangriffen

Das TLS-Protokoll erlaubt es Clients, bestimmte Aspekte der TLS-Sitzung neu zu verhandeln. Leider erfordert die Neuverhandlung der Sitzung überproportional viele serverseitige Ressourcen, was sie zu einem potenziellen Vektor für Denial-of-Service-Angriffe macht.

Um das Risiko zu mindern, ist die Neuverhandlung auf drei Mal alle zehn Minuten beschränkt. Ein 'error'-Ereignis wird auf der tls.TLSSocket-Instanz ausgelöst, wenn dieser Schwellenwert überschritten wird. Die Grenzwerte sind konfigurierbar:

• tls.CLIENT_RENEG_LIMIT <number> Gibt die Anzahl der Neuverhandlungsanfragen an. Standard: 3.
• tls.CLIENT_RENEG_WINDOW <number> Gibt das Zeitfenster für die Neuverhandlung in Sekunden an. Standard: 600 (10 Minuten).

Die Standardgrenzwerte für die Neuverhandlung sollten nicht ohne vollständiges Verständnis der Auswirkungen und Risiken geändert werden.

TLSv1.3 unterstützt keine Neuverhandlung.

Sitzungswiederaufnahme

Das Einrichten einer TLS-Sitzung kann relativ langsam sein. Der Prozess kann beschleunigt werden, indem der Sitzungsstatus gespeichert und später wiederverwendet wird. Es gibt mehrere Mechanismen, um dies zu tun, die hier vom ältesten zum neuesten (und bevorzugten) diskutiert werden.

Sitzungskennungen

Server generieren eine eindeutige ID für neue Verbindungen und senden sie an den Client. Clients und Server speichern den Sitzungsstatus. Wenn Clients sich wieder verbinden, senden sie die ID ihres gespeicherten Sitzungsstatus, und wenn der Server auch den Status für diese ID hat, kann er zustimmen, ihn zu verwenden. Andernfalls erstellt der Server eine neue Sitzung. Siehe RFC 2246 für weitere Informationen, Seite 23 und 30.

Die Wiederaufnahme mit Sitzungskennungen wird von den meisten Webbrowsern bei der Durchführung von HTTPS-Anfragen unterstützt.

Für Node.js warten Clients auf das 'session'-Ereignis, um die Sitzungsdaten zu erhalten, und stellen die Daten der session-Option eines nachfolgenden tls.connect() zur Verfügung, um die Sitzung wiederzuverwenden. Server müssen Handler für die Ereignisse 'newSession' und 'resumeSession' implementieren, um die Sitzungsdaten zu speichern und wiederherzustellen, wobei die Sitzungs-ID als Nachschlage-Schlüssel verwendet wird, um Sitzungen wiederzuverwenden. Um Sitzungen über Lastverteiler oder Cluster-Worker hinweg wiederzuverwenden, müssen Server einen gemeinsamen Sitzungscache (wie z. B. Redis) in ihren Sitzungshandlern verwenden.

Session-Tickets

Die Server verschlüsseln den gesamten Sitzungsstatus und senden ihn als "Ticket" an den Client. Beim erneuten Verbinden wird der Status in der anfänglichen Verbindung an den Server gesendet. Dieser Mechanismus vermeidet die Notwendigkeit eines serverseitigen Sitzungscaches. Wenn der Server das Ticket aus irgendeinem Grund nicht verwendet (Entschlüsselung fehlgeschlagen, es ist zu alt usw.), erstellt er eine neue Sitzung und sendet ein neues Ticket. Weitere Informationen finden Sie in RFC 5077.

Die Wiederaufnahme von Sitzungen mit Session-Tickets wird von vielen Webbrowsern bei HTTPS-Anfragen zunehmend unterstützt.

Bei Node.js verwenden Clients die gleichen APIs für die Wiederaufnahme mit Sitzungsbezeichnern wie für die Wiederaufnahme mit Session-Tickets. Zum Debuggen gilt: Wenn tls.TLSSocket.getTLSTicket() einen Wert zurückgibt, enthalten die Sitzungsdaten ein Ticket, andernfalls enthalten sie einen clientseitigen Sitzungsstatus.

Beachten Sie bei TLSv1.3, dass der Server möglicherweise mehrere Tickets sendet, was zu mehreren 'session'-Ereignissen führt. Weitere Informationen finden Sie unter 'session'.

Single-Prozess-Server benötigen keine spezielle Implementierung, um Session-Tickets zu verwenden. Um Session-Tickets über Serverneustarts oder Load Balancer hinweg zu verwenden, müssen alle Server die gleichen Ticket-Schlüssel haben. Intern gibt es drei 16-Byte-Schlüssel, aber die TLS-API stellt sie aus praktischen Gründen als einen einzigen 48-Byte-Puffer bereit.

Es ist möglich, die Ticket-Schlüssel abzurufen, indem Sie server.getTicketKeys() auf einer Serverinstanz aufrufen und sie dann verteilen, aber es ist vernünftiger, 48 Byte sicherer Zufallsdaten sicher zu generieren und sie mit der Option ticketKeys von tls.createServer() festzulegen. Die Schlüssel sollten regelmäßig neu generiert werden, und die Schlüssel des Servers können mit server.setTicketKeys() zurückgesetzt werden.

Session-Ticket-Schlüssel sind kryptografische Schlüssel, und sie müssen sicher aufbewahrt werden. Bei TLS 1.2 und älter können alle Sitzungen, die Tickets verwendet haben, die mit diesen Schlüsseln verschlüsselt wurden, entschlüsselt werden, wenn diese kompromittiert sind. Sie sollten nicht auf der Festplatte gespeichert und regelmäßig neu generiert werden.

Wenn Clients die Unterstützung für Tickets ankündigen, sendet der Server sie. Der Server kann Tickets deaktivieren, indem er require('node:constants').SSL_OP_NO_TICKET in secureOptions angibt.

Sowohl Sitzungsbezeichner als auch Session-Tickets laufen ab, wodurch der Server neue Sitzungen erstellt. Das Timeout kann mit der Option sessionTimeout von tls.createServer() konfiguriert werden.

Wenn die Wiederaufnahme der Sitzung bei allen Mechanismen fehlschlägt, erstellen die Server neue Sitzungen. Da ein Fehlschlagen der Wiederaufnahme der Sitzung nicht zu TLS/HTTPS-Verbindungsfehlern führt, ist es einfach, unnötig schlechte TLS-Leistung nicht zu bemerken. Die OpenSSL-CLI kann verwendet werden, um zu überprüfen, ob Server Sitzungen wiederaufnehmen. Verwenden Sie die Option -reconnect für openssl s_client, z. B.:

openssl s_client -connect localhost:443 -reconnect

Lesen Sie die Debug-Ausgabe. Die erste Verbindung sollte "New" anzeigen, z. B.:

New, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256

Nachfolgende Verbindungen sollten "Reused" anzeigen, z. B.:

Reused, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256

Ändern der Standard-TLS-Verschlüsselungssuite

Node.js ist mit einer Standard-Suite von aktivierten und deaktivierten TLS-Verschlüsselungen ausgestattet. Diese Standard-Verschlüsselungsliste kann beim Erstellen von Node.js konfiguriert werden, um Distributionen die Möglichkeit zu geben, ihre eigene Standardliste bereitzustellen.

Der folgende Befehl kann verwendet werden, um die Standard-Verschlüsselungssuite anzuzeigen:

node -p crypto.constants.defaultCoreCipherList | tr ':' '\n'
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES256-GCM-SHA384
DHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-SHA256
DHE-RSA-AES128-SHA256
ECDHE-RSA-AES256-SHA384
DHE-RSA-AES256-SHA384
ECDHE-RSA-AES256-SHA256
DHE-RSA-AES256-SHA256
HIGH
!aNULL
!eNULL
!EXPORT
!DES
!RC4
!MD5
!PSK
!SRP
!CAMELLIA

Diese Standardeinstellung kann vollständig durch Verwendung des Befehlszeilenschalters --tls-cipher-list (direkt oder über die Umgebungsvariable NODE_OPTIONS) ersetzt werden. Beispielsweise wird mit folgendem Befehl ECDHE-RSA-AES128-GCM-SHA256:!RC4 zur Standard-TLS-Verschlüsselungssuite:

node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' server.js

export NODE_OPTIONS=--tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4'
node server.js

Verwenden Sie zur Überprüfung den folgenden Befehl, um die festgelegte Verschlüsselungsliste anzuzeigen. Beachten Sie den Unterschied zwischen defaultCoreCipherList und defaultCipherList:

node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' -p crypto.constants.defaultCipherList | tr ':' '\n'
ECDHE-RSA-AES128-GCM-SHA256
!RC4

d.h. die defaultCoreCipherList-Liste wird zur Kompilierzeit festgelegt und die defaultCipherList wird zur Laufzeit festgelegt.

Um die Standard-Verschlüsselungssuiten innerhalb der Laufzeit zu ändern, ändern Sie die Variable tls.DEFAULT_CIPHERS. Dies muss erfolgen, bevor auf Sockets gelauscht wird. Dies wirkt sich nicht auf bereits geöffnete Sockets aus. Zum Beispiel:

// Entfernen Sie veraltete CBC-Verschlüsselungen und RSA-Schlüsselaustausch-basierte Verschlüsselungen, da sie keine Forward Secrecy bieten
tls.DEFAULT_CIPHERS +=
  ':!ECDHE-RSA-AES128-SHA:!ECDHE-RSA-AES128-SHA256:!ECDHE-RSA-AES256-SHA:!ECDHE-RSA-AES256-SHA384' +
  ':!ECDHE-ECDSA-AES128-SHA:!ECDHE-ECDSA-AES128-SHA256:!ECDHE-ECDSA-AES256-SHA:!ECDHE-ECDSA-AES256-SHA384' +
  ':!kRSA'

Die Standardeinstellung kann auch pro Client oder Server mit der Option ciphers von tls.createSecureContext() ersetzt werden, die auch in tls.createServer(), tls.connect() und beim Erstellen neuer tls.TLSSockets verfügbar ist.

Die Verschlüsselungsliste kann eine Mischung aus TLSv1.3-Verschlüsselungssuitennamen, denjenigen, die mit 'TLS_' beginnen, und Spezifikationen für TLSv1.2- und niedrigere Verschlüsselungssuiten enthalten. Die TLSv1.2-Verschlüsselungen unterstützen ein Legacy-Spezifikationsformat. Einzelheiten finden Sie in der OpenSSL-Dokumentation zum Verschlüsselungslistenformat, aber diese Spezifikationen gelten nicht für TLSv1.3-Verschlüsselungen. Die TLSv1.3-Suites können nur durch Aufnahme ihres vollständigen Namens in die Verschlüsselungsliste aktiviert werden. Sie können beispielsweise nicht mit der Legacy-TLSv1.2-Spezifikation 'EECDH' oder '!EECDH' aktiviert oder deaktiviert werden.

Trotz der relativen Reihenfolge von TLSv1.3- und TLSv1.2-Verschlüsselungssuiten ist das TLSv1.3-Protokoll deutlich sicherer als TLSv1.2 und wird immer gegenüber TLSv1.2 gewählt, wenn der Handshake angibt, dass es unterstützt wird und wenn TLSv1.3-Verschlüsselungssuiten aktiviert sind.

Die in Node.js enthaltene Standard-Verschlüsselungssuite wurde sorgfältig ausgewählt, um die aktuellen Sicherheitsrichtlinien und Risikominderungsmaßnahmen widerzuspiegeln. Das Ändern der Standard-Verschlüsselungssuite kann erhebliche Auswirkungen auf die Sicherheit einer Anwendung haben. Der Schalter --tls-cipher-list und die Option ciphers sollten nur verwendet werden, wenn dies unbedingt erforderlich ist.

Die Standard-Verschlüsselungssuite bevorzugt GCM-Verschlüsselungen für die Chrome-Einstellung "moderne Kryptografie" und bevorzugt auch ECDHE- und DHE-Verschlüsselungen für perfekte Vorwärtsgeheimhaltung, während einige Abwärtskompatibilität geboten wird.

Alte Clients, die auf unsichere und veraltete RC4- oder DES-basierte Verschlüsselungen angewiesen sind (wie Internet Explorer 6), können den Handshake-Prozess mit der Standardkonfiguration nicht abschließen. Wenn diese Clients unbedingt unterstützt werden müssen, bieten die TLS-Empfehlungen möglicherweise eine kompatible Verschlüsselungssuite. Weitere Einzelheiten zum Format finden Sie in der OpenSSL-Dokumentation zum Verschlüsselungslistenformat.

Es gibt nur fünf TLSv1.3-Verschlüsselungssuiten:

• 'TLS_AES_256_GCM_SHA384'
• 'TLS_CHACHA20_POLY1305_SHA256'
• 'TLS_AES_128_GCM_SHA256'
• 'TLS_AES_128_CCM_SHA256'
• 'TLS_AES_128_CCM_8_SHA256'

Die ersten drei sind standardmäßig aktiviert. Die beiden CCM-basierten Suiten werden von TLSv1.3 unterstützt, da sie auf eingeschränkten Systemen möglicherweise leistungsfähiger sind, aber sie sind standardmäßig nicht aktiviert, da sie weniger Sicherheit bieten.

OpenSSL-Sicherheitsstufe

Die OpenSSL-Bibliothek erzwingt Sicherheitsstufen, um die minimal akzeptable Sicherheitsstufe für kryptografische Operationen zu steuern. Die Sicherheitsstufen von OpenSSL reichen von 0 bis 5, wobei jede Stufe strengere Sicherheitsanforderungen stellt. Die Standard-Sicherheitsstufe ist 1, die im Allgemeinen für die meisten modernen Anwendungen geeignet ist. Einige ältere Funktionen und Protokolle, wie z. B. TLSv1, erfordern jedoch eine niedrigere Sicherheitsstufe (SECLEVEL=0), um ordnungsgemäß zu funktionieren. Weitere Informationen finden Sie in der OpenSSL-Dokumentation zu Sicherheitsstufen.

Einstellen von Sicherheitsstufen

Um die Sicherheitsstufe in Ihrer Node.js-Anwendung anzupassen, können Sie @SECLEVEL=X in eine Cipher-Zeichenkette aufnehmen, wobei X die gewünschte Sicherheitsstufe ist. Um beispielsweise die Sicherheitsstufe auf 0 zu setzen und gleichzeitig die standardmäßige OpenSSL-Cipher-Liste zu verwenden, könnten Sie Folgendes verwenden:

ESM

import { createServer, connect } from 'node:tls'
const port = 443

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function (socket) {
  console.log('Client verbunden mit Protokoll:', socket.getProtocol())
  socket.end()
  this.close()
}).listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' })
})

CJS

const { createServer, connect } = require('node:tls')
const port = 443

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function (socket) {
  console.log('Client verbunden mit Protokoll:', socket.getProtocol())
  socket.end()
  this.close()
}).listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' })
})

Dieser Ansatz setzt die Sicherheitsstufe auf 0, wodurch die Verwendung älterer Funktionen ermöglicht wird, während die standardmäßigen OpenSSL-Cipher weiterhin genutzt werden.

Verwendung

Sie können die Sicherheitsstufe und die Cipher auch über die Befehlszeile mit --tls-cipher-list=DEFAULT@SECLEVEL=X festlegen, wie in Ändern der standardmäßigen TLS-Cipher-Suite beschrieben. Es ist jedoch allgemein davon abzuraten, die Befehlszeilenoption zum Festlegen von Ciphern zu verwenden, und es ist vorzuziehen, die Cipher für einzelne Kontexte in Ihrem Anwendungscode zu konfigurieren, da dieser Ansatz eine feinere Steuerung ermöglicht und das Risiko einer globalen Herabstufung der Sicherheitsstufe verringert.

X509-Zertifikat-Fehlercodes

Mehrere Funktionen können aufgrund von Zertifikatsfehlern, die von OpenSSL gemeldet werden, fehlschlagen. In einem solchen Fall stellt die Funktion über ihren Callback einen <Error> bereit, der die Eigenschaft code hat, die einen der folgenden Werte annehmen kann:

• 'UNABLE_TO_GET_ISSUER_CERT': Ausstellerzertifikat konnte nicht abgerufen werden.
• 'UNABLE_TO_GET_CRL': Zertifikats-CRL konnte nicht abgerufen werden.
• 'UNABLE_TO_DECRYPT_CERT_SIGNATURE': Signatur des Zertifikats konnte nicht entschlüsselt werden.
• 'UNABLE_TO_DECRYPT_CRL_SIGNATURE': Signatur der CRL konnte nicht entschlüsselt werden.
• 'UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY': Öffentlicher Schlüssel des Ausstellers konnte nicht dekodiert werden.
• 'CERT_SIGNATURE_FAILURE': Zertifikatssignaturfehler.
• 'CRL_SIGNATURE_FAILURE': CRL-Signaturfehler.
• 'CERT_NOT_YET_VALID': Zertifikat ist noch nicht gültig.
• 'CERT_HAS_EXPIRED': Zertifikat ist abgelaufen.
• 'CRL_NOT_YET_VALID': CRL ist noch nicht gültig.
• 'CRL_HAS_EXPIRED': CRL ist abgelaufen.
• 'ERROR_IN_CERT_NOT_BEFORE_FIELD': Formatfehler im notBefore-Feld des Zertifikats.
• 'ERROR_IN_CERT_NOT_AFTER_FIELD': Formatfehler im notAfter-Feld des Zertifikats.
• 'ERROR_IN_CRL_LAST_UPDATE_FIELD': Formatfehler im lastUpdate-Feld der CRL.
• 'ERROR_IN_CRL_NEXT_UPDATE_FIELD': Formatfehler im nextUpdate-Feld der CRL.
• 'OUT_OF_MEM': Nicht genügend Speicher.
• 'DEPTH_ZERO_SELF_SIGNED_CERT': Selbstsigniertes Zertifikat.
• 'SELF_SIGNED_CERT_IN_CHAIN': Selbstsigniertes Zertifikat in der Zertifikatskette.
• 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY': Lokales Ausstellerzertifikat konnte nicht abgerufen werden.
• 'UNABLE_TO_VERIFY_LEAF_SIGNATURE': Das erste Zertifikat konnte nicht verifiziert werden.
• 'CERT_CHAIN_TOO_LONG': Zertifikatskette ist zu lang.
• 'CERT_REVOKED': Zertifikat wurde widerrufen.
• 'INVALID_CA': Ungültiges CA-Zertifikat.
• 'PATH_LENGTH_EXCEEDED': Pfadlängenbeschränkung überschritten.
• 'INVALID_PURPOSE': Nicht unterstützter Zertifikatszweck.
• 'CERT_UNTRUSTED': Zertifikat nicht vertrauenswürdig.
• 'CERT_REJECTED': Zertifikat abgelehnt.
• 'HOSTNAME_MISMATCH': Hostname stimmt nicht überein.

Klasse: tls.CryptoStream

Hinzugefügt in: v0.3.4

Veraltet seit: v0.11.3

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet: Verwenden Sie stattdessen tls.TLSSocket.

Die Klasse tls.CryptoStream repräsentiert einen Stream verschlüsselter Daten. Diese Klasse ist veraltet und sollte nicht mehr verwendet werden.

cryptoStream.bytesWritten

Hinzugefügt in: v0.3.4

Veraltet seit: v0.11.3

Die Eigenschaft cryptoStream.bytesWritten gibt die Gesamtzahl der Bytes zurück, die an den zugrunde liegenden Socket geschrieben wurden, einschließlich der Bytes, die für die Implementierung des TLS-Protokolls erforderlich sind.

Klasse: tls.SecurePair

Hinzugefügt in: v0.3.2

Veraltet seit: v0.11.3

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet: Verwenden Sie stattdessen tls.TLSSocket.

Wird von tls.createSecurePair() zurückgegeben.

Ereignis: 'secure'

Hinzugefügt in: v0.3.2

Veraltet seit: v0.11.3

Das 'secure'-Ereignis wird vom SecurePair-Objekt ausgelöst, sobald eine sichere Verbindung hergestellt wurde.

Wie beim Überprüfen des Serverereignisses 'secureConnection' sollte pair.cleartext.authorized überprüft werden, um zu bestätigen, ob das verwendete Zertifikat ordnungsgemäß autorisiert ist.

Klasse: tls.Server

Hinzugefügt in: v0.3.2

• Erweitert: <net.Server>

Akzeptiert verschlüsselte Verbindungen mit TLS oder SSL.

Ereignis: 'connection'

Hinzugefügt in: v0.3.2

• socket <stream.Duplex>

Dieses Ereignis wird ausgelöst, wenn ein neuer TCP-Stream hergestellt wird, bevor der TLS-Handshake beginnt. socket ist typischerweise ein Objekt vom Typ net.Socket, empfängt jedoch keine Ereignisse im Gegensatz zum Socket, der vom Ereignis net.Server 'connection' erstellt wurde. Normalerweise möchten Benutzer nicht auf dieses Ereignis zugreifen.

Dieses Ereignis kann auch explizit von Benutzern ausgelöst werden, um Verbindungen in den TLS-Server einzuspeisen. In diesem Fall kann jeder Duplex-Stream übergeben werden.

Ereignis: 'keylog'

Hinzugefügt in: v12.3.0, v10.20.0

• line <Buffer> Zeile ASCII-Text, im NSS SSLKEYLOGFILE-Format.
• tlsSocket <tls.TLSSocket> Die tls.TLSSocket-Instanz, auf der sie generiert wurde.

Das keylog-Ereignis wird ausgelöst, wenn Schlüsselmaterial von einer Verbindung zu diesem Server generiert oder empfangen wird (normalerweise bevor der Handshake abgeschlossen ist, aber nicht notwendigerweise). Dieses Schlüsselmaterial kann zur Fehlersuche gespeichert werden, da es die Entschlüsselung des erfassten TLS-Verkehrs ermöglicht. Es kann für jeden Socket mehrmals ausgelöst werden.

Ein typischer Anwendungsfall ist das Anhängen empfangener Zeilen an eine gemeinsame Textdatei, die später von Software (wie Wireshark) zur Entschlüsselung des Datenverkehrs verwendet wird:

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' })
// ...
server.on('keylog', (line, tlsSocket) => {
  if (tlsSocket.remoteAddress !== '...') return // Nur Schlüssel für eine bestimmte IP protokollieren
  logFile.write(line)
})

Ereignis: 'newSession'

[Verlauf]

Version	Änderungen
v0.11.12	Das callback-Argument wird jetzt unterstützt.
v0.9.2	Hinzugefügt in: v0.9.2

Das Ereignis 'newSession' wird bei der Erstellung einer neuen TLS-Sitzung ausgelöst. Dies kann verwendet werden, um Sitzungen in externen Speichern zu speichern. Die Daten sollten an den 'resumeSession'-Callback übergeben werden.

Der Listener-Callback erhält beim Aufruf drei Argumente:

• sessionId <Buffer> Der TLS-Sitzungsbezeichner
• sessionData <Buffer> Die TLS-Sitzungsdaten
• callback <Function> Eine Callback-Funktion ohne Argumente, die aufgerufen werden muss, damit Daten über die sichere Verbindung gesendet oder empfangen werden können.

Das Abhören dieses Ereignisses wirkt sich nur auf Verbindungen aus, die nach dem Hinzufügen des Ereignislisteners hergestellt werden.

Ereignis: 'OCSPRequest'

Hinzugefügt in: v0.11.13

Das Ereignis 'OCSPRequest' wird ausgelöst, wenn der Client eine Zertifikatsstatusanfrage sendet. Der Listener-Callback erhält beim Aufruf drei Argumente:

• certificate <Buffer> Das Serverzertifikat
• issuer <Buffer> Das Zertifikat des Ausstellers
• callback <Function> Eine Callback-Funktion, die aufgerufen werden muss, um die Ergebnisse der OCSP-Anfrage bereitzustellen.

Das aktuelle Zertifikat des Servers kann analysiert werden, um die OCSP-URL und die Zertifikats-ID zu erhalten. Nach dem Abrufen einer OCSP-Antwort wird callback(null, resp) aufgerufen, wobei resp eine Buffer-Instanz ist, die die OCSP-Antwort enthält. Sowohl certificate als auch issuer sind Buffer-DER-Darstellungen der primären und der Ausstellerzertifikate. Diese können verwendet werden, um die OCSP-Zertifikats-ID und die OCSP-Endpunkt-URL zu erhalten.

Alternativ kann callback(null, null) aufgerufen werden, um anzuzeigen, dass keine OCSP-Antwort vorlag.

Das Aufrufen von callback(err) führt zu einem socket.destroy(err)-Aufruf.

Der typische Ablauf einer OCSP-Anfrage ist wie folgt:

Der issuer kann null sein, wenn das Zertifikat entweder selbstsigniert ist oder der Aussteller nicht in der Liste der Root-Zertifikate enthalten ist. (Ein Aussteller kann über die Option ca beim Aufbau der TLS-Verbindung bereitgestellt werden.)

Das Abhören dieses Ereignisses wirkt sich nur auf Verbindungen aus, die nach dem Hinzufügen des Ereignislisteners hergestellt werden.

Ein NPM-Modul wie asn1.js kann verwendet werden, um die Zertifikate zu analysieren.

Event: 'resumeSession'

Hinzugefügt in: v0.9.2

Das 'resumeSession'-Ereignis wird ausgelöst, wenn der Client anfordert, eine vorherige TLS-Sitzung wiederaufzunehmen. Der Listener-Callback erhält beim Aufruf zwei Argumente übergeben:

• sessionId <Buffer> Der TLS-Sitzungsidentifikator
• callback <Function> Eine Callback-Funktion, die aufgerufen wird, wenn die vorherige Sitzung wiederhergestellt wurde: callback([err[, sessionData]])
  • err <Error>
  • sessionData <Buffer>

Der Event-Listener sollte in einem externen Speicher nach den sessionData suchen, die durch den 'newSession'-Event-Handler unter Verwendung der gegebenen sessionId gespeichert wurden. Wenn sie gefunden werden, rufe callback(null, sessionData) auf, um die Sitzung wiederaufzunehmen. Wenn sie nicht gefunden werden, kann die Sitzung nicht wiederaufgenommen werden. callback() muss ohne sessionData aufgerufen werden, damit der Handshake fortgesetzt und eine neue Sitzung erstellt werden kann. Es ist möglich, callback(err) aufzurufen, um die eingehende Verbindung zu beenden und den Socket zu zerstören.

Das Abhören dieses Ereignisses hat nur Auswirkungen auf Verbindungen, die nach dem Hinzufügen des Event-Listeners hergestellt werden.

Das Folgende veranschaulicht die Wiederaufnahme einer TLS-Sitzung:

const tlsSessionStore = {}
server.on('newSession', (id, data, cb) => {
  tlsSessionStore[id.toString('hex')] = data
  cb()
})
server.on('resumeSession', (id, cb) => {
  cb(null, tlsSessionStore[id.toString('hex')] || null)
})

Event: 'secureConnection'

Hinzugefügt in: v0.3.2

Das 'secureConnection'-Ereignis wird ausgelöst, nachdem der Handshake-Prozess für eine neue Verbindung erfolgreich abgeschlossen wurde. Der Listener-Callback erhält beim Aufruf ein einzelnes Argument übergeben:

• tlsSocket <tls.TLSSocket> Der aufgebaute TLS-Socket.

Die tlsSocket.authorized-Eigenschaft ist ein boolean, der angibt, ob der Client von einer der mitgelieferten Zertifizierungsstellen für den Server verifiziert wurde. Wenn tlsSocket.authorized false ist, wird socket.authorizationError gesetzt, um zu beschreiben, wie die Autorisierung fehlgeschlagen ist. Abhängig von den Einstellungen des TLS-Servers können nicht autorisierte Verbindungen dennoch akzeptiert werden.

Die tlsSocket.alpnProtocol-Eigenschaft ist ein String, der das ausgewählte ALPN-Protokoll enthält. Wenn ALPN kein ausgewähltes Protokoll hat, weil der Client oder der Server keine ALPN-Erweiterung gesendet hat, ist tlsSocket.alpnProtocol gleich false.

Die tlsSocket.servername-Eigenschaft ist ein String, der den über SNI angeforderten Servernamen enthält.

Ereignis: 'tlsClientError'

Hinzugefügt in: v6.0.0

Das Ereignis 'tlsClientError' wird ausgelöst, wenn ein Fehler auftritt, bevor eine sichere Verbindung hergestellt wird. Der Listener-Callback erhält beim Aufruf zwei Argumente:

• exception <Error> Das Error-Objekt, das den Fehler beschreibt
• tlsSocket <tls.TLSSocket> Die tls.TLSSocket-Instanz, von der der Fehler stammt.

server.addContext(hostname, context)

Hinzugefügt in: v0.5.3

• hostname <string> Ein SNI-Hostname oder ein Platzhalter (z. B. '*')
• context <Object> | <tls.SecureContext> Ein Objekt, das beliebige der möglichen Eigenschaften aus den options-Argumenten von tls.createSecureContext() enthält (z. B. key, cert, ca, usw.), oder ein TLS-Kontextobjekt, das mit tls.createSecureContext() selbst erstellt wurde.

Die Methode server.addContext() fügt einen sicheren Kontext hinzu, der verwendet wird, wenn der SNI-Name der Client-Anfrage mit dem angegebenen hostname (oder Platzhalter) übereinstimmt.

Wenn mehrere übereinstimmende Kontexte vorhanden sind, wird der zuletzt hinzugefügte Kontext verwendet.

server.address()

Hinzugefügt in: v0.6.0

• Gibt zurück: <Object>

Gibt die gebundene Adresse, den Adressfamiliennamen und den Port des Servers zurück, wie vom Betriebssystem gemeldet. Weitere Informationen finden Sie unter net.Server.address().

server.close([callback])

Hinzugefügt in: v0.3.2

• callback <Function> Ein Listener-Callback, der registriert wird, um auf das 'close'-Ereignis der Serverinstanz zu lauschen.
• Gibt zurück: <tls.Server>

Die Methode server.close() verhindert, dass der Server neue Verbindungen akzeptiert.

Diese Funktion arbeitet asynchron. Das 'close'-Ereignis wird ausgelöst, wenn der Server keine offenen Verbindungen mehr hat.

server.getTicketKeys()

Hinzugefügt in: v3.0.0

• Gibt zurück: <Buffer> Ein 48-Byte-Buffer, der die Sitzungsticket-Schlüssel enthält.

Gibt die Sitzungsticket-Schlüssel zurück.

Weitere Informationen finden Sie unter Sitzungswiederaufnahme.

server.listen()

Startet den Server, der auf verschlüsselte Verbindungen lauscht. Diese Methode ist identisch mit server.listen() von net.Server.

server.setSecureContext(options)

Hinzugefügt in: v11.0.0

• options <Object> Ein Objekt, das alle möglichen Eigenschaften aus den options-Argumenten von tls.createSecureContext() enthält (z. B. key, cert, ca usw.).

Die Methode server.setSecureContext() ersetzt den sicheren Kontext eines bestehenden Servers. Bestehende Verbindungen zum Server werden nicht unterbrochen.

server.setTicketKeys(keys)

Hinzugefügt in: v3.0.0

• keys <Buffer> | <TypedArray> | <DataView> Ein 48-Byte-Buffer, der die Sitzungsticket-Schlüssel enthält.

Legt die Sitzungsticket-Schlüssel fest.

Änderungen an den Ticket-Schlüsseln werden erst für zukünftige Serververbindungen wirksam. Bestehende oder aktuell ausstehende Serververbindungen verwenden die vorherigen Schlüssel.

Weitere Informationen finden Sie unter Sitzungswiederaufnahme.

Klasse: tls.TLSSocket

Hinzugefügt in: v0.11.4

• Erweitert: <net.Socket>

Führt eine transparente Verschlüsselung der geschriebenen Daten und alle erforderlichen TLS-Verhandlungen durch.

Instanzen von tls.TLSSocket implementieren die Duplex Stream-Schnittstelle.

Methoden, die TLS-Verbindungsmetadaten zurückgeben (z. B. tls.TLSSocket.getPeerCertificate()), geben nur Daten zurück, während die Verbindung geöffnet ist.

new tls.TLSSocket(socket[, options])

[History]

Version	Änderungen
v12.2.0	Die Option enableTrace wird jetzt unterstützt.
v5.0.0	ALPN-Optionen werden jetzt unterstützt.
v0.11.4	Hinzugefügt in: v0.11.4

• socket <net.Socket> | <stream.Duplex> Auf der Serverseite ein beliebiger Duplex-Stream. Auf der Clientseite jede Instanz von net.Socket (für generische Duplex-Stream-Unterstützung auf der Clientseite muss tls.connect() verwendet werden).
• options <Object>
  • enableTrace: Siehe tls.createServer()
  • isServer: Das SSL/TLS-Protokoll ist asymmetrisch. TLSSockets müssen wissen, ob sie sich als Server oder Client verhalten sollen. Wenn true, wird der TLS-Socket als Server instanziiert. Standard: false.
  • server <net.Server> Eine net.Server-Instanz.
  • requestCert: Ob der Remote-Peer authentifiziert werden soll, indem ein Zertifikat angefordert wird. Clients fordern immer ein Serverzertifikat an. Server (isServer ist true) können requestCert auf true setzen, um ein Clientzertifikat anzufordern.
  • rejectUnauthorized: Siehe tls.createServer()
  • ALPNProtocols: Siehe tls.createServer()
  • SNICallback: Siehe tls.createServer()
  • session <Buffer> Eine Buffer-Instanz, die eine TLS-Sitzung enthält.
  • requestOCSP <boolean> Wenn true, gibt an, dass die OCSP-Statusanforderungserweiterung zum Client-Hallo hinzugefügt wird und ein 'OCSPResponse'-Ereignis auf dem Socket ausgelöst wird, bevor eine sichere Kommunikation hergestellt wird.
  • secureContext: TLS-Kontextobjekt, das mit tls.createSecureContext() erstellt wurde. Wenn kein secureContext bereitgestellt wird, wird einer erstellt, indem das gesamte options-Objekt an tls.createSecureContext() übergeben wird.
  • ...: tls.createSecureContext()-Optionen, die verwendet werden, wenn die secureContext-Option fehlt. Andernfalls werden sie ignoriert.

Konstruiert ein neues tls.TLSSocket-Objekt aus einem vorhandenen TCP-Socket.

Ereignis: 'keylog'

Hinzugefügt in: v12.3.0, v10.20.0

• line <Buffer> Zeile ASCII-Text im NSS SSLKEYLOGFILE-Format.

Das keylog-Ereignis wird auf einem tls.TLSSocket ausgelöst, wenn Schlüsselmaterial von dem Socket erzeugt oder empfangen wird. Dieses Schlüsselmaterial kann zur Fehlersuche gespeichert werden, da es ermöglicht, aufgezeichneten TLS-Traffic zu entschlüsseln. Es kann mehrmals ausgelöst werden, vor oder nachdem der Handshake abgeschlossen ist.

Ein typischer Anwendungsfall ist das Anhängen empfangener Zeilen an eine gemeinsame Textdatei, die später von Software (wie z.B. Wireshark) verwendet wird, um den Traffic zu entschlüsseln:

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' })
// ...
tlsSocket.on('keylog', line => logFile.write(line))

Ereignis: 'OCSPResponse'

Hinzugefügt in: v0.11.13

Das 'OCSPResponse'-Ereignis wird ausgelöst, wenn die requestOCSP-Option gesetzt wurde, als der tls.TLSSocket erstellt wurde und eine OCSP-Antwort empfangen wurde. Der Listener-Callback erhält bei Aufruf ein einzelnes Argument:

• response <Buffer> Die OCSP-Antwort des Servers

Typischerweise ist die response ein digital signiertes Objekt von der CA des Servers, das Informationen über den Sperrstatus des Serverzertifikats enthält.

Ereignis: 'secureConnect'

Hinzugefügt in: v0.11.4

Das Ereignis 'secureConnect' wird ausgelöst, nachdem der Handshake-Prozess für eine neue Verbindung erfolgreich abgeschlossen wurde. Der Listener-Callback wird unabhängig davon aufgerufen, ob das Serverzertifikat autorisiert wurde oder nicht. Es liegt in der Verantwortung des Clients, die tlsSocket.authorized-Eigenschaft zu überprüfen, um festzustellen, ob das Serverzertifikat von einer der angegebenen CAs signiert wurde. Wenn tlsSocket.authorized === false, kann der Fehler durch Untersuchung der tlsSocket.authorizationError-Eigenschaft gefunden werden. Wenn ALPN verwendet wurde, kann die tlsSocket.alpnProtocol-Eigenschaft überprüft werden, um das ausgehandelte Protokoll zu ermitteln.

Das 'secureConnect'-Ereignis wird nicht ausgelöst, wenn ein <tls.TLSSocket> mit dem Konstruktor new tls.TLSSocket() erstellt wird.

Ereignis: 'session'

Hinzugefügt in: v11.10.0

• session <Buffer>

Das 'session'-Ereignis wird auf einem Client tls.TLSSocket ausgelöst, wenn eine neue Sitzung oder ein TLS-Ticket verfügbar ist. Dies kann vor oder nach Abschluss des Handshakes erfolgen, abhängig von der ausgehandelten TLS-Protokollversion. Das Ereignis wird nicht auf dem Server ausgelöst oder wenn keine neue Sitzung erstellt wurde, z. B. wenn die Verbindung wieder aufgenommen wurde. Bei einigen TLS-Protokollversionen kann das Ereignis mehrmals ausgelöst werden. In diesem Fall können alle Sitzungen zur Wiederaufnahme verwendet werden.

Auf dem Client kann die session der session-Option von tls.connect() bereitgestellt werden, um die Verbindung wiederaufzunehmen.

Weitere Informationen finden Sie unter Sitzungswiederaufnahme.

Für TLSv1.2 und älter kann tls.TLSSocket.getSession() aufgerufen werden, sobald der Handshake abgeschlossen ist. Für TLSv1.3 ist gemäß dem Protokoll nur die ticketbasierte Wiederaufnahme zulässig, es werden mehrere Tickets gesendet und die Tickets werden erst nach Abschluss des Handshakes gesendet. Daher ist es erforderlich, auf das 'session'-Ereignis zu warten, um eine wiederaufnehmbare Sitzung zu erhalten. Anwendungen sollten das 'session'-Ereignis anstelle von getSession() verwenden, um sicherzustellen, dass sie für alle TLS-Versionen funktionieren. Anwendungen, die nur eine Sitzung erwarten oder verwenden möchten, sollten dieses Ereignis nur einmal abhören:

tlsSocket.once('session', session => {
  // Die Sitzung kann sofort oder später verwendet werden.
  tls.connect({
    session: session,
    // Andere Verbindungsoptionen...
  })
})

tlsSocket.address()

[Verlauf]

Version	Änderungen
v18.4.0	Die family-Eigenschaft gibt jetzt einen String anstelle einer Zahl zurück.
v18.0.0	Die family-Eigenschaft gibt jetzt eine Zahl anstelle eines Strings zurück.
v0.11.4	Hinzugefügt in: v0.11.4

• Gibt zurück: <Object>

Gibt die gebundene address, den Adressfamiliennamen family und den port des zugrunde liegenden Sockets zurück, wie vom Betriebssystem gemeldet: { port: 12346, family: 'IPv4', address: '127.0.0.1' }.

tlsSocket.authorizationError

Hinzugefügt in: v0.11.4

Gibt den Grund zurück, warum das Zertifikat des Peers nicht verifiziert wurde. Diese Eigenschaft wird nur gesetzt, wenn tlsSocket.authorized === false ist.

tlsSocket.authorized

Hinzugefügt in: v0.11.4

• <boolean>

Diese Eigenschaft ist true, wenn das Peer-Zertifikat von einer der CAs signiert wurde, die beim Erstellen der tls.TLSSocket-Instanz angegeben wurden, andernfalls false.

tlsSocket.disableRenegotiation()

Hinzugefügt in: v8.4.0

Deaktiviert die TLS-Neuverhandlung für diese TLSSocket-Instanz. Sobald diese Funktion aufgerufen wird, lösen Versuche zur Neuverhandlung ein 'error'-Ereignis auf dem TLSSocket aus.

tlsSocket.enableTrace()

Hinzugefügt in: v12.2.0

Wenn aktiviert, werden TLS-Paket-Trace-Informationen nach stderr geschrieben. Dies kann verwendet werden, um TLS-Verbindungsprobleme zu debuggen.

Das Format der Ausgabe ist identisch mit der Ausgabe von openssl s_client -trace oder openssl s_server -trace. Obwohl sie von der SSL_trace()-Funktion von OpenSSL erzeugt wird, ist das Format undokumentiert, kann sich ohne Vorankündigung ändern und sollte nicht als zuverlässig angesehen werden.

tlsSocket.encrypted

Hinzugefügt in: v0.11.4

Gibt immer true zurück. Dies kann verwendet werden, um TLS-Sockets von regulären net.Socket-Instanzen zu unterscheiden.

tlsSocket.exportKeyingMaterial(length, label[, context])

Hinzugefügt in: v13.10.0, v12.17.0

• length <number> Anzahl der Bytes, die aus dem Schlüsselmaterial abgerufen werden sollen
• label <string> eine anwendungsspezifische Bezeichnung, typischerweise ist dies ein Wert aus der IANA Exporter Label Registry.
• context <Buffer> Optional einen Kontext angeben.
• Gibt zurück: <Buffer> angeforderte Bytes des Schlüsselmaterials

Schlüsselmaterial wird für Validierungen verwendet, um verschiedene Arten von Angriffen in Netzwerkprotokollen zu verhindern, beispielsweise in den Spezifikationen von IEEE 802.1X.

Beispiel:

const keyingMaterial = tlsSocket.exportKeyingMaterial(128, 'client finished')

/*
 Beispielhafter Rückgabewert von keyingMaterial:
 <Buffer 76 26 af 99 c5 56 8e 42 09 91 ef 9f 93 cb ad 6c 7b 65 f8 53 f1 d8 d9
    12 5a 33 b8 b5 25 df 7b 37 9f e0 e2 4f b8 67 83 a3 2f cd 5d 41 42 4c 91
    74 ef 2c ... 78 weitere Bytes>
*/

Weitere Informationen finden Sie in der OpenSSL-Dokumentation SSL_export_keying_material.

tlsSocket.getCertificate()

Hinzugefügt in: v11.2.0

• Gibt zurück: <Object>

Gibt ein Objekt zurück, das das lokale Zertifikat repräsentiert. Das zurückgegebene Objekt hat einige Eigenschaften, die den Feldern des Zertifikats entsprechen.

Siehe tls.TLSSocket.getPeerCertificate() für ein Beispiel der Zertifikatsstruktur.

Wenn kein lokales Zertifikat vorhanden ist, wird ein leeres Objekt zurückgegeben. Wenn der Socket zerstört wurde, wird null zurückgegeben.

tlsSocket.getCipher()

[Verlauf]

Version	Änderungen
v13.4.0, v12.16.0	Gibt den IETF-Chiffrenamen als standardName zurück.
v12.0.0	Gibt die minimale Chiffrenversion zurück, anstatt einer festen Zeichenfolge ('TLSv1/SSLv3').
v0.11.4	Hinzugefügt in: v0.11.4

• Gibt zurück: <Object>
  • name <string> OpenSSL-Name für die Chiffrensuite.
  • standardName <string> IETF-Name für die Chiffrensuite.
  • version <string> Die minimale TLS-Protokollversion, die von dieser Chiffrensuite unterstützt wird. Für das tatsächlich ausgehandelte Protokoll siehe tls.TLSSocket.getProtocol().

Gibt ein Objekt zurück, das Informationen über die ausgehandelte Chiffrensuite enthält.

Zum Beispiel ein TLSv1.2-Protokoll mit AES256-SHA-Chiffre:

{
  "name": "AES256-SHA",
  "standardName": "TLS_RSA_WITH_AES_256_CBC_SHA",
  "version": "SSLv3"
}

Siehe SSL_CIPHER_get_name für weitere Informationen.

tlsSocket.getEphemeralKeyInfo()

Hinzugefügt in: v5.0.0

• Gibt zurück: <Object>

Gibt ein Objekt zurück, das den Typ, den Namen und die Größe des Parameters eines temporären Schlüsselaustauschs in Perfect Forward Secrecy bei einer Clientverbindung darstellt. Es gibt ein leeres Objekt zurück, wenn der Schlüsselaustausch nicht temporär ist. Da dies nur auf einem Client-Socket unterstützt wird, wird null zurückgegeben, wenn es auf einem Server-Socket aufgerufen wird. Die unterstützten Typen sind 'DH' und 'ECDH'. Die name-Eigenschaft ist nur verfügbar, wenn der Typ 'ECDH' ist.

Zum Beispiel: { type: 'ECDH', name: 'prime256v1', size: 256 }.

tlsSocket.getFinished()

Hinzugefügt in: v9.9.0

• Gibt zurück: <Buffer> | <undefined> Die letzte Finished-Nachricht, die im Rahmen eines SSL/TLS-Handshakes an den Socket gesendet wurde, oder undefined, wenn noch keine Finished-Nachricht gesendet wurde.

Da die Finished-Nachrichten Nachrichtendigests des vollständigen Handshakes sind (mit insgesamt 192 Bit für TLS 1.0 und mehr für SSL 3.0), können sie für externe Authentifizierungsverfahren verwendet werden, wenn die von SSL/TLS bereitgestellte Authentifizierung nicht erwünscht oder nicht ausreichend ist.

Entspricht der SSL_get_finished-Routine in OpenSSL und kann verwendet werden, um das tls-unique-Channel-Binding aus RFC 5929 zu implementieren.

tlsSocket.getPeerCertificate([detailed])

Hinzugefügt in: v0.11.4

• detailed <boolean> Schließt die vollständige Zertifikatskette ein, wenn true, andernfalls nur das Zertifikat des Peers.
• Gibt zurück: <Object> Ein Zertifikatsobjekt.

Gibt ein Objekt zurück, das das Zertifikat des Peers darstellt. Wenn der Peer kein Zertifikat bereitstellt, wird ein leeres Objekt zurückgegeben. Wenn der Socket zerstört wurde, wird null zurückgegeben.

Wenn die vollständige Zertifikatskette angefordert wurde, enthält jedes Zertifikat eine issuerCertificate-Eigenschaft, die ein Objekt enthält, das das Zertifikat seines Ausstellers darstellt.

Zertifikatsobjekt

[Verlauf]

Version	Änderungen
v19.1.0, v18.13.0	Füge die Eigenschaft "ca" hinzu.
v17.2.0, v16.14.0	Füge fingerprint512 hinzu.
v11.4.0	Unterstützung für Informationen zum öffentlichen Schlüssel der elliptischen Kurve.

Ein Zertifikatsobjekt hat Eigenschaften, die den Feldern des Zertifikats entsprechen.

• ca <boolean> true, wenn eine Zertifizierungsstelle (CA), false andernfalls.
• raw <Buffer> Die DER-codierten X.509-Zertifikatsdaten.
• subject <Object> Der Zertifikatbetreff, beschrieben in Bezug auf Land (C), Bundesland oder Provinz (ST), Ort (L), Organisation (O), Organisationseinheit (OU) und CommonName (CN). Der CommonName ist typischerweise ein DNS-Name mit TLS-Zertifikaten. Beispiel: {C: 'UK', ST: 'BC', L: 'Metro', O: 'Node Fans', OU: 'Docs', CN: 'example.com'}.
• issuer <Object> Der Aussteller des Zertifikats, beschrieben in denselben Begriffen wie der subject.
• valid_from <string> Das Datum und die Uhrzeit, ab der das Zertifikat gültig ist.
• valid_to <string> Das Datum und die Uhrzeit, bis zu der das Zertifikat gültig ist.
• serialNumber <string> Die Seriennummer des Zertifikats als Hexadezimalzeichenfolge. Beispiel: 'B9B0D332A1AA5635'.
• fingerprint <string> Der SHA-1-Digest des DER-codierten Zertifikats. Er wird als :-getrennte Hexadezimalzeichenfolge zurückgegeben. Beispiel: '2A:7A:C2:DD:...'.
• fingerprint256 <string> Der SHA-256-Digest des DER-codierten Zertifikats. Er wird als :-getrennte Hexadezimalzeichenfolge zurückgegeben. Beispiel: '2A:7A:C2:DD:...'.
• fingerprint512 <string> Der SHA-512-Digest des DER-codierten Zertifikats. Er wird als :-getrennte Hexadezimalzeichenfolge zurückgegeben. Beispiel: '2A:7A:C2:DD:...'.
• ext_key_usage <Array> (Optional) Die erweiterte Schlüsselverwendung, eine Reihe von OIDs.
• subjectaltname <string> (Optional) Eine Zeichenkette, die verkettete Namen für den Betreff enthält, eine Alternative zu den subject-Namen.
• infoAccess <Array> (Optional) Ein Array, das AuthorityInfoAccess beschreibt, das mit OCSP verwendet wird.
• issuerCertificate <Object> (Optional) Das Ausstellerzertifikatobjekt. Für selbstsignierte Zertifikate kann dies eine zyklische Referenz sein.

Das Zertifikat kann je nach Schlüsseltyp Informationen über den öffentlichen Schlüssel enthalten.

Für RSA-Schlüssel können die folgenden Eigenschaften definiert werden:

• bits <number> Die RSA-Bitgröße. Beispiel: 1024.
• exponent <string> Der RSA-Exponent als Zeichenkette in hexadezimaler Zahlendarstellung. Beispiel: '0x010001'.
• modulus <string> Der RSA-Modul als hexadezimale Zeichenkette. Beispiel: 'B56CE45CB7...'.
• pubkey <Buffer> Der öffentliche Schlüssel.

Für EC-Schlüssel können die folgenden Eigenschaften definiert werden:

• pubkey <Buffer> Der öffentliche Schlüssel.
• bits <number> Die Schlüsselgröße in Bits. Beispiel: 256.
• asn1Curve <string> (Optional) Der ASN.1-Name der OID der elliptischen Kurve. Bekannte Kurven werden durch eine OID identifiziert. Es ist zwar ungewöhnlich, aber es ist möglich, dass die Kurve durch ihre mathematischen Eigenschaften identifiziert wird, in diesem Fall hat sie keine OID. Beispiel: 'prime256v1'.
• nistCurve <string> (Optional) Der NIST-Name für die elliptische Kurve, falls sie einen hat (nicht alle bekannten Kurven haben von NIST Namen zugewiesen bekommen). Beispiel: 'P-256'.

Beispielzertifikat:

{ subject:
   { OU: [ 'Domain Control Validated', 'PositiveSSL Wildcard' ],
     CN: '*.nodejs.org' },
  issuer:
   { C: 'GB',
     ST: 'Greater Manchester',
     L: 'Salford',
     O: 'COMODO CA Limited',
     CN: 'COMODO RSA Domain Validation Secure Server CA' },
  subjectaltname: 'DNS:*.nodejs.org, DNS:nodejs.org',
  infoAccess:
   { 'CA Issuers - URI':
      [ 'http://crt.comodoca.com/COMODORSADomainValidationSecureServerCA.crt' ],
     'OCSP - URI': [ 'http://ocsp.comodoca.com' ] },
  modulus: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59C93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1',
  exponent: '0x10001',
  pubkey: <Buffer ... >,
  valid_from: 'Aug 14 00:00:00 2017 GMT',
  valid_to: 'Nov 20 23:59:59 2019 GMT',
  fingerprint: '01:02:59:D9:C3:D2:0D:08:F7:82:4E:44:A4:B4:53:C5:E2:3A:87:4D',
  fingerprint256: '69:AE:1A:6A:D4:3D:C6:C1:1B:EA:C6:23:DE:BA:2A:14:62:62:93:5C:7A:EA:06:41:9B:0B:BC:87:CE:48:4E:02',
  fingerprint512: '19:2B:3E:C3:B3:5B:32:E8:AE:BB:78:97:27:E4:BA:6C:39:C9:92:79:4F:31:46:39:E2:70:E5:5F:89:42:17:C9:E8:64:CA:FF:BB:72:56:73:6E:28:8A:92:7E:A3:2A:15:8B:C2:E0:45:CA:C3:BC:EA:40:52:EC:CA:A2:68:CB:32',
  ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ],
  serialNumber: '66593D57F20CBC573E433381B5FEC280',
  raw: <Buffer ... > }

tlsSocket.getPeerFinished()

Hinzugefügt in: v9.9.0

• Gibt zurück: <Buffer> | <undefined> Die letzte Finished-Nachricht, die im Rahmen eines SSL/TLS-Handshakes von dem Socket erwartet oder tatsächlich empfangen wurde, oder undefined, falls bisher keine Finished-Nachricht vorhanden ist.

Da die Finished-Nachrichten Nachrichtendigests des gesamten Handshakes sind (mit insgesamt 192 Bit für TLS 1.0 und mehr für SSL 3.0), können sie für externe Authentifizierungsverfahren verwendet werden, wenn die von SSL/TLS bereitgestellte Authentifizierung nicht gewünscht oder nicht ausreichend ist.

Entspricht der SSL_get_peer_finished-Routine in OpenSSL und kann verwendet werden, um das tls-unique Channel Binding aus RFC 5929 zu implementieren.

tlsSocket.getPeerX509Certificate()

Hinzugefügt in: v15.9.0

• Gibt zurück: <X509Certificate>

Gibt das Peer-Zertifikat als <X509Certificate>-Objekt zurück.

Wenn kein Peer-Zertifikat vorhanden ist oder der Socket zerstört wurde, wird undefined zurückgegeben.

tlsSocket.getProtocol()

Hinzugefügt in: v5.7.0

• Gibt zurück: <string> | <null>

Gibt einen String zurück, der die ausgehandelte SSL/TLS-Protokollversion der aktuellen Verbindung enthält. Der Wert 'unknown' wird für verbundene Sockets zurückgegeben, die den Handshake-Prozess nicht abgeschlossen haben. Der Wert null wird für Server-Sockets oder getrennte Client-Sockets zurückgegeben.

Protokollversionen sind:

• 'SSLv3'
• 'TLSv1'
• 'TLSv1.1'
• 'TLSv1.2'
• 'TLSv1.3'

Weitere Informationen finden Sie in der OpenSSL SSL_get_version-Dokumentation.

tlsSocket.getSession()

Hinzugefügt in: v0.11.4

• <Buffer>

Gibt die TLS-Sitzungsdaten oder undefined zurück, wenn keine Sitzung ausgehandelt wurde. Auf dem Client können die Daten der session-Option von tls.connect() bereitgestellt werden, um die Verbindung wiederaufzunehmen. Auf dem Server kann es für das Debuggen nützlich sein.

Weitere Informationen finden Sie unter Sitzungswiederaufnahme.

Hinweis: getSession() funktioniert nur für TLSv1.2 und darunter. Für TLSv1.3 müssen Anwendungen das 'session'-Ereignis verwenden (es funktioniert auch für TLSv1.2 und darunter).

tlsSocket.getSharedSigalgs()

Hinzugefügt in: v12.11.0

• Gibt zurück: <Array> Liste der Signaturalgorithmen, die sich Server und Client teilen, in der Reihenfolge absteigender Präferenz.

Weitere Informationen finden Sie unter SSL_get_shared_sigalgs.

tlsSocket.getTLSTicket()

Hinzugefügt in: v0.11.4

• <Buffer>

Gibt für einen Client das TLS-Session-Ticket zurück, falls vorhanden, oder undefined. Für einen Server wird immer undefined zurückgegeben.

Dies kann zur Fehlersuche nützlich sein.

Weitere Informationen finden Sie unter Session Resumption.

tlsSocket.getX509Certificate()

Hinzugefügt in: v15.9.0

• Gibt zurück: <X509Certificate>

Gibt das lokale Zertifikat als <X509Certificate>-Objekt zurück.

Wenn kein lokales Zertifikat vorhanden ist oder der Socket zerstört wurde, wird undefined zurückgegeben.

tlsSocket.isSessionReused()

Hinzugefügt in: v0.5.6

• Gibt zurück: <boolean> true, wenn die Session wiederverwendet wurde, andernfalls false.

Weitere Informationen finden Sie unter Session Resumption.

tlsSocket.localAddress

Hinzugefügt in: v0.11.4

• <string>

Gibt die String-Darstellung der lokalen IP-Adresse zurück.

tlsSocket.localPort

Hinzugefügt in: v0.11.4

• <integer>

Gibt die numerische Darstellung des lokalen Ports zurück.

tlsSocket.remoteAddress

Hinzugefügt in: v0.11.4

• <string>

Gibt die String-Darstellung der Remote-IP-Adresse zurück. Zum Beispiel '74.125.127.100' oder '2001:4860:a005::68'.

tlsSocket.remoteFamily

Hinzugefügt in: v0.11.4

• <string>

Gibt die Stringdarstellung der Remote-IP-Familie zurück. 'IPv4' oder 'IPv6'.

tlsSocket.remotePort

Hinzugefügt in: v0.11.4

• <integer>

Gibt die numerische Darstellung des Remote-Ports zurück. Zum Beispiel 443.

tlsSocket.renegotiate(options, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Die Übergabe eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v0.11.8	Hinzugefügt in: v0.11.8

• options <Object>

  • rejectUnauthorized <boolean> Wenn nicht false, wird das Serverzertifikat anhand der Liste der mitgelieferten CAs verifiziert. Ein 'error'-Ereignis wird ausgelöst, wenn die Verifizierung fehlschlägt; err.code enthält den OpenSSL-Fehlercode. Standard: true.
  • requestCert

• callback <Function> Wenn renegotiate() true zurückgegeben hat, wird der Callback einmal an das 'secure'-Ereignis angehängt. Wenn renegotiate() false zurückgegeben hat, wird callback im nächsten Tick mit einem Fehler aufgerufen, es sei denn, der tlsSocket wurde zerstört, in diesem Fall wird callback überhaupt nicht aufgerufen.

• Gibt zurück: <boolean> true, wenn die Neuverhandlung initiiert wurde, false andernfalls.

Die Methode tlsSocket.renegotiate() initiiert einen TLS-Neuverhandlungsprozess. Nach Abschluss wird der callback-Funktion ein einzelnes Argument übergeben, das entweder ein Error (wenn die Anfrage fehlgeschlagen ist) oder null ist.

Diese Methode kann verwendet werden, um das Zertifikat eines Peers anzufordern, nachdem die sichere Verbindung hergestellt wurde.

Wenn der Socket als Server ausgeführt wird, wird er nach dem handshakeTimeout mit einem Fehler zerstört.

Für TLSv1.3 kann keine Neuverhandlung initiiert werden, da sie vom Protokoll nicht unterstützt wird.

tlsSocket.setKeyCert(context)

Hinzugefügt in: v22.5.0, v20.17.0

• context <Object> | <tls.SecureContext> Ein Objekt, das mindestens die Eigenschaften key und cert aus den tls.createSecureContext() options enthält, oder ein TLS-Kontextobjekt, das mit tls.createSecureContext() selbst erstellt wurde.

Die Methode tlsSocket.setKeyCert() legt den privaten Schlüssel und das Zertifikat fest, die für den Socket verwendet werden sollen. Dies ist hauptsächlich nützlich, wenn Sie ein Serverzertifikat von einem ALPNCallback eines TLS-Servers auswählen möchten.

tlsSocket.setMaxSendFragment(size)

Hinzugefügt in: v0.11.11

• size <number> Die maximale TLS-Fragmentgröße. Der maximale Wert ist 16384. Standard: 16384.
• Gibt zurück: <boolean>

Die Methode tlsSocket.setMaxSendFragment() legt die maximale TLS-Fragmentgröße fest. Gibt true zurück, wenn die Festlegung des Limits erfolgreich war; andernfalls false.

Kleinere Fragmentgrößen verringern die Pufferungslatenz auf dem Client: Größere Fragmente werden von der TLS-Schicht gepuffert, bis das gesamte Fragment empfangen und seine Integrität überprüft wurde; große Fragmente können sich über mehrere Roundtrips erstrecken und ihre Verarbeitung kann aufgrund von Paketverlust oder Neuanordnung verzögert werden. Kleinere Fragmente fügen jedoch zusätzliche TLS-Framing-Bytes und CPU-Overhead hinzu, was den Gesamtdurchsatz des Servers verringern kann.

tls.checkServerIdentity(hostname, cert)

[Verlauf]

Version	Änderungen
v17.3.1, v16.13.2, v14.18.3, v12.22.9	Die Unterstützung für alternative Subjektnamen uniformResourceIdentifier wurde als Reaktion auf CVE-2021-44531 deaktiviert.
v0.8.4	Hinzugefügt in: v0.8.4

• hostname <string> Der Hostname oder die IP-Adresse, anhand derer das Zertifikat überprüft werden soll.
• cert <Object> Ein Zertifikatsobjekt, das das Zertifikat des Peers darstellt.
• Gibt zurück: <Error> | <undefined>

Überprüft, ob das Zertifikat cert für hostname ausgestellt wurde.

Gibt ein <Error>-Objekt zurück, das bei einem Fehler mit reason, host und cert gefüllt wird. Bei Erfolg wird <undefined> zurückgegeben.

Diese Funktion ist für die Verwendung in Kombination mit der Option checkServerIdentity vorgesehen, die an tls.connect() übergeben werden kann, und arbeitet als solche mit einem Zertifikatsobjekt. Für andere Zwecke sollte x509.checkHost() verwendet werden.

Diese Funktion kann überschrieben werden, indem eine alternative Funktion als options.checkServerIdentity-Option bereitgestellt wird, die an tls.connect() übergeben wird. Die überschreibende Funktion kann natürlich tls.checkServerIdentity() aufrufen, um die durchgeführten Prüfungen mit zusätzlichen Überprüfungen zu erweitern.

Diese Funktion wird nur aufgerufen, wenn das Zertifikat alle anderen Prüfungen bestanden hat, z. B. ob es von einer vertrauenswürdigen Zertifizierungsstelle ausgestellt wurde (options.ca).

Frühere Versionen von Node.js akzeptierten Zertifikate für einen bestimmten hostname fälschlicherweise, wenn ein übereinstimmender alternativer Subjektname uniformResourceIdentifier vorhanden war (siehe CVE-2021-44531). Anwendungen, die alternative Subjektnamen uniformResourceIdentifier akzeptieren möchten, können eine benutzerdefinierte options.checkServerIdentity-Funktion verwenden, die das gewünschte Verhalten implementiert.

tls.connect(options[, callback])

[History]

Version	Änderungen
v15.1.0, v14.18.0	Option onread hinzugefügt.
v14.1.0, v13.14.0	Die Option highWaterMark wird jetzt akzeptiert.
v13.6.0, v12.16.0	Die Option pskCallback wird jetzt unterstützt.
v12.9.0	Unterstützung für die Option allowHalfOpen.
v12.4.0	Die Option hints wird jetzt unterstützt.
v12.2.0	Die Option enableTrace wird jetzt unterstützt.
v11.8.0, v10.16.0	Die Option timeout wird jetzt unterstützt.
v8.0.0	Die Option lookup wird jetzt unterstützt.
v8.0.0	Die Option ALPNProtocols kann jetzt ein TypedArray oder DataView sein.
v5.0.0	ALPN-Optionen werden jetzt unterstützt.
v5.3.0, v4.7.0	Die Option secureContext wird jetzt unterstützt.
v0.11.3	Hinzugefügt in: v0.11.3

• options <Object>

  • enableTrace: Siehe tls.createServer()
  • host <string> Der Host, zu dem der Client eine Verbindung herstellen soll. Standard: 'localhost'.
  • port <number> Der Port, zu dem der Client eine Verbindung herstellen soll.
  • path <string> Erstellt eine Unix-Socketverbindung zum Pfad. Wenn diese Option angegeben ist, werden host und port ignoriert.
  • socket <stream.Duplex> Stellt eine sichere Verbindung über einen gegebenen Socket her, anstatt einen neuen Socket zu erstellen. Typischerweise ist dies eine Instanz von net.Socket, aber jeder Duplex-Stream ist erlaubt. Wenn diese Option angegeben ist, werden path, host und port ignoriert, mit Ausnahme der Zertifikatsvalidierung. Normalerweise ist ein Socket bereits verbunden, wenn er an tls.connect() übergeben wird, er kann aber auch später verbunden werden. Die Verbindung/Trennung/Zerstörung von socket liegt in der Verantwortung des Benutzers; das Aufrufen von tls.connect() führt nicht dazu, dass net.connect() aufgerufen wird.
  • allowHalfOpen <boolean> Wenn auf false gesetzt, wird der Socket die beschreibbare Seite automatisch beenden, wenn die lesbare Seite endet. Wenn die Option socket gesetzt ist, hat diese Option keine Wirkung. Siehe die Option allowHalfOpen von net.Socket für Details. Standard: false.
  • rejectUnauthorized <boolean> Wenn nicht false, wird das Serverzertifikat anhand der Liste der bereitgestellten CAs überprüft. Ein 'error'-Ereignis wird ausgelöst, wenn die Überprüfung fehlschlägt; err.code enthält den OpenSSL-Fehlercode. Standard: true.
  • pskCallback <Function> Für TLS-PSK-Verhandlung, siehe Vorab gemeinsame Schlüssel.
  • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> Ein Array von Strings, Buffers, TypedArrays oder DataViews, oder ein einzelner Buffer, TypedArray oder DataView mit den unterstützten ALPN-Protokollen. Buffer sollten das Format [len][name][len][name]... haben, z.B. '\x08http/1.1\x08http/1.0', wobei das len-Byte die Länge des nächsten Protokollnamens ist. Das Übergeben eines Arrays ist normalerweise viel einfacher, z.B. ['http/1.1', 'http/1.0']. Protokolle, die weiter oben in der Liste stehen, haben eine höhere Priorität als die weiter unten stehenden.
  • servername: <string> Servername für die SNI (Server Name Indication) TLS-Erweiterung. Es ist der Name des Hosts, mit dem eine Verbindung hergestellt wird, und muss ein Hostname und keine IP-Adresse sein. Er kann von einem Multi-Homed-Server verwendet werden, um das richtige Zertifikat auszuwählen, das dem Client präsentiert werden soll. Siehe die Option SNICallback für tls.createServer().
  • checkServerIdentity(servername, cert) <Function> Eine Callback-Funktion, die (anstelle der integrierten tls.checkServerIdentity()-Funktion) verwendet werden soll, wenn der Hostname des Servers (oder der bereitgestellte servername, wenn er explizit gesetzt ist) gegen das Zertifikat geprüft wird. Dies sollte einen <Error> zurückgeben, wenn die Überprüfung fehlschlägt. Die Methode sollte undefined zurückgeben, wenn servername und cert überprüft sind.
  • session <Buffer> Eine Buffer-Instanz, die eine TLS-Sitzung enthält.
  • minDHSize <number> Minimale Größe des DH-Parameters in Bits, um eine TLS-Verbindung zu akzeptieren. Wenn ein Server einen DH-Parameter mit einer Größe kleiner als minDHSize anbietet, wird die TLS-Verbindung zerstört und ein Fehler geworfen. Standard: 1024.
  • highWaterMark: <number> Konsistent mit dem highWaterMark-Parameter des lesbaren Streams. Standard: 16 * 1024.
  • secureContext: TLS-Kontextobjekt, das mit tls.createSecureContext() erstellt wurde. Wenn kein secureContext bereitgestellt wird, wird eines erstellt, indem das gesamte options-Objekt an tls.createSecureContext() übergeben wird.
  • onread <Object> Wenn die Option socket fehlt, werden eingehende Daten in einem einzelnen buffer gespeichert und an den bereitgestellten callback übergeben, wenn Daten auf dem Socket eintreffen, andernfalls wird die Option ignoriert. Siehe die Option onread von net.Socket für Details.
  • ...: tls.createSecureContext() Optionen, die verwendet werden, wenn die Option secureContext fehlt, andernfalls werden sie ignoriert.
  • ...: Jede Option socket.connect(), die noch nicht aufgeführt ist.

• callback <Function>

• Gibt zurück: <tls.TLSSocket>

Die callback-Funktion wird, falls angegeben, als Listener für das 'secureConnect'-Ereignis hinzugefügt.

tls.connect() gibt ein tls.TLSSocket-Objekt zurück.

Im Gegensatz zur https-API aktiviert tls.connect() die SNI (Server Name Indication)-Erweiterung nicht standardmäßig, was dazu führen kann, dass einige Server ein falsches Zertifikat zurückgeben oder die Verbindung ganz ablehnen. Um SNI zu aktivieren, setzen Sie die Option servername zusätzlich zu host.

Das folgende Beispiel zeigt einen Client für das Echo-Server-Beispiel von tls.createServer():

ESM

// Geht von einem Echo-Server aus, der an Port 8000 lauscht.
import { connect } from 'node:tls'
import { readFileSync } from 'node:fs'
import { stdin } from 'node:process'

const options = {
  // Nur notwendig, wenn der Server eine Client-Zertifikatsauthentifizierung erfordert.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // Nur notwendig, wenn der Server ein selbstsigniertes Zertifikat verwendet.
  ca: [readFileSync('server-cert.pem')],

  // Nur notwendig, wenn das Zertifikat des Servers nicht für "localhost" gilt.
  checkServerIdentity: () => {
    return null
  },
}

const socket = connect(8000, options, () => {
  console.log('client connected', socket.authorized ? 'authorized' : 'unauthorized')
  stdin.pipe(socket)
  stdin.resume()
})
socket.setEncoding('utf8')
socket.on('data', data => {
  console.log(data)
})
socket.on('end', () => {
  console.log('server ends connection')
})

CJS

// Geht von einem Echo-Server aus, der an Port 8000 lauscht.
const { connect } = require('node:tls')
const { readFileSync } = require('node:fs')

const options = {
  // Nur notwendig, wenn der Server eine Client-Zertifikatsauthentifizierung erfordert.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // Nur notwendig, wenn der Server ein selbstsigniertes Zertifikat verwendet.
  ca: [readFileSync('server-cert.pem')],

  // Nur notwendig, wenn das Zertifikat des Servers nicht für "localhost" gilt.
  checkServerIdentity: () => {
    return null
  },
}

const socket = connect(8000, options, () => {
  console.log('client connected', socket.authorized ? 'authorized' : 'unauthorized')
  process.stdin.pipe(socket)
  process.stdin.resume()
})
socket.setEncoding('utf8')
socket.on('data', data => {
  console.log(data)
})
socket.on('end', () => {
  console.log('server ends connection')
})

Um das Zertifikat und den Schlüssel für dieses Beispiel zu generieren, führen Sie Folgendes aus:

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout client-key.pem -out client-cert.pem

Um dann das server-cert.pem-Zertifikat für dieses Beispiel zu generieren, führen Sie Folgendes aus:

openssl pkcs12 -certpbe AES-256-CBC -export -out server-cert.pem \
  -inkey client-key.pem -in client-cert.pem

tls.connect(path[, options][, callback])

Hinzugefügt in: v0.11.3

• path <string> Standardwert für options.path.
• options <Object> Siehe tls.connect().
• callback <Function> Siehe tls.connect().
• Gibt zurück: <tls.TLSSocket>

Gleich wie tls.connect(), außer dass path als Argument anstelle einer Option angegeben werden kann.

Eine Pfadoption, falls angegeben, hat Vorrang vor dem Pfadargument.

tls.connect(port[, host][, options][, callback])

Hinzugefügt in: v0.11.3

• port <number> Standardwert für options.port.
• host <string> Standardwert für options.host.
• options <Object> Siehe tls.connect().
• callback <Function> Siehe tls.connect().
• Gibt zurück: <tls.TLSSocket>

Gleich wie tls.connect(), außer dass port und host als Argumente anstelle von Optionen angegeben werden können.

Eine Port- oder Hostoption, falls angegeben, hat Vorrang vor jedem Port- oder Hostargument.

tls.createSecureContext([options])

[Historie]

Version	Änderungen
v22.9.0, v20.18.0	Die Option allowPartialTrustChain wurde hinzugefügt.
v22.4.0, v20.16.0	Die Optionen clientCertEngine, privateKeyEngine und privateKeyIdentifier sind von der Unterstützung benutzerdefinierter Engines in OpenSSL abhängig, die in OpenSSL 3 als veraltet gilt.
v19.8.0, v18.16.0	Die Option dhparam kann jetzt auf 'auto' gesetzt werden, um DHE mit geeigneten, bekannten Parametern zu aktivieren.
v12.12.0	Die Optionen privateKeyIdentifier und privateKeyEngine wurden hinzugefügt, um den privaten Schlüssel von einer OpenSSL-Engine zu erhalten.
v12.11.0	Die Option sigalgs wurde hinzugefügt, um die unterstützten Signaturalgorithmen zu überschreiben.
v12.0.0	TLSv1.3-Unterstützung hinzugefügt.
v11.5.0	Die ca:-Option unterstützt jetzt BEGIN TRUSTED CERTIFICATE.
v11.4.0, v10.16.0	Mit minVersion und maxVersion können die zulässigen TLS-Protokollversionen eingeschränkt werden.
v10.0.0	Die ecdhCurve kann aufgrund einer Änderung in OpenSSL nicht mehr auf false gesetzt werden.
v9.3.0	Der Parameter options kann nun clientCertEngine enthalten.
v9.0.0	Die ecdhCurve-Option kann nun mehrere ':'-getrennte Kurvennamen oder 'auto' sein.
v7.3.0	Wenn die key-Option ein Array ist, benötigen einzelne Einträge keine passphrase-Eigenschaft mehr. Array-Einträge können jetzt auch nur noch strings oder Buffers sein.
v5.2.0	Die ca-Option kann nun ein einzelner String sein, der mehrere CA-Zertifikate enthält.
v0.11.13	Hinzugefügt in: v0.11.13

• options <Object>
  • allowPartialTrustChain <boolean> Behandeln Sie Zwischenzertifikate (nicht selbstsignierte) in der CA-Vertrauenszertifikatsliste als vertrauenswürdig.
  • ca <string> | <string[]> | <Buffer> | <Buffer[]> Überschreiben Sie optional die vertrauenswürdigen CA-Zertifikate. Standardmäßig werden die von Mozilla kuratierten, bekannten CAs als vertrauenswürdig eingestuft. Die CAs von Mozilla werden vollständig ersetzt, wenn CAs explizit mit dieser Option angegeben werden. Der Wert kann eine Zeichenkette oder ein Buffer oder ein Array aus Zeichenketten und/oder Buffers sein. Eine beliebige Zeichenkette oder ein Buffer kann mehrere zusammengefügte PEM-CAs enthalten. Das Zertifikat des Peers muss mit einer CA verkettet werden können, die vom Server für die Authentifizierung der Verbindung als vertrauenswürdig eingestuft wird. Wenn Zertifikate verwendet werden, die nicht mit einer bekannten CA verkettet werden können, muss die CA des Zertifikats explizit als vertrauenswürdig angegeben werden, da die Verbindung sonst nicht authentifiziert werden kann. Wenn der Peer ein Zertifikat verwendet, das nicht mit einer der Standard-CAs übereinstimmt oder nicht mit dieser verkettet werden kann, verwenden Sie die Option ca, um ein CA-Zertifikat bereitzustellen, mit dem das Zertifikat des Peers übereinstimmen oder verkettet werden kann. Bei selbstsignierten Zertifikaten ist das Zertifikat seine eigene CA und muss bereitgestellt werden. Für PEM-kodierte Zertifikate werden die Typen "TRUSTED CERTIFICATE", "X509 CERTIFICATE" und "CERTIFICATE" unterstützt. Siehe auch tls.rootCertificates.
  • cert <string> | <string[]> | <Buffer> | <Buffer[]> Zertifikatsketten im PEM-Format. Pro privatem Schlüssel sollte eine Zertifikatskette bereitgestellt werden. Jede Zertifikatskette sollte aus dem PEM-formatierten Zertifikat für einen bereitgestellten privaten key bestehen, gefolgt von den PEM-formatierten Zwischenzertifikaten (falls vorhanden) in der entsprechenden Reihenfolge und ohne die Root-CA (die Root-CA muss dem Peer bekannt sein, siehe ca). Wenn mehrere Zertifikatsketten bereitgestellt werden, müssen sie nicht in der gleichen Reihenfolge wie ihre privaten Schlüssel in key sein. Wenn die Zwischenzertifikate nicht bereitgestellt werden, kann der Peer das Zertifikat nicht validieren, und der Handshake schlägt fehl.
  • sigalgs <string> Durch Doppelpunkte getrennte Liste der unterstützten Signaturalgorithmen. Die Liste kann Digest-Algorithmen (SHA256, MD5 usw.), Algorithmen für öffentliche Schlüssel (RSA-PSS, ECDSA usw.), eine Kombination aus beiden (z. B. RSA+SHA384) oder TLS v1.3-Schema-Namen (z. B. rsa_pss_pss_sha512) enthalten. Weitere Informationen finden Sie in den OpenSSL-Handbuchseiten.
  • ciphers <string> Chiffrierungs-Suite-Spezifikation, die die Standardeinstellung ersetzt. Weitere Informationen finden Sie unter Ändern der Standard-TLS-Chiffrierungs-Suite. Zulässige Chiffren können über tls.getCiphers() abgerufen werden. Chiffrenamen müssen in Großbuchstaben geschrieben werden, damit OpenSSL sie akzeptiert.
  • clientCertEngine <string> Name einer OpenSSL-Engine, die das Client-Zertifikat bereitstellen kann. Veraltet.
  • crl <string> | <string[]> | <Buffer> | <Buffer[]> PEM-formatierte CRLs (Certificate Revocation Lists).
  • dhparam <string> | <Buffer> 'auto' oder benutzerdefinierte Diffie-Hellman-Parameter, die für nicht-ECDHE perfect forward secrecy erforderlich sind. Wenn sie weggelassen oder ungültig sind, werden die Parameter stillschweigend verworfen und DHE-Chiffren sind nicht verfügbar. ECDHE-basiertes perfect forward secrecy ist weiterhin verfügbar.
  • ecdhCurve <string> Eine Zeichenkette, die eine benannte Kurve oder eine durch Doppelpunkte getrennte Liste von Kurven-NIDs oder -Namen beschreibt, z. B. P-521:P-384:P-256, die für die ECDH-Schlüsselvereinbarung verwendet werden soll. Setzen Sie sie auf auto, um die Kurve automatisch auszuwählen. Verwenden Sie crypto.getCurves(), um eine Liste der verfügbaren Kurvennamen zu erhalten. In den aktuellen Versionen zeigt openssl ecparam -list_curves auch den Namen und die Beschreibung jeder verfügbaren elliptischen Kurve an. Standard: tls.DEFAULT_ECDH_CURVE.
  • honorCipherOrder <boolean> Versuchen Sie, die Chiffrierungssuite-Einstellungen des Servers anstelle der des Clients zu verwenden. Wenn true, wird SSL_OP_CIPHER_SERVER_PREFERENCE in secureOptions gesetzt, siehe OpenSSL-Optionen für weitere Informationen.
  • key <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> Private Schlüssel im PEM-Format. PEM ermöglicht die Option, dass private Schlüssel verschlüsselt werden. Verschlüsselte Schlüssel werden mit options.passphrase entschlüsselt. Es können mehrere Schlüssel mit unterschiedlichen Algorithmen entweder als Array von unverschlüsselten Schlüssel-Strings oder -Puffern oder als Array von Objekten in der Form {pem: \<string|buffer\>[, passphrase: \<string\>]} bereitgestellt werden. Die Objektform kann nur in einem Array vorkommen. object.passphrase ist optional. Verschlüsselte Schlüssel werden mit object.passphrase entschlüsselt, falls angegeben, oder mit options.passphrase, falls nicht.
  • privateKeyEngine <string> Name einer OpenSSL-Engine, aus der der private Schlüssel abgerufen werden soll. Sollte zusammen mit privateKeyIdentifier verwendet werden. Veraltet.
  • privateKeyIdentifier <string> Kennung eines privaten Schlüssels, der von einer OpenSSL-Engine verwaltet wird. Sollte zusammen mit privateKeyEngine verwendet werden. Sollte nicht zusammen mit key gesetzt werden, da beide Optionen einen privaten Schlüssel auf unterschiedliche Weise definieren. Veraltet.
  • maxVersion <string> Legt optional die maximal zulässige TLS-Version fest. Eine von 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' oder 'TLSv1'. Kann nicht zusammen mit der Option secureProtocol angegeben werden; verwenden Sie entweder die eine oder die andere. Standard: tls.DEFAULT_MAX_VERSION.
  • minVersion <string> Legt optional die minimal zulässige TLS-Version fest. Eine von 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' oder 'TLSv1'. Kann nicht zusammen mit der Option secureProtocol angegeben werden; verwenden Sie entweder die eine oder die andere. Vermeiden Sie es, die Version auf weniger als TLSv1.2 zu setzen, aber dies kann für die Interoperabilität erforderlich sein. Für Versionen vor TLSv1.2 kann es erforderlich sein, das OpenSSL-Sicherheitsniveau herabzusetzen. Standard: tls.DEFAULT_MIN_VERSION.
  • passphrase <string> Gemeinsame Passphrase, die für einen einzelnen privaten Schlüssel und/oder eine PFX verwendet wird.
  • pfx <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> PFX- oder PKCS12-codierter privater Schlüssel und Zertifikatskette. pfx ist eine Alternative zur einzelnen Bereitstellung von key und cert. PFX ist normalerweise verschlüsselt, und wenn dies der Fall ist, wird passphrase verwendet, um es zu entschlüsseln. Es können mehrere PFX entweder als Array von unverschlüsselten PFX-Puffern oder als Array von Objekten in der Form {buf: \<string|buffer\>[, passphrase: \<string\>]} bereitgestellt werden. Die Objektform kann nur in einem Array vorkommen. object.passphrase ist optional. Verschlüsselte PFX werden mit object.passphrase entschlüsselt, falls angegeben, oder mit options.passphrase, falls nicht.
  • secureOptions <number> Beeinflusst optional das OpenSSL-Protokollverhalten, was normalerweise nicht erforderlich ist. Dies sollte mit Vorsicht verwendet werden, wenn überhaupt! Der Wert ist eine numerische Bitmaske der SSL_OP_*-Optionen aus OpenSSL-Optionen.
  • secureProtocol <string> Legacy-Mechanismus zur Auswahl der zu verwendenden TLS-Protokollversion, der keine unabhängige Steuerung der minimalen und maximalen Version unterstützt und die Einschränkung des Protokolls auf TLSv1.3 nicht unterstützt. Verwenden Sie stattdessen minVersion und maxVersion. Die möglichen Werte sind als SSL_METHODS aufgelistet, verwenden Sie die Funktionsnamen als Zeichenketten. Verwenden Sie beispielsweise 'TLSv1_1_method', um TLS-Version 1.1 zu erzwingen, oder 'TLS_method', um jede TLS-Protokollversion bis zu TLSv1.3 zuzulassen. Es wird nicht empfohlen, TLS-Versionen unter 1.2 zu verwenden, aber dies kann für die Interoperabilität erforderlich sein. Standard: keine, siehe minVersion.
  • sessionIdContext <string> Opake Kennung, die von Servern verwendet wird, um sicherzustellen, dass der Sitzungsstatus nicht zwischen Anwendungen geteilt wird. Wird von Clients nicht verwendet.
  • ticketKeys: <Buffer> 48 Byte kryptographisch starker, pseudozufälliger Daten. Weitere Informationen finden Sie unter Session Resumption.
  • sessionTimeout <number> Die Anzahl der Sekunden, nach denen eine vom Server erstellte TLS-Sitzung nicht mehr fortgesetzt werden kann. Weitere Informationen finden Sie unter Session Resumption. Standard: 300.

tls.createServer() setzt den Standardwert der Option honorCipherOrder auf true, andere APIs, die sichere Kontexte erstellen, lassen sie ungesetzt.

tls.createServer() verwendet einen 128-Bit-abgeschnittenen SHA1-Hashwert, der aus process.argv generiert wird, als Standardwert der Option sessionIdContext, andere APIs, die sichere Kontexte erstellen, haben keinen Standardwert.

Die Methode tls.createSecureContext() erstellt ein SecureContext-Objekt. Es kann als Argument für mehrere tls-APIs verwendet werden, z. B. server.addContext(), hat aber keine öffentlichen Methoden. Der Konstruktor tls.Server und die Methode tls.createServer() unterstützen die Option secureContext nicht.

Ein Schlüssel ist erforderlich für Chiffren, die Zertifikate verwenden. Entweder key oder pfx können verwendet werden, um ihn bereitzustellen.

Wenn die Option ca nicht angegeben wird, verwendet Node.js standardmäßig die öffentlich vertrauenswürdige CA-Liste von Mozilla.

Benutzerdefinierte DHE-Parameter sind nicht empfehlenswert, stattdessen sollte die neue Option dhparam: 'auto' verwendet werden. Wenn sie auf 'auto' gesetzt ist, werden automatisch bekannte DHE-Parameter mit ausreichender Stärke ausgewählt. Andernfalls kann, falls erforderlich, openssl dhparam verwendet werden, um benutzerdefinierte Parameter zu erstellen. Die Schlüssellänge muss größer oder gleich 1024 Bit sein, andernfalls wird ein Fehler ausgegeben. Obwohl 1024 Bit zulässig sind, sollten für eine stärkere Sicherheit 2048 Bit oder mehr verwendet werden.

tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])

[Verlauf]

Version	Änderungen
v5.0.0	ALPN-Optionen werden jetzt unterstützt.
v0.11.3	Veraltet seit: v0.11.3
v0.3.2	Hinzugefügt in: v0.3.2

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet: Verwenden Sie stattdessen tls.TLSSocket.

• context <Object> Ein sicheres Kontextobjekt, das von tls.createSecureContext() zurückgegeben wird.
• isServer <boolean> true, um anzugeben, dass diese TLS-Verbindung als Server geöffnet werden soll.
• requestCert <boolean> true, um anzugeben, ob ein Server ein Zertifikat von einem sich verbindenden Client anfordern soll. Gilt nur, wenn isServer true ist.
• rejectUnauthorized <boolean> Wenn nicht false, lehnt ein Server Clients mit ungültigen Zertifikaten automatisch ab. Gilt nur, wenn isServer true ist.
• options
  • enableTrace: Siehe tls.createServer()
  • secureContext: Ein TLS-Kontextobjekt von tls.createSecureContext()
  • isServer: Wenn true, wird der TLS-Socket im Servermodus instanziiert. Standard: false.
  • server <net.Server> Eine net.Server-Instanz
  • requestCert: Siehe tls.createServer()
  • rejectUnauthorized: Siehe tls.createServer()
  • ALPNProtocols: Siehe tls.createServer()
  • SNICallback: Siehe tls.createServer()
  • session <Buffer> Eine Buffer-Instanz, die eine TLS-Sitzung enthält.
  • requestOCSP <boolean> Wenn true, wird angegeben, dass die OCSP-Statusanforderungserweiterung zum Client Hello hinzugefügt wird und ein 'OCSPResponse'-Ereignis auf dem Socket ausgelöst wird, bevor eine sichere Kommunikation aufgebaut wird.

Erstellt ein neues sicheres Paarobjekt mit zwei Streams, von denen einer die verschlüsselten Daten liest und schreibt und der andere die Klartextdaten liest und schreibt. Im Allgemeinen wird der verschlüsselte Stream zu/von einem eingehenden verschlüsselten Datenstrom geleitet, und der Klartext-Stream wird als Ersatz für den anfänglichen verschlüsselten Stream verwendet.

tls.createSecurePair() gibt ein tls.SecurePair-Objekt mit den Stream-Eigenschaften cleartext und encrypted zurück.

Die Verwendung von cleartext hat die gleiche API wie tls.TLSSocket.

Die Methode tls.createSecurePair() ist jetzt zugunsten von tls.TLSSocket() veraltet. Zum Beispiel kann der Code:

pair = tls.createSecurePair(/* ... */)
pair.encrypted.pipe(socket)
socket.pipe(pair.encrypted)

ersetzt werden durch:

secureSocket = tls.TLSSocket(socket, options)

wobei secureSocket die gleiche API wie pair.cleartext hat.

tls.createServer([options][, secureConnectionListener])

[Verlauf]

Version	Änderungen
v22.4.0, v20.16.0	Die Option clientCertEngine hängt von der Unterstützung benutzerdefinierter Engines in OpenSSL ab, die in OpenSSL 3 als veraltet gilt.
v19.0.0	Wenn ALPNProtocols gesetzt ist, werden eingehende Verbindungen, die eine ALPN-Erweiterung ohne unterstützte Protokolle senden, mit einer fatalen no_application_protocol-Warnung beendet.
v20.4.0, v18.19.0	Der Parameter options kann jetzt ALPNCallback enthalten.
v12.3.0	Der Parameter options unterstützt jetzt net.createServer()-Optionen.
v9.3.0	Der Parameter options kann jetzt clientCertEngine enthalten.
v8.0.0	Die Option ALPNProtocols kann jetzt ein TypedArray oder DataView sein.
v5.0.0	ALPN-Optionen werden jetzt unterstützt.
v0.3.2	Hinzugefügt in: v0.3.2

• options <Object>

  • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> Ein Array von Strings, Buffers, TypedArrays oder DataViews oder ein einzelner Buffer, TypedArray oder DataView, der die unterstützten ALPN-Protokolle enthält. Buffers sollten das Format [len][name][len][name]... haben, z.B. 0x05hello0x05world, wobei das erste Byte die Länge des nächsten Protokollnamens ist. Das Übergeben eines Arrays ist in der Regel viel einfacher, z.B. ['hello', 'world']. (Protokolle sollten nach ihrer Priorität geordnet sein.)
  • ALPNCallback: <Function> Wenn diese Option gesetzt ist, wird sie aufgerufen, wenn ein Client eine Verbindung mit der ALPN-Erweiterung öffnet. Ein Argument wird an den Callback übergeben: ein Objekt mit den Feldern servername und protocols, die jeweils den Servernamen aus der SNI-Erweiterung (falls vorhanden) und ein Array von ALPN-Protokollnamen-Strings enthalten. Der Callback muss entweder einen der in protocols aufgeführten Strings zurückgeben, der dem Client als ausgewähltes ALPN-Protokoll zurückgegeben wird, oder undefined, um die Verbindung mit einer fatalen Warnung abzulehnen. Wenn ein String zurückgegeben wird, der nicht mit einem der ALPN-Protokolle des Clients übereinstimmt, wird ein Fehler ausgelöst. Diese Option kann nicht mit der Option ALPNProtocols verwendet werden, und das Setzen beider Optionen führt zu einem Fehler.
  • clientCertEngine <string> Name einer OpenSSL-Engine, die das Client-Zertifikat bereitstellen kann. Veraltet.
  • enableTrace <boolean> Wenn true, wird tls.TLSSocket.enableTrace() bei neuen Verbindungen aufgerufen. Die Ablaufverfolgung kann aktiviert werden, nachdem die sichere Verbindung hergestellt wurde, aber diese Option muss verwendet werden, um die Einrichtung der sicheren Verbindung zu verfolgen. Standard: false.
  • handshakeTimeout <number> Die Verbindung wird abgebrochen, wenn der SSL/TLS-Handshake nicht innerhalb der angegebenen Anzahl von Millisekunden abgeschlossen ist. Ein 'tlsClientError' wird auf dem tls.Server-Objekt ausgegeben, wenn ein Handshake abläuft. Standard: 120000 (120 Sekunden).
  • rejectUnauthorized <boolean> Wenn nicht false, lehnt der Server jede Verbindung ab, die nicht mit der Liste der mitgelieferten CAs autorisiert ist. Diese Option hat nur dann eine Auswirkung, wenn requestCert true ist. Standard: true.
  • requestCert <boolean> Wenn true, fordert der Server ein Zertifikat von Clients an, die sich verbinden, und versucht, dieses Zertifikat zu verifizieren. Standard: false.
  • sessionTimeout <number> Die Anzahl der Sekunden, nach denen eine vom Server erstellte TLS-Sitzung nicht mehr wieder aufgenommen werden kann. Weitere Informationen finden Sie unter Sitzungswiederaufnahme. Standard: 300.
  • SNICallback(servername, callback) <Function> Eine Funktion, die aufgerufen wird, wenn der Client die SNI-TLS-Erweiterung unterstützt. Beim Aufruf werden zwei Argumente übergeben: servername und callback. callback ist ein Error-First-Callback, der zwei optionale Argumente entgegennimmt: error und ctx. ctx ist, falls vorhanden, eine SecureContext-Instanz. tls.createSecureContext() kann verwendet werden, um einen korrekten SecureContext zu erhalten. Wenn callback mit einem Falsy-Argument ctx aufgerufen wird, wird der Standard-Sicherheitskontext des Servers verwendet. Wenn SNICallback nicht bereitgestellt wurde, wird der Standard-Callback mit High-Level-API verwendet (siehe unten).
  • ticketKeys: <Buffer> 48 Byte kryptografisch starke pseudozufällige Daten. Weitere Informationen finden Sie unter Sitzungswiederaufnahme.
  • pskCallback <Function> Für die TLS-PSK-Aushandlung siehe Pre-Shared Keys.
  • pskIdentityHint <string> Optionaler Hinweis, der an einen Client gesendet wird, um die Auswahl der Identität während der TLS-PSK-Aushandlung zu erleichtern. Wird in TLS 1.3 ignoriert. Wenn pskIdentityHint nicht festgelegt werden kann, wird 'tlsClientError' mit dem Code 'ERR_TLS_PSK_SET_IDENTITY_HINT_FAILED' ausgegeben.
  • ...: Jede tls.createSecureContext()-Option kann angegeben werden. Für Server sind die Identitätsoptionen (pfx, key/cert oder pskCallback) normalerweise erforderlich.
  • ...: Jede net.createServer()-Option kann angegeben werden.

• secureConnectionListener <Function>

• Gibt zurück: <tls.Server>

Erstellt einen neuen tls.Server. Der secureConnectionListener wird, falls angegeben, automatisch als Listener für das Ereignis 'secureConnection' gesetzt.

Die Option ticketKeys wird automatisch zwischen den Worker des Moduls node:cluster geteilt.

Das folgende Beispiel veranschaulicht einen einfachen Echo-Server:

ESM

import { createServer } from 'node:tls'
import { readFileSync } from 'node:fs'

const options = {
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),

  // Dies ist nur erforderlich, wenn die Client-Zertifikatsauthentifizierung verwendet wird.
  requestCert: true,

  // Dies ist nur erforderlich, wenn der Client ein selbstsigniertes Zertifikat verwendet.
  ca: [readFileSync('client-cert.pem')],
}

const server = createServer(options, socket => {
  console.log('server verbunden', socket.authorized ? 'autorisiert' : 'nicht autorisiert')
  socket.write('willkommen!\n')
  socket.setEncoding('utf8')
  socket.pipe(socket)
})
server.listen(8000, () => {
  console.log('server gebunden')
})

CJS

const { createServer } = require('node:tls')
const { readFileSync } = require('node:fs')

const options = {
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),

  // Dies ist nur erforderlich, wenn die Client-Zertifikatsauthentifizierung verwendet wird.
  requestCert: true,

  // Dies ist nur erforderlich, wenn der Client ein selbstsigniertes Zertifikat verwendet.
  ca: [readFileSync('client-cert.pem')],
}

const server = createServer(options, socket => {
  console.log('server verbunden', socket.authorized ? 'autorisiert' : 'nicht autorisiert')
  socket.write('willkommen!\n')
  socket.setEncoding('utf8')
  socket.pipe(socket)
})
server.listen(8000, () => {
  console.log('server gebunden')
})

Um das Zertifikat und den Schlüssel für dieses Beispiel zu generieren, führen Sie Folgendes aus:

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout server-key.pem -out server-cert.pem

Um dann das Zertifikat client-cert.pem für dieses Beispiel zu generieren, führen Sie Folgendes aus:

openssl pkcs12 -certpbe AES-256-CBC -export -out client-cert.pem \
  -inkey server-key.pem -in server-cert.pem

Der Server kann getestet werden, indem man sich mit dem Beispielclient von tls.connect() verbindet.

tls.getCiphers()

Hinzugefügt in: v0.10.2

• Gibt zurück: <string[]>

Gibt ein Array mit den Namen der unterstützten TLS-Chiffren zurück. Die Namen sind aus historischen Gründen kleingeschrieben, müssen aber in Großbuchstaben geschrieben werden, um in der Option ciphers von tls.createSecureContext() verwendet zu werden.

Nicht alle unterstützten Chiffren sind standardmäßig aktiviert. Siehe Ändern der Standard-TLS-Chiffrensuite.

Chiffrennamen, die mit 'tls_' beginnen, sind für TLSv1.3, alle anderen sind für TLSv1.2 und darunter.

console.log(tls.getCiphers()) // ['aes128-gcm-sha256', 'aes128-sha', ...]

tls.rootCertificates

Hinzugefügt in: v12.3.0

• <string[]>

Ein unveränderliches Array von Strings, die die Root-Zertifikate (im PEM-Format) aus dem gebündelten Mozilla CA-Store darstellen, wie sie von der aktuellen Node.js-Version bereitgestellt werden.

Der von Node.js bereitgestellte gebündelte CA-Store ist eine Momentaufnahme des Mozilla CA-Stores, die zum Zeitpunkt der Veröffentlichung festgelegt wird. Er ist auf allen unterstützten Plattformen identisch.

tls.DEFAULT_ECDH_CURVE

[Historie]

Version	Änderungen
v10.0.0	Der Standardwert wurde auf 'auto' geändert.
v0.11.13	Hinzugefügt in: v0.11.13

Der Standardkurvenname für die ECDH-Schlüsselaushandlung in einem TLS-Server. Der Standardwert ist 'auto'. Weitere Informationen finden Sie unter tls.createSecureContext().

tls.DEFAULT_MAX_VERSION

Hinzugefügt in: v11.4.0

• <string> Der Standardwert der Option maxVersion von tls.createSecureContext(). Es kann eine der unterstützten TLS-Protokollversionen zugewiesen werden: 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' oder 'TLSv1'. Standard: 'TLSv1.3', sofern nicht durch CLI-Optionen geändert. Mit --tls-max-v1.2 wird der Standardwert auf 'TLSv1.2' gesetzt. Mit --tls-max-v1.3 wird der Standardwert auf 'TLSv1.3' gesetzt. Wenn mehrere Optionen angegeben werden, wird das höchste Maximum verwendet.

tls.DEFAULT_MIN_VERSION

Hinzugefügt in: v11.4.0

• <string> Der Standardwert der Option minVersion von tls.createSecureContext(). Er kann auf eine der unterstützten TLS-Protokollversionen gesetzt werden: 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' oder 'TLSv1'. Versionen vor TLSv1.2 erfordern möglicherweise eine Herabstufung des OpenSSL-Sicherheitslevels. Standard: 'TLSv1.2', sofern nicht über CLI-Optionen geändert. Die Verwendung von --tls-min-v1.0 setzt den Standard auf 'TLSv1'. Die Verwendung von --tls-min-v1.1 setzt den Standard auf 'TLSv1.1'. Die Verwendung von --tls-min-v1.3 setzt den Standard auf 'TLSv1.3'. Wenn mehrere Optionen angegeben werden, wird das niedrigste Minimum verwendet.

tls.DEFAULT_CIPHERS

Hinzugefügt in: v19.8.0, v18.16.0

• <string> Der Standardwert der Option ciphers von tls.createSecureContext(). Er kann auf eine der unterstützten OpenSSL-Verschlüsselungen gesetzt werden. Der Standardwert ist der Inhalt von crypto.constants.defaultCoreCipherList, sofern nicht über CLI-Optionen mit --tls-default-ciphers geändert.