TLS Proxy (Enterprise)¶

Enterprise MarchProxy includes advanced TLS proxy capabilities with certificate authority management and wildcard certificate generation.

Overview¶

The TLS proxy feature enables:

TLS Termination: Decrypt incoming TLS traffic for inspection
TLS Re-encryption: Re-encrypt traffic to backend services
Certificate Authority Management: Self-signed or imported CA certificates
Wildcard Certificate Generation: Automatic wildcard certificate creation
Modern Cryptography: ECC P-384, SHA-512, and strong cipher suites

Features¶

Certificate Authority Management¶

Self-Signed CA Generation¶

Elliptic Curve Cryptography: ECC P-384 for optimal security and performance
Strong Hashing: SHA-512 for certificate signatures
Long Lifetime: 10-year default certificate lifetime
Automatic Key Generation: Secure random key generation
PEM Format Export: Standard format for certificate and key

CA Import/Export¶

Import Existing CA: Upload existing CA certificates and keys
Export Certificates: Download CA certificates and keys
Multiple Formats: Support for PEM, DER, and PKCS#12 formats
Secure Storage: Encrypted storage of private keys in database

Wildcard Certificate Generation¶

Automatic Generation¶

Domain-based: Generate wildcard certificates for any domain
SAN Support: Subject Alternative Names for multiple domains
Chain Building: Complete certificate chain construction
Validation: Certificate validation and verification

Certificate Types¶

Wildcard Certificates: *.example.com for subdomain coverage
Multi-domain Certificates: Multiple domains in single certificate
Standard Certificates: Single domain certificates

TLS Configuration¶

Supported TLS Versions¶

TLS 1.2: Minimum supported version
TLS 1.3: Preferred version for performance and security
Version Negotiation: Automatic version selection

Cipher Suites¶

Modern cipher suites with forward secrecy: - TLS_AES_256_GCM_SHA384 (TLS 1.3) - TLS_CHACHA20_POLY1305_SHA256 (TLS 1.3) - ECDHE-RSA-AES256-GCM-SHA384 (TLS 1.2) - ECDHE-ECDSA-AES256-GCM-SHA384 (TLS 1.2)

Configuration¶

Manager Portal Configuration¶

TLS Proxy Settings¶

Access via: Features → TLS Proxy

Enable TLS Proxy: Toggle TLS proxy functionality
CA Configuration:
Generate new self-signed CA
Import existing CA certificate and key
View current CA information
Certificate Management:
Generate wildcard certificates
View active certificates
Certificate renewal and rotation

Certificate Authority Setup¶

Generate Self-Signed CA¶

ca_config:
  domain: "proxy.company.com"
  key_type: "ecc"           # ecc or rsa
  key_size: 384             # 384 for ECC, 2048/4096 for RSA
  hash_algorithm: "sha512"  # sha256, sha384, sha512
  lifetime_years: 10        # Certificate lifetime
  country: "US"
  organization: "Company Inc"
  organizational_unit: "IT Department"

Import Existing CA¶

ca_import:
  certificate: |
    -----BEGIN CERTIFICATE-----
    ... CA certificate in PEM format ...
    -----END CERTIFICATE-----
  private_key: |
    -----BEGIN PRIVATE KEY-----
    ... CA private key in PEM format ...
    -----END PRIVATE KEY-----

Wildcard Certificate Generation¶

wildcard_cert:
  domain: "*.company.com"
  san_domains:
    - "company.com"
    - "*.api.company.com"
  lifetime_years: 2
  auto_renewal: true

Proxy Configuration¶

Environment Variables¶

# TLS Proxy settings
TLS_PROXY_ENABLED=true              # Enable TLS proxy functionality
TLS_PROXY_PORT=443                  # TLS proxy listen port
TLS_PROXY_MODE=terminate            # terminate, passthrough, or bridge

# Certificate settings
TLS_CA_CERT_PATH=/app/certs/ca.crt  # CA certificate path
TLS_CA_KEY_PATH=/app/certs/ca.key   # CA private key path
TLS_CERT_PATH=/app/certs/server.crt # Server certificate path
TLS_KEY_PATH=/app/certs/server.key  # Server private key path

# TLS Configuration
TLS_MIN_VERSION=1.2                 # Minimum TLS version
TLS_MAX_VERSION=1.3                 # Maximum TLS version
TLS_PREFER_SERVER_CIPHERS=true      # Prefer server cipher order

Service-level TLS Configuration¶

services:
  - name: "web-app"
    backend_ip: "10.0.1.100"
    backend_port: 8080
    tls_config:
      enabled: true
      mode: "terminate"              # terminate, passthrough, bridge
      certificate: "wildcard-company-com"
      backend_tls: false             # Re-encrypt to backend
      sni_matching: true             # SNI-based routing

TLS Proxy Modes¶

Terminate Mode¶

Description: Decrypt TLS traffic, forward as HTTP
Use Case: TLS termination for backend inspection
Performance: High (no re-encryption overhead)
Security: Backend traffic unencrypted

tls_config:
  mode: "terminate"
  certificate: "wildcard-cert"
  backend_tls: false

Passthrough Mode¶

Description: Forward TLS traffic without decryption
Use Case: End-to-end encryption preservation
Performance: Highest (no crypto overhead)
Security: End-to-end encryption maintained

