Determining if crypto support is unavailable#

It is possible for Node.js to be built without including support for thenode:crypto module. In such cases, attempting toimport fromhttps orcallingrequire('node:https') will result in an error being thrown.

When using CommonJS, the error thrown can be caught using try/catch:

let https;try {  https =require('node:https');}catch (err) {console.error('https support is disabled!');}copy

When using the lexical ESMimport keyword, the error can only becaught if a handler forprocess.on('uncaughtException') is registeredbefore any attempt to load the module is made (using, for instance,a preload module).

When using ESM, if there is a chance that the code may be run on a buildof Node.js where crypto support is not enabled, consider using theimport() function instead of the lexicalimport keyword:

let https;try {  https =awaitimport('node:https');}catch (err) {console.error('https support is disabled!');}copy

Class:https.Agent#

AnAgent object for HTTPS similar tohttp.Agent. Seehttps.request() for more information.

Likehttp.Agent, thecreateConnection(options[, callback]) method can be overriddento customize how TLS connections are established.

Seeagent.createConnection() for details on overriding this method,including asynchronous socket creation with a callback.

// ...https.globalAgent.on('keylog',(line, tlsSocket) => {  fs.appendFileSync('/tmp/ssl-keys.log', line, {mode:0o600 });});copy

Class:https.Server#

• Extends:<tls.Server>

Seehttp.Server for more information.

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

• options<Object> Acceptsoptions fromtls.createServer(),tls.createSecureContext() andhttp.createServer().
• requestListener<Function> A listener to be added to the'request' event.
• Returns:<https.Server>

// curl -k https://localhost:8000/import { createServer }from'node:https';import { readFileSync }from'node:fs';const options = {key:readFileSync('private-key.pem'),cert:readFileSync('certificate.pem'),};createServer(options,(req, res) => {  res.writeHead(200);  res.end('hello world\n');}).listen(8000);// curl -k https://localhost:8000/const https =require('node:https');const fs =require('node:fs');const options = {key: fs.readFileSync('private-key.pem'),cert: fs.readFileSync('certificate.pem'),};https.createServer(options,(req, res) => {  res.writeHead(200);  res.end('hello world\n');}).listen(8000);copy

Or

import { createServer }from'node:https';import { readFileSync }from'node:fs';const options = {pfx:readFileSync('test_cert.pfx'),passphrase:'sample',};createServer(options,(req, res) => {  res.writeHead(200);  res.end('hello world\n');}).listen(8000);const https =require('node:https');const fs =require('node:fs');const options = {pfx: fs.readFileSync('test_cert.pfx'),passphrase:'sample',};https.createServer(options,(req, res) => {  res.writeHead(200);  res.end('hello world\n');}).listen(8000);copy

To generate the certificate and key for this example, run:

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj'/CN=localhost' \  -keyout private-key.pem -out certificate.pemcopy

Then, to generate thepfx certificate for this example, run:

openssl pkcs12 -certpbe AES-256-CBC -export -out test_cert.pfx \  -inkey private-key.pem -in certificate.pem -passout pass:samplecopy

https.get(options[, callback])#

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

• url<string> |<URL>
• options<Object> |<string> |<URL> Accepts the sameoptions ashttps.request(), with the method set to GET by default.
• callback<Function>
• Returns:<http.ClientRequest>

Likehttp.get() but for HTTPS.

options can be an object, a string, or aURL object. Ifoptions is astring, it is automatically parsed withnew URL(). If it is aURLobject, it will be automatically converted to an ordinaryoptions object.

