HTTPS

[Stable: 2 - Stabil]

HTTPS ist das HTTP-Protokoll über TLS/SSL. In Node.js ist dies als separates Modul implementiert.

Feststellen, ob die Krypto-Unterstützung nicht verfügbar ist

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

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

let https;
try {
  https = require('node:https');
} catch (err) {
  console.error('https-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. mithilfe eines Preload-Moduls).

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 https;
try {
  https = await import('node:https');
} catch (err) {
  console.error('https-Unterstützung ist deaktiviert!');
}

Klasse: `https.Agent`

[Verlauf]

Version	Änderungen
v5.3.0	Unterstützung für `0` `maxCachedSessions` zum Deaktivieren des TLS-Sitzungs-Cachings.
v2.5.0	Parameter `maxCachedSessions` zu `options` für die Wiederverwendung von TLS-Sitzungen hinzugefügt.
v0.4.5	Hinzugefügt in: v0.4.5

Ein Agent-Objekt für HTTPS, ähnlich wie http.Agent. Weitere Informationen finden Sie unter https.request().

`new Agent([options])`

[Verlauf]

Version	Änderungen
v12.5.0	servername nicht automatisch setzen, wenn der Zielhost über eine IP-Adresse angegeben wurde.

options <Object> Satz von konfigurierbaren Optionen, die für den Agenten festgelegt werden sollen. Kann die gleichen Felder wie für http.Agent(options) haben, und
- maxCachedSessions <number> maximale Anzahl von zwischengespeicherten TLS-Sitzungen. Verwenden Sie 0, um das TLS-Sitzungs-Caching zu deaktivieren. Standard: 100.
- servername <string> der Wert der Server Name Indication extension, die an den Server gesendet werden soll. Verwenden Sie die leere Zeichenfolge '', um das Senden der Erweiterung zu deaktivieren. Standard: Hostname des Zielservers, es sei denn, der Zielserver wird über eine IP-Adresse angegeben. In diesem Fall ist der Standardwert '' (keine Erweiterung). Informationen zur Wiederverwendung von TLS-Sitzungen finden Sie unter Session Resumption.

Ereignis: `'keylog'`

Hinzugefügt in: v13.2.0, v12.16.0

line <Buffer> Zeile mit 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 generiert oder empfangen wird, die von diesem Agenten verwaltet wird (typischerweise bevor der Handshake abgeschlossen ist, aber nicht unbedingt). Dieses Schlüsselmaterial kann zur Fehlersuche gespeichert werden, da es ermöglicht, den erfassten TLS-Traffic zu entschlüsseln. 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) verwendet wird, um den Traffic zu entschlüsseln:

// ...
https.globalAgent.on('keylog', (line, tlsSocket) => {
  fs.appendFileSync('/tmp/ssl-keys.log', line, { mode: 0o600 });
});

Klasse: `https.Server`

Hinzugefügt in: v0.3.4

Erweitert: <tls.Server>

Siehe http.Server für weitere Informationen.

`server.close([callback])`

Hinzugefügt in: v0.1.90

callback <Function>
Gibt zurück: <https.Server>

Siehe server.close() im node:http-Modul.

`server[Symbol.asyncDispose]()`

Hinzugefügt in: v20.4.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Ruft server.close() auf und gibt ein Promise zurück, das erfüllt wird, wenn der Server geschlossen wurde.

`server.closeAllConnections()`

Hinzugefügt in: v18.2.0

Siehe server.closeAllConnections() im node:http-Modul.

`server.closeIdleConnections()`

Hinzugefügt in: v18.2.0

Siehe server.closeIdleConnections() im node:http-Modul.

`server.headersTimeout`

Hinzugefügt in: v11.3.0

<number> Standardwert: 60000

Siehe server.headersTimeout im node:http-Modul.

`server.listen()`

Startet den HTTPS-Server, um auf verschlüsselte Verbindungen zu warten. Diese Methode ist identisch mit server.listen() von net.Server.

`server.maxHeadersCount`

<number> Standardwert: 2000

Siehe server.maxHeadersCount im node:http-Modul.

`server.requestTimeout`

[Verlauf]

Version	Änderungen
v18.0.0	Das Standard-Request-Timeout wurde von keinem Timeout auf 300 Sekunden (5 Minuten) geändert.
v14.11.0	Hinzugefügt in: v14.11.0

<number> Standardwert: 300000

Siehe server.requestTimeout im node:http-Modul.

`server.setTimeout([msecs][, callback])`

Hinzugefügt in: v0.11.2

msecs <number> Standardwert: 120000 (2 Minuten)
callback <Function>
Rückgabe: <https.Server>

Siehe server.setTimeout() im node:http-Modul.

`server.timeout`

[Verlauf]

Version	Änderungen
v13.0.0	Das Standard-Timeout wurde von 120 Sekunden auf 0 (kein Timeout) geändert.
v0.11.2	Hinzugefügt in: v0.11.2

<number> Standardwert: 0 (kein Timeout)

Siehe server.timeout im node:http-Modul.

`server.keepAliveTimeout`

Hinzugefügt in: v8.0.0

<number> Standardwert: 5000 (5 Sekunden)

Siehe server.keepAliveTimeout im Modul node:http.

`https.createServer([options][, requestListener])`

Hinzugefügt in: v0.3.4

options <Object> Akzeptiert options von tls.createServer(), tls.createSecureContext() und http.createServer().
requestListener <Function> Ein Listener, der dem 'request'-Ereignis hinzugefügt werden soll.
Gibt zurück: <https.Server>

ESMCJS

// curl -k https://localhost:8000/
import { createServer } from 'node:https';
import { readFileSync } from 'node:fs';

const options = {
  key: readFileSync('private-key.pem'),
  cert: readFileSync('certificate.pem'),
};

createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('hello world\n');
}).listen(8000);

