doc/api/https.markdown

   1 # HTTPS
   2
   3     Stability: 3 - Stable
   4
   5 HTTPS is the HTTP protocol over TLS/SSL. In Node this is implemented as a
   6 separate module.
   7
   8 ## Class: https.Server
   9
  10 This class is a subclass of `tls.Server` and emits events same as
  11 `http.Server`. See `http.Server` for more information.
  12
  13 ## https.createServer(options, [requestListener])
  14
  15 Returns a new HTTPS web server object. The `options` is similar to
  16 [tls.createServer()](tls.html#tls.createServer).  The `requestListener` is
  17 a function which is automatically added to the `'request'` event.
  18
  19 Example:
  20
  21     // curl -k https://localhost:8000/
  22     var https = require('https');
  23     var fs = require('fs');
  24
  25     var options = {
  26       key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  27       cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
  28     };
  29
  30     https.createServer(options, function (req, res) {
  31       res.writeHead(200);
  32       res.end("hello world\n");
  33     }).listen(8000);
  34
  35 Or
  36
  37     var https = require('https');
  38     var fs = require('fs');
  39
  40     var options = {
  41       pfx: fs.readFileSync('server.pfx')
  42     };
  43
  44     https.createServer(options, function (req, res) {
  45       res.writeHead(200);
  46       res.end("hello world\n");
  47     }).listen(8000);
  48
  49 ## https.request(options, callback)
  50
  51 Makes a request to a secure web server.
  52 All options from [http.request()](http.html#http.request) are valid.
  53
  54 Example:
  55
  56     var https = require('https');
  57
  58     var options = {
  59       host: 'encrypted.google.com',
  60       port: 443,
  61       path: '/',
  62       method: 'GET'
  63     };
  64
  65     var req = https.request(options, function(res) {
  66       console.log("statusCode: ", res.statusCode);
  67       console.log("headers: ", res.headers);
  68
  69       res.on('data', function(d) {
  70         process.stdout.write(d);
  71       });
  72     });
  73     req.end();
  74
  75     req.on('error', function(e) {
  76       console.error(e);
  77     });
  78
  79 The options argument has the following options
  80
  81 - host: IP or domain of host to make request to. Defaults to `'localhost'`.
  82 - port: port of host to request to. Defaults to 443.
  83 - path: Path to request. Default `'/'`.
  84 - method: HTTP request method. Default `'GET'`.
  85
  86 - `host`: A domain name or IP address of the server to issue the request to.
  87   Defaults to `'localhost'`.
  88 - `hostname`: To support `url.parse()` `hostname` is preferred over `host`
  89 - `port`: Port of remote server. Defaults to 443.
  90 - `method`: A string specifying the HTTP request method. Defaults to `'GET'`.
  91 - `path`: Request path. Defaults to `'/'`. Should include query string if any.
  92   E.G. `'/index.html?page=12'`
  93 - `headers`: An object containing request headers.
  94 - `auth`: Basic authentication i.e. `'user:password'` to compute an
  95   Authorization header.
  96 - `agent`: Controls [Agent](#https.Agent) behavior. When an Agent is
  97   used request will default to `Connection: keep-alive`. Possible values:
  98  - `undefined` (default): use [globalAgent](#https.globalAgent) for this
  99    host and port.
 100  - `Agent` object: explicitly use the passed in `Agent`.
 101  - `false`: opts out of connection pooling with an Agent, defaults request to
 102    `Connection: close`.
 103
 104 The following options from [tls.connect()](tls.html#tls.connect) can also be
 105 specified. However, a [globalAgent](#https.globalAgent) silently ignores these.
 106
 107 - `pfx`: Certificate, Private key and CA certificates to use for SSL. Default `null`.
 108 - `key`: Private key to use for SSL. Default `null`.
 109 - `passphrase`: A string of passphrase for the private key or pfx. Default `null`.
 110 - `cert`: Public x509 certificate to use. Default `null`.
 111 - `ca`: An authority certificate or array of authority certificates to check
 112   the remote host against.
 113 - `ciphers`: A string describing the ciphers to use or exclude. Consult
 114   <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT> for
 115   details on the format.
 116 - `rejectUnauthorized`: If `true`, the server certificate is verified against
 117   the list of supplied CAs. An `'error'` event is emitted if verification
 118   fails. Verification happens at the connection level, *before* the HTTP
 119   request is sent. Default `false`.
 120
 121 In order to specify these options, use a custom `Agent`.
 122
 123 Example:
 124
 125     var options = {
 126       host: 'encrypted.google.com',
 127       port: 443,
 128       path: '/',
 129       method: 'GET',
 130       key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
 131       cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
 132     };
 133     options.agent = new https.Agent(options);
 134
 135     var req = https.request(options, function(res) {
 136       ...
 137     }
 138
 139 Or does not use an `Agent`.
 140
 141 Example:
 142
 143     var options = {
 144       host: 'encrypted.google.com',
 145       port: 443,
 146       path: '/',
 147       method: 'GET',
 148       key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
 149       cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
 150       agent: false
 151     };
 152
 153     var req = https.request(options, function(res) {
 154       ...
 155     }
 156
 157 ## https.get(options, callback)
 158
 159 Like `http.get()` but for HTTPS.
 160
 161 Example:
 162
 163     var https = require('https');
 164
 165     https.get({ host: 'encrypted.google.com', path: '/' }, function(res) {
 166       console.log("statusCode: ", res.statusCode);
 167       console.log("headers: ", res.headers);
 168
 169       res.on('data', function(d) {
 170         process.stdout.write(d);
 171       });
 172
 173     }).on('error', function(e) {
 174       console.error(e);
 175     });
 176
 177
 178 ## Class: https.Agent
 179
 180 An Agent object for HTTPS similar to [http.Agent](http.html#http.Agent).
 181 See [https.request()](#https.request) for more information.
 182
 183
 184 ## https.globalAgent
 185
 186 Global instance of [https.Agent](#https.Agent) which is used as the default
 187 for all HTTPS client requests.