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

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 <Object> Набор настраиваемых параметров для установки в агенте. Может содержать те же поля, что и для http.Agent(options), и

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

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

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

Событие: 'keylog'

• 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

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

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

server.close([callback])

• callback <Function>
• Возвращает: <https.Server>

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

server.closeAllConnections()

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

server.closeIdleConnections()

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

server.headersTimeout

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

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

server.listen()

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

server.maxHeadersCount

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

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

server.requestTimeout

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

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

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

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

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

server.timeout

• <number> По умолчанию: 0 (без времени ожидания)

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

server.keepAliveTimeout

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

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

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

• options <Object> Принимает options из tls.createServer(), tls.createSecureContext() и http.createServer().
• requestListener <Function> Слушатель, который будет добавлен к событию '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 <string> | <URL>
• options <Object> | <string> | <URL> Принимает те же options, что и https.request(), с методом, установленным в GET по умолчанию.
• callback <Function>

Как 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.request(options[, callback])

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

• 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.

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