{ "source": "doc/api/https.md", "modules": [ { "textRaw": "HTTPS", "name": "https", "introduced_in": "v0.10.0", "stability": 2, "stabilityText": "Stable", "desc": "

HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a\nseparate module.

\n", "classes": [ { "textRaw": "Class: https.Agent", "type": "class", "name": "https.Agent", "meta": { "added": [ "v0.4.5" ], "changes": [] }, "desc": "

An Agent object for HTTPS similar to http.Agent. See\nhttps.request() for more information.

\n" }, { "textRaw": "Class: https.Server", "type": "class", "name": "https.Server", "meta": { "added": [ "v0.3.4" ], "changes": [] }, "desc": "

This class is a subclass of tls.Server and emits events same as\nhttp.Server. See http.Server for more information.

\n", "methods": [ { "textRaw": "server.close([callback])", "type": "method", "name": "close", "meta": { "added": [ "v0.1.90" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`callback` {Function} ", "name": "callback", "type": "Function", "optional": true } ] }, { "params": [ { "name": "callback", "optional": true } ] } ], "desc": "

See server.close() from the HTTP module for details.

\n" }, { "textRaw": "server.listen()", "type": "method", "name": "listen", "desc": "

Starts the HTTPS server listening for encrypted connections.\nThis method is identical to server.listen() from net.Server.

\n", "signatures": [ { "params": [] } ] }, { "textRaw": "server.setTimeout([msecs][, callback])", "type": "method", "name": "setTimeout", "meta": { "added": [ "v0.11.2" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`msecs` {number} **Default:** `120000` (2 minutes) ", "name": "msecs", "type": "number", "default": "`120000` (2 minutes)", "optional": true }, { "textRaw": "`callback` {Function} ", "name": "callback", "type": "Function", "optional": true } ] }, { "params": [ { "name": "msecs", "optional": true }, { "name": "callback", "optional": true } ] } ], "desc": "

See http.Server#setTimeout().

\n" } ], "properties": [ { "textRaw": "`timeout` {number} **Default:** `120000` (2 minutes) ", "type": "number", "name": "timeout", "meta": { "added": [ "v0.11.2" ], "changes": [] }, "default": "`120000` (2 minutes)", "desc": "

See http.Server#timeout.

\n" }, { "textRaw": "`keepAliveTimeout` {number} **Default:** `5000` (5 seconds) ", "type": "number", "name": "keepAliveTimeout", "meta": { "added": [ "v8.0.0" ], "changes": [] }, "default": "`5000` (5 seconds)", "desc": "

See http.Server#keepAliveTimeout.

\n" } ] } ], "methods": [ { "textRaw": "https.createServer([options][, requestListener])", "type": "method", "name": "createServer", "meta": { "added": [ "v0.3.4" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`options` {Object} Accepts `options` from [`tls.createServer()`][], [`tls.createSecureContext()`][] and [`http.createServer()`][]. ", "name": "options", "type": "Object", "desc": "Accepts `options` from [`tls.createServer()`][], [`tls.createSecureContext()`][] and [`http.createServer()`][].", "optional": true }, { "textRaw": "`requestListener` {Function} A listener to be added to the `'request'` event. ", "name": "requestListener", "type": "Function", "desc": "A listener to be added to the `'request'` event.", "optional": true } ] }, { "params": [ { "name": "options", "optional": true }, { "name": "requestListener", "optional": true } ] } ], "desc": "

Example:

\n
// curl -k https://localhost:8000/\nconst https = require('https');\nconst fs = require('fs');\n\nconst options = {\n  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')\n};\n\nhttps.createServer(options, (req, res) => {\n  res.writeHead(200);\n  res.end('hello world\\n');\n}).listen(8000);\n
\n

Or

