Skip to main content
Transport Layer Security (TLS) ensures secure communication between clients, TrustGate, and upstream services. TrustGate supports two types of TLS configurations:
  • Server-Side TLS: Secures incoming connections to TrustGate.
  • Client-Side TLS: Secures outgoing connections from TrustGate to upstream services.
This guide details the configuration of both server-side and client-side TLS within TrustGate.

​
Server-Side TLS

Server-side TLS is configured using environment variables. This configuration secures incoming connections to the TrustGate proxy server. TLS settings are loaded once at proxy startup.

​
Environment Variables Configuration

Add the following variables to your .env file: 
# TLS Configuration
TLS_DISABLED=false                    # Set to true to disable TLS entirely
TLS_ENABLE_MTLS=true                  # Enable mutual TLS (mTLS)
TLS_DISABLE_SYSTEM_CA_POOL=false      # Disable system CA pool if true
TLS_CA_CERT=/path/to/ca.pem           # Path to CA certificate
TLS_KEYS_PUBLIC_KEY=/path/to/cert.pem # Path to public certificate
TLS_KEYS_PRIVATE_KEY=/path/to/key.pem # Path to private key
TLS_CIPHER_SUITES=4865,4866,4867      # Comma-separated cipher suite IDs
TLS_CURVE_PREFERENCES=23,24,25        # Comma-separated curve preference IDs
TLS_MIN_VERSION=TLS12                 # Minimum TLS version
TLS_MAX_VERSION=TLS13                 # Maximum TLS version
TLS_CERTS_BASE_PATH=/tmp/certs        # Base path for certificates

​
Configuration Parameters

  • disabled: Set to true to disable TLS entirely.
  • enable_mtls: Enables mutual TLS (mTLS) to require client certificates for authentication.
  • disable_system_ca_pool: If true, disables the system certificate authority (CA) pool.
  • ca_cert: Absolute path to the CA certificate file used to verify client certificates.
  • keys.public_key: Absolute path to the server’s public certificate file.
  • keys.private_key: Absolute path to the server’s private key file.
  • cipher_suites: List of cipher suite IDs supported (e.g., 4865 corresponds to TLS_AES_128_GCM_SHA256).
  • curve_preferences: List of elliptic curve IDs used for ECDHE key exchange (e.g., 23 = secp256r1).
  • min_version: Minimum supported TLS version (TLS12 or TLS13).
  • max_version: Maximum supported TLS version (TLS12 or `TLS13_
Note: All certificate and key paths must be absolute. Place certificates and keys in the certs/ directory within your deployment.

​
Client-Side TLS

Client-side TLS settings in TrustGate are host-specific, allowing you to define distinct TLS configurations for each upstream host. This provides flexibility to tailor certificates, cipher suites, and security parameters based on individual service requirements. In the client_tls section of the gateway configuration, each entry is keyed by the upstream host name (e.g., localhost). This allows different upstream services to have their own:
  • CA certificates
  • Client certificates and private keys (for mutual TLS)
  • Cipher suites
  • Curve preferences
  • TLS version ranges

​
Example Configuration (Gateway Creation)

{
  "name": "Gateway",
  "client_tls": {
    "localhost": {
      "allow_insecure_connections": false,
      "ca_cert": "certs/ca.pem",
      "client_certs": {
        "certificate": "certs/client.pem",
        "private_key": "certs/client.key"
      },
      "cipher_suites": [
        4865,
        4866,
        4867
      ],
      "curve_preferences": [
        23,
        24,
        25
      ],
      "disable_system_ca_pool": false,
      "min_version": "TLS12",
      "max_version": "TLS13"
    }
  }
}
In this example:
  • The TLS settings apply only to outbound connections targeting localhost.
  • Each upstream service you interact with (e.g., api.example.com, service.internal) can have its own unique TLS configuration.
This design ensures fine-grained control over security settings per upstream, enhancing flexibility and compliance with differing service requirements.

​
Configuration Parameters

  • allow_insecure_connections: Set to true to allow non-TLS connections to upstream services. Defaults to false for secure communication.
  • ca_cert: Absolute path to the CA certificate file used to verify upstream service certificates.
  • client_certs.certificate: Absolute path to the client certificate for mutual TLS authentication with upstream services.
  • client_certs.private_key: Absolute path to the private key associated with the client certificate.
  • cipher_suites: List of supported cipher suite IDs (e.g., 4865, 4866).
  • curve_preferences: List of elliptic curve IDs used for ECDHE key exchange (e.g., 23, 24).
  • disable_system_ca_pool: If true, disables use of the system CA pool for upstream certificate verification.
  • min_version: Minimum supported TLS version (TLS12 or TLS13).
  • max_version: Maximum supported TLS version (TLS12 or TLS13).
Note: All certificate and key paths must be absolute. Place certificates and keys in the certs/ directory within your deployment.

​
Certificate Management

  • Directory Structure: Store all certificates and keys in the certs/ directory at the root of your deployment.
  • Absolute Paths: Ensure all configuration entries for certificates and keys use absolute paths.

​
Best Practices

  • Use TLS 1.2 or higher for all communications.
  • Enable mutual TLS (mTLS) where possible for enhanced security.
  • Regularly rotate certificates and keys to maintain strong security posture.