Quantum/docs/tls-setup-guide.md

TLS/HTTPS Setup Guide for Quantum

Overview

Quantum includes enterprise-grade TLS/HTTPS support with:

• Manual certificate configuration (production-ready)
• Self-signed certificates (development/testing)
• ACME/Let's Encrypt framework (coming soon)
• HTTP/2 automatic negotiation
• Wildcard certificate support

Quick Start

1. Generate Development Certificates

Self-Signed Certificate (localhost testing):

# Generate certificate valid for localhost
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes \
  -subj "/CN=localhost/O=Quantum Dev/C=US"

# Verify certificate
openssl x509 -in cert.pem -text -noout | grep -E "(Subject|DNS|IP)"

Multi-Domain Certificate:

# Create config file for Subject Alternative Names
cat > cert.conf <<EOF
[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no

[req_distinguished_name]
CN = quantum.local

[v3_req]
subjectAltName = @alt_names

[alt_names]
DNS.1 = localhost
DNS.2 = quantum.local
DNS.3 = *.quantum.local
IP.1 = 127.0.0.1
IP.2 = ::1
EOF

# Generate multi-domain certificate
openssl req -x509 -newkey rsa:4096 -keyout multi-key.pem -out multi-cert.pem \
  -days 365 -nodes -config cert.conf -extensions v3_req

2. Production Certificates

Using Let's Encrypt (certbot):

# Install certbot
sudo apt-get install certbot  # Ubuntu/Debian
# or
brew install certbot          # macOS

# Generate certificate for your domain
sudo certbot certonly --standalone -d yourdomain.com -d www.yourdomain.com

# Certificates will be in: /etc/letsencrypt/live/yourdomain.com/
# - fullchain.pem (certificate)
# - privkey.pem (private key)

Using existing certificates:

# Copy your certificates to Quantum directory
cp /path/to/your/fullchain.pem ./production-cert.pem
cp /path/to/your/privkey.pem ./production-key.pem

# Set proper permissions
chmod 644 ./production-cert.pem
chmod 600 ./production-key.pem

Configuration Examples

Basic HTTPS Configuration

{
  "admin": {
    "listen": ":2019"
  },
  "apps": {
    "http": {
      "servers": {
        "https_server": {
          "listen": [":443", ":8443"],
          "routes": [
            {
              "handle": [
                {
                  "handler": "static_response",
                  "status_code": 200,
                  "body": "Hello from Quantum HTTPS Server!"
                }
              ]
            }
          ],
          "tls": {
            "certificates": [
              {
                "certificate": "./cert.pem",
                "key": "./key.pem",
                "subjects": ["localhost", "127.0.0.1"]
              }
            ]
          }
        }
      }
    }
  }
}

Multi-Domain HTTPS Configuration

{
  "admin": {
    "listen": ":2019"
  },
  "apps": {
    "http": {
      "servers": {
        "multi_domain_server": {
          "listen": [":443"],
          "routes": [
            {
              "match": [
                {
                  "matcher": "host",
                  "hosts": ["api.example.com"]
                }
              ],
              "handle": [
                {
                  "handler": "reverse_proxy",
                  "upstreams": [
                    {
                      "dial": "backend-api:8080"
                    }
                  ]
                }
              ]
            },
            {
              "match": [
                {
                  "matcher": "host", 
                  "hosts": ["files.example.com"]
                }
              ],
              "handle": [
                {
                  "handler": "file_sync",
                  "root": "./sync-data",
                  "enable_upload": true
                }
              ]
            },
            {
              "handle": [
                {
                  "handler": "file_server",
                  "root": "./public"
                }
              ]
            }
          ],
          "tls": {
            "certificates": [
              {
                "certificate": "/etc/ssl/certs/example.com.pem",
                "key": "/etc/ssl/private/example.com.key",
                "subjects": ["example.com", "*.example.com"]
              }
            ]
          }
        }
      }
    }
  }
}

ACME/Let's Encrypt Configuration (Framework)

{
  "admin": {
    "listen": ":2019"
  },
  "apps": {
    "http": {
      "servers": {
        "auto_https_server": {
          "listen": [":443"],
          "routes": [
            {
              "handle": [
                {
                  "handler": "file_server",
                  "root": "./public"
                }
              ]
            }
          ],
          "tls": {
            "automation": {
              "policies": [
                {
                  "subjects": ["yourdomain.com", "www.yourdomain.com"],
                  "issuer": {
                    "module": "acme",
                    "ca": "https://acme-v02.api.letsencrypt.org/directory",
                    "email": "admin@yourdomain.com",
                    "agreed": true
                  }
                }
              ]
            }
          }
        }
      }
    }
  }
}

Testing Your HTTPS Setup

1. Basic Connection Test

# Test HTTPS connection
curl -k https://localhost:8443

# Test with certificate verification (should fail with self-signed)
curl https://localhost:8443

# Test HTTP/2 support
curl -k --http2 -I https://localhost:8443

# Test with verbose output
curl -k -v https://localhost:8443

2. Certificate Information

# View certificate details
openssl s_client -connect localhost:8443 -servername localhost < /dev/null 2>/dev/null | \
  openssl x509 -noout -text | grep -E "(Subject|Issuer|Not Before|Not After|DNS)"

# Test certificate chain
openssl s_client -connect localhost:8443 -showcerts < /dev/null

3. Performance Testing

# Test HTTP/2 multiplexing
curl -k --http2-prior-knowledge https://localhost:8443/file1 \
     https://localhost:8443/file2 \
     https://localhost:8443/file3

# Load testing with ApacheBench (HTTP/2)
h2load -n 1000 -c 10 -m 10 https://localhost:8443/

Security Best Practices

1. Certificate Management

# Set proper file permissions
chmod 644 *.pem  # Certificates (public)
chmod 600 *.key  # Private keys (secure)

# Store certificates securely
sudo mkdir -p /etc/quantum/certificates
sudo mkdir -p /etc/quantum/private
sudo chown root:quantum /etc/quantum/private
sudo chmod 750 /etc/quantum/private

2. Production Deployment

# Create systemd service with proper security
sudo tee /etc/systemd/system/quantum.service > /dev/null <<EOF
[Unit]
Description=Quantum HTTPS Server
After=network.target

[Service]
Type=simple
User=quantum
Group=quantum
WorkingDirectory=/var/lib/quantum
ExecStart=/usr/local/bin/quantum -c /etc/quantum/config.json
Restart=always
RestartSec=5

# Security settings
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/quantum

[Install]
WantedBy=multi-user.target
EOF

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable quantum
sudo systemctl start quantum

3. Firewall Configuration

# Open HTTPS ports
sudo ufw allow 443/tcp
sudo ufw allow 8443/tcp

# Close HTTP if not needed
sudo ufw deny 80/tcp

Troubleshooting

Common Issues

Certificate Loading Errors:

# Check certificate format
openssl x509 -in cert.pem -noout -text

# Check private key format  
openssl rsa -in key.pem -noout -text

# Verify certificate and key match
openssl x509 -in cert.pem -noout -pubkey | sha256sum
openssl rsa -in key.pem -pubout 2>/dev/null | sha256sum

Connection Issues:

# Check server is listening
ss -tlnp | grep :443

# Test with openssl client
openssl s_client -connect localhost:443 -debug

# Check logs
tail -f /var/log/quantum/error.log

HTTP/2 Issues:

# Verify HTTP/2 support
curl -k --http2 -I https://localhost:8443 | grep -i "http/2"

# Test ALPN negotiation
openssl s_client -connect localhost:8443 -alpn h2,http/1.1

What's Next

• ACME Integration: Automatic Let's Encrypt certificate management (coming soon)
• Certificate Renewal: Automated certificate rotation
• HTTP/3 Support: QUIC protocol with TLS 1.3
• Advanced Security: OCSP stapling, HSTS headers, certificate pinning

Support

For TLS-related issues:

• Check certificate validity and format
• Verify network connectivity and firewall rules
• Review Quantum logs for detailed error messages
• Test with simple configurations first

Quantum now provides revolutionary TLS termination with quantum leap performance! ⚡🔒