• url {string | URL}
    • options {Object | string | URL} 接受来自 [http.request()] 的所有 options，但默认值有一些差异：
      • protocol 默认值: 'https:'。
      • port 默认值: 443。
      • agent 默认值: https.globalAgent。
    • callback {Function}

    发送一个请求到一个加密的 Web 服务器。

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

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

    1. const https = require('https');
    3. const options = {
    4.   hostname: 'encrypted.google.com',
    5.   port: 443,
    6.   path: '/',
    7.   method: 'GET'
    8. };
    10. const req = https.request(options, (res) => {
    11.   console.log('状态码:', res.statusCode);
    12.   console.log('请求头:', res.headers);
    14.   res.on('data', (d) => {
    15.     process.stdout.write(d);
    16.   });
    17. });
    19. req.on('error', (e) => {
    20.   console.error(e);
    21. });
    22. req.end();

    使用 [tls.connect()] 的选项的示例：

    1. const options = {
    2.   hostname: 'encrypted.google.com',
    3.   port: 443,
    4.   path: '/',
    5.   method: 'GET',
    6.   key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
    7.   cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
    8. };
    9. options.agent = new https.Agent(options);
    11. const req = https.request(options, (res) => {
    12.   // ...
    13. });

    或者，不使用 [Agent] 而选择退出连接池。

    1. const options = {
    2.   hostname: 'encrypted.google.com',
    3.   port: 443,
    4.   path: '/',
    5.   method: 'GET',
    6.   key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
    7.   cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
    8.   agent: false
    9. };
    11. const req = https.request(options, (res) => {
    12.   // ...
    13. });

    使用 [URL] 作为 options 的示例：

    1. const options = new URL('https://abc:xyz@example.com');
    3. const req = https.request(options, (res) => {
    4.   // ...
    5. });

    固定证书指纹或公钥（类似于 pin-sha256）的示例：

    1. const tls = require('tls');
    2. const https = require('https');
    3. const crypto = require('crypto');
    5. function sha256(s) {
    6.   return crypto.createHash('sha256').update(s).digest('base64');
    7. }
    8. const options = {
    9.   hostname: 'github.com',
    10.   port: 443,
    11.   path: '/',
    12.   method: 'GET',
    13.   checkServerIdentity: function(host, cert) {
    14.     // 确保将证书颁发给所连接的主机。
    15.     const err = tls.checkServerIdentity(host, cert);
    16.     if (err) {
    17.       return err;
    18.     }
    20.     // 固定公钥，类似于固定的 HPKP pin-sha25。
    21.     const pubkey256 = 'pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=';
    22.     if (sha256(cert.pubkey) !== pubkey256) {
    23.       const msg = '证书验证错误: ' +
    24.         `'${cert.subject.CN}' 的公钥` +
    25.         '与固定的指纹不符';
    26.       return new Error(msg);
    27.     }
    29.     // 固定确切的证书，而不是公钥。
    30.     const cert256 = '25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:' +
    31.       'D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16';
    32.     if (cert.fingerprint256 !== cert256) {
    33.       const msg = '证书验证错误: ' +
    34.         `'${cert.subject.CN}' 的证书` +
    35.         '与固定的指纹不符';
    36.       return new Error(msg);
    37.     }
    39.     // 此循环仅供参考。
    40.     // 打印链条中所有证书的证书与公钥指纹。 
    41.     // 通常，将发行人的公钥固定在公共互联网上，同时将服务的公钥固定在私密的环境中。
    42.     do {
    43.       console.log('主体的常用名称:', cert.subject.CN);
    44.       console.log('  证书的 SHA256 指纹:', cert.fingerprint256);
    46.       hash = crypto.createHash('sha256');
    47.       console.log('  公钥的 ping-sha256:', sha256(cert.pubkey));
    49.       lastprint256 = cert.fingerprint256;
    50.       cert = cert.issuerCertificate;
    51.     } while (cert.fingerprint256 !== lastprint256);
    53.   },
    54. };
    56. options.agent = new https.Agent(options);
    57. const req = https.request(options, (res) => {
    58.   console.log('一切正常。服务器与固定的证书或公钥相匹配。');
    59.   console.log('状态码:', res.statusCode);
    60.   // 打印 HPKP 的值。
    61.   console.log('请求头:', res.headers['public-key-pins']);
    63.   res.on('data', (d) => {});
    64. });
    66. req.on('error', (e) => {
    67.   console.error(e.message);
    68. });
    69. req.end();

    示例的输出：

    1. 主体的常用名称: github.com
    2.   证书的 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
    3.   公钥的 ping-sha256: pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=
    4. 主体的常用名称: DigiCert SHA2 Extended Validation Server CA
    5.   证书的 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
    6.   公钥的 ping-sha256: RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho=
    7. 主体的常用名称: DigiCert High Assurance EV Root CA
    8.   证书的 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
    9.   公钥的 ping-sha256: WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18=
    10. 一切正常。服务器与固定的证书或公钥相匹配。
    11. 状态码: 200
    12. 请求头: 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