tls_config:
  mode: "passthrough"
  sni_routing: true  # Route based on SNI

Bridge Mode¶

Description: Decrypt, inspect, then re-encrypt
Use Case: Deep packet inspection with end-to-end security
Performance: Lower (double encryption overhead)
Security: Full inspection with backend encryption

tls_config:
  mode: "bridge"
  certificate: "wildcard-cert"
  backend_tls: true
  backend_ca: "internal-ca"

Performance Characteristics¶

Throughput Impact¶

Terminate Mode: ~10% performance impact
Passthrough Mode: ~2% performance impact
Bridge Mode: ~20% performance impact

TLS Handshake Performance¶

ECC P-384: ~2ms handshake time
RSA 2048: ~5ms handshake time
Session Resumption: ~0.5ms handshake time

Memory Usage¶

Certificate Storage: ~2KB per certificate
TLS Session Cache: ~1KB per session
Crypto Buffers: ~16KB per connection

Management Interface¶

Dashboard Features¶

Certificate Overview: View all certificates and expiration dates
TLS Statistics: Handshake success rates, cipher usage
Performance Metrics: TLS overhead and throughput impact
Certificate Health: Validation status and renewal alerts

Certificate Management¶

Certificate Generation: Web-based wildcard certificate creation
Certificate Rotation: Automated certificate renewal
Certificate Validation: Real-time certificate health checks
Certificate Export: Download certificates and keys

Monitoring and Alerting¶

Prometheus Metrics¶

# TLS handshake metrics
tls_handshakes_total{status="success|failed"}
tls_handshake_duration_seconds

# Certificate metrics
tls_certificate_expiry_seconds{cert_name="wildcard-company-com"}
tls_certificate_validation_status{cert_name="wildcard-company-com"}

# Performance metrics
tls_connection_duration_seconds
tls_bytes_encrypted_total
tls_bytes_decrypted_total

Alerting Rules¶

groups:
  - name: tls_proxy
    rules:
      - alert: CertificateExpiringSoon
        expr: tls_certificate_expiry_seconds < 7 * 24 * 3600
        labels:
          severity: warning
        annotations:
          summary: "TLS certificate expiring soon"

      - alert: TLSHandshakeFailures
        expr: rate(tls_handshakes_total{status="failed"}[5m]) > 0.1
        labels:
          severity: critical
        annotations:
          summary: "High TLS handshake failure rate"

Security Considerations¶

CA Security¶

Private Key Protection: Encrypted storage of CA private keys
Access Control: Role-based access to CA operations
Audit Logging: Complete audit trail of CA operations
Key Rotation: Regular CA key rotation recommendations

Certificate Security¶

Strong Cryptography: ECC P-384 and SHA-512 by default
Short Lifetimes: 2-year maximum certificate lifetime
Automatic Renewal: Prevent certificate expiration
Revocation Support: Certificate revocation list (CRL) support

TLS Security¶

Modern Protocols: TLS 1.2 minimum, TLS 1.3 preferred
Strong Ciphers: Forward secrecy and AEAD ciphers only
HSTS Headers: HTTP Strict Transport Security support
OCSP Stapling: Online Certificate Status Protocol support

Troubleshooting¶

Common Issues¶

Certificate Generation Failures¶

# Check CA certificate validity
openssl x509 -in /app/certs/ca.crt -text -noout

# Verify private key matches certificate
openssl x509 -noout -modulus -in /app/certs/ca.crt | openssl md5
openssl rsa -noout -modulus -in /app/certs/ca.key | openssl md5

# Test certificate chain
openssl verify -CAfile /app/certs/ca.crt /app/certs/server.crt

TLS Handshake Failures¶

# Test TLS connection
openssl s_client -connect proxy.company.com:443 -servername test.company.com

# Check cipher compatibility
openssl s_client -connect proxy.company.com:443 -cipher ECDHE-RSA-AES256-GCM-SHA384

# Verify certificate chain
curl -vI https://test.company.com

Performance Issues¶

# Monitor TLS overhead
curl http://localhost:8080/metrics | grep tls_

# Check certificate cache performance
curl http://localhost:8080/admin/tls/cache-stats

# Test handshake performance
time openssl s_client -connect proxy.company.com:443 -sess_out /tmp/session
time openssl s_client -connect proxy.company.com:443 -sess_in /tmp/session

API Reference¶

Certificate Authority Operations¶

# Generate new CA
curl -X POST http://localhost:8000/api/v1/tls/ca/generate \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "proxy.company.com",
    "key_type": "ecc",
    "key_size": 384,
    "lifetime_years": 10
  }'

# Get CA information
curl http://localhost:8000/api/v1/tls/ca/info

# Export CA certificate
curl http://localhost:8000/api/v1/tls/ca/export?format=pem

Certificate Management¶

# Generate wildcard certificate
curl -X POST http://localhost:8000/api/v1/tls/certificates/generate \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "*.company.com",
    "san_domains": ["company.com"],
    "lifetime_years": 2
  }'

# List certificates
curl http://localhost:8000/api/v1/tls/certificates

# Get certificate details
curl http://localhost:8000/api/v1/tls/certificates/wildcard-company-com

Next: Authentication Features