https 安全超文本传输协议

Node.js 中文网

https 安全超文本传输协议

https 安全超文本传输协议#

中英对照

稳定性: 2 - 稳定

源代码: lib/https.js

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

`https.Agent` 类#

中英对照

版本历史

版本	变更
v5.3.0	支持 `0` `maxCachedSessions` 禁用 TLS 会话缓存。
v2.5.0	参数 `maxCachedSessions` 添加到 `options` 用于 TLS 会话重用。
v0.4.5	新增于: v0.4.5

HTTPS 的 Agent 对象，类似于 http.Agent。有关详细信息，请参阅 https.request()。

`new Agent([options])`#

中英对照

版本历史

版本	变更
v12.5.0	如果目标主机是使用 IP 地址指定的，则不要自动设置服务器名称。

options <Object> 要在代理上设置的可配置选项集。可以具有与 http.Agent(options) 相同的字段，以及
- maxCachedSessions <number> TLS 缓存会话的最大数量。使用 0 禁用 TLS 会话缓存。 默认值: 100。
- servername <string> 要发送到服务器的服务器名称指示扩展的值。使用空字符串 '' 禁用发送扩展名。 默认值: 目标服务器的主机名，除非使用 IP 地址指定目标服务器，在这种情况下，默认为 ''（无扩展名）。
  
  有关 TLS 会话重用的信息，请参阅会话恢复。

`'keylog'` 事件#

中英对照

新增于: v13.2.0, v12.16.0

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 });
});

`https.Server` 类#

中英对照

新增于: v0.3.4

继承自: <tls.Server>

有关详细信息，请参阅 http.Server。

`server.close([callback])`#

中英对照

新增于: v0.1.90

callback <Function>
返回: <https.Server>

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

`server.headersTimeout`#

中英对照

新增于: v11.3.0

<number> 默认值: 60000

参见 http.Server#headersTimeout。

`server.listen()`#

中英对照

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

`server.maxHeadersCount`#

中英对照

<number> 默认值: 2000

参见 http.Server#maxHeadersCount。

`server.requestTimeout`#

中英对照

新增于: v14.11.0

<number> 默认值: 0

参见 http.Server#requestTimeout。

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

中英对照

新增于: v0.11.2

msecs <number> 默认值: 120000 （2 分钟）
callback <Function>
返回: <https.Server>

参见 http.Server#setTimeout()。

`server.timeout`#

中英对照

版本历史

版本	变更
v13.0.0	默认超时时间从 120 秒更改为 0（无超时）。
v0.11.2	新增于: v0.11.2

<number> 默认值: 0（无超时）

参见 http.Server#timeout。

`server.keepAliveTimeout`#

中英对照

新增于: v8.0.0

<number> 默认值: 5000 （5 秒）

参见 http.Server#keepAliveTimeout。

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

中英对照

新增于: v0.3.4

options <Object> 接受来自 tls.createServer()、tls.createSecureContext() 和 http.createServer() 的 options。
requestListener <Function> 要添加到 '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])`#

中英对照

版本历史

版本	变更
v10.9.0	参数 `url` 现在可以使用单独的 `options` 对象传入。
v7.5.0	参数 `options` 可以是 WHATWG `URL` 对象。
v0.3.6	新增于: v0.3.6

url <string> | <URL>
options <Object> | <string> | <URL> 接受与 https.request() 相同的 options，但 method 始终设置为 GET。
callback <Function>

类似于 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`#

中英对照

新增于: v0.5.9

所有 HTTPS 客户端请求的 https.Agent 全局实例。

`https.request(options[, callback])`#

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

中英对照

版本历史

版本	变更
v14.18.0	当使用 `URL` 对象解析用户名和密码时，现在将正确地解码统一资源标识符。
v14.1.0	现在接受 `highWaterMark` 选项。
v10.9.0	参数 `url` 现在可以使用单独的 `options` 对象传入。
v9.3.0	参数 `options` 现在可以包含 `clientCertEngine`。
v7.5.0	参数 `options` 可以是 WHATWG `URL` 对象。
v0.3.6	新增于: v0.3.6

url <string> | <URL>
options <Object> | <string> | <URL> 接受来自 http.request() 的所有 options，默认值有一些不同：
- protocol 默认值: 'https:'
- port 默认值: 443
- agent 默认值: https.globalAgent
callback <Function>
返回: <http.ClientRequest>

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

还接受来自 tls.connect() 的以下额外的 options：ca、cert、ciphers、clientCertEngine、crl、dhparam、ecdhCurve、honorCipherOrder、key、passphrase、pfx、rejectUnauthorized、secureOptions、secureProtocol、servername、sessionIdContext、highWaterMark。

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) {
    // 确保证书颁发给连接的主机
    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 = 'Certificate verification error: ' +
        `The public key of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      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 = 'Certificate verification error: ' +
        `The certificate of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      return new Error(msg);
    }

    // 此循环仅供参考。
    // 打印链中所有证书的证书和公钥指纹。
    // 通常，在公共互联网上固定发行者的公钥，在敏感环境中固定服务的公钥。
    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);
  // 打印 HPKP 值
  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