Spec-Zone.ru › Node.js 24 LTS

HTTPS

Стабильность: 2 - Стабильный

Исходный код: lib/https.js

HTTPS — это протокол HTTP поверх TLS/SSL. В Node.js он реализован в виде отдельного модуля.

Определение отсутствия поддержки crypto

Node.js может быть собран без поддержки модуля node:crypto. В таких случаях попытка выполнить import из https или вызов require('node:https') приведёт к возникновению ошибки.

При использовании CommonJS возникшую ошибку можно перехватить с помощью try/catch:

let https;
try {
  https = require('node:https');
} catch (err) {
  console.error('https support is disabled!');
} copy

При использовании лексического ключевого слова ESM import ошибку можно перехватить, только если обработчик для process.on('uncaughtException') зарегистрирован до попытки загрузить модуль (например, с помощью модуля предварительной загрузки).

При использовании ESM, если код может выполняться в сборке Node.js без поддержки crypto, рассмотрите возможность использовать функцию import() вместо лексического ключевого слова import:

let https;
try {
  https = await import('node:https');
} catch (err) {
  console.error('https support is disabled!');
} copy

Класс: https.Agent

История
Версия Изменения
v5.3.0

Добавлена поддержка 0 maxCachedSessions для отключения кэширования TLS-сессий.

v2.5.0

Параметр maxCachedSessions добавлен в options для повторного использования TLS-сессий.

v0.4.5

Добавлено в: v0.4.5

Объект Agent для HTTPS, аналогичный http.Agent. Дополнительные сведения см. в разделе https.request().

Как и у http.Agent, метод createConnection(options[, callback]) можно переопределить, чтобы настроить установление TLS-соединений.

Сведения о переопределении этого метода, в том числе о создании сокета асинхронно с помощью обратного вызова, см. в разделе agent.createConnection().

new Agent([options])

История
Версия Изменения
v24.5.0

Добавлена поддержка proxyEnv.

v24.5.0

Добавлена поддержка defaultPort и protocol.

v12.5.0

Имя сервера не устанавливается автоматически, если целевой узел задан с помощью IP-адреса.

  • options <Object> Набор настраиваемых параметров агента. Может содержать те же поля, что и http.Agent(options), а также
    • maxCachedSessions <number> максимальное количество кэшируемых TLS-сессий. Используйте 0, чтобы отключить кэширование TLS-сессий. По умолчанию: 100.

    • servername <string> значение расширения Server Name Indication, отправляемое серверу. Используйте пустую строку '', чтобы отключить отправку расширения. По умолчанию: имя узла целевого сервера, если только целевой сервер не задан с помощью IP-адреса; в этом случае по умолчанию используется '' (расширение не отправляется).

      Сведения о повторном использовании TLS-сессий см. в разделе Session Resumption.

Событие: 'keylog'
Добавлено в: v13.2.0, v12.16.0
  • line <Buffer> Строка текста ASCII в формате NSS SSLKEYLOGFILE.
  • tlsSocket <tls.TLSSocket> Экземпляр tls.TLSSocket, для которого он был создан.

Событие keylog возникает, когда соединение, управляемое этим агентом, генерирует или получает ключевой материал (обычно до завершения рукопожатия, но не обязательно). Этот ключевой материал можно сохранить для отладки, поскольку он позволяет расшифровать перехваченный TLS-трафик. Для каждого сокета событие может возникать несколько раз.

Обычно полученные строки добавляют в общий текстовый файл, который впоследствии используется программным обеспечением (например, Wireshark) для расшифровки трафика:

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

Класс: https.Server

Добавлено в: v0.3.4
  • Расширяет: <tls.Server>

Дополнительные сведения см. в разделе http.Server.

server.close([callback])

Добавлено в: v0.1.90
  • callback <Function>
  • Возвращает: <https.Server>

См. server.close() в модуле node:http.

server[Symbol.asyncDispose]()

История
Версия Изменения
v24.2.0

Больше не является экспериментальным.

v20.4.0

Добавлено в: v20.4.0

Вызывает server.close() и возвращает промис, который выполняется после закрытия сервера.

server.closeAllConnections()

Добавлено в: v18.2.0

См. server.closeAllConnections() в модуле node:http.

server.closeIdleConnections()

Добавлено в: v18.2.0

См. server.closeIdleConnections() в модуле node:http.

server.headersTimeout

Добавлено в: v11.3.0
  • Тип: <number> По умолчанию: 60000

См. server.headersTimeout в модуле node:http.

server.listen()

Запускает HTTPS-сервер, который начинает прослушивать зашифрованные соединения. Этот метод идентичен методу server.listen() класса net.Server.

server.maxHeadersCount

  • Тип: <number> По умолчанию: 2000

См. server.maxHeadersCount в модуле node:http.

server.requestTimeout

История
Версия Изменения
v18.0.0

Тайм-аут запроса по умолчанию изменён: вместо отсутствия тайм-аута установлено значение 300 с (5 минут).

v14.11.0

Добавлено в: v14.11.0

  • Тип: <number> По умолчанию: 300000

