How to Configure TLS/HTTPS Termination in INFINI Gateway: A Complete Guide to Automatic Certificate Management

INFINI Gateway supports TLS/HTTPS termination through the tls configuration block in entry definitions, offering both automatic self-signed certificate generation and custom certificate file support.

INFINI Gateway acts as a high-performance reverse proxy for Elasticsearch and other backends, requiring secure HTTPS termination at the edge. This guide explains how to configure TLS/HTTPS termination in INFINI Gateway, including the automatic certificate management system that generates and stores self-signed certificates when custom files are not provided.

TLS Architecture and Implementation

Inbound TLS Termination (Entry Configuration)

TLS termination is handled within the entry point configuration (EntryConfig). When an entry starts in proxy/entry/entry.go (lines 261–447), the gateway checks this.config.TLSConfig.TLSEnabled to determine whether to wrap the listener with TLS.

If enabled, the gateway constructs a tls.Config with the following security defaults:

• Minimum TLS 1.2 (MinVersion: tls.VersionTLS12)
• Secure curves: tls.CurveP256, tls.X25519
• Cipher suites: ECDHE/ECDSA, ECDHE/RSA, and CHACHA20-POLY1305
• Session caching: LRU client session cache sized by TLSConfig.ClientSessionCacheSize

Outbound TLS for Upstream Connections

The same TLSConfig structure drives client-side TLS when proxying to upstream services. Modules such as proxy/output/http/http.go (line 352) and proxy/output/elastic/reverseproxy.go (lines 244–268) invoke api.SimpleGetTLSConfig(runner.TLSConfig) to propagate settings like TLSEnabled and TLSInsecureSkipVerify to the upstream connection.

TLS Configuration Reference

All TLS parameters are defined under the tls section of an entry or output definition. These fields map directly to the TLSConfig struct in common/entry.go:

• tls.enabled – Boolean flag to enable HTTPS termination.
• tls.cert_file – Path to a PEM-encoded certificate file (optional).
• tls.key_file – Path to the matching PEM-encoded private key (optional).
• tls.skip_insecure_verify – If true, disables client certificate chain verification (useful for self-signed certs).
• tls.default_domain – Server name used for SNI and auto-generated certificates; defaults to "localhost".
• tls.client_session_cache_size – Size of the client TLS session cache (default 0 disables caching).

Configuring HTTPS with Automatic Certificates

Auto-Generated Certificate Workflow

When tls.enabled is true but cert_file and key_file are omitted, INFINI Gateway automatically generates a private root CA and a leaf certificate signed by that CA. The implementation in proxy/entry/entry.go (lines 308–447) performs the following:

1. Root CA creation: Invokes util.GetRootCert to generate a self-signed root CA (stored once per process).
2. Leaf certificate generation: Calls util.CreateCert to produce a certificate for DefaultDomain (or "localhost").
3. File persistence: Writes the certificates to:
   • <data-dir>/certs/auto.cert (leaf certificate)
   • <data-dir>/certs/auto.key (leaf private key)
   • <data-dir>/certs/root.cert (root CA certificate)

The listener is then wrapped with tls.NewListener(ln, cfg) using this generated configuration.

Custom Certificate Files

For production environments, provide your own certificates by specifying absolute paths:

entry:
  - name: secure_gateway
    enabled: true
    router: default
    network:
      binding: 0.0.0.0:443
    tls:
      enabled: true
      cert_file: /etc/infini/gateway/server.crt
      key_file: /etc/infini/gateway/server.key
      skip_insecure_verify: false
      default_domain: gateway.example.com

Securing Upstream Connections

Apply the same tls block to output definitions to encrypt traffic between INFINI Gateway and backend services. The proxy/output/elastic/reverseproxy.go module (lines 244–268) translates these settings into the Elasticsearch client configuration.

output:
  - name: elasticsearch_backend
    type: elasticsearch
    network:
      address: "https://es-cluster.internal:9200"
    tls:
      enabled: true
      skip_insecure_verify: true  # Accept self-signed upstream certs

Key Source Files and Implementation Details

File	Purpose
proxy/entry/entry.go (lines 261–447)	Core TLS termination logic, certificate loading, and automatic generation workflow.
common/entry.go	EntryConfig struct definition exposing TLS fields to the configuration system.
proxy/output/http/http.go (line 352)	Client TLS configuration for HTTP proxy output modules.
proxy/output/elastic/reverseproxy.go (lines 244–268)	Application of TLS settings to Elasticsearch upstream connections.
docs/content.en/docs/references/entry.md	Official documentation for all TLS configuration parameters.

Summary

• Enable TLS termination by setting tls.enabled: true in any entry definition.
• Automatic certificate management generates self-signed root CA and leaf certificates stored in <data-dir>/certs/ when cert_file and key_file are omitted.
• Custom certificates are loaded by specifying absolute paths to PEM-encoded cert_file and key_file.
• Outbound TLS uses the same configuration structure to secure connections to Elasticsearch and HTTP backends.
• Security defaults enforce TLS 1.2+, modern cipher suites, and secure elliptic curves.

Frequently Asked Questions

Where does INFINI Gateway store automatically generated certificates?

When you enable TLS without specifying custom certificate files, INFINI Gateway stores the auto-generated certificates in the <data-dir>/certs/ directory. Specifically, the leaf certificate is saved as auto.cert, the private key as auto.key, and the self-signed root CA as root.cert. These files persist across restarts unless deleted.

Can I use Let's Encrypt certificates with INFINI Gateway?

Yes, INFINI Gateway accepts any valid PEM-encoded certificates, including those issued by Let's Encrypt. Configure the absolute paths to your Let's Encrypt certificate and key files using the tls.cert_file and tls.key_file parameters. The gateway does not include a built-in ACME client, so you must handle certificate renewal externally using tools like Certbot.

How do I troubleshoot TLS handshake errors?

Enable tls.skip_insecure_verify: true temporarily to bypass certificate validation and isolate whether the error stems from certificate trust issues. Check the gateway logs for specific TLS handshake failures, and verify that your certificate files are valid PEM format with matching private keys. For auto-generated certificates, ensure the <data-dir>/certs/ directory is writable and that the root CA is trusted by your clients.

Does INFINI Gateway support mutual TLS (mTLS)?

Currently, INFINI Gateway has limited support for mutual TLS. While the configuration structure includes placeholders for client certificate verification, the proxy/entry/entry.go implementation notes that optional client certificate verification is currently disabled in the code comments. You can still present client certificates to upstream servers for outbound mTLS, but inbound client certificate verification is not yet fully implemented.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}