Node.js (1)

- About these Docs
- Synopsis
- Assertion Testing
- Buffer
- C/C++ Addons
- Child Processes
- Cluster
- 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

# 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)#

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:

    // 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.end();

    req.on('error', (e) => {
      console.error(e);
    });

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 for `host`. To support `url.parse()` `hostname` is preferred over `host`.
- `family`: IP address family to use when resolving `host` and `hostname`. Valid values are `4` or `6`. 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`: 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`: A string, `Buffer` or array of strings or `Buffer`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/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. `SSLv3_method` to force SSL version 3. 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:

    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) => {
      ...
    }