import { get }from'node:https';import processfrom'node:process';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);});const https =require('node: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);});copy

https.globalAgent#

Global instance ofhttps.Agent for all HTTPS client requests. Divergesfrom a defaulthttps.Agent configuration by havingkeepAlive enabled andatimeout of 5 seconds.

https.request(options[, callback])#

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

• url<string> |<URL>
• options<Object> |<string> |<URL> Accepts alloptions fromhttp.request(), with some differences in default values:
  • protocolDefault:'https:'
  • portDefault:443
  • agentDefault:https.globalAgent
• callback<Function>
• Returns:<http.ClientRequest>

Makes a request to a secure web server.

The following additionaloptions fromtls.connect() are also accepted:ca,cert,ciphers,clientCertEngine (deprecated),crl,dhparam,ecdhCurve,honorCipherOrder,key,passphrase,pfx,rejectUnauthorized,secureOptions,secureProtocol,servername,sessionIdContext,highWaterMark.

options can be an object, a string, or aURL object. Ifoptions is astring, it is automatically parsed withnew URL(). If it is aURLobject, it will be automatically converted to an ordinaryoptions object.

https.request() returns an instance of thehttp.ClientRequestclass. TheClientRequest instance is a writable stream. If one needs toupload a file with a POST request, then write to theClientRequest object.

import { request }from'node:https';import processfrom'node:process';const options = {hostname:'encrypted.google.com',port:443,path:'/',method:'GET',};const req =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();const https =require('node: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();copy

Example using options fromtls.connect():

const options = {hostname:'encrypted.google.com',port:443,path:'/',method:'GET',key: fs.readFileSync('private-key.pem'),cert: fs.readFileSync('certificate.pem'),};options.agent =new https.Agent(options);const req = https.request(options,(res) => {// ...});copy

Alternatively, opt out of connection pooling by not using anAgent.

const options = {hostname:'encrypted.google.com',port:443,path:'/',method:'GET',key: fs.readFileSync('private-key.pem'),cert: fs.readFileSync('certificate.pem'),agent:false,};const req = https.request(options,(res) => {// ...});copy

Example using aURL asoptions:

const options =newURL('https://abc:xyz@example.com');const req = https.request(options,(res) => {// ...});copy

Example pinning on certificate fingerprint, or the public key (similar topin-sha256):

import { checkServerIdentity }from'node:tls';import {Agent, request }from'node:https';import { createHash }from'node:crypto';functionsha256(s) {returncreateHash('sha256').update(s).digest('base64');}const options = {hostname:'github.com',port:443,path:'/',method:'GET',checkServerIdentity:function(host, cert) {// Make sure the certificate is issued to the host we are connected toconst err =checkServerIdentity(host, cert);if (err) {return err;    }// Pin the public key, similar to HPKP pin-sha256 pinningconst pubkey256 ='SIXvRyDmBJSgatgTQRGbInBaAK+hZOQ18UmrSwnDlK8=';if (sha256(cert.pubkey) !== pubkey256) {const msg ='Certificate verification error: ' +`The public key of '${cert.subject.CN}' ` +'does not match our pinned fingerprint';returnnewError(msg);    }// Pin the exact certificate, rather than the pub keyconst cert256 ='FD:6E:9B:0E:F3:98:BC:D9:04:C3:B2:EC:16:7A:7B:' +'0F:DA:72:01:C9:03:C5:3A:6A:6A:E5:D0:41:43:63:EF:65';if (cert.fingerprint256 !== cert256) {const msg ='Certificate verification error: ' +`The certificate of '${cert.subject.CN}' ` +'does not match our pinned fingerprint';returnnewError(msg);    }// This loop is informational only.// Print the certificate and public key fingerprints of all certs in the// chain. Its common to pin the public key of the issuer on the public// internet, while pinning the public key of the service in sensitive// environments.let lastprint256;do {console.log('Subject Common Name:', cert.subject.CN);console.log('  Certificate SHA256 fingerprint:', cert.fingerprint256);const hash =createHash('sha256');console.log('  Public key ping-sha256:',sha256(cert.pubkey));      lastprint256 = cert.fingerprint256;      cert = cert.issuerCertificate;    }while (cert.fingerprint256 !== lastprint256);  },};options.agent =newAgent(options);const req =request(options,(res) => {console.log('All OK. Server matched our pinned cert or public key');console.log('statusCode:', res.statusCode);  res.on('data',(d) => {});});req.on('error',(e) => {console.error(e.message);});req.end();const tls =require('node:tls');const https =require('node:https');const crypto =require('node:crypto');functionsha256(s) {return crypto.createHash('sha256').update(s).digest('base64');}const options = {hostname:'github.com',port:443,path:'/',method:'GET',checkServerIdentity:function(host, cert) {// Make sure the certificate is issued to the host we are connected toconst err = tls.checkServerIdentity(host, cert);if (err) {return err;    }// Pin the public key, similar to HPKP pin-sha256 pinningconst pubkey256 ='SIXvRyDmBJSgatgTQRGbInBaAK+hZOQ18UmrSwnDlK8=';if (sha256(cert.pubkey) !== pubkey256) {const msg ='Certificate verification error: ' +`The public key of '${cert.subject.CN}' ` +'does not match our pinned fingerprint';returnnewError(msg);    }// Pin the exact certificate, rather than the pub keyconst cert256 ='FD:6E:9B:0E:F3:98:BC:D9:04:C3:B2:EC:16:7A:7B:' +'0F:DA:72:01:C9:03:C5:3A:6A:6A:E5:D0:41:43:63:EF:65';if (cert.fingerprint256 !== cert256) {const msg ='Certificate verification error: ' +`The certificate of '${cert.subject.CN}' ` +'does not match our pinned fingerprint';returnnewError(msg);    }// This loop is informational only.// Print the certificate and public key fingerprints of all certs in the// chain. Its common to pin the public key of the issuer on the public// internet, while pinning the public key of the service in sensitive// environments.do {console.log('Subject Common Name:', cert.subject.CN);console.log('  Certificate SHA256 fingerprint:', cert.fingerprint256);      hash = crypto.createHash('sha256');console.log('  Public key ping-sha256:',sha256(cert.pubkey));      lastprint256 = cert.fingerprint256;      cert = cert.issuerCertificate;    }while (cert.fingerprint256 !== lastprint256);  },};options.agent =new https.Agent(options);const req = https.request(options,(res) => {console.log('All OK. Server matched our pinned cert or public key');console.log('statusCode:', res.statusCode);  res.on('data',(d) => {});});req.on('error',(e) => {console.error(e.message);});req.end();copy

Outputs for example:

Subject Common Name: github.com  Certificate SHA256 fingerprint: FD:6E:9B:0E:F3:98:BC:D9:04:C3:B2:EC:16:7A:7B:0F:DA:72:01:C9:03:C5:3A:6A:6A:E5:D0:41:43:63:EF:65  Public key ping-sha256: SIXvRyDmBJSgatgTQRGbInBaAK+hZOQ18UmrSwnDlK8=Subject Common Name: Sectigo ECC Domain Validation Secure Server CA  Certificate SHA256 fingerprint: 61:E9:73:75:E9:F6:DA:98:2F:F5:C1:9E:2F:94:E6:6C:4E:35:B6:83:7C:E3:B9:14:D2:24:5C:7F:5F:65:82:5F  Public key ping-sha256: Eep0p/AsSa9lFUH6KT2UY+9s1Z8v7voAPkQ4fGknZ2g=Subject Common Name: USERTrust ECC Certification Authority  Certificate SHA256 fingerprint: A6:CF:64:DB:B4:C8:D5:FD:19:CE:48:89:60:68:DB:03:B5:33:A8:D1:33:6C:62:56:A8:7D:00:CB:B3:DE:F3:EA  Public key ping-sha256: UJM2FOhG9aTNY0Pg4hgqjNzZ/lQBiMGRxPD5Y2/e0bw=Subject Common Name: AAA Certificate Services  Certificate SHA256 fingerprint: D7:A7:A0:FB:5D:7E:27:31:D7:71:E9:48:4E:BC:DE:F7:1D:5F:0C:3E:0A:29:48:78:2B:C8:3E:E0:EA:69:9E:F4  Public key ping-sha256: vRU+17BDT2iGsXvOi76E7TQMcTLXAqj0+jGPdW7L1vM=All OK. Server matched our pinned cert or public keystatusCode: 200copy