561 lines
38 KiB
HTML
561 lines
38 KiB
HTML
<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width">
|
|
<meta name="nodejs.org:node-version" content="v12.22.12">
|
|
<title>HTTPS | Node.js v12.22.12 Documentation</title>
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback">
|
|
<link rel="stylesheet" href="assets/style.css">
|
|
<link rel="stylesheet" href="assets/hljs.css">
|
|
<link rel="canonical" href="https://nodejs.org/api/https.html">
|
|
</head>
|
|
<body class="alt apidoc" id="api-section-https">
|
|
<div id="content" class="clearfix">
|
|
<div id="column2" class="interior">
|
|
<div id="intro" class="interior">
|
|
<a href="/" title="Go back to the home page">
|
|
Node.js
|
|
</a>
|
|
</div>
|
|
<ul>
|
|
<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li>
|
|
<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li>
|
|
</ul>
|
|
<hr class="line">
|
|
<ul>
|
|
<li><a href="assert.html" class="nav-assert">Assertion testing</a></li>
|
|
<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li>
|
|
<li><a href="buffer.html" class="nav-buffer">Buffer</a></li>
|
|
<li><a href="addons.html" class="nav-addons">C++ Addons</a></li>
|
|
<li><a href="n-api.html" class="nav-n-api">C/C++ Addons with N-API</a></li>
|
|
<li><a href="embedding.html" class="nav-embedding">C++ Embedder API</a></li>
|
|
<li><a href="child_process.html" class="nav-child_process">Child Processes</a></li>
|
|
<li><a href="cluster.html" class="nav-cluster">Cluster</a></li>
|
|
<li><a href="cli.html" class="nav-cli">Command line options</a></li>
|
|
<li><a href="console.html" class="nav-console">Console</a></li>
|
|
<li><a href="crypto.html" class="nav-crypto">Crypto</a></li>
|
|
<li><a href="debugger.html" class="nav-debugger">Debugger</a></li>
|
|
<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li>
|
|
<li><a href="dns.html" class="nav-dns">DNS</a></li>
|
|
<li><a href="domain.html" class="nav-domain">Domain</a></li>
|
|
<li><a href="errors.html" class="nav-errors">Errors</a></li>
|
|
<li><a href="events.html" class="nav-events">Events</a></li>
|
|
<li><a href="fs.html" class="nav-fs">File system</a></li>
|
|
<li><a href="globals.html" class="nav-globals">Globals</a></li>
|
|
<li><a href="http.html" class="nav-http">HTTP</a></li>
|
|
<li><a href="http2.html" class="nav-http2">HTTP/2</a></li>
|
|
<li><a href="https.html" class="nav-https active">HTTPS</a></li>
|
|
<li><a href="inspector.html" class="nav-inspector">Inspector</a></li>
|
|
<li><a href="intl.html" class="nav-intl">Internationalization</a></li>
|
|
<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li>
|
|
<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li>
|
|
<li><a href="module.html" class="nav-module">Modules: <code>module</code> API</a></li>
|
|
<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li>
|
|
<li><a href="net.html" class="nav-net">Net</a></li>
|
|
<li><a href="os.html" class="nav-os">OS</a></li>
|
|
<li><a href="path.html" class="nav-path">Path</a></li>
|
|
<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li>
|
|
<li><a href="policy.html" class="nav-policy">Policies</a></li>
|
|
<li><a href="process.html" class="nav-process">Process</a></li>
|
|
<li><a href="punycode.html" class="nav-punycode">Punycode</a></li>
|
|
<li><a href="querystring.html" class="nav-querystring">Query strings</a></li>
|
|
<li><a href="readline.html" class="nav-readline">Readline</a></li>
|
|
<li><a href="repl.html" class="nav-repl">REPL</a></li>
|
|
<li><a href="report.html" class="nav-report">Report</a></li>
|
|
<li><a href="stream.html" class="nav-stream">Stream</a></li>
|
|
<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li>
|
|
<li><a href="timers.html" class="nav-timers">Timers</a></li>
|
|
<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li>
|
|
<li><a href="tracing.html" class="nav-tracing">Trace events</a></li>
|
|
<li><a href="tty.html" class="nav-tty">TTY</a></li>
|
|
<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li>
|
|
<li><a href="url.html" class="nav-url">URL</a></li>
|
|
<li><a href="util.html" class="nav-util">Utilities</a></li>
|
|
<li><a href="v8.html" class="nav-v8">V8</a></li>
|
|
<li><a href="vm.html" class="nav-vm">VM</a></li>
|
|
<li><a href="wasi.html" class="nav-wasi">WASI</a></li>
|
|
<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li>
|
|
<li><a href="zlib.html" class="nav-zlib">Zlib</a></li>
|
|
</ul>
|
|
<hr class="line">
|
|
<ul>
|
|
<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div id="column1" data-id="https" class="interior">
|
|
<header>
|
|
<h1>Node.js v12.22.12 Documentation</h1>
|
|
<div id="gtoc">
|
|
<ul>
|
|
<li>
|
|
<a href="index.html">Index</a>
|
|
</li>
|
|
<li>
|
|
<a href="all.html">View on single page</a>
|
|
</li>
|
|
<li>
|
|
<a href="https.json">View as JSON</a>
|
|
</li>
|
|
|
|
<li class="version-picker">
|
|
<a href="#">View another version <span>▼</span></a>
|
|
<ol class="version-picker"><li><a href="https://nodejs.org/docs/latest-v17.x/api/https.html">17.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v16.x/api/https.html">16.x <b>LTS</b></a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v15.x/api/https.html">15.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v14.x/api/https.html">14.x <b>LTS</b></a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v13.x/api/https.html">13.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v12.x/api/https.html">12.x <b>LTS</b></a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v11.x/api/https.html">11.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v10.x/api/https.html">10.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v9.x/api/https.html">9.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v8.x/api/https.html">8.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v7.x/api/https.html">7.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v6.x/api/https.html">6.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v5.x/api/https.html">5.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v4.x/api/https.html">4.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v0.12.x/api/https.html">0.12.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v0.10.x/api/https.html">0.10.x</a></li></ol>
|
|
</li>
|
|
|
|
<li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/master/doc/api/https.md"><span class="github_icon"><svg height="16" width="16" viewBox="0 0 16.1 16.1" fill="currentColor"><path d="M8 0a8 8 0 0 0-2.5 15.6c.4 0 .5-.2.5-.4v-1.5c-2 .4-2.5-.5-2.7-1 0-.1-.5-.9-.8-1-.3-.2-.7-.6 0-.6.6 0 1 .6 1.2.8.7 1.2 1.9 1 2.4.7 0-.5.2-.9.5-1-1.8-.3-3.7-1-3.7-4 0-.9.3-1.6.8-2.2 0-.2-.3-1 .1-2 0 0 .7-.3 2.2.7a7.4 7.4 0 0 1 4 0c1.5-1 2.2-.8 2.2-.8.5 1.1.2 2 .1 2.1.5.6.8 1.3.8 2.2 0 3-1.9 3.7-3.6 4 .3.2.5.7.5 1.4v2.2c0 .2.1.5.5.4A8 8 0 0 0 16 8a8 8 0 0 0-8-8z"/></svg></span>Edit on GitHub</a></li>
|
|
</ul>
|
|
</div>
|
|
<hr>
|
|
</header>
|
|
|
|
<div id="toc">
|
|
<h2>Table of Contents</h2>
|
|
<ul>
|
|
<li><span class="stability_2"><a href="#https_https">HTTPS</a></span>
|
|
<ul>
|
|
<li><a href="#https_class_https_agent">Class: <code>https.Agent</code></a>
|
|
<ul>
|
|
<li><a href="#https_new_agent_options"><code>new Agent([options])</code></a>
|
|
<ul>
|
|
<li><a href="#https_event_keylog">Event: <code>'keylog'</code></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#https_class_https_server">Class: <code>https.Server</code></a>
|
|
<ul>
|
|
<li><a href="#https_server_close_callback"><code>server.close([callback])</code></a></li>
|
|
<li><a href="#https_server_headerstimeout"><code>server.headersTimeout</code></a></li>
|
|
<li><a href="#https_server_listen"><code>server.listen()</code></a></li>
|
|
<li><a href="#https_server_maxheaderscount"><code>server.maxHeadersCount</code></a></li>
|
|
<li><a href="#https_server_settimeout_msecs_callback"><code>server.setTimeout([msecs][, callback])</code></a></li>
|
|
<li><a href="#https_server_timeout"><code>server.timeout</code></a></li>
|
|
<li><a href="#https_server_keepalivetimeout"><code>server.keepAliveTimeout</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#https_https_createserver_options_requestlistener"><code>https.createServer([options][, requestListener])</code></a></li>
|
|
<li><a href="#https_https_get_options_callback"><code>https.get(options[, callback])</code></a></li>
|
|
<li><a href="#https_https_get_url_options_callback"><code>https.get(url[, options][, callback])</code></a></li>
|
|
<li><a href="#https_https_globalagent"><code>https.globalAgent</code></a></li>
|
|
<li><a href="#https_https_request_options_callback"><code>https.request(options[, callback])</code></a></li>
|
|
<li><a href="#https_https_request_url_options_callback"><code>https.request(url[, options][, callback])</code></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div id="apicontent">
|
|
<h1>HTTPS<span><a class="mark" href="#https_https" id="https_https">#</a></span></h1>
|
|
|
|
<p></p><div class="api_stability api_stability_2"><a href="documentation.html#documentation_stability_index">Stability: 2</a> - Stable</div><p></p>
|
|
<p><strong>Source Code:</strong> <a href="https://github.com/nodejs/node/blob/v12.22.12/lib/https.js">lib/https.js</a></p>
|
|
<p>HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a
|
|
separate module.</p>
|
|
<h2>Class: <code>https.Agent</code><span><a class="mark" href="#https_class_https_agent" id="https_class_https_agent">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v5.3.0</td>
|
|
<td><p>support <code>0</code> <code>maxCachedSessions</code> to disable TLS session caching.</p></td></tr>
|
|
<tr><td>v2.5.0</td>
|
|
<td><p>parameter <code>maxCachedSessions</code> added to <code>options</code> for TLS sessions reuse.</p></td></tr>
|
|
<tr><td>v0.4.5</td>
|
|
<td><p><span>Added in: v0.4.5</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<p>An <a href="#https_class_https_agent"><code>Agent</code></a> 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> for more information.</p>
|
|
<h3><code>new Agent([options])</code><span><a class="mark" href="#https_new_agent_options" id="https_new_agent_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.5.0</td>
|
|
<td><p>do not automatically set servername if the target host was specified using an IP address.</p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li>
|
|
<p><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Set of configurable options to set on the agent.
|
|
Can have the same fields as for <a href="http.html#http_new_agent_options"><code>http.Agent(options)</code></a>, and</p>
|
|
<ul>
|
|
<li>
|
|
<p><code>maxCachedSessions</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> maximum number of TLS cached sessions.
|
|
Use <code>0</code> to disable TLS session caching. <strong>Default:</strong> <code>100</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>servername</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> the value of
|
|
<a href="https://en.wikipedia.org/wiki/Server_Name_Indication">Server Name Indication extension</a> to be sent to the server. Use
|
|
empty string <code>''</code> to disable sending the extension.
|
|
<strong>Default:</strong> host name of the target server, unless the target server
|
|
is specified using an IP address, in which case the default is <code>''</code> (no
|
|
extension).</p>
|
|
<p>See <a href="tls.html#tls_session_resumption"><code>Session Resumption</code></a> for information about TLS session reuse.</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<h4>Event: <code>'keylog'</code><span><a class="mark" href="#https_event_keylog" id="https_event_keylog">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v12.16.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>line</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> Line of ASCII text, in NSS <code>SSLKEYLOGFILE</code> format.</li>
|
|
<li><code>tlsSocket</code> <a href="tls.html#tls_class_tls_tlssocket" class="type"><tls.TLSSocket></a> The <code>tls.TLSSocket</code> instance on which it was
|
|
generated.</li>
|
|
</ul>
|
|
<p>The <code>keylog</code> event is emitted when key material is generated or received by a
|
|
connection managed by this agent (typically before handshake has completed, but
|
|
not necessarily). This keying material can be stored for debugging, as it
|
|
allows captured TLS traffic to be decrypted. It may be emitted multiple times
|
|
for each socket.</p>
|
|
<p>A typical use case is to append received lines to a common text file, which is
|
|
later used by software (such as Wireshark) to decrypt the traffic:</p>
|
|
<pre><code class="language-js"><span class="hljs-comment">// ...</span>
|
|
https.globalAgent.on(<span class="hljs-string">'keylog'</span>, <span class="hljs-function">(<span class="hljs-params">line, tlsSocket</span>) =></span> {
|
|
fs.appendFileSync(<span class="hljs-string">'/tmp/ssl-keys.log'</span>, line, { <span class="hljs-attr">mode</span>: <span class="hljs-number">0o600</span> });
|
|
});</code></pre>
|
|
<h2>Class: <code>https.Server</code><span><a class="mark" href="#https_class_https_server" id="https_class_https_server">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.3.4</span>
|
|
</div>
|
|
<ul>
|
|
<li>Extends: <a href="tls.html#tls_class_tls_server" class="type"><tls.Server></a></li>
|
|
</ul>
|
|
<p>See <a href="http.html#http_class_http_server"><code>http.Server</code></a> for more information.</p>
|
|
<h3><code>server.close([callback])</code><span><a class="mark" href="#https_server_close_callback" id="https_server_close_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li>
|
|
<li>Returns: <a href="https.html#https_class_https_server" class="type"><https.Server></a></li>
|
|
</ul>
|
|
<p>See <a href="http.html#http_server_close_callback"><code>server.close()</code></a> from the HTTP module for details.</p>
|
|
<h3><code>server.headersTimeout</code><span><a class="mark" href="#https_server_headerstimeout" id="https_server_headerstimeout">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v11.3.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> <strong>Default:</strong> <code>60000</code></li>
|
|
</ul>
|
|
<p>See <a href="http.html#http_server_headerstimeout"><code>http.Server#headersTimeout</code></a>.</p>
|
|
<h3><code>server.listen()</code><span><a class="mark" href="#https_server_listen" id="https_server_listen">#</a></span></h3>
|
|
<p>Starts the HTTPS server listening for encrypted connections.
|
|
This method is identical to <a href="net.html#net_server_listen"><code>server.listen()</code></a> from <a href="net.html#net_class_net_server"><code>net.Server</code></a>.</p>
|
|
<h3><code>server.maxHeadersCount</code><span><a class="mark" href="#https_server_maxheaderscount" id="https_server_maxheaderscount">#</a></span></h3>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> <strong>Default:</strong> <code>2000</code></li>
|
|
</ul>
|
|
<p>See <a href="http.html#http_server_maxheaderscount"><code>http.Server#maxHeadersCount</code></a>.</p>
|
|
<h3><code>server.setTimeout([msecs][, callback])</code><span><a class="mark" href="#https_server_settimeout_msecs_callback" id="https_server_settimeout_msecs_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.2</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>msecs</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> <strong>Default:</strong> <code>120000</code> (2 minutes)</li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li>
|
|
<li>Returns: <a href="https.html#https_class_https_server" class="type"><https.Server></a></li>
|
|
</ul>
|
|
<p>See <a href="http.html#http_server_settimeout_msecs_callback"><code>http.Server#setTimeout()</code></a>.</p>
|
|
<h3><code>server.timeout</code><span><a class="mark" href="#https_server_timeout" id="https_server_timeout">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.11.2</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> <strong>Default:</strong> <code>120000</code> (2 minutes)</li>
|
|
</ul>
|
|
<p>See <a href="http.html#http_server_timeout"><code>http.Server#timeout</code></a>.</p>
|
|
<h3><code>server.keepAliveTimeout</code><span><a class="mark" href="#https_server_keepalivetimeout" id="https_server_keepalivetimeout">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v8.0.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> <strong>Default:</strong> <code>5000</code> (5 seconds)</li>
|
|
</ul>
|
|
<p>See <a href="http.html#http_server_keepalivetimeout"><code>http.Server#keepAliveTimeout</code></a>.</p>
|
|
<h2><code>https.createServer([options][, requestListener])</code><span><a class="mark" href="#https_https_createserver_options_requestlistener" id="https_https_createserver_options_requestlistener">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.3.4</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Accepts <code>options</code> from <a href="tls.html#tls_tls_createserver_options_secureconnectionlistener"><code>tls.createServer()</code></a>,
|
|
<a href="tls.html#tls_tls_createsecurecontext_options"><code>tls.createSecureContext()</code></a> and <a href="http.html#http_http_createserver_options_requestlistener"><code>http.createServer()</code></a>.</li>
|
|
<li><code>requestListener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A listener to be added to the <code>'request'</code> event.</li>
|
|
<li>Returns: <a href="https.html#https_class_https_server" class="type"><https.Server></a></li>
|
|
</ul>
|
|
<pre><code class="language-js"><span class="hljs-comment">// curl -k https://localhost:8000/</span>
|
|
<span class="hljs-keyword">const</span> https = <span class="hljs-built_in">require</span>(<span class="hljs-string">'https'</span>);
|
|
<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> options = {
|
|
<span class="hljs-attr">key</span>: fs.readFileSync(<span class="hljs-string">'test/fixtures/keys/agent2-key.pem'</span>),
|
|
<span class="hljs-attr">cert</span>: fs.readFileSync(<span class="hljs-string">'test/fixtures/keys/agent2-cert.pem'</span>)
|
|
};
|
|
|
|
https.createServer(options, <span class="hljs-function">(<span class="hljs-params">req, res</span>) =></span> {
|
|
res.writeHead(<span class="hljs-number">200</span>);
|
|
res.end(<span class="hljs-string">'hello world\n'</span>);
|
|
}).listen(<span class="hljs-number">8000</span>);</code></pre>
|
|
<p>Or</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> https = <span class="hljs-built_in">require</span>(<span class="hljs-string">'https'</span>);
|
|
<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> options = {
|
|
<span class="hljs-attr">pfx</span>: fs.readFileSync(<span class="hljs-string">'test/fixtures/test_cert.pfx'</span>),
|
|
<span class="hljs-attr">passphrase</span>: <span class="hljs-string">'sample'</span>
|
|
};
|
|
|
|
https.createServer(options, <span class="hljs-function">(<span class="hljs-params">req, res</span>) =></span> {
|
|
res.writeHead(<span class="hljs-number">200</span>);
|
|
res.end(<span class="hljs-string">'hello world\n'</span>);
|
|
}).listen(<span class="hljs-number">8000</span>);</code></pre>
|
|
<h2><code>https.get(options[, callback])</code><span><a class="mark" href="#https_https_get_options_callback" id="https_https_get_options_callback">#</a></span></h2>
|
|
<h2><code>https.get(url[, options][, callback])</code><span><a class="mark" href="#https_https_get_url_options_callback" id="https_https_get_url_options_callback">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v10.9.0</td>
|
|
<td><p>The <code>url</code> parameter can now be passed along with a separate <code>options</code> object.</p></td></tr>
|
|
<tr><td>v7.5.0</td>
|
|
<td><p>The <code>options</code> parameter can be a WHATWG <code>URL</code> object.</p></td></tr>
|
|
<tr><td>v0.3.6</td>
|
|
<td><p><span>Added in: v0.3.6</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>url</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> Accepts the same <code>options</code> as
|
|
<a href="#https_https_request_options_callback"><code>https.request()</code></a>, with the <code>method</code> always set to <code>GET</code>.</li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li>
|
|
</ul>
|
|
<p>Like <a href="http.html#http_http_get_options_callback"><code>http.get()</code></a> but for HTTPS.</p>
|
|
<p><code>options</code> can be an object, a string, or a <a href="url.html#url_the_whatwg_url_api"><code>URL</code></a> object. If <code>options</code> is a
|
|
string, it is automatically parsed with <a href="url.html#url_new_url_input_base"><code>new URL()</code></a>. If it is a <a href="url.html#url_the_whatwg_url_api"><code>URL</code></a>
|
|
object, it will be automatically converted to an ordinary <code>options</code> object.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> https = <span class="hljs-built_in">require</span>(<span class="hljs-string">'https'</span>);
|
|
|
|
https.get(<span class="hljs-string">'https://encrypted.google.com/'</span>, <span class="hljs-function">(<span class="hljs-params">res</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'statusCode:'</span>, res.statusCode);
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'headers:'</span>, res.headers);
|
|
|
|
res.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">d</span>) =></span> {
|
|
process.stdout.write(d);
|
|
});
|
|
|
|
}).on(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">e</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.error(e);
|
|
});</code></pre>
|
|
<h2><code>https.globalAgent</code><span><a class="mark" href="#https_https_globalagent" id="https_https_globalagent">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.9</span>
|
|
</div>
|
|
<p>Global instance of <a href="#https_class_https_agent"><code>https.Agent</code></a> for all HTTPS client requests.</p>
|
|
<h2><code>https.request(options[, callback])</code><span><a class="mark" href="#https_https_request_options_callback" id="https_https_request_options_callback">#</a></span></h2>
|
|
<h2><code>https.request(url[, options][, callback])</code><span><a class="mark" href="#https_https_request_url_options_callback" id="https_https_request_url_options_callback">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v10.9.0</td>
|
|
<td><p>The <code>url</code> parameter can now be passed along with a separate <code>options</code> object.</p></td></tr>
|
|
<tr><td>v9.3.0</td>
|
|
<td><p>The <code>options</code> parameter can now include <code>clientCertEngine</code>.</p></td></tr>
|
|
<tr><td>v7.5.0</td>
|
|
<td><p>The <code>options</code> parameter can be a WHATWG <code>URL</code> object.</p></td></tr>
|
|
<tr><td>v0.3.6</td>
|
|
<td><p><span>Added in: v0.3.6</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>url</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> Accepts all <code>options</code> from
|
|
<a href="http.html#http_http_request_options_callback"><code>http.request()</code></a>, with some differences in default values:
|
|
<ul>
|
|
<li><code>protocol</code> <strong>Default:</strong> <code>'https:'</code></li>
|
|
<li><code>port</code> <strong>Default:</strong> <code>443</code></li>
|
|
<li><code>agent</code> <strong>Default:</strong> <code>https.globalAgent</code></li>
|
|
</ul>
|
|
</li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li>
|
|
</ul>
|
|
<p>Makes a request to a secure web server.</p>
|
|
<p>The following additional <code>options</code> from <a href="tls.html#tls_tls_connect_options_callback"><code>tls.connect()</code></a> are also accepted:
|
|
<code>ca</code>, <code>cert</code>, <code>ciphers</code>, <code>clientCertEngine</code>, <code>crl</code>, <code>dhparam</code>, <code>ecdhCurve</code>,
|
|
<code>honorCipherOrder</code>, <code>key</code>, <code>passphrase</code>, <code>pfx</code>, <code>rejectUnauthorized</code>,
|
|
<code>secureOptions</code>, <code>secureProtocol</code>, <code>servername</code>, <code>sessionIdContext</code>.</p>
|
|
<p><code>options</code> can be an object, a string, or a <a href="url.html#url_the_whatwg_url_api"><code>URL</code></a> object. If <code>options</code> is a
|
|
string, it is automatically parsed with <a href="url.html#url_new_url_input_base"><code>new URL()</code></a>. If it is a <a href="url.html#url_the_whatwg_url_api"><code>URL</code></a>
|
|
object, it will be automatically converted to an ordinary <code>options</code> object.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> https = <span class="hljs-built_in">require</span>(<span class="hljs-string">'https'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> options = {
|
|
<span class="hljs-attr">hostname</span>: <span class="hljs-string">'encrypted.google.com'</span>,
|
|
<span class="hljs-attr">port</span>: <span class="hljs-number">443</span>,
|
|
<span class="hljs-attr">path</span>: <span class="hljs-string">'/'</span>,
|
|
<span class="hljs-attr">method</span>: <span class="hljs-string">'GET'</span>
|
|
};
|
|
|
|
<span class="hljs-keyword">const</span> req = https.request(options, <span class="hljs-function">(<span class="hljs-params">res</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'statusCode:'</span>, res.statusCode);
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'headers:'</span>, res.headers);
|
|
|
|
res.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">d</span>) =></span> {
|
|
process.stdout.write(d);
|
|
});
|
|
});
|
|
|
|
req.on(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">e</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.error(e);
|
|
});
|
|
req.end();</code></pre>
|
|
<p>Example using options from <a href="tls.html#tls_tls_connect_options_callback"><code>tls.connect()</code></a>:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> options = {
|
|
<span class="hljs-attr">hostname</span>: <span class="hljs-string">'encrypted.google.com'</span>,
|
|
<span class="hljs-attr">port</span>: <span class="hljs-number">443</span>,
|
|
<span class="hljs-attr">path</span>: <span class="hljs-string">'/'</span>,
|
|
<span class="hljs-attr">method</span>: <span class="hljs-string">'GET'</span>,
|
|
<span class="hljs-attr">key</span>: fs.readFileSync(<span class="hljs-string">'test/fixtures/keys/agent2-key.pem'</span>),
|
|
<span class="hljs-attr">cert</span>: fs.readFileSync(<span class="hljs-string">'test/fixtures/keys/agent2-cert.pem'</span>)
|
|
};
|
|
options.agent = <span class="hljs-keyword">new</span> https.Agent(options);
|
|
|
|
<span class="hljs-keyword">const</span> req = https.request(options, <span class="hljs-function">(<span class="hljs-params">res</span>) =></span> {
|
|
<span class="hljs-comment">// ...</span>
|
|
});</code></pre>
|
|
<p>Alternatively, opt out of connection pooling by not using an <a href="#https_class_https_agent"><code>Agent</code></a>.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> options = {
|
|
<span class="hljs-attr">hostname</span>: <span class="hljs-string">'encrypted.google.com'</span>,
|
|
<span class="hljs-attr">port</span>: <span class="hljs-number">443</span>,
|
|
<span class="hljs-attr">path</span>: <span class="hljs-string">'/'</span>,
|
|
<span class="hljs-attr">method</span>: <span class="hljs-string">'GET'</span>,
|
|
<span class="hljs-attr">key</span>: fs.readFileSync(<span class="hljs-string">'test/fixtures/keys/agent2-key.pem'</span>),
|
|
<span class="hljs-attr">cert</span>: fs.readFileSync(<span class="hljs-string">'test/fixtures/keys/agent2-cert.pem'</span>),
|
|
<span class="hljs-attr">agent</span>: <span class="hljs-literal">false</span>
|
|
};
|
|
|
|
<span class="hljs-keyword">const</span> req = https.request(options, <span class="hljs-function">(<span class="hljs-params">res</span>) =></span> {
|
|
<span class="hljs-comment">// ...</span>
|
|
});</code></pre>
|
|
<p>Example using a <a href="url.html#url_the_whatwg_url_api"><code>URL</code></a> as <code>options</code>:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> options = <span class="hljs-keyword">new</span> URL(<span class="hljs-string">'https://abc:xyz@example.com'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> req = https.request(options, <span class="hljs-function">(<span class="hljs-params">res</span>) =></span> {
|
|
<span class="hljs-comment">// ...</span>
|
|
});</code></pre>
|
|
<p>Example pinning on certificate fingerprint, or the public key (similar to
|
|
<code>pin-sha256</code>):</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> tls = <span class="hljs-built_in">require</span>(<span class="hljs-string">'tls'</span>);
|
|
<span class="hljs-keyword">const</span> https = <span class="hljs-built_in">require</span>(<span class="hljs-string">'https'</span>);
|
|
<span class="hljs-keyword">const</span> crypto = <span class="hljs-built_in">require</span>(<span class="hljs-string">'crypto'</span>);
|
|
|
|
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">sha256</span>(<span class="hljs-params">s</span>) </span>{
|
|
<span class="hljs-keyword">return</span> crypto.createHash(<span class="hljs-string">'sha256'</span>).update(s).digest(<span class="hljs-string">'base64'</span>);
|
|
}
|
|
<span class="hljs-keyword">const</span> options = {
|
|
<span class="hljs-attr">hostname</span>: <span class="hljs-string">'github.com'</span>,
|
|
<span class="hljs-attr">port</span>: <span class="hljs-number">443</span>,
|
|
<span class="hljs-attr">path</span>: <span class="hljs-string">'/'</span>,
|
|
<span class="hljs-attr">method</span>: <span class="hljs-string">'GET'</span>,
|
|
<span class="hljs-attr">checkServerIdentity</span>: <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">host, cert</span>) </span>{
|
|
<span class="hljs-comment">// Make sure the certificate is issued to the host we are connected to</span>
|
|
<span class="hljs-keyword">const</span> err = tls.checkServerIdentity(host, cert);
|
|
<span class="hljs-keyword">if</span> (err) {
|
|
<span class="hljs-keyword">return</span> err;
|
|
}
|
|
|
|
<span class="hljs-comment">// Pin the public key, similar to HPKP pin-sha25 pinning</span>
|
|
<span class="hljs-keyword">const</span> pubkey256 = <span class="hljs-string">'pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU='</span>;
|
|
<span class="hljs-keyword">if</span> (sha256(cert.pubkey) !== pubkey256) {
|
|
<span class="hljs-keyword">const</span> msg = <span class="hljs-string">'Certificate verification error: '</span> +
|
|
<span class="hljs-string">`The public key of '<span class="hljs-subst">${cert.subject.CN}</span>' `</span> +
|
|
<span class="hljs-string">'does not match our pinned fingerprint'</span>;
|
|
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Error</span>(msg);
|
|
}
|
|
|
|
<span class="hljs-comment">// Pin the exact certificate, rather than the pub key</span>
|
|
<span class="hljs-keyword">const</span> cert256 = <span class="hljs-string">'25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:'</span> +
|
|
<span class="hljs-string">'D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16'</span>;
|
|
<span class="hljs-keyword">if</span> (cert.fingerprint256 !== cert256) {
|
|
<span class="hljs-keyword">const</span> msg = <span class="hljs-string">'Certificate verification error: '</span> +
|
|
<span class="hljs-string">`The certificate of '<span class="hljs-subst">${cert.subject.CN}</span>' `</span> +
|
|
<span class="hljs-string">'does not match our pinned fingerprint'</span>;
|
|
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Error</span>(msg);
|
|
}
|
|
|
|
<span class="hljs-comment">// This loop is informational only.</span>
|
|
<span class="hljs-comment">// Print the certificate and public key fingerprints of all certs in the</span>
|
|
<span class="hljs-comment">// chain. Its common to pin the public key of the issuer on the public</span>
|
|
<span class="hljs-comment">// internet, while pinning the public key of the service in sensitive</span>
|
|
<span class="hljs-comment">// environments.</span>
|
|
<span class="hljs-keyword">do</span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'Subject Common Name:'</span>, cert.subject.CN);
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">' Certificate SHA256 fingerprint:'</span>, cert.fingerprint256);
|
|
|
|
hash = crypto.createHash(<span class="hljs-string">'sha256'</span>);
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">' Public key ping-sha256:'</span>, sha256(cert.pubkey));
|
|
|
|
lastprint256 = cert.fingerprint256;
|
|
cert = cert.issuerCertificate;
|
|
} <span class="hljs-keyword">while</span> (cert.fingerprint256 !== lastprint256);
|
|
|
|
},
|
|
};
|
|
|
|
options.agent = <span class="hljs-keyword">new</span> https.Agent(options);
|
|
<span class="hljs-keyword">const</span> req = https.request(options, <span class="hljs-function">(<span class="hljs-params">res</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'All OK. Server matched our pinned cert or public key'</span>);
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'statusCode:'</span>, res.statusCode);
|
|
<span class="hljs-comment">// Print the HPKP values</span>
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'headers:'</span>, res.headers[<span class="hljs-string">'public-key-pins'</span>]);
|
|
|
|
res.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">d</span>) =></span> {});
|
|
});
|
|
|
|
req.on(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">e</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.error(e.message);
|
|
});
|
|
req.end();</code></pre>
|
|
<p>Outputs for example:</p>
|
|
<pre><code class="language-text">Subject Common Name: github.com
|
|
Certificate SHA256 fingerprint: 25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16
|
|
Public key ping-sha256: pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=
|
|
Subject Common Name: DigiCert SHA2 Extended Validation Server CA
|
|
Certificate SHA256 fingerprint: 40:3E:06:2A:26:53:05:91:13:28:5B:AF:80:A0:D4:AE:42:2C:84:8C:9F:78:FA:D0:1F:C9:4B:C5:B8:7F:EF:1A
|
|
Public key ping-sha256: RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho=
|
|
Subject Common Name: DigiCert High Assurance EV Root CA
|
|
Certificate SHA256 fingerprint: 74:31:E5:F4:C3:C1:CE:46:90:77:4F:0B:61:E0:54:40:88:3B:A9:A0:1E:D0:0B:A6:AB:D7:80:6E:D3:B1:18:CF
|
|
Public key ping-sha256: WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18=
|
|
All OK. Server matched our pinned cert or public key
|
|
statusCode: 200
|
|
headers: max-age=0; pin-sha256="WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18="; pin-sha256="RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho="; pin-sha256="k2v657xBsOVe1PQRwOsHsw3bsGT2VzIqz5K+59sNQws="; pin-sha256="K87oWBWM9UZfyddvDfoxL+8lpNyoUB2ptGtn0fv6G2Q="; pin-sha256="IQBnNBEiFuhj+8x6X8XLgh01V9Ic5/V3IRQLNFFc7v4="; pin-sha256="iie1VXtL7HzAMF+/PVPR9xzT80kQxdZeJ+zduCB3uj0="; pin-sha256="LvRiGEjRqfzurezaWuj8Wie2gyHMrW5Q06LspMnox7A="; includeSubDomains</code></pre>
|
|
<!-- API END -->
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|