TLS/SSL configuration guide

import https from 'https';
import tls from 'tls';
import { readFileSync } from 'fs';
import { createHash } from 'crypto';

interface TlsClientConfig {
  caPath: string;
  certPath?: string;
  keyPath?: string;
  passphrase?: string;
  pinFingerprint?: string;
  rejectUnauthorized: boolean;
}

export function createSecureTlsAgent(config: TlsClientConfig): https.Agent {
  const tlsOptions: tls.SecureContextOptions = {
    ca: readFileSync(config.caPath),
    rejectUnauthorized: config.rejectUnauthorized,
    minVersion: 'TLSv1.3',
    maxVersion: 'TLSv1.3',
    ciphers: 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256',
    honorCipherOrder: true,
    secureOptions: 
      tls.constants.SSL_OP_NO_TLSv1 |
      tls.constants.SSL_OP_NO_TLSv1_1 |
      tls.constants.SSL_OP_NO_TLSv1_2,
  };

  if (config.certPath && config.keyPath) {
    tlsOptions.cert = readFileSync(config.certPath);
    tlsOptions.key = readFileSync(config.keyPath);
    if (config.passphrase) tlsOptions.passphrase = config.passphrase;
  }

  const agent = new https.Agent({
    ...tlsOptions,
    checkServerIdentity: (host, cert) => {
      // Default Node.js validation
      const defaultResult = tls.checkServerIdentity(host, cert);
      if (defaultResult) return defaultResult;

      // Optional: Certificate pinning validation
      if (config.pinFingerprint) {
        const fingerprint = createHash('sha256')
          .update(cert.raw)
          .digest('base64');
        if (fingerprint !== config.pinFingerprint) {
          return new Error('Certificate pin mismatch');
        }
      }
      return undefined;
    },
  });

  return agent;
}

// Usage example
const secureAgent = createSecureTlsAgent({
  caPath: './certs/ca-bundle.pem',
  rejectUnauthorized: true,
  pinFingerprint: 'XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX',
});

https.get('https://api.production.internal/health', { agent: secureAgent }, (res) => {
  console.log(`Status: ${res.statusCode}`);
}).on('error', (err) => {
  console.error('TLS handshake failed:', err.message);
});

Architecture Decisions and Rationale

• TLS 1.3 enforcement: Eliminates legacy handshake complexity, removes RSA key exchange, and enforces forward secrecy by default.
• Explicit cipher ordering: Prevents downgrade attacks and ensures hardware acceleration paths are prioritized.
• Client-side checkServerIdentity override: Allows integration with internal PKI, certificate pinning, or custom validation logic without disabling rejectUnauthorized.
• OCSP stapling + CRL fallback: Balances revocation accuracy with latency. Staging servers should validate stapled responses before production rollout.
• Session ticket key rotation: Maintains forward secrecy when 0-RTT is enabled. Keys must be rotated at least every 24 hours or per deployment.

Pitfall Guide

1. Enabling TLS 1.0/1.1 for "Compatibility"

Legacy protocols are vulnerable to POODLE, BEAST, SLOTH, and protocol downgrade attacks. Modern clients ignore them regardless of server advertisement. Best practice: Disable at the network edge. If legacy clients exist, isolate them behind a dedicated endpoint with strict rate limiting and monitoring.

2. Incomplete Certificate Chain

Missing intermediate certificates cause validation failures on Android, iOS, and enterprise proxy environments. Browsers often cache intermediates, masking the issue during development. Best practice: Always concatenate leaf + intermediates in server configuration. Validate chain completeness using openssl s_client -connect host:port -showcerts.

3. Static Certificate Management

Manual renewal causes expiration outages and breaks CI/CD velocity. Certificates rotated outside automation lack audit trails and rollback capability. Best practice: Implement ACME automation with webhook validation. Store private keys in HSM or KMS. Enforce 90-day maximum validity for public endpoints.

4. HSTS Misconfiguration

Setting max-age too low provides no protection. Preloading without includeSubDomains leaves subdomains vulnerable. Incorrect preload submission triggers browser warnings. Best practice: Start with max-age=300, monitor error rates, then escalate to 31536000. Submit to HSTS preload list only after 30 days of stable operation.

5. Disabling OCSP Stapling

Clients must query OCSP responders directly, increasing latency and exposing browsing patterns to third parties. Revocation checks fail silently when responders are unreachable. Best practice: Enable stapling at the reverse proxy. Configure ssl_stapling_verify on and validate responder certificates. Fall back to CRL only if stapling fails.

6. Client-Side rejectUnauthorized: false in Production

