TLS

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 in the config/config.yaml file. This configuration secures incoming connections to the TrustGate proxy server. TLS settings are loaded once at proxy startup.

​

Example Configuration (config/config.yaml)

tls:
  disabled: false
  enable_mtls: true
  disable_system_ca_pool: false
  ca_cert: ${TLS_CA_CERT}
  keys:
    public_key: ${TLS_KEYS_PUBLIC_KEY}
    private_key: ${TLS_KEYS_PRIVATE_KEY}
  cipher_suites:
    - 4865
    - 4866
    - 4867
  curve_preferences:
    - 23
    - 24
    - 25
  min_version: TLS12
  max_version: TLS13

​

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",
  "subdomain": "{{gateway_subdomain}}",
  "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.