Класс: 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 });
});

Класс: https.Server

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

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

server.close([callback])

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

См. server.close() из модуля HTTP для получения подробностей.

server.headersTimeout

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

См. http.Server#headersTimeout.

server.listen()

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

server.maxHeadersCount

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

См. http.Server#maxHeadersCount.

server.requestTimeout

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

См. http.Server#requestTimeout.

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

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

См. http.Server#setTimeout().

server.timeout

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

См. http.Server#timeout.

server.keepAliveTimeout

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

См. http.Server#keepAliveTimeout.

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

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

// curl -k https://localhost:8000/
const https = require('https');
const fs = require('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);

Или

const https = require('https');
const fs = require('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);

https.get(options[, callback])

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

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

Аналогично http.get(), но для HTTPS.

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

const https = require('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

Глобальный экземпляр https.Agent для всех HTTPS-клиентских запросов.

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

В качестве альтернативы, откажитесь от пулинга подключений, не используя 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) => {
  // ...
});

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

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

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

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

const tls = require('tls');
const https = require('https');
const crypto = require('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-sha25 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();

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

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