node:https

require('https')

The node:https module provides HTTPS server and client functionality in Node.js. It’s similar to the http module but adds TLS/SSL encryption for secure communications. This module is essential for building secure web servers and making encrypted API requests.

Common Usage

Creating an HTTPS Server

const https = require('https');
const fs = require('fs');

const options = {
  key: fs.readFileSync('server.key'),
  cert: fs.readFileSync('server.cert')
};

const server = https.createServer(options, (req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Secure Hello, World!');
});

server.listen(443, () => {
  console.log('HTTPS Server running on https://localhost');
});

Making HTTPS GET Requests

const https = require('https');

const req = https.get('https://example.com', (res) => {
  console.log(`STATUS: ${res.statusCode}`);
  
  res.on('data', (chunk) => {
    console.log(`DATA: ${chunk}`);
  });
  
  res.on('end', () => {
    console.log('Response complete');
  });
});

req.on('error', (err) => {
  console.error(`Error: ${err.message}`);
});

Making HTTPS POST Requests with Options

const https = require('https');

const data = JSON.stringify({ name: 'John', age: 30 });

const options = {
  hostname: 'api.example.com',
  port: 443,
  path: '/users',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(data)
  }
};

const req = https.request(options, (res) => {
  let body = '';
  
  res.on('data', (chunk) => {
    body += chunk;
  });
  
  res.on('end', () => {
    console.log('Response:', body);
  });
});

req.write(data);
req.end();

Key Options

When creating an HTTPS server or making HTTPS requests, you can configure TLS/SSL options:

Option	Type	Description
key	string | Buffer	Private key in PEM format
cert	string | Buffer	Certificate in PEM format
ca	string | Buffer	Certificate Authority certificate(s)
rejectUnauthorized	boolean	Whether to reject unauthorized certificates
pfx	string | Buffer	Private key, certificate, and CA certs in PFX/PKCS12 format

Server-Side Examples

Using a Self-Signed Certificate (Development)

const https = require('https');
const fs = require('fs');
const crypto = require('crypto');

function generateSelfSigned() {
  const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', {
    modulusLength: 2048,
    publicKeyEncoding: { type: 'spki', format: 'pem' },
    privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
  });
  
  return { privateKey, publicKey };
}

const { privateKey, publicKey } = generateSelfSigned();

const server = https.createServer({
  key: privateKey,
  cert: publicKey
}, (req, res) => {
  res.writeHead(200);
  res.end('Secure (but self-signed)!');
});

server.listen(443);

Requiring Client Certificates (Mutual TLS)

const https = require('https');
const fs = require('fs');

const options = {
  key: fs.readFileSync('server.key'),
  cert: fs.readFileSync('server.cert'),
  ca: fs.readFileSync('client-ca.crt'),  // CA that signed client certs
  requestCert: true,                        // Require client certificate
  rejectUnauthorized: true                 // Reject unauthorized clients
};

const server = https.createServer(options, (req, res) => {
  // Client certificate available in req.socket.getPeerCertificate()
  console.log('Client:', req.socket.getPeerCertificate().subject);
  res.writeHead(200);
  res.end('Authenticated!');
});

server.listen(443);

Client-Side Examples

Disabling Certificate Verification (Development Only!)

const https = require('https');

const options = {
  hostname: 'self-signed.example.com',
  port: 443,
  rejectUnauthorized: false  // ⚠️ Never use in production!
};

const req = https.get(options, (res) => {
  console.log('STATUS:', res.statusCode);
  res.on('data', console.log);
});

req.on('error', console.error);

Using Custom CA

const https = require('https');
const fs = require('fs');

const options = {
  hostname: 'api.internal.company.com',
  port: 443,
  ca: fs.readFileSync('company-ca.crt')  // Custom CA certificate
};

const req = https.get(options, (res) => {
  console.log('STATUS:', res.statusCode);
  let data = '';
  
  res.on('data', (chunk) => { data += chunk; });
  res.on('end', () => { console.log(data); });
});

req.on('error', console.error);

Key Differences from HTTP

1. Default Port: HTTP uses port 80, HTTPS uses port 443
2. Encryption: All data is encrypted using TLS/SSL
3. Certificate Required: Servers need SSL certificates
4. Module API: Nearly identical to http module, but with TLS options

See Also

• Http::Request — HTTP server and client
• URL::parse — URL parsing and manipulation
• node:crypto — Cryptographic functions