См. server.requestTimeout в модуле node:http.

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

Добавлено в: v0.11.2
  • msecs <number> По умолчанию: 120000 (2 минуты)
  • callback <Function>
  • Возвращает: <https.Server>

См. server.setTimeout() в модуле node:http.

server.timeout

История
Версия Изменения
v13.0.0

Тайм-аут по умолчанию изменён со 120 с на 0 (тайм-аут отсутствует).

v0.11.2

Добавлено в: v0.11.2

  • Тип: <number> По умолчанию: 0 (тайм-аут отсутствует)

См. server.timeout в модуле node:http.

server.keepAliveTimeout

Добавлено в: v8.0.0
  • Тип: <number> По умолчанию: 5000 (5 секунд)

См. server.keepAliveTimeout в модуле node:http.

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

Добавлено в: v0.3.4
  • options <Object> Принимает options из разделов tls.createServer(), tls.createSecureContext() и http.createServer().
  • requestListener <Function> Обработчик, добавляемый к событию 'request'.
  • Возвращает: <https.Server>
Модули JavaScript
// 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);
CommonJS
// 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);

Или

Модули JavaScript
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);
CommonJS
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);

Чтобы создать сертификат и ключ для этого примера, выполните команду:

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

Затем, чтобы создать pfx сертификат для этого примера, выполните команду:

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

https.get(options[, callback])

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

История
Версия Изменения
v10.9.0

Параметр url теперь можно передавать вместе с отдельным объектом options.

v7.5.0

Параметр options может быть объектом WHATWG URL.

v0.3.6

Добавлено в: v0.3.6

  • url <string> | <URL>
  • options <Object> | <string> | <URL> Принимает те же options, что и https.request(); по умолчанию в качестве метода используется GET.
  • callback <Function>
  • Возвращает: <http.ClientRequest>

Аналог метода http.get(), но для HTTPS.

options может быть объектом, строкой или объектом URL. Если options — строка, она автоматически разбирается с помощью new URL(). Если это объект URL, он автоматически преобразуется в обычный объект options.

Модули JavaScript
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);
});
CommonJS
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

История
Версия Изменения
v19.0.0

Теперь агент по умолчанию использует HTTP Keep-Alive и тайм-аут 5 секунд.

v0.5.9

Добавлено в: v0.5.9

Глобальный экземпляр https.Agent для всех HTTPS-запросов клиента. Отличается от стандартной конфигурации https.Agent тем, что keepAlive включён, а значение timeout составляет 5 секунд.

https.request(options[, callback])

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

История
Версия Изменения
v22.4.0, v20.16.0

Параметр clientCertEngine зависит от поддержки пользовательских движков в OpenSSL, которая считается устаревшей в OpenSSL 3.

v16.7.0, v14.18.0

При использовании объекта URL разобранные имя пользователя и пароль теперь корректно декодируются из URI.

v14.1.0, v13.14.0

Теперь принимается параметр highWaterMark.

v10.9.0

Параметр url теперь можно передавать вместе с отдельным объектом options.

v9.3.0

Параметр options теперь может включать clientCertEngine.

v7.5.0

Параметр options может быть объектом WHATWG URL.

v0.3.6

Добавлено в: v0.3.6

  • url <string> | <URL>
  • options <Object> | <string> | <URL> Принимает все options из http.request(), но со следующими отличиями в значениях по умолчанию:
    • protocol По умолчанию: 'https:'
    • port По умолчанию: 443
    • agent По умолчанию: https.globalAgent
  • callback <Function>
  • Возвращает: <http.ClientRequest>

Выполняет запрос к защищённому веб-серверу.

Также принимаются следующие дополнительные options из раздела tls.connect(): ca, cert, ciphers, clientCertEngine (устарел), crl, dhparam, ecdhCurve, honorCipherOrder, key, passphrase, pfx, rejectUnauthorized, secureOptions, secureProtocol, servername, sessionIdContext, highWaterMark.

options может быть объектом, строкой или объектом URL. Если options — строка, она автоматически разбирается с помощью new URL(). Если это объект URL, он автоматически преобразуется в обычный объект options.

https.request() возвращает экземпляр класса http.ClientRequest. Экземпляр ClientRequest представляет собой поток для записи. Чтобы отправить файл в POST-запросе, запишите его в объект ClientRequest.

Модули JavaScript
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();
CommonJS
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();

Пример с использованием параметров из раздела 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) => {
  // ...
}); copy

В качестве альтернативы можно отказаться от пула соединений, не используя Agent.

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) => {
  // ...
}); copy

Пример использования URL в качестве options:

const options = new URL('https://abc:xyz@example.com');

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

Пример закрепления отпечатка сертификата или открытого ключа (аналогично pin-sha256):

Модули JavaScript
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();
CommonJS
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();

Например, будет выведено:

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 copy

© Joyent, Inc. and other Node contributors
Licensed under the MIT License.
Node.js is a trademark of Joyent, Inc. and is used with its permission.
We are not endorsed by or affiliated with Joyent.
https://nodejs.org/dist/latest-v24.x/docs/api/https.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API