Disabling certificate validation removes all TLS guarantees. Often introduced in development and accidentally deployed. Best practice: Never disable validation in production. Use custom CA bundles or checkServerIdentity overrides for internal PKI. Enforce via linting and CI gates.

7. Over-Reliance on Framework Defaults

Express, Fastify, and cloud load balancers ship with permissive cipher lists and TLS 1.2 fallbacks. Defaults prioritize compatibility over security. Best practice: Explicitly declare protocol and cipher constraints in configuration. Audit framework defaults against NIST SP 800-52 Rev 2 guidelines.

Production Bundle

Action Checklist

• Enforce TLS 1.3 minimum: Disable TLS 1.0/1.1/1.2 unless legacy isolation is architecturally justified.
• Audit cipher suite order: Prioritize AES-GCM and ChaCha20-Poly1305; remove CBC, RSA key exchange, and SHA-1.
• Validate certificate chain completeness: Bundle leaf + intermediates; verify with openssl s_client.
• Automate certificate rotation: Implement ACME v2 with webhook validation; enforce 90-day max validity.
• Configure HSTS parameters: max-age=31536000; includeSubDomains; preload after staging validation.
• Enable OCSP stapling: Set ssl_stapling on, verify responder chain, monitor stapling latency.
• Implement client-side strict validation: Never disable rejectUnauthorized; use custom CA or pinning for internal services.
• Schedule continuous TLS scanning: Integrate SSL Labs API or testssl.sh into CI/CD; block deployments on B- rating.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Public-facing API	TLS 1.3 only, ECDSA P-256, ACME automation	Maximizes security, minimizes handshake latency, reduces operational overhead	Low (cloud-native certs, automated rotation)
Internal mTLS service	TLS 1.3, private CA, certificate pinning, mutual auth	Ensures service identity, prevents lateral movement, enforces zero-trust	Medium (PKI infrastructure, key management)
Legacy client support	Isolated endpoint, TLS 1.2 ECDHE+AESGCM only, strict rate limiting	Contains vulnerability surface, preserves primary endpoint security	High (dual infrastructure, monitoring overhead)
High-throughput CDN	TLS 1.3, session tickets with key rotation, OCSP stapling	Optimizes 0-RTT resumption, reduces CPU per connection, maintains forward secrecy	Low (edge provider handles most config)

Configuration Template

Nginx Production TLS Configuration

server {
    listen 443 ssl http2;
    server_name api.example.com;

    # Certificate chain
    ssl_certificate /etc/ssl/certs/leaf+chain.pem;
    ssl_certificate_key /etc/ssl/private/leaf.key;

    # Protocol enforcement
    ssl_protocols TLSv1.3;
    ssl_prefer_server_ciphers on;

    # Cipher suite ordering
    ssl_ciphers TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;

    # Session and handshake optimization
    ssl_session_timeout 1d;
    ssl_session_cache shared:TLS:10m;
    ssl_session_tickets off;

    # OCSP stapling
    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 8.8.8.8 8.8.4.4 valid=300s;
    resolver_timeout 5s;

    # HSTS
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;

    # Security headers
    add_header X-Content-Type-Options nosniff always;
    add_header X-Frame-Options DENY always;
}

TypeScript Server TLS Context (Node.js)

import https from 'https';
import { readFileSync } from 'fs';
import { createServer } from 'http';

const tlsOptions = {
  key: readFileSync('./certs/server.key'),
  cert: readFileSync('./certs/server+chain.pem'),
  minVersion: 'TLSv1.3',
  maxVersion: 'TLSv1.3',
  ciphers: 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256',
  honorCipherOrder: true,
  secureOptions: 0x00000004, // SSL_OP_NO_COMPRESSION
  requestCert: false, // Set true for mTLS
  rejectUnauthorized: true,
};

const server = https.createServer(tlsOptions, (req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('TLS 1.3 secure connection established.\n');
});

server.listen(443, () => {
  console.log('Secure server running on port 443');
});

Quick Start Guide

1. Generate test certificates: Run openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -keyout server.key -out server.pem -days 90 -nodes -subj "/CN=localhost" for local validation.
2. Configure server constraints: Apply the Nginx or TypeScript template above. Ensure ssl_protocols TLSv1.3 and explicit cipher ordering are set.
3. Validate handshake: Execute openssl s_client -connect localhost:443 -tls1_3 -brief. Confirm protocol version, cipher suite, and chain completeness.
4. Enable HSTS and scan: Add HSTS header, restart service, then run testssl.sh localhost:443 or submit to SSL Labs. Verify A+ rating and zero warnings before production deployment.