Node.js v12.16.1 文档


https(HTTPS)#

中英对照提交修改

稳定性: 2 - 稳定

HTTPS 是基于 TLS/SSL 的 HTTP 协议。在 Node.js 中,作为一个单独的模块实现。

https.Agent 类#

中英对照提交修改

HTTPS 的 Agent 对象,类似于 http.Agent。 有关更多信息,请参阅 https.request()

new Agent([options])#

中英对照提交修改

  • options <Object> 在代理上设置的一组可配置的选项。可以具有与 http.Agent(options) 相同的字段,以及:

    • maxCachedSessions <number> TLS 缓存会话的最大数量。使用 0 可禁用 TLS 会话缓存。默认值: 100

    • servername <string> 要发送到服务器的服务器名称指示的扩展名的值。使用空字符串 '' 可以禁用发送扩展名。默认值: 目标服务器的主机名,除非目标服务器被指定为使用 IP 地址,在这种情况下默认为 ''(无扩展名)。

      有关 TLS 会话复用的信息,请参阅会话恢复

Event: 'keylog'#

暂无中英对照提交修改

  • line <Buffer> Line of ASCII text, in NSS SSLKEYLOGFILE format.
  • tlsSocket <tls.TLSSocket> The tls.TLSSocket instance on which it was generated.

The keylog event is emitted when key material is generated or received by a connection managed by this agent (typically before handshake has completed, but not necessarily). This keying material can be stored for debugging, as it allows captured TLS traffic to be decrypted. It may be emitted multiple times for each socket.

A typical use case is to append received lines to a common text file, which is later used by software (such as Wireshark) to decrypt the traffic:

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

https.Server 类#

中英对照提交修改

有关更多信息,请参阅 http.Server

server.close([callback])#

中英对照提交修改

有关详细信息,请参阅 HTTP 模块中的 server.close()

server.headersTimeout#

中英对照提交修改

请参阅 http.Server#headersTimeout

server.listen()#

中英对照提交修改

启动 HTTPS 服务器监听加密的连接。 此方法与 net.Serverserver.listen() 相同。

server.maxHeadersCount#

中英对照提交修改

请参阅 http.Server#maxHeadersCount

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

中英对照提交修改

请参阅 http.Server#setTimeout()

server.timeout#

中英对照提交修改

  • <number> 默认值: 120000(2 分钟)。

请参阅 http.Server#timeout

server.keepAliveTimeout#

中英对照提交修改

  • <number> 默认值: 5000(5 秒)。

请参阅 http.Server#keepAliveTimeout

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

中英对照提交修改

// 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])#

中英对照提交修改

类似 http.get(),但是用于 HTTPS。

options 可以是对象、字符串、或 URL 对象。 如果 options 是一个字符串, 则自动使用 new URL() 解析它。 如果它是一个 URL 对象,则将自动转换为普通的 options 对象。

const https = require('https');

https.get('https://encrypted.google.com/', (res) => {
  console.log('状态码:', res.statusCode);
  console.log('请求头:', 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])#

中英对照提交修改

向安全的 Web 服务器发出请求。

还接受来自 tls.connect() 的以下额外的 optionscacertciphersclientCertEnginecrldhparamecdhCurvehonorCipherOrderkeypassphrasepfxrejectUnauthorizedsecureOptionssecureProtocolservernamesessionIdContext

options 可以是对象、字符串、或 URL 对象。 如果 options 是一个字符串, 则自动使用 new URL() 解析它。 如果它是一个 URL 对象,则将自动转换为普通的 options 对象。

const https = require('https');

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET'
};

const req = https.request(options, (res) => {
  console.log('状态码:', res.statusCode);
  console.log('请求头:', 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) {
    // 确保将证书颁发给所连接的主机。
    const err = tls.checkServerIdentity(host, cert);
    if (err) {
      return err;
    }

    // 固定公钥,类似于固定的 HPKP pin-sha25。
    const pubkey256 = 'pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=';
    if (sha256(cert.pubkey) !== pubkey256) {
      const msg = '证书验证错误: ' +
        `'${cert.subject.CN}' 的公钥` +
        '与固定的指纹不符';
      return new Error(msg);
    }

    // 固定确切的证书,而不是公钥。
    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 = '证书验证错误: ' +
        `'${cert.subject.CN}' 的证书` +
        '与固定的指纹不符';
      return new Error(msg);
    }

    // 此循环仅供参考。
    // 打印链中所有证书的证书和公钥指纹。 
    // 将公共互联网上的发行人的公钥固定在公共互联网上是很常见的,同时在敏感环境中固定服务的公钥。
    do {
      console.log('主题通用名称:', cert.subject.CN);
      console.log('  证书 SHA256 指纹:', cert.fingerprint256);

      hash = crypto.createHash('sha256');
      console.log('  公钥 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('一切正常。服务器匹配固定证书或公钥。');
  console.log('状态码:', res.statusCode);
  // 打印 HPKP 值。
  console.log('请求头:', res.headers['public-key-pins']);

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

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

示例的输出:

主题通用名称: github.com
  证书 SHA256 指纹: 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
  公钥 ping-sha256: pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=
主题通用名称: DigiCert SHA2 Extended Validation Server CA
  证书 SHA256 指纹: 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
  公钥 ping-sha256: RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho=
主题通用名称: DigiCert High Assurance EV Root CA
  证书 SHA256 指纹: 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
  公钥 ping-sha256: WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18=
一切正常。服务器匹配固定证书或公钥。
状态码: 200
请求头: 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