{ "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 https.request()
\nfor 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#timeout
.
See http.Server#keepAliveTimeout
.
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
\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
\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.
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.
Example:
\nconst 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": "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` Defaults to `https:` ",
"name": "protocol",
"desc": "Defaults to `https:`"
},
{
"textRaw": "`port` Defaults to `443`. ",
"name": "port",
"desc": "Defaults to `443`."
},
{
"textRaw": "`agent` Defaults to `https.globalAgent`. ",
"name": "agent",
"desc": "Defaults to `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.
\nThe following additional options
from tls.connect()
are also accepted when using a\n custom Agent
:\n pfx
, key
, passphrase
, cert
, ca
, ciphers
, rejectUnauthorized
, secureProtocol
, servername
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.
Example:
\nconst 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
.
Example:
\nconst 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 { URL } = require('url');\n\nconst options = new URL('https://abc:xyz@example.com');\n\nconst req = https.request(options, (res) => {\n // ...\n});\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.