TLS/HTTPS Configuration

mockd supports HTTPS for both the mock server and proxy modes. This guide covers certificate generation, configuration, and common use cases.

Mock Server HTTPS

Quick Start

Enable HTTPS with auto-generated certificates:

mockd start --config mocks.json --https

mockd generates a self-signed certificate and starts on port 8443.

Custom Port

mockd start --config mocks.json --https --port 443

With Your Own Certificates

mockd start --config mocks.json \
  --cert ./certs/server.crt \
  --key ./certs/server.key

Configuration File

{
  "server": {
    "port": 8443,
    "tls": {
      "enabled": true,
      "certFile": "./certs/server.crt",
      "keyFile": "./certs/server.key"
    }
  },
  "mocks": [...]
}

Certificate Generation

Self-Signed (Development)

Generate a self-signed certificate:

mockd cert generate --name localhost --days 365

Output:

Generated certificate: ./certs/localhost.crt
Generated private key: ./certs/localhost.key

With Subject Alternative Names:

mockd cert generate \
  --name localhost \
  --san "127.0.0.1" \
  --san "::1" \
  --san "myapp.local"

CA Certificate (For Proxy)

Generate a CA for MITM proxying:

mockd cert generate-ca --name "mockd CA" --days 3650

Output:

Generated CA certificate: ./certs/mockd-ca.crt
Generated CA private key: ./certs/mockd-ca.key

Proxy HTTPS

MITM Proxy Setup

For the proxy to intercept HTTPS traffic, clients must trust the mockd CA.

1. Generate CA Certificate:

mockd cert generate-ca

2. Start Proxy:

mockd proxy --target https://api.example.com \
  --ca-cert ./certs/mockd-ca.crt \
  --ca-key ./certs/mockd-ca.key

3. Install CA on Client:

See Installing CA Certificates below.

Proxy Configuration

{
  "proxy": {
    "target": "https://api.example.com",
    "tls": {
      "caCertFile": "./certs/mockd-ca.crt",
      "caKeyFile": "./certs/mockd-ca.key",
      "certCacheDir": "./certs/generated"
    }
  }
}

Field	Description
caCertFile	CA certificate for signing
caKeyFile	CA private key
certCacheDir	Cache for generated certs

Installing CA Certificates

macOS

# Add to system keychain
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain \
  ./certs/mockd-ca.crt

# Or for current user only
security add-trusted-cert -r trustRoot \
  -k ~/Library/Keychains/login.keychain \
  ./certs/mockd-ca.crt

Linux

# Copy certificate
sudo cp ./certs/mockd-ca.crt /usr/local/share/ca-certificates/mockd-ca.crt

# Update certificate store
sudo update-ca-certificates

Windows

# Import to Trusted Root Certification Authorities
Import-Certificate -FilePath .\certs\mockd-ca.crt `
  -CertStoreLocation Cert:\LocalMachine\Root

Node.js

export NODE_EXTRA_CA_CERTS=./certs/mockd-ca.crt
node app.js

Python (requests)

import requests
requests.get('https://localhost:8443', verify='./certs/mockd-ca.crt')

curl

curl --cacert ./certs/mockd-ca.crt https://localhost:8443/api/users

Docker

Mount the CA certificate:

docker run -v $(pwd)/certs/mockd-ca.crt:/etc/ssl/certs/mockd-ca.crt \
  myapp

TLS Options

Minimum TLS Version

{
  "server": {
    "tls": {
      "enabled": true,
      "minVersion": "1.2"
    }
  }
}

Supported: 1.0, 1.1, 1.2, 1.3

Cipher Suites

{
  "server": {
    "tls": {
      "enabled": true,
      "cipherSuites": [
        "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
        "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
      ]
    }
  }
}

Client Certificate Authentication (mTLS)

Require client certificates:

{
  "server": {
    "tls": {
      "enabled": true,
      "certFile": "./certs/server.crt",
      "keyFile": "./certs/server.key",
      "clientAuth": "require",
      "clientCAs": ["./certs/client-ca.crt"]
    }
  }
}

Client auth modes:

• none - No client cert required
• request - Request but don’t require
• require - Require valid client cert

Mixed HTTP/HTTPS

Serve both protocols:

{
  "server": {
    "port": 4280,
    "tls": {
      "enabled": true,
      "port": 8443,
      "certFile": "./certs/server.crt",
      "keyFile": "./certs/server.key"
    }
  }
}

Both endpoints serve the same mocks:

• http://localhost:4280
• https://localhost:8443

HTTPS Redirect

Redirect HTTP to HTTPS:

{
  "server": {
    "port": 4280,
    "httpsRedirect": true,
    "tls": {
      "enabled": true,
      "port": 8443
    }
  }
}

Common Issues

Certificate Not Trusted

Symptom: CERT_AUTHORITY_INVALID or similar errors

Solution: Install the CA certificate as described above, or use --insecure flags for testing:

curl -k https://localhost:8443/api/users

Certificate Hostname Mismatch

Symptom: HOSTNAME_MISMATCH error

Solution: Generate certificate with correct SANs:

mockd cert generate --name localhost --san "myapp.local"

Certificate Expired

Symptom: CERT_HAS_EXPIRED error

Solution: Regenerate with longer validity:

mockd cert generate --name localhost --days 3650

Permission Denied (Port 443)

Symptom: Cannot bind to port 443

Solution: Use a high port or grant capability:

# Use high port
mockd start --https --port 8443

# Or grant capability (Linux)
sudo setcap 'cap_net_bind_service=+ep' $(which mockd)

Security Considerations

1. Never use self-signed certs in production - They’re for development only

2. Protect private keys - Restrict file permissions:

   chmod 600 ./certs/*.key

3. Short-lived certificates - Use shorter validity for development certs

4. Don’t commit certs - Add to .gitignore:

   certs/
   *.crt
   *.key
   *.pem

Next Steps

• Proxy Recording - HTTPS proxy setup
• CLI Reference - Certificate commands
• Configuration Reference - Full TLS options