Node.js v25.1.0 documentation

Determining if crypto support is unavailable#

It is possible for Node.js to be built without including support for the node:crypto module. In such cases, attempting to import from https or calling require('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 ESM import keyword, the error can only be caught if a handler for process.on('uncaughtException') is registered before 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 build of Node.js where crypto support is not enabled, consider using the import() function instead of the lexical import keyword:

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

Class: https.Agent#

An Agent object for HTTPS similar to http.Agent. See https.request() for more information.

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

Class: https.Server#

• Extends: <tls.Server>

See http.Server for more information.

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

• options <Object> Accepts options from tls.createServer(), tls.createSecureContext() and http.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.pem copy

Then, to generate the pfx 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:sample copy

https.get(options[, callback])#

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

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

Like http.get() but for HTTPS.

options can be an object, a string, or a URL object. If options is a string, it is automatically parsed with new URL(). If it is a URL object, it will be automatically converted to an ordinary options object.

import { get } from 'node:https';
import process from '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 of https.Agent for all HTTPS client requests. Diverges from a default https.Agent configuration by having keepAlive enabled and a timeout of 5 seconds.

https.request(options[, callback])#

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

• url <string> | <URL>
• options <Object> | <string> | <URL> Accepts all options from http.request(), with some differences in default values:
  • protocol Default: 'https:'
  • port Default: 443
  • agent Default: https.globalAgent
• callback <Function>
• Returns: <http.ClientRequest>

Makes a request to a secure web server.

The following additional options from tls.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 a URL object. If options is a string, it is automatically parsed with new URL(). If it is a URL object, it will be automatically converted to an ordinary options object.

https.request() returns an instance of the http.ClientRequest class. The ClientRequest instance is a writable stream. If one needs to upload a file with a POST request, then write to the ClientRequest object.

import { request } from 'node:https';
import process from '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 from tls.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 an Agent.

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 a URL as options:

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

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

import { checkServerIdentity } from 'node:tls';
import { Agent, request } from 'node:https';
import { createHash } from 'node:crypto';
function sha256(s) {
 return 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 to
 const err = checkServerIdentity(host, cert);
 if (err) {
 return err;
 }
 // Pin the public key, similar to HPKP pin-sha256 pinning
 const 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';
 return new Error(msg);
 }
 // Pin the exact certificate, rather than the pub key
 const 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';
 return new Error(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 = new Agent(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');
function sha256(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 to
 const err = tls.checkServerIdentity(host, cert);
 if (err) {
 return err;
 }
 // Pin the public key, similar to HPKP pin-sha256 pinning
 const 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';
 return new Error(msg);
 }
 // Pin the exact certificate, rather than the pub key
 const 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';
 return new Error(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 key
statusCode: 200 copy