Node.js

- About these Docs
- Usage & Example

- Assertion Testing
- Async Hooks
- Buffer
- C++ Addons
- C/C++ Addons - N-API
- Child Processes
- Cluster
- Command Line Options
- Console
- Crypto
- Debugger
- Deprecated APIs
- DNS
- Domain
- ECMAScript Modules
- Errors
- Events
- File System
- Globals
- HTTP
- HTTP/2
- HTTPS
- Inspector
- Internationalization
- Modules
- Net
- OS
- Path
- Performance Hooks
- Process
- Punycode
- Query Strings
- Readline
- REPL
- Stream
- String Decoder
- Timers
- TLS/SSL
- Tracing
- TTY
- UDP/Datagram
- URL
- Utilities
- V8
- VM
- ZLIB

- GitHub Repo & Issue Tracker
- Mailing List

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

Added in: v0.4.5

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

## Class: https.Server#

Added in: v0.3.4

This class is a subclass of `tls.Server` and emits events same as `http.Server`. See `http.Server` for more information.

### server.close([callback])#

Added in: v0.1.90

- `callback` <Function>

See `server.close()` from the HTTP module for details.

### server.listen()#

Starts the HTTPS server listening for encrypted connections. This method is identical to `server.listen()` from `net.Server`.

### server.setTimeout([msecs][, callback])#

Added in: v0.11.2

- `msecs` <number> Defaults to 120000 (2 minutes).
- `callback` <Function>

See `http.Server#setTimeout()`.

### server.timeout#

Added in: v0.11.2

- <number> Defaults to 120000 (2 minutes).

See `http.Server#timeout`.

### server.keepAliveTimeout#

Added in: v8.0.0

- <number> Defaults to 5000 (5 seconds).

See `http.Server#keepAliveTimeout`.

## https.createServer([options][, requestListener])#

Added in: v0.3.4

- `options` <Object> Accepts `options` from `tls.createServer()`, `tls.createSecureContext()` and `http.createServer()`.
- `requestListener` <Function> A listener to be 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('test/fixtures/test_cert.pfx'),
      passphrase: 'sample'
    };

    https.createServer(options, (req, res) => {
      res.writeHead(200);
      res.end('hello world\n');
    }).listen(8000);

## https.get(options[, callback])#

History

Version | Changes
--- | ---
v7.5.0 | The `options` parameter can be a WHATWG `URL` object.
v0.3.6 | Added in: v0.3.6

- `options` <Object> | <string> | <URL> Accepts the same `options` as `https.request()`, with the `method` always set to `GET`.
- `callback` <Function>

Like `http.get()` but for HTTPS.

`options` can be an object, a string, or a `URL` object. If `options` is a string, it is automatically parsed with `url.parse()`. If it is a `URL` object, it will be automatically converted to an ordinary `options` object.

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#

Added in: v0.5.9

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

## https.request(options[, callback])#

History

Version | Changes
--- | ---
v9.3.0 | The `options` parameter can now include `clientCertEngine`.
v7.5.0 | The `options` parameter can be a WHATWG `URL` object.
v0.3.6 | Added in: v0.3.6

- `options` <Object> | <string> | <URL> Accepts all `options` from `http.request()`, with some differences in default values:
  - `protocol` Defaults to `https:`
  - `port` Defaults to `443`.
  - `agent` Defaults to `https.globalAgent`.
- `callback` <Function>

Makes a request to a secure web server.

The following additional `options` from `tls.connect()` are also accepted: `ca`, `cert`, `ciphers`, `clientCertEngine`, `crl`, `dhparam`, `ecdhCurve`, `honorCipherOrder`, `key`, `passphrase`, `pfx`, `rejectUnauthorized`, `secureOptions`, `secureProtocol`, `servername`, `sessionIdContext`

`options` can be an object, a string, or a `URL` object. If `options` is a string, it is automatically parsed with `url.parse()`. If it is a `URL` object, it will be automatically converted to an ordinary `options` object.

Example:

    const https = require('https');

    const options = {
      hostname: 'encrypted.google.com',
      port: 443,
      path: '/',
      method: 'GET'
    };

    const 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();

Example using options from `tls.connect()`:

    const 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);

    const req = https.request(options, (res) => {
      // ...
    });

Alternatively, opt out of connection pooling by not using an `Agent`.

Example:

    const 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
    };

    const req = https.request(options, (res) => {
      // ...
    });

Example using a `URL` as `options`:

    const { URL } = require('url');

    const options = new URL('https://abc:xyz@example.com');

    const req = https.request(options, (res) => {
      // ...
    });