{ "source": "doc/api/https.markdown", "modules": [ { "textRaw": "HTTPS", "name": "https", "stability": 3, "stabilityText": "Stable", "desc": "
HTTPS is the HTTP protocol over TLS/SSL. In Node this is implemented as a\nseparate module.\n\n
\n", "classes": [ { "textRaw": "Class: https.Server", "type": "class", "name": "https.Server", "desc": "This class is a subclass of tls.Server
and emits events same as\nhttp.Server
. See http.Server
for more information.\n\n
An Agent object for HTTPS similar to [http.Agent][]. See [https.request()][]\nfor more information.\n\n\n
\n" } ], "methods": [ { "textRaw": "https.createServer(options, [requestListener])", "type": "method", "name": "createServer", "desc": "Returns a new HTTPS web server object. The options
is similar to\n[tls.createServer()][]. The requestListener
is a function which is\nautomatically added to the 'request'
event.\n\n
Example:\n\n
\n// curl -k https://localhost:8000/\nvar https = require('https');\nvar fs = require('fs');\n\nvar 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, function (req, res) {\n res.writeHead(200);\n res.end("hello world\\n");\n}).listen(8000);
\nOr\n\n
\nvar https = require('https');\nvar fs = require('fs');\n\nvar options = {\n pfx: fs.readFileSync('server.pfx')\n};\n\nhttps.createServer(options, function (req, res) {\n res.writeHead(200);\n res.end("hello world\\n");\n}).listen(8000);
\n",
"methods": [
{
"textRaw": "server.listen(path, [callback])",
"type": "method",
"name": "listen",
"desc": "See [http.listen()][] for details.\n\n
\n", "signatures": [ { "params": [ { "name": "handle" }, { "name": "callback", "optional": true } ] }, { "params": [ { "name": "path" }, { "name": "callback", "optional": true } ] } ] }, { "textRaw": "server.listen(handle, [callback])", "type": "method", "name": "listen", "desc": "See [http.listen()][] for details.\n\n
\n", "signatures": [ { "params": [ { "name": "handle" }, { "name": "callback", "optional": true } ] } ] }, { "textRaw": "server.close([callback])", "type": "method", "name": "close", "desc": "See [http.close()][] for details.\n\n
\n", "signatures": [ { "params": [ { "name": "callback", "optional": true } ] } ] } ], "signatures": [ { "params": [ { "name": "options" }, { "name": "requestListener", "optional": true } ] } ] }, { "textRaw": "https.request(options, callback)", "type": "method", "name": "request", "desc": "Makes a request to a secure web server.\n\n
\noptions
can be an object or a string. If options
is a string, it is\nautomatically parsed with url.parse().\n\n
All options from [http.request()][] are valid.\n\n
\nExample:\n\n
\nvar https = require('https');\n\nvar options = {\n hostname: 'encrypted.google.com',\n port: 443,\n path: '/',\n method: 'GET'\n};\n\nvar req = https.request(options, function(res) {\n console.log("statusCode: ", res.statusCode);\n console.log("headers: ", res.headers);\n\n res.on('data', function(d) {\n process.stdout.write(d);\n });\n});\nreq.end();\n\nreq.on('error', function(e) {\n console.error(e);\n});
\nThe options argument has the following options\n\n
\nhost
: A domain name or IP address of the server to issue the request to.\nDefaults to 'localhost'
.hostname
: To support url.parse()
hostname
is preferred over host
port
: Port of remote server. Defaults to 443.method
: A string specifying the HTTP request method. Defaults to 'GET'
.path
: Request path. Defaults to '/'
. Should include query string if any.\nE.G. '/index.html?page=12'
headers
: An object containing request headers.auth
: Basic authentication i.e. 'user:password'
to compute an\nAuthorization header.agent
: Controls [Agent][] behavior. When an Agent is used request will\ndefault to Connection: keep-alive
. Possible values:undefined
(default): use [globalAgent][] for this host and port.Agent
object: explicitly use the passed in Agent
.false
: opts out of connection pooling with an Agent, defaults request to\nConnection: close
.The following options from [tls.connect()][] can also be specified. However, a\n[globalAgent][] silently ignores these.\n\n
\npfx
: Certificate, Private key and CA certificates to use for SSL. Default null
.key
: Private key to use for SSL. Default null
.passphrase
: A string of passphrase for the private key or pfx. Default null
.cert
: Public x509 certificate to use. Default null
.ca
: An authority certificate or array of authority certificates to check\nthe remote host against.ciphers
: A string describing the ciphers to use or exclude. Consult\nhttp://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for\ndetails on the format.rejectUnauthorized
: If true
, the server certificate is verified against\nthe list of supplied CAs. An 'error'
event is emitted if verification\nfails. Verification happens at the connection level, before the HTTP\nrequest is sent. Default true
.secureProtocol
: The SSL method to use, e.g. TLSv1_method
to force\nTLS version 1. The possible values depend on your installation of\nOpenSSL and are defined in the constant [SSL_METHODS][].In order to specify these options, use a custom Agent
.\n\n
Example:\n\n
\nvar 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\nvar req = https.request(options, function(res) {\n ...\n}
\nOr does not use an Agent
.\n\n
Example:\n\n
\nvar 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\nvar req = https.request(options, function(res) {\n ...\n}
\n",
"signatures": [
{
"params": [
{
"name": "options"
},
{
"name": "callback"
}
]
}
]
},
{
"textRaw": "https.get(options, callback)",
"type": "method",
"name": "get",
"desc": "Like http.get()
but for HTTPS.\n\n
options
can be an object or a string. If options
is a string, it is\nautomatically parsed with url.parse().\n\n
Example:\n\n
\nvar https = require('https');\n\nhttps.get('https://encrypted.google.com/', function(res) {\n console.log("statusCode: ", res.statusCode);\n console.log("headers: ", res.headers);\n\n res.on('data', function(d) {\n process.stdout.write(d);\n });\n\n}).on('error', function(e) {\n console.error(e);\n});
\n",
"signatures": [
{
"params": [
{
"name": "options"
},
{
"name": "callback"
}
]
}
]
}
],
"properties": [
{
"textRaw": "https.globalAgent",
"name": "globalAgent",
"desc": "Global instance of [https.Agent][] for all HTTPS client requests.\n\n
\n" } ], "type": "module", "displayName": "HTTPS" } ] }