{ "type": "module", "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.
", "classes": [ { "textRaw": "Class: https.Agent", "type": "class", "name": "https.Agent", "meta": { "added": [ "v0.4.5" ], "changes": [ { "version": "v2.5.0", "pr-url": "https://github.com/nodejs/node/pull/2228", "description": "parameter `maxCachedSessions` added to `options` for TLS sessions reuse." }, { "version": "v5.3.0", "pr-url": "https://github.com/nodejs/node/pull/4252", "description": "support `0` `maxCachedSessions` to disable TLS session caching." } ] }, "desc": "An Agent
object for HTTPS similar to http.Agent
. See\nhttps.request()
for more information.
This class is a subclass of tls.Server
and emits events same as\nhttp.Server
. See http.Server
for more information.
See server.close()
from the HTTP module for details.
Starts the HTTPS server listening for encrypted connections.\nThis method is identical to server.listen()
from net.Server
.
See http.Server#headersTimeout
.
See http.Server#maxHeadersCount
.
See http.Server#timeout
.
See http.Server#keepAliveTimeout
.
// 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
\nOr
\nconst 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
"
},
{
"textRaw": "https.get(options[, callback])",
"type": "method",
"name": "get",
"meta": {
"added": [
"v0.3.6"
],
"changes": [
{
"version": "v10.9.0",
"pr-url": "https://github.com/nodejs/node/pull/21616",
"description": "The `url` parameter can now be passed along with a separate `options` object."
},
{
"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
}
]
}
],
"desc": "Like http.get()
but for HTTPS.
options
can be an object, a string, or a URL
object. If options
is a\nstring, it is automatically parsed with new URL()
. If it is a URL
\nobject, it will be automatically converted to an ordinary options
object.
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
"
},
{
"textRaw": "https.get(url[, options][, callback])",
"type": "method",
"name": "get",
"meta": {
"added": [
"v0.3.6"
],
"changes": [
{
"version": "v10.9.0",
"pr-url": "https://github.com/nodejs/node/pull/21616",
"description": "The `url` parameter can now be passed along with a separate `options` object."
},
{
"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": "`url` {string | URL}",
"name": "url",
"type": "string | URL"
},
{
"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`.",
"optional": true
},
{
"textRaw": "`callback` {Function}",
"name": "callback",
"type": "Function",
"optional": true
}
]
}
],
"desc": "Like http.get()
but for HTTPS.
options
can be an object, a string, or a URL
object. If options
is a\nstring, it is automatically parsed with new URL()
. If it is a URL
\nobject, it will be automatically converted to an ordinary options
object.
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
"
},
{
"textRaw": "https.request(options[, callback])",
"type": "method",
"name": "request",
"meta": {
"added": [
"v0.3.6"
],
"changes": [
{
"version": "v10.9.0",
"pr-url": "https://github.com/nodejs/node/pull/21616",
"description": "The `url` parameter can now be passed along with a separate `options` object."
},
{
"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:",
"name": "options",
"type": "Object | string | URL",
"desc": "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`"
}
]
},
{
"textRaw": "`callback` {Function}",
"name": "callback",
"type": "Function",
"optional": true
}
]
}
],
"desc": "Makes a request to a secure web server.
\nThe 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
.
options
can be an object, a string, or a URL
object. If options
is a\nstring, it is automatically parsed with new URL()
. If it is a URL
\nobject, it will be automatically converted to an ordinary options
object.
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
\nExample using options from tls.connect()
:
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
\nAlternatively, opt out of connection pooling by not using an Agent
.
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
\nExample using a URL
as options
:
const options = new URL('https://abc:xyz@example.com');\n\nconst req = https.request(options, (res) => {\n // ...\n});\n
\nExample pinning on certificate fingerprint, or the public key (similar to\npin-sha256
):
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
\nOutputs for example:
\nSubject 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
"
},
{
"textRaw": "https.request(url[, options][, callback])",
"type": "method",
"name": "request",
"meta": {
"added": [
"v0.3.6"
],
"changes": [
{
"version": "v10.9.0",
"pr-url": "https://github.com/nodejs/node/pull/21616",
"description": "The `url` parameter can now be passed along with a separate `options` object."
},
{
"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": "`url` {string | URL}",
"name": "url",
"type": "string | URL"
},
{
"textRaw": "`options` {Object | string | URL} Accepts all `options` from [`http.request()`][], with some differences in default values:",
"name": "options",
"type": "Object | string | URL",
"desc": "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`"
}
],
"optional": true
},
{
"textRaw": "`callback` {Function}",
"name": "callback",
"type": "Function",
"optional": true
}
]
}
],
"desc": "Makes a request to a secure web server.
\nThe 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
.
options
can be an object, a string, or a URL
object. If options
is a\nstring, it is automatically parsed with new URL()
. If it is a URL
\nobject, it will be automatically converted to an ordinary options
object.
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
\nExample using options from tls.connect()
:
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
\nAlternatively, opt out of connection pooling by not using an Agent
.
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
\nExample using a URL
as options
:
const options = new URL('https://abc:xyz@example.com');\n\nconst req = https.request(options, (res) => {\n // ...\n});\n
\nExample pinning on certificate fingerprint, or the public key (similar to\npin-sha256
):
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
\nOutputs for example:
\nSubject 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
"
}
],
"properties": [
{
"textRaw": "https.globalAgent",
"name": "globalAgent",
"meta": {
"added": [
"v0.5.9"
],
"changes": []
},
"desc": "Global instance of https.Agent
for all HTTPS client requests.