// curl -k https://localhost:8000/
const https = require('node:https');
const fs = require('node:fs');

const options = {
  key: fs.readFileSync('private-key.pem'),
  cert: fs.readFileSync('certificate.pem'),
};

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('hello world\n');
}).listen(8000);

Oder

ESMCJS

import { createServer } from 'node:https';
import { readFileSync } from 'node:fs';

const options = {
  pfx: readFileSync('test_cert.pfx'),
  passphrase: 'sample',
};

createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('hello world\n');
}).listen(8000);

const https = require('node:https');
const fs = require('node:fs');

const options = {
  pfx: fs.readFileSync('test_cert.pfx'),
  passphrase: 'sample',
};

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('hello world\n');
}).listen(8000);

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

bash

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

Um das pfx-Zertifikat für dieses Beispiel zu generieren, führen Sie Folgendes aus:

bash

openssl pkcs12 -certpbe AES-256-CBC -export -out test_cert.pfx \
  -inkey private-key.pem -in certificate.pem -passout pass:sample

`https.get(options[, callback])`

`https.get(url[, options][, callback])`

[Verlauf]

Version	Änderungen
v10.9.0	Der Parameter `url` kann jetzt zusammen mit einem separaten `options`-Objekt übergeben werden.
v7.5.0	Der Parameter `options` kann ein WHATWG `URL`-Objekt sein.
v0.3.6	Hinzugefügt in: v0.3.6

url <string> | <URL>
options <Object> | <string> | <URL> Akzeptiert die gleichen options wie https.request(), wobei die Methode standardmäßig auf GET gesetzt ist.
callback <Function>

Wie http.get(), aber für HTTPS.

options kann ein Objekt, eine Zeichenkette oder ein URL-Objekt sein. Wenn options eine Zeichenkette ist, wird sie automatisch mit new URL() geparst. Wenn es sich um ein URL-Objekt handelt, wird es automatisch in ein gewöhnliches options-Objekt konvertiert.

ESMCJS

import { get } from 'node:https';
import process from 'node:process';

get('https://encrypted.google.com/', (res) => {
  console.log('statusCode:', res.statusCode);
  console.log('headers:', res.headers);

  res.on('data', (d) => {
    process.stdout.write(d);
  });

}).on('error', (e) => {
  console.error(e);
});

const https = require('node:https');

