478 lines
34 KiB
JSON
478 lines
34 KiB
JSON
|
{
|
||
|
|
"type": "module",
|
||
|
|
"source": "doc/api/https.md",
|
||
|
|
"modules": [
|
||
|
|
{
|
||
|
|
"textRaw": "HTTPS",
|
||
|
|
"name": "https",
|
||
|
|
"introduced_in": "v0.10.0",
|
||
|
|
"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>",
|
||
|
|
"classes": [
|
||
|
|
{
|
||
|
|
"textRaw": "Class: `https.Agent`",
|
||
|
|
"type": "class",
|
||
|
|
"name": "https.Agent",
|
||
|
|
"meta": {
|
||
|
|
"added": [
|
||
|
|
"v0.4.5"
|
||
|
|
],
|
||
|
|
"changes": [
|
||
|
|
{
|
||
|
|
"version": "v2.5.0",
|
||
|
|
"pr-url": "https://github.com/nodejs/node/pull/2228",
|
||
|
|
"description": "parameter `maxCachedSessions` added to `options` for TLS sessions reuse."
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"version": "v5.3.0",
|
||
|
|
"pr-url": "https://github.com/nodejs/node/pull/4252",
|
||
|
|
"description": "support `0` `maxCachedSessions` to disable TLS session caching."
|
||
|
|
}
|
||
|
|
]
|
||
|
|
},
|
||
|
|
"desc": "<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\n<a href=\"#https_https_request_options_callback\"><code>https.request()</code></a> for more information.</p>",
|
||
|
|
"signatures": [
|
||
|
|
{
|
||
|
|
"params": [
|
||
|
|
{
|
||
|
|
"textRaw": "`options` {Object} Set of configurable options to set on the agent. Can have the same fields as for [`http.Agent(options)`][], and",
|
||
|
|
"name": "options",
|
||
|
|
"type": "Object",
|
||
|
|
"desc": "Set of configurable options to set on the agent. Can have the same fields as for [`http.Agent(options)`][], and",
|
||
|
|
"options": [
|
||
|
|
{
|
||
|
|
"textRaw": "`maxCachedSessions` {number} maximum number of TLS cached sessions. Use `0` to disable TLS session caching. **Default:** `100`.",
|
||
|
|
"name": "maxCachedSessions",
|
||
|
|
"type": "number",
|
||
|
|
"default": "`100`",
|
||
|
|
"desc": "maximum number of TLS cached sessions. Use `0` to disable TLS session caching."
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`servername` {string} the value of [Server Name Indication extension][sni wiki] to be sent to the server. Use empty string `''` to disable sending the extension. **Default:** host name of the target server, unless the target server is specified using an IP address, in which case the default is `''` (no extension).See [`Session Resumption`][] for information about TLS session reuse.",
|
||
|
|
"name": "servername",
|
||
|
|
"type": "string",
|
||
|
|
"default": "host name of the target server, unless the target server is specified using an IP address, in which case the default is `''` (no extension).See [`Session Resumption`][] for information about TLS session reuse",
|
||
|
|
"desc": "the value of [Server Name Indication extension][sni wiki] to be sent to the server. Use empty string `''` to disable sending the extension."
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
]
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "Class: `https.Server`",
|
||
|
|
"type": "class",
|
||
|
|
"name": "https.Server",
|
||
|
|
"meta": {
|
||
|
|
"added": [
|
||
|
|
"v0.3.4"
|
||
|
|
],
|
||
|
|
"changes": []
|
||
|
|
},
|
||
|
|
"desc": "<ul>\n<li>Extends: <a href=\"tls.html#tls_class_tls_server\" class=\"type\"><tls.Server></a></li>\n</ul>\n<p>See <a href=\"http.html#http_class_http_server\"><code>http.Server</code></a> for more information.</p>",
|
||
|
|
"methods": [
|
||
|
|
{
|
||
|
|
"textRaw": "`server.close([callback])`",
|
||
|
|
"type": "method",
|
||
|
|
"name": "close",
|
||
|
|
"meta": {
|
||
|
|
"added": [
|
||
|
|
"v0.1.90"
|
||
|
|
],
|
||
|
|
"changes": []
|
||
|
|
},
|
||
|
|
"signatures": [
|
||
|
|
{
|
||
|
|
"return": {
|
||
|
|
"textRaw": "Returns: {https.Server}",
|
||
|
|
"name": "return",
|
||
|
|
"type": "https.Server"
|
||
|
|
},
|
||
|
|
"params": [
|
||
|
|
{
|
||
|
|
"textRaw": "`callback` {Function}",
|
||
|
|
"name": "callback",
|
||
|
|
"type": "Function"
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"desc": "<p>See <a href=\"http.html#http_server_close_callback\"><code>server.close()</code></a> from the HTTP module for details.</p>"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`server.listen()`",
|
||
|
|
"type": "method",
|
||
|
|
"name": "listen",
|
||
|
|
"signatures": [
|
||
|
|
{
|
||
|
|
"params": []
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"desc": "<p>Starts the HTTPS server listening for encrypted connections.\nThis 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>"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`server.setTimeout([msecs][, callback])`",
|
||
|
|
"type": "method",
|
||
|
|
"name": "setTimeout",
|
||
|
|
"meta": {
|
||
|
|
"added": [
|
||
|
|
"v0.11.2"
|
||
|
|
],
|
||
|
|
"changes": []
|
||
|
|
},
|
||
|
|
"signatures": [
|
||
|
|
{
|
||
|
|
"return": {
|
||
|
|
"textRaw": "Returns: {https.Server}",
|
||
|
|
"name": "return",
|
||
|
|
"type": "https.Server"
|
||
|
|
},
|
||
|
|
"params": [
|
||
|
|
{
|
||
|
|
"textRaw": "`msecs` {number} **Default:** `120000` (2 minutes)",
|
||
|
|
"name": "msecs",
|
||
|
|
"type": "number",
|
||
|
|
"default": "`120000` (2 minutes)"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`callback` {Function}",
|
||
|
|
"name": "callback",
|
||
|
|
"type": "Function"
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"desc": "<p>See <a href=\"http.html#http_server_settimeout_msecs_callback\"><code>http.Server#setTimeout()</code></a>.</p>"
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"properties": [
|
||
|
|
{
|
||
|
|
"textRaw": "`headersTimeout` {number} **Default:** `60000`",
|
||
|
|
"type": "number",
|
||
|
|
"name": "headersTimeout",
|
||
|
|
"meta": {
|
||
|
|
"added": [
|
||
|
|
"v11.3.0"
|
||
|
|
],
|
||
|
|
"changes": []
|
||
|
|
},
|
||
|
|
"default": "`60000`",
|
||
|
|
"desc": "<p>See <a href=\"http.html#http_server_headerstimeout\"><code>http.Server#headersTimeout</code></a>.</p>"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`maxHeadersCount` {number} **Default:** `2000`",
|
||
|
|
"type": "number",
|
||
|
|
"name": "maxHeadersCount",
|
||
|
|
"default": "`2000`",
|
||
|
|
"desc": "<p>See <a href=\"http.html#http_server_maxheaderscount\"><code>http.Server#maxHeadersCount</code></a>.</p>"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`timeout` {number} **Default:** `120000` (2 minutes)",
|
||
|
|
"type": "number",
|
||
|
|
"name": "timeout",
|
||
|
|
"meta": {
|
||
|
|
"added": [
|
||
|
|
"v0.11.2"
|
||
|
|
],
|
||
|
|
"changes": []
|
||
|
|
},
|
||
|
|
"default": "`120000` (2 minutes)",
|
||
|
|
"desc": "<p>See <a href=\"http.html#http_server_timeout\"><code>http.Server#timeout</code></a>.</p>"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`keepAliveTimeout` {number} **Default:** `5000` (5 seconds)",
|
||
|
|
"type": "number",
|
||
|
|
"name": "keepAliveTimeout",
|
||
|
|
"meta": {
|
||
|
|
"added": [
|
||
|
|
"v8.0.0"
|
||
|
|
],
|
||
|
|
"changes": []
|
||
|
|
},
|
||
|
|
"default": "`5000` (5 seconds)",
|
||
|
|
"desc": "<p>See <a href=\"http.html#http_server_keepalivetimeout\"><code>http.Server#keepAliveTimeout</code></a>.</p>"
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"methods": [
|
||
|
|
{
|
||
|
|
"textRaw": "`https.createServer([options][, requestListener])`",
|
||
|
|
"type": "method",
|
||
|
|
"name": "createServer",
|
||
|
|
"meta": {
|
||
|
|
"added": [
|
||
|
|
"v0.3.4"
|
||
|
|
],
|
||
|
|
"changes": []
|
||
|
|
},
|
||
|
|
"signatures": [
|
||
|
|
{
|
||
|
|
"return": {
|
||
|
|
"textRaw": "Returns: {https.Server}",
|
||
|
|
"name": "return",
|
||
|
|
"type": "https.Server"
|
||
|
|
},
|
||
|
|
"params": [
|
||
|
|
{
|
||
|
|
"textRaw": "`options` {Object} Accepts `options` from [`tls.createServer()`][], [`tls.createSecureContext()`][] and [`http.createServer()`][].",
|
||
|
|
"name": "options",
|
||
|
|
"type": "Object",
|
||
|
|
"desc": "Accepts `options` from [`tls.createServer()`][], [`tls.createSecureContext()`][] and [`http.createServer()`][]."
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`requestListener` {Function} A listener to be added to the `'request'` event.",
|
||
|
|
"name": "requestListener",
|
||
|
|
"type": "Function",
|
||
|
|
"desc": "A listener to be added to the `'request'` event."
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"desc": "<pre><code class=\"language-js\">// curl -k https://localhost:8000/\nconst https = require('https');\nconst fs = require('fs');\n\nconst options = {\n key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')\n};\n\nhttps.createServer(options, (req, res) => {\n res.writeHead(200);\n res.end('hello world\\n');\n}).listen(8000);\n</code></pre>\n<p>Or</p>\n<pre><code class=\"language-js\">const https = require('https');\nconst fs = require('fs');\n\nconst options = {\n pfx: fs.readFileSync('test/fixtures/test_cert.pfx'),\n passphrase: 'sample'\n};\n\nhttps.createServer(options, (req, res) => {\n res.writeHead(200);\n res.end('hello world\\n');\n}).listen(8000);\n</code></pre>"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`https.get(options[, callback])`",
|
||
|
|
"type": "method",
|
||
|
|
"name": "get",
|
||
|
|
"meta": {
|
||
|
|
"added": [
|
||
|
|
"v0.3.6"
|
||
|
|
],
|
||
|
|
"changes": [
|
||
|
|
{
|
||
|
|
"version": "v10.9.0",
|
||
|
|
"pr-url": "https://github.com/nodejs/node/pull/21616",
|
||
|
|
"description": "The `url` parameter can now be passed along with a separate `options` object."
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"version": "v7.5.0",
|
||
|
|
"pr-url": "https://github.com/nodejs/node/pull/10638",
|
||
|
|
"description": "The `options` parameter can be a WHATWG `URL` object."
|
||
|
|
}
|
||
|
|
]
|
||
|
|
},
|
||
|
|
"signatures": [
|
||
|
|
{
|
||
|
|
"params": [
|
||
|
|
{
|
||
|
|
"textRaw": "`url` {string | URL}",
|
||
|
|
"name": "url",
|
||
|
|
"type": "string | URL"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`options` {Object | string | URL} Accepts the same `options` as [`https.request()`][], with the `method` always set to `GET`.",
|
||
|
|
"name": "options",
|
||
|
|
"type": "Object | string | URL",
|
||
|
|
"desc": "Accepts the same `options` as [`https.request()`][], with the `method` always set to `GET`."
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`callback` {Function}",
|
||
|
|
"name": "callback",
|
||
|
|
"type": "Function"
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"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, a string, or a <a href=\"url.html#url_the_whatwg_url_api\"><code>URL</code></a> object. If <code>options</code> is a\nstring, it is automatically parsed with <a href=\"url.html#url_constructor_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>\nobject, it will be automatically converted to an ordinary <code>options</code> object.</p>\n<pre><code class=\"language-js\">const https = require('https');\n\nhttps.get('https://encrypted.google.com/', (res) => {\n console.log('statusCode:', res.statusCode);\n console.log('headers:', res.headers);\n\n res.on('data', (d) => {\n process.stdout.write(d);\n });\n\n}).on('error', (e) => {\n console.error(e);\n});\n</code></pre>"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`https.get(url[, options][, callback])`",
|
||
|
|
"type": "method",
|
||
|
|
"name": "get",
|
||
|
|
"meta": {
|
||
|
|
"added": [
|
||
|
|
"v0.3.6"
|
||
|
|
],
|
||
|
|
"changes": [
|
||
|
|
{
|
||
|
|
"version": "v10.9.0",
|
||
|
|
"pr-url": "https://github.com/nodejs/node/pull/21616",
|
||
|
|
"description": "The `url` parameter can now be passed along with a separate `options` object."
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"version": "v7.5.0",
|
||
|
|
"pr-url": "https://github.com/nodejs/node/pull/10638",
|
||
|
|
"description": "The `options` parameter can be a WHATWG `URL` object."
|
||
|
|
}
|
||
|
|
]
|
||
|
|
},
|
||
|
|
"signatures": [
|
||
|
|
{
|
||
|
|
"params": [
|
||
|
|
{
|
||
|
|
"textRaw": "`url` {string | URL}",
|
||
|
|
"name": "url",
|
||
|
|
"type": "string | URL"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`options` {Object | string | URL} Accepts the same `options` as [`https.request()`][], with the `method` always set to `GET`.",
|
||
|
|
"name": "options",
|
||
|
|
"type": "Object | string | URL",
|
||
|
|
"desc": "Accepts the same `options` as [`https.request()`][], with the `method` always set to `GET`."
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`callback` {Function}",
|
||
|
|
"name": "callback",
|
||
|
|
"type": "Function"
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"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, a string, or a <a href=\"url.html#url_the_whatwg_url_api\"><code>URL</code></a> object. If <code>options</code> is a\nstring, it is automatically parsed with <a href=\"url.html#url_constructor_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>\nobject, it will be automatically converted to an ordinary <code>options</code> object.</p>\n<pre><code class=\"language-js\">const https = require('https');\n\nhttps.get('https://encrypted.google.com/', (res) => {\n console.log('statusCode:', res.statusCode);\n console.log('headers:', res.headers);\n\n res.on('data', (d) => {\n process.stdout.write(d);\n });\n\n}).on('error', (e) => {\n console.error(e);\n});\n</code></pre>"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`https.request(options[, callback])`",
|
||
|
|
"type": "method",
|
||
|
|
"name": "request",
|
||
|
|
"meta": {
|
||
|
|
"added": [
|
||
|
|
"v0.3.6"
|
||
|
|
],
|
||
|
|
"changes": [
|
||
|
|
{
|
||
|
|
"version": "v10.9.0",
|
||
|
|
"pr-url": "https://github.com/nodejs/node/pull/21616",
|
||
|
|
"description": "The `url` parameter can now be passed along with a separate `options` object."
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"version": "v9.3.0",
|
||
|
|
"pr-url": "https://github.com/nodejs/node/pull/14903",
|
||
|
|
"description": "The `options` parameter can now include `clientCertEngine`."
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"version": "v7.5.0",
|
||
|
|
"pr-url": "https://github.com/nodejs/node/pull/10638",
|
||
|
|
"description": "The `options` parameter can be a WHATWG `URL` object."
|
||
|
|
}
|
||
|
|
]
|
||
|
|
},
|
||
|
|
"signatures": [
|
||
|
|
{
|
||
|
|
"params": [
|
||
|
|
{
|
||
|
|
"textRaw": "`url` {string | URL}",
|
||
|
|
"name": "url",
|
||
|
|
"type": "string | URL"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`options` {Object | string | URL} Accepts all `options` from [`http.request()`][], with some differences in default values:",
|
||
|
|
"name": "options",
|
||
|
|
"type": "Object | string | URL",
|
||
|
|
"desc": "Accepts all `options` from [`http.request()`][], with some differences in default values:",
|
||
|
|
"options": [
|
||
|
|
{
|
||
|
|
"textRaw": "`protocol` **Default:** `'https:'`",
|
||
|
|
"name": "protocol",
|
||
|
|
"default": "`'https:'`"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`port` **Default:** `443`",
|
||
|
|
"name": "port",
|
||
|
|
"default": "`443`"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`agent` **Default:** `https.globalAgent`",
|
||
|
|
"name": "agent",
|
||
|
|
"default": "`https.globalAgent`"
|
||
|
|
}
|
||
|
|
]
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`callback` {Function}",
|
||
|
|
"name": "callback",
|
||
|
|
"type": "Function"
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"desc": "<p>Makes a request to a secure web server.</p>\n<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:\n<code>ca</code>, <code>cert</code>, <code>ciphers</code>, <code>clientCertEngine</code>, <code>crl</code>, <code>dhparam</code>, <code>ecdhCurve</code>,\n<code>honorCipherOrder</code>, <code>key</code>, <code>passphrase</code>, <code>pfx</code>, <code>rejectUnauthorized</code>,\n<code>secureOptions</code>, <code>secureProtocol</code>, <code>servername</code>, <code>sessionIdContext</code>.</p>\n<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\nstring, it is automatically parsed with <a href=\"url.html#url_constructor_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>\nobject, it will be automatically converted to an ordinary <code>options</code> object.</p>\n<pre><code class=\"language-js\">const https = require('https');\n\nconst options = {\n hostname: 'encrypted.google.com',\n port: 443,\n path: '/',\n method: 'GET'\n};\n\nconst req = https.request(options, (res) => {\n console.log('statusCode:', res.statusCode);\n console.log('headers:', res.headers);\n\n res.on('data', (d) => {\n process.stdout.write(d);\n });\n});\n\nreq.on('error', (e) => {\n console.error(e);\n});\nreq.end();\n</code></pre>\n<p>Example using options from <a href=\"tls.html#tls_tls_connect_options_callback\"><code>tls.connect()</code></a>:</p>\n<pre><code class=\"language-js\">const options = {\n hostname: 'encrypted.google.com',\n port: 443,\n path: '/',\n method: 'GET',\n key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')\n};\noptions.agent = new https.Agent(options);\n\nconst req = https.request(options, (res) => {\n // ...\n});\n</code></pre>\n<p>Alternatively, opt out of connection pooling by not using an <a href=\"#https_class_https_agent\"><code>Agent</code></a>.</p>\n<pre><code class=\"language-js\">const options = {\n hostname: 'encrypted.google.com',\n port: 443,\n path: '/',\n method: 'GET',\n key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),\n agent: false\n};\n\nconst req = https.request(options, (res) => {\n // ...\n});\n</code></pre>\n<p>Example using a <a href=\"url.html#url_the_whatwg_url_api\"><code>URL</code></a> as <code>options</code>:</p>\n<pre><code class=\"language-js\">const options = new URL('https://abc:xyz@example.com');\n\nconst req = https.request(options, (res) => {\n // ...\n});\n</code></pre>\n<p>Example pinning on certificate fingerprint, or the public key (similar to\n<code>pin-sha256</code>):</p>\n<pre><code class=\"language-js\">const tls = require('tls');\nconst https = require('https');\nconst crypto = require('crypto');\n\nfunction sha256(s) {\n return crypto.createHash('sha256').update(s).digest('base64');\n}\nconst options = {\n hostname: 'github.com',\n port: 443,\n path: '/',\n method: 'GET',\n checkServerIdentity: function(host, cert) {\n // Make sure the certificate is issued to the host we are connected to\n const err = tls.checkServerIdentity(host, cert);\n if (err) {\n return err;\n }\n\n // Pin the public key, similar to HPKP pin-sha25 pinning\n const pubkey256 = 'pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=';\n if (sha256(cert.pubkey) !== pubkey256) {\n const msg = 'Certificate verification error: ' +\n `The public key of '${cert.subject.CN}' ` +\n 'does not match our pinned fingerprint';\n return new Error(msg);\n }\n\n // Pin the exact certificate, rather than the pub key\n const cert256 = '25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:' +\n 'D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16';\n if (cert.fingerprint256 !== cert256) {\n const msg = '
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`https.request(url[, options][, callback])`",
|
||
|
|
"type": "method",
|
||
|
|
"name": "request",
|
||
|
|
"meta": {
|
||
|
|
"added": [
|
||
|
|
"v0.3.6"
|
||
|
|
],
|
||
|
|
"changes": [
|
||
|
|
{
|
||
|
|
"version": "v10.9.0",
|
||
|
|
"pr-url": "https://github.com/nodejs/node/pull/21616",
|
||
|
|
"description": "The `url` parameter can now be passed along with a separate `options` object."
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"version": "v9.3.0",
|
||
|
|
"pr-url": "https://github.com/nodejs/node/pull/14903",
|
||
|
|
"description": "The `options` parameter can now include `clientCertEngine`."
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"version": "v7.5.0",
|
||
|
|
"pr-url": "https://github.com/nodejs/node/pull/10638",
|
||
|
|
"description": "The `options` parameter can be a WHATWG `URL` object."
|
||
|
|
}
|
||
|
|
]
|
||
|
|
},
|
||
|
|
"signatures": [
|
||
|
|
{
|
||
|
|
"params": [
|
||
|
|
{
|
||
|
|
"textRaw": "`url` {string | URL}",
|
||
|
|
"name": "url",
|
||
|
|
"type": "string | URL"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`options` {Object | string | URL} Accepts all `options` from [`http.request()`][], with some differences in default values:",
|
||
|
|
"name": "options",
|
||
|
|
"type": "Object | string | URL",
|
||
|
|
"desc": "Accepts all `options` from [`http.request()`][], with some differences in default values:",
|
||
|
|
"options": [
|
||
|
|
{
|
||
|
|
"textRaw": "`protocol` **Default:** `'https:'`",
|
||
|
|
"name": "protocol",
|
||
|
|
"default": "`'https:'`"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`port` **Default:** `443`",
|
||
|
|
"name": "port",
|
||
|
|
"default": "`443`"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`agent` **Default:** `https.globalAgent`",
|
||
|
|
"name": "agent",
|
||
|
|
"default": "`https.globalAgent`"
|
||
|
|
}
|
||
|
|
]
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"textRaw": "`callback` {Function}",
|
||
|
|
"name": "callback",
|
||
|
|
"type": "Function"
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"desc": "<p>Makes a request to a secure web server.</p>\n<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:\n<code>ca</code>, <code>cert</code>, <code>ciphers</code>, <code>clientCertEngine</code>, <code>crl</code>, <code>dhparam</code>, <code>ecdhCurve</code>,\n<code>honorCipherOrder</code>, <code>key</code>, <code>passphrase</code>, <code>pfx</code>, <code>rejectUnauthorized</code>,\n<code>secureOptions</code>, <code>secureProtocol</code>, <code>servername</code>, <code>sessionIdContext</code>.</p>\n<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\nstring, it is automatically parsed with <a href=\"url.html#url_constructor_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>\nobject, it will be automatically converted to an ordinary <code>options</code> object.</p>\n<pre><code class=\"language-js\">const https = require('https');\n\nconst options = {\n hostname: 'encrypted.google.com',\n port: 443,\n path: '/',\n method: 'GET'\n};\n\nconst req = https.request(options, (res) => {\n console.log('statusCode:', res.statusCode);\n console.log('headers:', res.headers);\n\n res.on('data', (d) => {\n process.stdout.write(d);\n });\n});\n\nreq.on('error', (e) => {\n console.error(e);\n});\nreq.end();\n</code></pre>\n<p>Example using options from <a href=\"tls.html#tls_tls_connect_options_callback\"><code>tls.connect()</code></a>:</p>\n<pre><code class=\"language-js\">const options = {\n hostname: 'encrypted.google.com',\n port: 443,\n path: '/',\n method: 'GET',\n key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')\n};\noptions.agent = new https.Agent(options);\n\nconst req = https.request(options, (res) => {\n // ...\n});\n</code></pre>\n<p>Alternatively, opt out of connection pooling by not using an <a href=\"#https_class_https_agent\"><code>Agent</code></a>.</p>\n<pre><code class=\"language-js\">const options = {\n hostname: 'encrypted.google.com',\n port: 443,\n path: '/',\n method: 'GET',\n key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),\n agent: false\n};\n\nconst req = https.request(options, (res) => {\n // ...\n});\n</code></pre>\n<p>Example using a <a href=\"url.html#url_the_whatwg_url_api\"><code>URL</code></a> as <code>options</code>:</p>\n<pre><code class=\"language-js\">const options = new URL('https://abc:xyz@example.com');\n\nconst req = https.request(options, (res) => {\n // ...\n});\n</code></pre>\n<p>Example pinning on certificate fingerprint, or the public key (similar to\n<code>pin-sha256</code>):</p>\n<pre><code class=\"language-js\">const tls = require('tls');\nconst https = require('https');\nconst crypto = require('crypto');\n\nfunction sha256(s) {\n return crypto.createHash('sha256').update(s).digest('base64');\n}\nconst options = {\n hostname: 'github.com',\n port: 443,\n path: '/',\n method: 'GET',\n checkServerIdentity: function(host, cert) {\n // Make sure the certificate is issued to the host we are connected to\n const err = tls.checkServerIdentity(host, cert);\n if (err) {\n return err;\n }\n\n // Pin the public key, similar to HPKP pin-sha25 pinning\n const pubkey256 = 'pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=';\n if (sha256(cert.pubkey) !== pubkey256) {\n const msg = 'Certificate verification error: ' +\n `The public key of '${cert.subject.CN}' ` +\n 'does not match our pinned fingerprint';\n return new Error(msg);\n }\n\n // Pin the exact certificate, rather than the pub key\n const cert256 = '25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:' +\n 'D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16';\n if (cert.fingerprint256 !== cert256) {\n const msg = '
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"properties": [
|
||
|
|
{
|
||
|
|
"textRaw": "`https.globalAgent`",
|
||
|
|
"name": "globalAgent",
|
||
|
|
"meta": {
|
||
|
|
"added": [
|
||
|
|
"v0.5.9"
|
||
|
|
],
|
||
|
|
"changes": []
|
||
|
|
},
|
||
|
|
"desc": "<p>Global instance of <a href=\"#https_class_https_agent\"><code>https.Agent</code></a> for all HTTPS client requests.</p>"
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"type": "module",
|
||
|
|
"displayName": "HTTPS"
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|