Files

StellaOps Bot e6c47c8f50 save progress

2025-12-28 23:49:56 +02:00

6.9 KiB

Raw Blame History

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)

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)

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

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

# 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

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

Air-Gap Deployment

For offline environments:

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

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

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

mTLS Handshake Failed

Error: The client certificate is not provided

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

TLS Protocol Mismatch

Error: A call to SSPI failed, TLS version mismatch

Ensure both sides support compatible TLS versions
Update TlsProtocols to include common version
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.

6.9 KiB Raw Blame History