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

Возможна ситуация, когда 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, где поддержка криптографии не включена, рекомендуется использовать функцию 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 и таймаутом в 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