https.get('https://encrypted.google.com/', (res) => {
  console.log('statusCode:', res.statusCode);
  console.log('headers:', res.headers);

  res.on('data', (d) => {
    process.stdout.write(d);
  });

}).on('error', (e) => {
  console.error(e);
});

`https.globalAgent`

[Verlauf]

Version	Änderungen
v19.0.0	Der Agent verwendet jetzt standardmäßig HTTP Keep-Alive und ein Timeout von 5 Sekunden.
v0.5.9	Hinzugefügt in: v0.5.9

Globale Instanz von https.Agent für alle HTTPS-Clientanfragen. Weicht von einer Standardkonfiguration https.Agent ab, indem keepAlive aktiviert ist und ein Timeout von 5 Sekunden festgelegt ist.

`https.request(options[, callback])`

`https.request(url[, options][, callback])`

[Verlauf]

Version	Änderungen
v22.4.0, v20.16.0	Die Option `clientCertEngine` hängt von der benutzerdefinierten Engine-Unterstützung in OpenSSL ab, die in OpenSSL 3 als veraltet gilt.
v16.7.0, v14.18.0	Bei Verwendung eines `URL`-Objekts werden geparste Benutzername und Passwort jetzt korrekt URI-dekodiert.
v14.1.0, v13.14.0	Die Option `highWaterMark` wird jetzt akzeptiert.
v10.9.0	Der Parameter `url` kann jetzt zusammen mit einem separaten `options`-Objekt übergeben werden.
v9.3.0	Der Parameter `options` kann jetzt `clientCertEngine` enthalten.
v7.5.0	Der Parameter `options` kann ein WHATWG `URL`-Objekt sein.
v0.3.6	Hinzugefügt in: v0.3.6

url <string> | <URL>
options <Object> | <string> | <URL> Akzeptiert alle options von http.request(), mit einigen Unterschieden in den Standardwerten:
- protocol Standard: 'https:'
- port Standard: 443
- agent Standard: https.globalAgent
callback <Function>
Rückgabe: <http.ClientRequest>

Sendet eine Anfrage an einen sicheren Webserver.

Die folgenden zusätzlichen options von tls.connect() werden ebenfalls akzeptiert: ca, cert, ciphers, clientCertEngine (deprecated), crl, dhparam, ecdhCurve, honorCipherOrder, key, passphrase, pfx, rejectUnauthorized, secureOptions, secureProtocol, servername, sessionIdContext, highWaterMark.

options kann ein Objekt, ein String oder ein URL-Objekt sein. Wenn options ein String ist, wird er automatisch mit new URL() geparst. Wenn es sich um ein URL-Objekt handelt, wird es automatisch in ein normales options-Objekt konvertiert.

https.request() gibt eine Instanz der Klasse http.ClientRequest zurück. Die ClientRequest-Instanz ist ein beschreibbarer Stream. Wenn eine Datei mit einer POST-Anfrage hochgeladen werden muss, schreiben Sie in das ClientRequest-Objekt.

ESMCJS

import { request } from 'node:https';
import process from 'node:process';

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
};

const req = request(options, (res) => {
  console.log('statusCode:', res.statusCode);
  console.log('headers:', res.headers);

  res.on('data', (d) => {
    process.stdout.write(d);
  });
});

req.on('error', (e) => {
  console.error(e);
});
req.end();

const https = require('node:https');

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
};

const req = https.request(options, (res) => {
  console.log('statusCode:', res.statusCode);
  console.log('headers:', res.headers);

  res.on('data', (d) => {
    process.stdout.write(d);
  });
});

req.on('error', (e) => {
  console.error(e);
});
req.end();

Beispiel für die Verwendung von Optionen aus tls.connect():

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
  key: fs.readFileSync('private-key.pem'),
  cert: fs.readFileSync('certificate.pem'),
};
options.agent = new https.Agent(options);

const req = https.request(options, (res) => {
  // ...
});

Alternativ können Sie Connection Pooling deaktivieren, indem Sie keinen Agent verwenden.

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
  key: fs.readFileSync('private-key.pem'),
  cert: fs.readFileSync('certificate.pem'),
  agent: false,
};

const req = https.request(options, (res) => {
  // ...
});

Beispiel für die Verwendung einer URL als options:

const options = new URL('https://abc:');

const req = https.request(options, (res) => {
  // ...
});

Beispiel für das Pinnen am Zertifikats-Fingerabdruck oder am öffentlichen Schlüssel (ähnlich wie pin-sha256):

ESMCJS

import { checkServerIdentity } from 'node:tls';
import { Agent, request } from 'node:https';
import { createHash } from 'node:crypto';

function sha256(s) {
  return createHash('sha256').update(s).digest('base64');
}
const options = {
  hostname: 'github.com',
  port: 443,
  path: '/',
  method: 'GET',
  checkServerIdentity: function(host, cert) {
    // Make sure the certificate is issued to the host we are connected to
    const err = checkServerIdentity(host, cert);
    if (err) {
      return err;
    }

    // Pin the public key, similar to HPKP pin-sha256 pinning
    const pubkey256 = 'SIXvRyDmBJSgatgTQRGbInBaAK+hZOQ18UmrSwnDlK8=';
    if (sha256(cert.pubkey) !== pubkey256) {
      const msg = 'Certificate verification error: ' +
        `The public key of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      return new Error(msg);
    }

    // Pin the exact certificate, rather than the pub key
    const cert256 = 'FD:6E:9B:0E:F3:98:BC:D9:04:C3:B2:EC:16:7A:7B:' +
      '0F:DA:72:01:C9:03:C5:3A:6A:6A:E5:D0:41:43:63:EF:65';
    if (cert.fingerprint256 !== cert256) {
      const msg = 'Certificate verification error: ' +
        `The certificate of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      return new Error(msg);
    }

    // This loop is informational only.
    // Print the certificate and public key fingerprints of all certs in the
    // chain. Its common to pin the public key of the issuer on the public
    // internet, while pinning the public key of the service in sensitive
    // environments.
    let lastprint256;
    do {
      console.log('Subject Common Name:', cert.subject.CN);
      console.log('  Certificate SHA256 fingerprint:', cert.fingerprint256);

      const hash = createHash('sha256');
      console.log('  Public key ping-sha256:', sha256(cert.pubkey));

      lastprint256 = cert.fingerprint256;
      cert = cert.issuerCertificate;
    } while (cert.fingerprint256 !== lastprint256);

  },
};

options.agent = new Agent(options);
const req = request(options, (res) => {
  console.log('All OK. Server matched our pinned cert or public key');
  console.log('statusCode:', res.statusCode);

  res.on('data', (d) => {});
});

req.on('error', (e) => {
  console.error(e.message);
});
req.end();

const tls = require('node:tls');
const https = require('node:https');
const crypto = require('node:crypto');

function sha256(s) {
  return crypto.createHash('sha256').update(s).digest('base64');
}
const options = {
  hostname: 'github.com',
  port: 443,
  path: '/',
  method: 'GET',
  checkServerIdentity: function(host, cert) {
    // Make sure the certificate is issued to the host we are connected to
    const err = tls.checkServerIdentity(host, cert);
    if (err) {
      return err;
    }

    // Pin the public key, similar to HPKP pin-sha256 pinning
    const pubkey256 = 'SIXvRyDmBJSgatgTQRGbInBaAK+hZOQ18UmrSwnDlK8=';
    if (sha256(cert.pubkey) !== pubkey256) {
      const msg = 'Certificate verification error: ' +
        `The public key of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      return new Error(msg);
    }

    // Pin the exact certificate, rather than the pub key
    const cert256 = 'FD:6E:9B:0E:F3:98:BC:D9:04:C3:B2:EC:16:7A:7B:' +
      '0F:DA:72:01:C9:03:C5:3A:6A:6A:E5:D0:41:43:63:EF:65';
    if (cert.fingerprint256 !== cert256) {
      const msg = 'Certificate verification error: ' +
        `The certificate of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      return new Error(msg);
    }

    // This loop is informational only.
    // Print the certificate and public key fingerprints of all certs in the
    // chain. Its common to pin the public key of the issuer on the public
    // internet, while pinning the public key of the service in sensitive
    // environments.
    do {
      console.log('Subject Common Name:', cert.subject.CN);
      console.log('  Certificate SHA256 fingerprint:', cert.fingerprint256);

      hash = crypto.createHash('sha256');
      console.log('  Public key ping-sha256:', sha256(cert.pubkey));

      lastprint256 = cert.fingerprint256;
      cert = cert.issuerCertificate;
    } while (cert.fingerprint256 !== lastprint256);

  },
};

