foxhunt/AGENT_H1_QUICK_REFERENCE.md

Agent H1: TLS Configuration - Quick Reference

Status: ✅ CONFIGURATION COMPLETE (Code initialization pending)

---

🚀 Quick Start

Enable TLS in Development

Edit .env:

TLS_ENABLED=true  # Change from false to true

Restart Services:

docker-compose down
docker-compose up -d

⚠️ WARNING: Services will start but TLS is NOT enforced (code changes required in Wave H2-H3).

---

📁 Files Changed

1. docker-compose.yml - Added TLS configuration to 5 services:

   • Trading Service (port 50052)
   • Backtesting Service (port 50053)
   • ML Training Service (port 50054)
   • Trading Agent Service (port 50055)
   • API Gateway (port 50051)

2. .env - Added TLS environment variables

---

🔑 TLS Environment Variables

Server-Side TLS (All Services)

TLS_ENABLED=false                     # Set to true to enable TLS
TLS_PROTOCOL_VERSION=TLS13            # Force TLS 1.3
TLS_REQUIRE_CLIENT_CERT=true          # Enforce mTLS
TLS_CERT_PATH=./certs/server-cert.pem
TLS_KEY_PATH=./certs/server-key.pem
TLS_CA_PATH=./certs/ca/ca-cert.pem

Client-Side TLS (API Gateway)

TLS_CLIENT_CERT_PATH=./certs/client-cert.pem
TLS_CLIENT_KEY_PATH=./certs/client-key.pem

# For Backtesting Service connections
BACKTESTING_TLS_CA_CERT=/tmp/foxhunt/certs/ca/ca-cert.pem
BACKTESTING_TLS_CLIENT_CERT=/tmp/foxhunt/certs/client-cert.pem
BACKTESTING_TLS_CLIENT_KEY=/tmp/foxhunt/certs/client-key.pem

# For ML Training Service connections
ML_TRAINING_TLS_CA_CERT=/tmp/foxhunt/certs/ca/ca-cert.pem
ML_TRAINING_TLS_CLIENT_CERT=/tmp/foxhunt/certs/client-cert.pem
ML_TRAINING_TLS_CLIENT_KEY=/tmp/foxhunt/certs/client-key.pem

mTLS Validation

MTLS_ENABLE_REVOCATION_CHECK=false    # Enable in production
MTLS_CRL_URL=                         # Certificate Revocation List URL

---

📊 Service Implementation Status

Service	TLS Config	Code Init	Status
API Gateway	✅	❌	Config ready, code pending (Wave H2)
Trading Service	✅	❌	Config ready, no TLS infrastructure
Backtesting Service	✅	❌	Config + infra ready, not initialized
ML Training Service	✅	❌	Config + infra ready, not initialized
Trading Agent Service	✅	❌	Config ready, no TLS infrastructure

Overall Progress: 20% (Configuration complete, 80% code implementation pending)

---

🔒 Certificate Files

Location: /home/jgrusewski/Work/foxhunt/certs/

certs/
├── ca/
│   ├── ca-cert.pem          ✅ CA certificate
│   ├── ca-key.pem           ✅ CA private key
│   └── ca-cert.srl          ✅ CA serial number
├── server-cert.pem          ✅ Server certificate
├── server-key.pem           ✅ Server private key
├── client-cert.pem          ✅ Client certificate
└── client-key.pem           ✅ Client private key

Status: ✅ All certificates present and valid (dev certificates)

---

⚠️ Known Limitations

TLS NOT Enforced (Services Ignore TLS_ENABLED)

Reason: Services don't initialize TLS configuration in their main.rs files.

Services Affected:

1. ❌ API Gateway - No server-side TLS initialization
2. ❌ Trading Service - No TLS infrastructure
3. ❌ Backtesting Service - TLS config exists, not used
4. ❌ ML Training Service - TLS config exists, not used
5. ❌ Trading Agent Service - No TLS infrastructure

Current Behavior: Even with TLS_ENABLED=true, services start without TLS validation.

Security Impact: 🟡 MEDIUM (plaintext gRPC traffic until code fixes applied)

---

