Определение отсутствия поддержки модуля 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

Объект Agent для HTTPS, аналогичный http.Agent. Смотрите https.request() для получения дополнительной информации.

new Agent([options])

• options <Объект> Набор настраиваемых параметров для агента. Может содержать те же поля, что и для http.Agent(options), а также

  • maxCachedSessions <число> максимальное количество кэшированных сессий TLS. Используйте 0 для отключения кэширования сессий TLS. По умолчанию: 100.

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

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

Событие: 'keylog'

• line <Буфер> Строка 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

• Расширяет: <tls.Server>

См. http.Server для получения дополнительной информации.

server.close([callback])

• callback <Функция>
• Возвращает: <https.Server>

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

server[Symbol.asyncDispose]()

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

server.closeAllConnections()

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

server.closeIdleConnections()

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

server.headersTimeout

• <число> По умолчанию: 60000

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

server.listen()

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

server.maxHeadersCount

• <число> По умолчанию: 2000

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

server.requestTimeout

• <число> По умолчанию: 300000

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

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

• msecs <число> По умолчанию: 120000 (2 минуты)
• callback <Функция>
• Возвращает: <https.Server>

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

server.timeout

• <число> По умолчанию: 0 (без тайм-аута)

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

server.keepAliveTimeout

• <число> По умолчанию: 5000 (5 секунд)

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

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

• options <Объект> Принимает параметры options из tls.createServer(), tls.createSecureContext() и http.createServer().
• requestListener <Функция> Обработчик события 'request'.
• Возвращает: <https.Server>

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

const options = {
  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
};

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

Или

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

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

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

https.get(options[, callback])

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

• url <строка> | <URL>
• options <Объект> | <строка> | <URL> Принимает те же options что и https.request(), с методом GET по умолчанию.
• callback <Функция>

Как http.get(), но для HTTPS.

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

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);
}); copy

https.globalAgent

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

https.request(options[, callback])

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

• url <строка> | <URL>
• options <Объект> | <строка> | <URL> Принимает все options из http.request(), с некоторыми отличиями в значениях по умолчанию:
  • protocol По умолчанию: 'https:'
  • port По умолчанию: 443
  • agent По умолчанию: https.globalAgent
• callback <Функция>
• Возвращает: <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.

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(); copy

Пример использования параметров из tls.connect():

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.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('test/fixtures/keys/agent2-key.pem'),
  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.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):

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 = 'pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=';
    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 = '25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:' +
      'D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16';
    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);
  // Print the HPKP values
  console.log('headers:', res.headers['public-key-pins']);

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

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

Примеры вывода:

Subject Common Name: github.com
  Certificate SHA256 fingerprint: 25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16
  Public key ping-sha256: pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=
Subject Common Name: DigiCert SHA2 Extended Validation Server CA
  Certificate SHA256 fingerprint: 40:3E:06:2A:26:53:05:91:13:28:5B:AF:80:A0:D4:AE:42:2C:84:8C:9F:78:FA:D0:1F:C9:4B:C5:B8:7F:EF:1A
  Public key ping-sha256: RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho=
Subject Common Name: DigiCert High Assurance EV Root CA
  Certificate SHA256 fingerprint: 74:31:E5:F4:C3:C1:CE:46:90:77:4F:0B:61:E0:54:40:88:3B:A9:A0:1E:D0:0B:A6:AB:D7:80:6E:D3:B1:18:CF
  Public key ping-sha256: WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18=
All OK. Server matched our pinned cert or public key
statusCode: 200
headers: max-age=0; pin-sha256="WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18="; pin-sha256="RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho="; pin-sha256="k2v657xBsOVe1PQRwOsHsw3bsGT2VzIqz5K+59sNQws="; pin-sha256="K87oWBWM9UZfyddvDfoxL+8lpNyoUB2ptGtn0fv6G2Q="; pin-sha256="IQBnNBEiFuhj+8x6X8XLgh01V9Ic5/V3IRQLNFFc7v4="; pin-sha256="iie1VXtL7HzAMF+/PVPR9xzT80kQxdZeJ+zduCB3uj0="; pin-sha256="LvRiGEjRqfzurezaWuj8Wie2gyHMrW5Q06LspMnox7A="; includeSubDomains copy