\n
const https = require('https');\nconst fs = require('fs');\n\nconst options = {\n  pfx: fs.readFileSync('test/fixtures/test_cert.pfx'),\n  passphrase: 'sample'\n};\n\nhttps.createServer(options, (req, res) => {\n  res.writeHead(200);\n  res.end('hello world\\n');\n}).listen(8000);\n
\n" }, { "textRaw": "https.get(options[, callback])", "type": "method", "name": "get", "meta": { "added": [ "v0.3.6" ], "changes": [ { "version": "v7.5.0", "pr-url": "https://github.com/nodejs/node/pull/10638", "description": "The `options` parameter can be a WHATWG `URL` object." } ] }, "signatures": [ { "params": [ { "textRaw": "`options` {Object | string | URL} Accepts the same `options` as [`https.request()`][], with the `method` always set to `GET`. ", "name": "options", "type": "Object | string | URL", "desc": "Accepts the same `options` as [`https.request()`][], with the `method` always set to `GET`." }, { "textRaw": "`callback` {Function} ", "name": "callback", "type": "Function", "optional": true } ] }, { "params": [ { "name": "options" }, { "name": "callback", "optional": true } ] } ], "desc": "

Like http.get() but for HTTPS.

\n

options can be an object, a string, or a URL object. If options is a\nstring, it is automatically parsed with url.parse(). If it is a URL\nobject, it will be automatically converted to an ordinary options object.

\n

Example:

\n
const https = require('https');\n\nhttps.get('https://encrypted.google.com/', (res) => {\n  console.log('statusCode:', res.statusCode);\n  console.log('headers:', res.headers);\n\n  res.on('data', (d) => {\n    process.stdout.write(d);\n  });\n\n}).on('error', (e) => {\n  console.error(e);\n});\n
\n" }, { "textRaw": "https.request(options[, callback])", "type": "method", "name": "request", "meta": { "added": [ "v0.3.6" ], "changes": [ { "version": "v9.3.0", "pr-url": "https://github.com/nodejs/node/pull/14903", "description": "The `options` parameter can now include `clientCertEngine`." }, { "version": "v7.5.0", "pr-url": "https://github.com/nodejs/node/pull/10638", "description": "The `options` parameter can be a WHATWG `URL` object." } ] }, "signatures": [ { "params": [ { "textRaw": "`options` {Object | string | URL} Accepts all `options` from [`http.request()`][], with some differences in default values: ", "options": [ { "textRaw": "`protocol` **Default:** `'https:'` ", "name": "protocol", "default": "`'https:'`" }, { "textRaw": "`port` **Default:** `443` ", "name": "port", "default": "`443`" }, { "textRaw": "`agent` **Default:** `https.globalAgent` ", "name": "agent", "default": "`https.globalAgent`" } ], "name": "options", "type": "Object | string | URL", "desc": "Accepts all `options` from [`http.request()`][], with some differences in default values:" }, { "textRaw": "`callback` {Function} ", "name": "callback", "type": "Function", "optional": true } ] }, { "params": [ { "name": "options" }, { "name": "callback", "optional": true } ] } ], "desc": "

Makes a request to a secure web server.

\n

The following additional options from tls.connect() are also accepted:\nca, cert, ciphers, clientCertEngine, crl, dhparam, ecdhCurve,\nhonorCipherOrder, key, passphrase, pfx, rejectUnauthorized,\nsecureOptions, secureProtocol, servername, sessionIdContext

\n

options can be an object, a string, or a URL object. If options is a\nstring, it is automatically parsed with url.parse(). If it is a URL\nobject, it will be automatically converted to an ordinary options object.

\n

Example:

\n
const https = require('https');\n\nconst options = {\n  hostname: 'encrypted.google.com',\n  port: 443,\n  path: '/',\n  method: 'GET'\n};\n\nconst req = https.request(options, (res) => {\n  console.log('statusCode:', res.statusCode);\n  console.log('headers:', res.headers);\n\n  res.on('data', (d) => {\n    process.stdout.write(d);\n  });\n});\n\nreq.on('error', (e) => {\n  console.error(e);\n});\nreq.end();\n
\n

Example using options from tls.connect():

