git.stella-ops.org/docs/router/transports/tls.md

# TLS Transport

The TLS transport provides encrypted communication with optional mutual TLS (mTLS) authentication for secure cross-datacenter and external service communication.

## Overview

| Property | Value |
|----------|-------|
| Plugin Assembly | `StellaOps.Router.Transport.Tls.dll` |
| Transport Name | `tls` |
| Default Port | 5101 |
| Security | TLS 1.3, optional mTLS |
| Use Case | Cross-datacenter, external services, compliance-required environments |

## Configuration

### router.yaml (Gateway/Server)

```yaml
Router:
  Transport:
    Type: tls
    Tls:
      Host: "0.0.0.0"
      Port: 5101
      CertificatePath: /certs/server.pfx
      CertificatePassword: ${TLS_CERT_PASSWORD:-}
      RequireClientCertificate: true      # Enable mTLS
      AllowedClientCertificates:
        - /certs/trusted/client1.cer
        - /certs/trusted/client2.cer
      TlsProtocols: Tls13                 # TLS 1.3 only
      CheckCertificateRevocation: true
```

### microservice.yaml (Client)

```yaml
routers:
  - host: gateway.external.company.com
    port: 5101
    transportType: Tls
    priority: 1
    tls:
      clientCertificatePath: /certs/client.pfx
      clientCertificatePassword: ${CLIENT_CERT_PASSWORD:-}
      validateServerCertificate: true
      serverCertificateThumbprints:
        - "A1B2C3D4E5F6..."
```

### Environment Variables

```bash
ROUTER__TRANSPORT__TYPE=tls
ROUTER__TRANSPORT__TLS__PORT=5101
ROUTER__TRANSPORT__TLS__CERTIFICATEPATH=/certs/server.pfx
ROUTER__TRANSPORT__TLS__CERTIFICATEPASSWORD=secret
ROUTER__TRANSPORT__TLS__REQUIRECLIENTCERTIFICATE=true
```

## Options Reference

### Server Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `Host` | string | `0.0.0.0` | Bind address |
| `Port` | int | `5101` | TLS port number |
| `CertificatePath` | string | - | Path to server certificate (PFX/P12) |
| `CertificatePassword` | string | - | Password for certificate file |
| `RequireClientCertificate` | bool | `false` | Enable mutual TLS |
| `AllowedClientCertificates` | string[] | - | Paths to trusted client certs |
| `TlsProtocols` | TlsProtocols | `Tls12,Tls13` | Allowed TLS versions |
| `CheckCertificateRevocation` | bool | `true` | Check CRL/OCSP |
| `CipherSuites` | string[] | - | Allowed cipher suites (TLS 1.3) |

### Client Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `ClientCertificatePath` | string | - | Path to client certificate (PFX/P12) |
| `ClientCertificatePassword` | string | - | Password for client certificate |
| `ValidateServerCertificate` | bool | `true` | Validate server certificate |
| `ServerCertificateThumbprints` | string[] | - | Pinned server cert thumbprints |
| `AllowUntrustedCertificates` | bool | `false` | Allow self-signed certs (dev only) |

## Mutual TLS (mTLS)

For zero-trust environments, enable mutual TLS authentication:

```
┌──────────────────┐                    ┌──────────────────┐
│   Microservice   │                    │     Gateway      │
│                  │                    │                  │
│  Client Cert     │◄───── TLS ────────►│  Server Cert     │
│  (identity)      │    Handshake       │  (identity)      │
│                  │                    │                  │
│  Validates:      │                    │  Validates:      │
│  - Server cert   │                    │  - Client cert   │
│  - Thumbprint    │                    │  - Allowlist     │
└──────────────────┘                    └──────────────────┘
```

### Certificate Requirements

**Server Certificate:**
- Extended Key Usage: `Server Authentication (1.3.6.1.5.5.7.3.1)`
- Subject Alternative Name: Include all DNS names clients will connect to

**Client Certificate:**
- Extended Key Usage: `Client Authentication (1.3.6.1.5.5.7.3.2)`
- Common Name or SAN identifying the service

## Performance Characteristics

| Metric | Typical Value |
|--------|---------------|
| Latency (p50) | < 2ms |
| Latency (p99) | < 10ms |
| Throughput | 80,000+ rps |
| Memory per connection | ~8KB |

*TLS 1.3 with session resumption on 10Gbps network*

## Certificate Management

### Generating Certificates

```bash
# Generate CA
openssl genrsa -out ca.key 4096
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt \
  -subj "/CN=StellaOps Internal CA"

# Generate server certificate
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr \
  -subj "/CN=gateway.internal" \
  -addext "subjectAltName=DNS:gateway.internal,DNS:localhost"
openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out server.crt \
  -extfile <(echo "subjectAltName=DNS:gateway.internal,DNS:localhost")

# Package as PFX
openssl pkcs12 -export -out server.pfx -inkey server.key -in server.crt \
  -certfile ca.crt -passout pass:changeit
```

### Certificate Rotation

1. Generate new certificate before expiry
2. Update `CertificatePath` in configuration
3. Restart Gateway (no connection interruption with graceful shutdown)
4. Update client thumbprint pins if using certificate pinning

## Air-Gap Deployment

For offline environments:

1. Pre-provision all certificates
2. Disable CRL/OCSP checks: `CheckCertificateRevocation: false`
3. Use certificate pinning instead of chain validation

```yaml
Router:
  Transport:
    Type: tls
    Tls:
      CheckCertificateRevocation: false
      AllowedClientCertificates:
        - /certs/trusted/client1.cer
```

## Troubleshooting

### Certificate Validation Failed

```
Error: The remote certificate is invalid according to the validation procedure
```

1. Verify certificate is not expired: `openssl x509 -in cert.pem -noout -dates`
2. Check certificate chain is complete
3. Verify CA is trusted by the system or explicitly configured

### mTLS Handshake Failed

```
Error: The client certificate is not provided
```

1. Ensure client certificate is configured with correct path
2. Verify certificate has Client Authentication EKU
3. Check certificate is in Gateway's allowlist

### TLS Protocol Mismatch

```
Error: A call to SSPI failed, TLS version mismatch
```

1. Ensure both sides support compatible TLS versions
2. Update `TlsProtocols` to include common version
3. TLS 1.3 recommended for new deployments

## Compliance

The TLS transport supports compliance requirements:

| Standard | Configuration |
|----------|---------------|
| PCI-DSS | TLS 1.2+, strong ciphers, certificate validation |
| HIPAA | TLS 1.2+, mTLS for service-to-service |
| FedRAMP | TLS 1.3, FIPS-validated crypto modules |

For FIPS mode, ensure .NET is configured for FIPS compliance and use FIPS-approved cipher suites.

## See Also

- [TCP Transport](./tcp.md) - Unencrypted variant for internal use
- [Transport Overview](./README.md)
- [Security Hardening Guide](../../17_SECURITY_HARDENING_GUIDE.md)