HTTPS

  1. Stability: 3 - Stable

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

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)

See http.Server#setTimeout().

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:

  1. // curl -k https://localhost:8000/
  2. var https = require('https');
  3. var fs = require('fs');
  5. var options = {
  6.   key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  7.   cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
  8. };
  10. https.createServer(options, function (req, res) {
  11.   res.writeHead(200);
  12.   res.end("hello world\n");
  13. }).listen(8000);

Or

  1. var https = require('https');
  2. var fs = require('fs');
  4. var options = {
  5.   pfx: fs.readFileSync('server.pfx')
  6. };
  8. https.createServer(options, function (req, res) {
  9.   res.writeHead(200);
  10.   res.end("hello world\n");
  11. }).listen(8000);

server.listen(port[, host][, backlog][, callback])

server.listen(path[, callback])

server.listen(handle[, callback])

See http.listen() for details.

server.close([callback])

See http.close() for details.

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:

  1. var https = require('https');
  3. var options = {
  4.   hostname: 'encrypted.google.com',
  5.   port: 443,
  6.   path: '/',
  7.   method: 'GET'
  8. };
  10. var req = https.request(options, function(res) {
  11.   console.log("statusCode: ", res.statusCode);
  12.   console.log("headers: ", res.headers);
  14.   res.on('data', function(d) {
  15.     process.stdout.write(d);
  16.   });
  17. });
  18. req.end();
  20. req.on('error', function(e) {
  21.   console.error(e);
  22. });

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: 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.
    E.G. '/index.html?page=12'
  • headers: An object containing request headers.
  • auth: Basic authentication i.e. 'user:password' to compute an
    Authorization header.
  • agent: Controls Agent behavior. When an Agent is used request will
    default 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
      Connection: close.

The following options from tls.connect() can also be specified. However, a
globalAgent silently ignores these.

  • pfx: 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
    the remote host against.
  • ciphers: A string describing the ciphers to use or exclude. Consult
    http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for
    details on the format.
  • rejectUnauthorized: If true, 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. Default true.
  • secureProtocol: The SSL method to use, e.g. TLSv1_method to force
    TLS version 1. The possible values depend on your installation of
    OpenSSL and are defined in the constant SSL_METHODS.

In order to specify these options, use a custom Agent.

Example:

  1. var options = {
  2.   hostname: 'encrypted.google.com',
  3.   port: 443,
  4.   path: '/',
  5.   method: 'GET',
  6.   key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  7.   cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
  8. };
  9. options.agent = new https.Agent(options);
  11. var req = https.request(options, function(res) {
  12.   ...
  13. }

Or does not use an Agent.

Example:

  1. var options = {
  2.   hostname: 'encrypted.google.com',
  3.   port: 443,
  4.   path: '/',
  5.   method: 'GET',
  6.   key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  7.   cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
  8.   agent: false
  9. };
  11. var req = https.request(options, function(res) {
  12.   ...
  13. }

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:

  1. var https = require('https');
  3. https.get('https://encrypted.google.com/', function(res) {
  4.   console.log("statusCode: ", res.statusCode);
  5.   console.log("headers: ", res.headers);
  7.   res.on('data', function(d) {
  8.     process.stdout.write(d);
  9.   });
  11. }).on('error', function(e) {
  12.   console.error(e);
  13. });

Class: https.Agent

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

https.globalAgent

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