\n
const options = {\n  hostname: 'encrypted.google.com',\n  port: 443,\n  path: '/',\n  method: 'GET',\n  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')\n};\noptions.agent = new https.Agent(options);\n\nconst req = https.request(options, (res) => {\n  // ...\n});\n
\n

Alternatively, opt out of connection pooling by not using an Agent.

\n

Example:

\n
const options = {\n  hostname: 'encrypted.google.com',\n  port: 443,\n  path: '/',\n  method: 'GET',\n  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),\n  agent: false\n};\n\nconst req = https.request(options, (res) => {\n  // ...\n});\n
\n

Example using a URL as options:

\n
const options = new URL('https://abc:xyz@example.com');\n\nconst req = https.request(options, (res) => {\n  // ...\n});\n
\n

Example pinning on certificate fingerprint, or the public key (similar to\npin-sha256):

\n
const tls = require('tls');\nconst https = require('https');\nconst crypto = require('crypto');\n\nfunction sha256(s) {\n  return crypto.createHash('sha256').update(s).digest('base64');\n}\nconst options = {\n  hostname: 'github.com',\n  port: 443,\n  path: '/',\n  method: 'GET',\n  checkServerIdentity: function(host, cert) {\n    // Make sure the certificate is issued to the host we are connected to\n    const err = tls.checkServerIdentity(host, cert);\n    if (err) {\n      return err;\n    }\n\n    // Pin the public key, similar to HPKP pin-sha25 pinning\n    const pubkey256 = 'pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=';\n    if (sha256(cert.pubkey) !== pubkey256) {\n      const msg = 'Certificate verification error: ' +\n        `The public key of '${cert.subject.CN}' ` +\n        'does not match our pinned fingerprint';\n      return new Error(msg);\n    }\n\n    // Pin the exact certificate, rather then the pub key\n    const cert256 = '25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:' +\n      'D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16';\n    if (cert.fingerprint256 !== cert256) {\n      const msg = 'Certificate verification error: ' +\n        `The certificate of '${cert.subject.CN}' ` +\n        'does not match our pinned fingerprint';\n      return new Error(msg);\n    }\n\n    // This loop is informational only.\n    // Print the certificate and public key fingerprints of all certs in the\n    // chain. Its common to pin the public key of the issuer on the public\n    // internet, while pinning the public key of the service in sensitive\n    // environments.\n    do {\n      console.log('Subject Common Name:', cert.subject.CN);\n      console.log('  Certificate SHA256 fingerprint:', cert.fingerprint256);\n\n      hash = crypto.createHash('sha256');\n      console.log('  Public key ping-sha256:', sha256(cert.pubkey));\n\n      lastprint256 = cert.fingerprint256;\n      cert = cert.issuerCertificate;\n    } while (cert.fingerprint256 !== lastprint256);\n\n  },\n};\n\noptions.agent = new https.Agent(options);\nconst req = https.request(options, (res) => {\n  console.log('All OK. Server matched our pinned cert or public key');\n  console.log('statusCode:', res.statusCode);\n  // Print the HPKP values\n  console.log('headers:', res.headers['public-key-pins']);\n\n  res.on('data', (d) => {});\n});\n\nreq.on('error', (e) => {\n  console.error(e.message);\n});\nreq.end();\n
\n

Outputs for example:

\n
Subject Common Name: github.com\n  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\n  Public key ping-sha256: pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=\nSubject Common Name: DigiCert SHA2 Extended Validation Server CA\n  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\n  Public key ping-sha256: RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho=\nSubject Common Name: DigiCert High Assurance EV Root CA\n  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\n  Public key ping-sha256: WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18=\nAll OK. Server matched our pinned cert or public key\nstatusCode: 200\nheaders: 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\n
\n" } ], "properties": [ { "textRaw": "https.globalAgent", "name": "globalAgent", "meta": { "added": [ "v0.5.9" ], "changes": [] }, "desc": "

Global instance of https.Agent for all HTTPS client requests.

\n" } ], "type": "module", "displayName": "HTTPS" } ] }