options.agent = new https.Agent(options);
const req = https.request(options, (res) => {
  console.log('All OK. Server matched our pinned cert or public key');
  console.log('statusCode:', res.statusCode);

  res.on('data', (d) => {});
});

req.on('error', (e) => {
  console.error(e.message);
});
req.end();

Beispiele für Ausgaben:

text

Subject Common Name: github.com
  Certificate SHA256 fingerprint: FD:6E:9B:0E:F3:98:BC:D9:04:C3:B2:EC:16:7A:7B:0F:DA:72:01:C9:03:C5:3A:6A:6A:E5:D0:41:43:63:EF:65
  Public key ping-sha256: SIXvRyDmBJSgatgTQRGbInBaAK+hZOQ18UmrSwnDlK8=
Subject Common Name: Sectigo ECC Domain Validation Secure Server CA
  Certificate SHA256 fingerprint: 61:E9:73:75:E9:F6:DA:98:2F:F5:C1:9E:2F:94:E6:6C:4E:35:B6:83:7C:E3:B9:14:D2:24:5C:7F:5F:65:82:5F
  Public key ping-sha256: Eep0p/AsSa9lFUH6KT2UY+9s1Z8v7voAPkQ4fGknZ2g=
Subject Common Name: USERTrust ECC Certification Authority
  Certificate SHA256 fingerprint: A6:CF:64:DB:B4:C8:D5:FD:19:CE:48:89:60:68:DB:03:B5:33:A8:D1:33:6C:62:56:A8:7D:00:CB:B3:DE:F3:EA
  Public key ping-sha256: UJM2FOhG9aTNY0Pg4hgqjNzZ/lQBiMGRxPD5Y2/e0bw=
Subject Common Name: AAA Certificate Services
  Certificate SHA256 fingerprint: D7:A7:A0:FB:5D:7E:27:31:D7:71:E9:48:4E:BC:DE:F7:1D:5F:0C:3E:0A:29:48:78:2B:C8:3E:E0:EA:69:9E:F4
  Public key ping-sha256: vRU+17BDT2iGsXvOi76E7TQMcTLXAqj0+jGPdW7L1vM=
All OK. Server matched our pinned cert or public key
statusCode: 200

HTTPS ​

Feststellen, ob die Krypto-Unterstützung nicht verfügbar ist ​

Klasse: https.Agent ​

new Agent([options]) ​

Ereignis: 'keylog' ​

Klasse: https.Server ​

server.close([callback]) ​

server[Symbol.asyncDispose]() ​

server.closeAllConnections() ​

server.closeIdleConnections() ​

server.headersTimeout ​

server.listen() ​

server.maxHeadersCount ​

server.requestTimeout ​

server.setTimeout([msecs][, callback]) ​

server.timeout ​

server.keepAliveTimeout ​

https.createServer([options][, requestListener]) ​

https.get(options[, callback]) ​

https.get(url[, options][, callback]) ​

https.globalAgent ​

https.request(options[, callback]) ​

https.request(url[, options][, callback]) ​

HTTPS

Feststellen, ob die Krypto-Unterstützung nicht verfügbar ist

Klasse: `https.Agent`

`new Agent([options])`

Ereignis: `'keylog'`

Klasse: `https.Server`

`server.close([callback])`

`server[Symbol.asyncDispose]()`

`server.closeAllConnections()`

`server.closeIdleConnections()`

`server.headersTimeout`

`server.listen()`

`server.maxHeadersCount`

`server.requestTimeout`

`server.setTimeout([msecs][, callback])`

`server.timeout`

`server.keepAliveTimeout`

`https.createServer([options][, requestListener])`

`https.get(options[, callback])`

`https.get(url[, options][, callback])`

`https.globalAgent`

`https.request(options[, callback])`

`https.request(url[, options][, callback])`