{
  "source": "doc/api/https.md",
  "modules": [
    {
      "textRaw": "HTTPS",
      "name": "https",
      "stability": 2,
      "stabilityText": "Stable",
      "desc": "<p>HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a\nseparate module.</p>\n",
      "classes": [
        {
          "textRaw": "Class: https.Agent",
          "type": "class",
          "name": "https.Agent",
          "meta": {
            "added": [
              "v0.4.5"
            ]
          },
          "desc": "<p>An Agent object for HTTPS similar to <a href=\"http.html#http_class_http_agent\"><code>http.Agent</code></a>.  See <a href=\"#https_https_request_options_callback\"><code>https.request()</code></a>\nfor more information.</p>\n"
        },
        {
          "textRaw": "Class: https.Server",
          "type": "class",
          "name": "https.Server",
          "meta": {
            "added": [
              "v0.3.4"
            ]
          },
          "desc": "<p>This class is a subclass of <code>tls.Server</code> and emits events same as\n<a href=\"http.html#http_class_http_server\"><code>http.Server</code></a>. See <a href=\"http.html#http_class_http_server\"><code>http.Server</code></a> for more information.</p>\n",
          "methods": [
            {
              "textRaw": "server.setTimeout(msecs, callback)",
              "type": "method",
              "name": "setTimeout",
              "meta": {
                "added": [
                  "v0.11.2"
                ]
              },
              "desc": "<p>See <a href=\"http.html#http_server_settimeout_msecs_callback\"><code>http.Server#setTimeout()</code></a>.</p>\n",
              "signatures": [
                {
                  "params": [
                    {
                      "name": "msecs"
                    },
                    {
                      "name": "callback"
                    }
                  ]
                }
              ]
            }
          ],
          "properties": [
            {
              "textRaw": "server.timeout",
              "name": "timeout",
              "meta": {
                "added": [
                  "v0.11.2"
                ]
              },
              "desc": "<p>See <a href=\"http.html#http_server_timeout\"><code>http.Server#timeout</code></a>.</p>\n"
            }
          ]
        }
      ],
      "methods": [
        {
          "textRaw": "https.createServer(options[, requestListener])",
          "type": "method",
          "name": "createServer",
          "meta": {
            "added": [
              "v0.3.4"
            ]
          },
          "desc": "<p>Returns a new HTTPS web server object. The <code>options</code> is similar to\n<a href=\"tls.html#tls_tls_createserver_options_secureconnectionlistener\"><code>tls.createServer()</code></a>.  The <code>requestListener</code> is a function which is\nautomatically added to the <code>&#39;request&#39;</code> event.</p>\n<p>Example:</p>\n<pre><code class=\"lang-js\">// curl -k https://localhost:8000/\nconst https = require(&#39;https&#39;);\nconst fs = require(&#39;fs&#39;);\n\nconst options = {\n  key: fs.readFileSync(&#39;test/fixtures/keys/agent2-key.pem&#39;),\n  cert: fs.readFileSync(&#39;test/fixtures/keys/agent2-cert.pem&#39;)\n};\n\nhttps.createServer(options, (req, res) =&gt; {\n  res.writeHead(200);\n  res.end(&#39;hello world\\n&#39;);\n}).listen(8000);\n</code></pre>\n<p>Or</p>\n<pre><code class=\"lang-js\">const https = require(&#39;https&#39;);\nconst fs = require(&#39;fs&#39;);\n\nconst options = {\n  pfx: fs.readFileSync(&#39;test/fixtures/test_cert.pfx&#39;),\n  passphrase: &#39;sample&#39;\n};\n\nhttps.createServer(options, (req, res) =&gt; {\n  res.writeHead(200);\n  res.end(&#39;hello world\\n&#39;);\n}).listen(8000);\n</code></pre>\n",
          "methods": [
            {
              "textRaw": "server.close([callback])",
              "type": "method",
              "name": "close",
              "meta": {
                "added": [
                  "v0.1.90"
                ]
              },
              "desc": "<p>See <a href=\"http.html#http_server_close_callback\"><code>http.close()</code></a> for details.</p>\n",
              "signatures": [
                {
                  "params": [
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ]
            },
            {
              "textRaw": "server.listen(path[, callback])",
              "type": "method",
              "name": "listen",
              "desc": "<p>See <a href=\"http.html#http_server_listen_port_hostname_backlog_callback\"><code>http.listen()</code></a> for details.</p>\n",
              "signatures": [
                {
                  "params": [
                    {
                      "name": "port"
                    },
                    {
                      "name": "host",
                      "optional": true
                    },
                    {
                      "name": "backlog",
                      "optional": true
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                },
                {
                  "params": [
                    {
                      "name": "path"
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ]
            },
            {
              "textRaw": "server.listen(port[, host][, backlog][, callback])",
              "type": "method",
              "name": "listen",
              "desc": "<p>See <a href=\"http.html#http_server_listen_port_hostname_backlog_callback\"><code>http.listen()</code></a> for details.</p>\n",
              "signatures": [
                {
                  "params": [
                    {
                      "name": "port"
                    },
                    {
                      "name": "host",
                      "optional": true
                    },
                    {
                      "name": "backlog",
                      "optional": true
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ]
            }
          ],
          "signatures": [
            {
              "params": [
                {
                  "name": "options"
                },
                {
                  "name": "requestListener",
                  "optional": true
                }
              ]
            }
          ]
        },
        {
          "textRaw": "https.get(options, callback)",
          "type": "method",
          "name": "get",
          "meta": {
            "added": [
              "v0.3.6"
            ]
          },
          "desc": "<p>Like <a href=\"http.html#http_http_get_options_callback\"><code>http.get()</code></a> but for HTTPS.</p>\n<p><code>options</code> can be an object or a string. If <code>options</code> is a string, it is\nautomatically parsed with <a href=\"url.html#url_url_parse_urlstring_parsequerystring_slashesdenotehost\"><code>url.parse()</code></a>.</p>\n<p>Example:</p>\n<pre><code class=\"lang-js\">const https = require(&#39;https&#39;);\n\nhttps.get(&#39;https://encrypted.google.com/&#39;, (res) =&gt; {\n  console.log(&#39;statusCode:&#39;, res.statusCode);\n  console.log(&#39;headers:&#39;, res.headers);\n\n  res.on(&#39;data&#39;, (d) =&gt; {\n    process.stdout.write(d);\n  });\n\n}).on(&#39;error&#39;, (e) =&gt; {\n  console.error(e);\n});\n</code></pre>\n",
          "signatures": [
            {
              "params": [
                {
                  "name": "options"
                },
                {
                  "name": "callback"
                }
              ]
            }
          ]
        },
        {
          "textRaw": "https.request(options, callback)",
          "type": "method",
          "name": "request",
          "meta": {
            "added": [
              "v0.3.6"
            ]
          },
          "desc": "<p>Makes a request to a secure web server.</p>\n<p><code>options</code> can be an object or a string. If <code>options</code> is a string, it is\nautomatically parsed with <a href=\"url.html#url_url_parse_urlstring_parsequerystring_slashesdenotehost\"><code>url.parse()</code></a>.</p>\n<p>All options from <a href=\"http.html#http_http_request_options_callback\"><code>http.request()</code></a> are valid.</p>\n<p>Example:</p>\n<pre><code class=\"lang-js\">const https = require(&#39;https&#39;);\n\nconst options = {\n  hostname: &#39;encrypted.google.com&#39;,\n  port: 443,\n  path: &#39;/&#39;,\n  method: &#39;GET&#39;\n};\n\nconst req = https.request(options, (res) =&gt; {\n  console.log(&#39;statusCode:&#39;, res.statusCode);\n  console.log(&#39;headers:&#39;, res.headers);\n\n  res.on(&#39;data&#39;, (d) =&gt; {\n    process.stdout.write(d);\n  });\n});\n\nreq.on(&#39;error&#39;, (e) =&gt; {\n  console.error(e);\n});\nreq.end();\n</code></pre>\n<p>The options argument has the following options</p>\n<ul>\n<li><code>host</code>: A domain name or IP address of the server to issue the request to.\nDefaults to <code>&#39;localhost&#39;</code>.</li>\n<li><code>hostname</code>: Alias for <code>host</code>. To support <code>url.parse()</code> <code>hostname</code> is\npreferred over <code>host</code>.</li>\n<li><code>family</code>: IP address family to use when resolving <code>host</code> and <code>hostname</code>.\nValid values are <code>4</code> or <code>6</code>. When unspecified, both IP v4 and v6 will be\nused.</li>\n<li><code>port</code>: Port of remote server. Defaults to 443.</li>\n<li><code>localAddress</code>: Local interface to bind for network connections.</li>\n<li><code>socketPath</code>: Unix Domain Socket (use one of host:port or socketPath).</li>\n<li><code>method</code>: A string specifying the HTTP request method. Defaults to <code>&#39;GET&#39;</code>.</li>\n<li><code>path</code>: Request path. Defaults to <code>&#39;/&#39;</code>. Should include query string if any.\nE.G. <code>&#39;/index.html?page=12&#39;</code>. An exception is thrown when the request path\ncontains illegal characters. Currently, only spaces are rejected but that\nmay change in the future.</li>\n<li><code>headers</code>: An object containing request headers.</li>\n<li><code>auth</code>: Basic authentication i.e. <code>&#39;user:password&#39;</code> to compute an\nAuthorization header.</li>\n<li><code>agent</code>: Controls <a href=\"#https_class_https_agent\"><code>Agent</code></a> behavior. When an Agent is used request will\ndefault to <code>Connection: keep-alive</code>. Possible values:<ul>\n<li><code>undefined</code> (default): use <a href=\"#https_https_globalagent\"><code>globalAgent</code></a> for this host and port.</li>\n<li><code>Agent</code> object: explicitly use the passed in <code>Agent</code>.</li>\n<li><code>false</code>: opts out of connection pooling with an Agent, defaults request to\n<code>Connection: close</code>.</li>\n</ul>\n</li>\n</ul>\n<p>The following options from <a href=\"tls.html#tls_tls_connect_options_callback\"><code>tls.connect()</code></a> can also be specified:</p>\n<ul>\n<li><code>pfx</code>: Certificate, Private key and CA certificates to use for SSL. Default <code>null</code>.</li>\n<li><code>key</code>: Private key to use for SSL. Default <code>null</code>.</li>\n<li><code>passphrase</code>: A string of passphrase for the private key or pfx. Default <code>null</code>.</li>\n<li><code>cert</code>: Public x509 certificate to use. Default <code>null</code>.</li>\n<li><code>ca</code>: A string, <a href=\"buffer.html#buffer_buffer\"><code>Buffer</code></a> or array of strings or <a href=\"buffer.html#buffer_buffer\"><code>Buffer</code></a>s of trusted\ncertificates in PEM format. If this is omitted several well known &quot;root&quot;\nCAs will be used, like VeriSign. These are used to authorize connections.</li>\n<li><code>ciphers</code>: A string describing the ciphers to use or exclude. Consult\n<a href=\"https://www.openssl.org/docs/man1.0.2/apps/ciphers.html#CIPHER-LIST-FORMAT\">https://www.openssl.org/docs/man1.0.2/apps/ciphers.html#CIPHER-LIST-FORMAT</a> for\ndetails on the format.</li>\n<li><code>rejectUnauthorized</code>: If <code>true</code>, the server certificate is verified against\nthe list of supplied CAs. An <code>&#39;error&#39;</code> event is emitted if verification\nfails. Verification happens at the connection level, <em>before</em> the HTTP\nrequest is sent. Default <code>true</code>.</li>\n<li><code>secureProtocol</code>: The SSL method to use, e.g. <code>SSLv3_method</code> to force\nSSL version 3. The possible values depend on your installation of\nOpenSSL and are defined in the constant <a href=\"https://www.openssl.org/docs/man1.0.2/ssl/ssl.html#DEALING-WITH-PROTOCOL-METHODS\"><code>SSL_METHODS</code></a>.</li>\n<li><code>servername</code>: Servername for SNI (Server Name Indication) TLS extension.</li>\n</ul>\n<p>In order to specify these options, use a custom <a href=\"#https_class_https_agent\"><code>Agent</code></a>.</p>\n<p>Example:</p>\n<pre><code class=\"lang-js\">const options = {\n  hostname: &#39;encrypted.google.com&#39;,\n  port: 443,\n  path: &#39;/&#39;,\n  method: &#39;GET&#39;,\n  key: fs.readFileSync(&#39;test/fixtures/keys/agent2-key.pem&#39;),\n  cert: fs.readFileSync(&#39;test/fixtures/keys/agent2-cert.pem&#39;)\n};\noptions.agent = new https.Agent(options);\n\nconst req = https.request(options, (res) =&gt; {\n  // ...\n});\n</code></pre>\n<p>Alternatively, opt out of connection pooling by not using an <code>Agent</code>.</p>\n<p>Example:</p>\n<pre><code class=\"lang-js\">const options = {\n  hostname: &#39;encrypted.google.com&#39;,\n  port: 443,\n  path: &#39;/&#39;,\n  method: &#39;GET&#39;,\n  key: fs.readFileSync(&#39;test/fixtures/keys/agent2-key.pem&#39;),\n  cert: fs.readFileSync(&#39;test/fixtures/keys/agent2-cert.pem&#39;),\n  agent: false\n};\n\nconst req = https.request(options, (res) =&gt; {\n  // ...\n});\n</code></pre>\n",
          "signatures": [
            {
              "params": [
                {
                  "name": "options"
                },
                {
                  "name": "callback"
                }
              ]
            }
          ]
        }
      ],
      "properties": [
        {
          "textRaw": "https.globalAgent",
          "name": "globalAgent",
          "meta": {
            "added": [
              "v0.5.9"
            ]
          },
          "desc": "<p>Global instance of <a href=\"#https_class_https_agent\"><code>https.Agent</code></a> for all HTTPS client requests.</p>\n"
        }
      ],
      "type": "module",
      "displayName": "HTTPS"
    }
  ]
}