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> 要设置到 agent 上的配置选项的集合。具有与 http.Agent(options) 相同的字段,以及:

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

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

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

'keylog' 事件#

中英对照提交修改

  • line <Buffer> ASCII 的文本行,采用 NSS 的 SSLKEYLOGFILE 格式。
  • tlsSocket <tls.TLSSocket> 生成 keylog 的 tls.TLSSocket 实例。

当此 agent 管理的连接生成或接收到密钥材料时(通常在握手完成之前,但不一定),则触发 keylog 事件。 此密钥材料可以保存起来用以调试,因为它可以对捕获的 TLS 通信进行解密。 每个 socket 可以被多次触发。

一个典型的用例是,将接收到的文本行附加到一个普通的文本文件,该文件随后可被软件(例如 Wireshark)进行解密通信:

// ...
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> 默认值: 0(不超时)。

请参阅 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('你好,世界\n');
}).listen(8000);

或者:

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

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

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('你好,世界\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() 的额外的 options 也会被接收: cacertciphersclientCertEnginecrldhparamecdhCurvehonorCipherOrderkeypassphrasepfxrejectUnauthorizedsecureOptionssecureProtocolservernamesessionIdContext

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