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

> Learn to configure TLS/HTTPS termination in INFINI Gateway. This guide covers automatic certificate management and custom certificate support for secure API gateway access.

- Repository: [INFINI Labs/gateway](https://github.com/infinilabs/gateway)
- Tags: how-to-guide
- Published: 2026-03-04

---

**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`](https://github.com/infinilabs/gateway/blob/main/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`](https://github.com/infinilabs/gateway/blob/main/proxy/output/http/http.go) (line 352) and [`proxy/output/elastic/reverseproxy.go`](https://github.com/infinilabs/gateway/blob/main/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`](https://github.com/infinilabs/gateway/blob/main/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`](https://github.com/infinilabs/gateway/blob/main/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:

```yaml
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`](https://github.com/infinilabs/gateway/blob/main/proxy/output/elastic/reverseproxy.go) module (lines 244–268) translates these settings into the Elasticsearch client configuration.

```yaml
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`](https://github.com/infinilabs/gateway/blob/main/proxy/entry/entry.go) (lines 261–447) | Core TLS termination logic, certificate loading, and automatic generation workflow. |
| [`common/entry.go`](https://github.com/infinilabs/gateway/blob/main/common/entry.go) | `EntryConfig` struct definition exposing TLS fields to the configuration system. |
| [`proxy/output/http/http.go`](https://github.com/infinilabs/gateway/blob/main/proxy/output/http/http.go) (line 352) | Client TLS configuration for HTTP proxy output modules. |
| [`proxy/output/elastic/reverseproxy.go`](https://github.com/infinilabs/gateway/blob/main/proxy/output/elastic/reverseproxy.go) (lines 244–268) | Application of TLS settings to Elasticsearch upstream connections. |
| [`docs/content.en/docs/references/entry.md`](https://github.com/infinilabs/gateway/blob/main/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`](https://github.com/infinilabs/gateway/blob/main/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.