save progress
This commit is contained in:
StellaOps Bot
223
docs/router/transports/tls.md
Normal file
223
docs/router/transports/tls.md
Normal file
@@ -0,0 +1,223 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user