🎯 Next Steps

Wave H2: API Gateway TLS (2 hours)

File: services/api_gateway/src/main.rs

Add:

use api_gateway::auth::mtls::tls_config::ApiGatewayTlsConfig;

let tls_config = if std::env::var("TLS_ENABLED")
    .unwrap_or_else(|_| "false".to_string())
    .parse::<bool>()
    .unwrap_or(false)
{
    Some(ApiGatewayTlsConfig::from_files(
        &std::env::var("TLS_CERT_PATH")?,
        &std::env::var("TLS_KEY_PATH")?,
        &std::env::var("TLS_CA_PATH")?,
        true,  // require_client_cert
        false, // enable_revocation_check
        None,  // crl_url
    ).await?)
} else {
    None
};

let server_builder = if let Some(tls) = tls_config {
    tonic::transport::Server::builder()
        .tls_config(tls.to_server_tls_config())?
} else {
    tonic::transport::Server::builder()
};

Wave H3: Backend Services TLS (4 hours)

Files:

• services/backtesting_service/src/main.rs
• services/ml_training_service/src/main.rs
• services/trading_service/src/main.rs (add tls_config.rs first)
• services/trading_agent_service/src/main.rs (add tls_config.rs first)

Pattern: Same as Wave H2 (load TLS config, apply to server builder)

Wave H4: TLS Testing (2 hours)

Tests:

1. ✅ Services start with TLS_ENABLED=true
2. ✅ gRPC connections fail without client certificates
3. ✅ gRPC connections succeed with valid certificates
4. ✅ TLS 1.2 connections rejected
5. ✅ Invalid certificates rejected

---

🛠️ Troubleshooting

Issue: Services fail to start with TLS_ENABLED=true

Cause: Code doesn't initialize TLS configuration Fix: Wait for Wave H2-H3 implementation

Issue: Certificate not found errors

Check:

ls -la /home/jgrusewski/Work/foxhunt/certs/
ls -la /home/jgrusewski/Work/foxhunt/certs/ca/

Fix: Regenerate certificates if missing

Issue: docker-compose validation fails

Check:

docker-compose config --quiet

Fix: Ensure YAML syntax is valid

---

📈 Performance Impact

TLS Overhead (Expected):

• Handshake: ~1-5ms (one-time per connection)
• Per-request: <100μs (acceptable for HFT)
• Total: <1% performance degradation

Mitigation:

• HTTP/2 connection reuse
• TLS session resumption
• Hardware acceleration (AES-NI)

---

🔐 Production Checklist

Before enabling TLS in production:

1. ⚠️ Complete Wave H2-H3: Implement TLS initialization
2. ⚠️ Replace Dev Certificates: Use CA-signed certificates
3. ⚠️ Enable Revocation Check: MTLS_ENABLE_REVOCATION_CHECK=true
4. ⚠️ Configure CRL URL: Set valid MTLS_CRL_URL
5. ⚠️ Test Certificate Rotation: Zero-downtime renewal
6. ⚠️ Set Expiration Alerts: Monitor 30 days before expiry
7. ⚠️ Enable Audit Logging: Track all TLS connections
8. ⚠️ Performance Test: Verify <100μs TLS overhead
9. ⚠️ Test Failure Modes: Invalid/expired/revoked certs
10. ⚠️ Document Runbook: TLS troubleshooting procedures

---

📞 Quick Commands

Check TLS Configuration

grep "TLS_ENABLED" .env
grep "TLS_ENABLED" docker-compose.yml

Validate Certificates

openssl x509 -in certs/server-cert.pem -text -noout
openssl x509 -in certs/ca/ca-cert.pem -text -noout
openssl verify -CAfile certs/ca/ca-cert.pem certs/server-cert.pem

Test TLS Connection (After Wave H2-H3)

grpcurl -insecure localhost:50051 list  # Should fail if TLS enforced
grpcurl -cert certs/client-cert.pem -key certs/client-key.pem \
  -cacert certs/ca/ca-cert.pem localhost:50051 list  # Should succeed

---

Last Updated: 2025-10-18 Next Wave: H2 (API Gateway TLS Initialization)