- Assertion Testing
- Buffer
- C/C++ Addons
- Child Processes
- Cluster
- Command Line Options
- Console
- Crypto
- Debugger
- DNS
- Domain
- Errors
- Events
- File System
- Globals
- HTTP
- HTTPS
- Modules
- Net
- OS
- Path
- Process
- Punycode
- Query Strings
- Readline
- REPL
- Stream
- String Decoder
- Timers
- TLS/SSL
- TTY
- UDP/Datagram
- URL
- Utilities
- V8
- VM
- ZLIB
Node.js v7.5.1-nightly2017020113a024d531 Documentation
Table of Contents
HTTPS#
Stability: 2 - Stable
HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a separate module.
Class: https.Agent#
An Agent object for HTTPS similar to http.Agent
. See https.request()
for more information.
Class: https.Server#
This class is a subclass of tls.Server
and emits events same as
http.Server
. See http.Server
for more information.
server.setTimeout(msecs, callback)#
server.timeout#
See http.Server#timeout
.
https.createServer(options[, requestListener])#
Returns a new HTTPS web server object. The options
is similar to
tls.createServer()
. The requestListener
is a function which is
automatically added to the 'request'
event.
Example:
// curl -k https://localhost:8000/
const https = require('https');
const fs = require('fs');
const options = {
key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
};
https.createServer(options, (req, res) => {
res.writeHead(200);
res.end('hello world\n');
}).listen(8000);
Or
const https = require('https');
const fs = require('fs');
const options = {
pfx: fs.readFileSync('server.pfx')
};
https.createServer(options, (req, res) => {
res.writeHead(200);
res.end('hello world\n');
}).listen(8000);
server.close([callback])#
See http.close()
for details.
server.listen(handle[, callback])#
server.listen(path[, callback])#
server.listen(port[, host][, backlog][, callback])#
See http.listen()
for details.
https.get(options, callback)#
Like http.get()
but for HTTPS.
options
can be an object or a string. If options
is a string, it is
automatically parsed with url.parse()
.
Example:
const https = require('https');
https.get('https://encrypted.google.com/', (res) => {
console.log('statusCode:', res.statusCode);
console.log('headers:', res.headers);
res.on('data', (d) => {
process.stdout.write(d);
});
}).on('error', (e) => {
console.error(e);
});
https.globalAgent#
Global instance of https.Agent
for all HTTPS client requests.
https.request(options, callback)#
Makes a request to a secure web server.
options
can be an object or a string. If options
is a string, it is
automatically parsed with url.parse()
.
All options from http.request()
are valid.
Example:
const https = require('https');
var options = {
hostname: 'encrypted.google.com',
port: 443,
path: '/',
method: 'GET'
};
var req = https.request(options, (res) => {
console.log('statusCode:', res.statusCode);
console.log('headers:', res.headers);
res.on('data', (d) => {
process.stdout.write(d);
});
});
req.on('error', (e) => {
console.error(e);
});
req.end();
The options argument has the following options
host
: A domain name or IP address of the server to issue the request to. Defaults to'localhost'
.hostname
: Alias forhost
. To supporturl.parse()
hostname
is preferred overhost
.family
: IP address family to use when resolvinghost
andhostname
. Valid values are4
or6
. When unspecified, both IP v4 and v6 will be used.port
: Port of remote server. Defaults to 443.localAddress
: Local interface to bind for network connections.socketPath
: Unix Domain Socket (use one of host:port or socketPath).method
: A string specifying the HTTP request method. Defaults to'GET'
.path
: Request path. Defaults to'/'
. Should include query string if any. E.G.'/index.html?page=12'
. An exception is thrown when the request path contains illegal characters. Currently, only spaces are rejected but that may change in the future.headers
: An object containing request headers.auth
: Basic authentication i.e.'user:password'
to compute an Authorization header.agent
: ControlsAgent
behavior. When an Agent is used request will default toConnection: keep-alive
. Possible values:undefined
(default): useglobalAgent
for this host and port.Agent
object: explicitly use the passed inAgent
.false
: opts out of connection pooling with an Agent, defaults request toConnection: close
.
The following options from tls.connect()
can also be specified:
pfx
: Certificate, Private key and CA certificates to use for SSL. Defaultnull
.key
: Private key to use for SSL. Defaultnull
.passphrase
: A string of passphrase for the private key or pfx. Defaultnull
.cert
: Public x509 certificate to use. Defaultnull
.ca
: A string,Buffer
or array of strings orBuffer
s of trusted certificates in PEM format. If this is omitted several well known "root" CAs will be used, like VeriSign. These are used to authorize connections.ciphers
: A string describing the ciphers to use or exclude. Consult https://www.openssl.org/docs/man1.0.2/apps/ciphers.html#CIPHER-LIST-FORMAT for details on the format.rejectUnauthorized
: Iftrue
, the server certificate is verified against the list of supplied CAs. An'error'
event is emitted if verification fails. Verification happens at the connection level, before the HTTP request is sent. Defaulttrue
.secureProtocol
: The SSL method to use, e.g.SSLv3_method
to force SSL version 3. The possible values depend on your installation of OpenSSL and are defined in the constantSSL_METHODS
.servername
: Servername for SNI (Server Name Indication) TLS extension.
In order to specify these options, use a custom Agent
.
Example:
var options = {
hostname: 'encrypted.google.com',
port: 443,
path: '/',
method: 'GET',
key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
};
options.agent = new https.Agent(options);
var req = https.request(options, (res) => {
...
});
Alternatively, opt out of connection pooling by not using an Agent
.
Example:
var options = {
hostname: 'encrypted.google.com',
port: 443,
path: '/',
method: 'GET',
key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
agent: false
};
var req = https.request(options, (res) => {
...
});