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):**
```bash
# 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:**
```bash
# 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):**
```bash
# 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:**
```bash
# 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

```json
{
  "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

```json
{
  "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)

```json
{
  "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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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!** ⚡🔒