TLSPROXY

Table of Contents

• 1. Overview
• 2. Installation
• From Source
• Docker Image
• Precompiled Binaries
• Verifying Signatures
• 3. Configuration
• config.yaml Structure
• Backend Configuration (Backend Object)
  • SSORule Object
  • LocalOIDCServer Object
  • LocalOIDCClient Object
  • LocalOIDCRewriteRule Object
  • TrustedIssuer Object
• Identity Provider Configuration
• Group and Member Objects
  • Group Object
  • Member Object
• PKI Configuration (ConfigPKI)
• SSH Certificate Authority Configuration (ConfigSSHCertificateAuthority)
• Bandwidth Limit Configuration (BWLimit)
• WebSocket Configuration (WebSocketConfig)
• ECH Configuration (ECH Object)
• ForwardECH Configuration (BackendECH Object)
• 4. Usage
• 5. Common Use Cases
• 5.1. Basic HTTP/HTTPS Proxying
  • 5.1.1. HTTP Mode (HTTPS to HTTP)
  • 5.1.2. HTTPS Mode (HTTPS to HTTPS)
• 5.2. TCP Proxying
  • 5.2.1. TCP Mode (TLS to Plain TCP)
  • 5.2.2. TLSPASSTHROUGH Mode (TLS Passthrough)
• 5.3. SSH Proxying with tlsclient
• 5.4. Setting up an SSH Certificate Authority (CA)
• 5.5. Getting SSH Certificates
• 5.6. Setting up PKI (Public Key Infrastructure)
• 5.7. Serving Static Files
• 5.8. QUIC/HTTP3 Proxying
• 6. Advanced Topics
• 7. Support and Community

flowchart LR
  subgraph Incoming TLS Connections
    h1("web.example.com")
    h2("foo.example.com")
    h3("bar.example.com")
    h4(...)
  end
  prx(((TLSPROXY)))
  subgraph Backend Services
    be1(HTTP Server)
    be2(HTTPS Server)
    be3(IMAP, SMTP, SSH)
    be4(Any TCP, TLS, or QUIC Server)
  end
  h1-->prx
  h2-->prx
  h3-->prx
  h4-->prx
  prx-->be1
  prx-->be2
  prx-->be3
  prx-->be4

1. Overview

TLSPROXY is a versatile TLS termination proxy designed to secure various network services. It automatically handles TLS encryption using Let's Encrypt, allowing multiple services and server names to share the same port. Beyond TLS termination, TLSPROXY can function as a simple web server, a reverse proxy for HTTP(S) services, and offers robust user authentication and authorization features.

Key Features:

• Automatic TLS Certificates: Integrates with Let's Encrypt for automatic certificate acquisition using http-01 and tls-alpn-01 challenges.
• Flexible TLS Termination:
  • Terminates TLS and forwards data to TCP servers in plain text.
  • Terminates TLS and forwards data to TLS servers (encrypted in transit, proxy sees plain text).
  • Passes through raw TLS connections to backend TLS servers (proxy does not see plain text).
• QUIC and HTTP/3 Support: Terminates QUIC connections and forwards data to QUIC or TLS/TCP servers.
• Encrypted Client Hello (ECH): Enhances privacy by encrypting ClientHello messages.
• Static File Serving: Can serve static content directly from the local filesystem.
• PROXY Protocol Support: Integrates with the PROXY protocol for incoming TCP connections (not for QUIC or HTTP/3 backends).
• Client Authentication & Authorization: Supports TLS client authentication and authorization when the proxy terminates TLS connections.
• Built-in Certificate Authorities:
  • Manages client and backend server TLS certificates.
  • Issues SSH user certificates based on SSO credentials.
• User Authentication: Supports OpenID Connect, SAML, and Passkeys for HTTP and HTTPS connections. Can optionally issue JSON Web Tokens (JWTs) and run a local OpenID Connect server.
• Access Control: Implements access control based on IP addresses.
• Routing & Load Balancing: Routes requests based on Server Name Indication (SNI) with optional default routes and simple round-robin load balancing.
• ALPN Protocol Support: Supports any ALPN protocol in TLS, TLSPASSTHROUGH, QUIC, or TCP mode.
• OCSP Stapling & Verification: Includes OCSP stapling and certificate verification.
• Local TLS Certificates: Supports using locally stored TLS certificates.
• Hardware-backed Cryptographic Keys: Can use a Trusted Platform Module (TPM) for enhanced security of cryptographic keys.
• Port Sharing: Allows multiple server names to share the same IP address and port.

2. Installation

From Source

To install TLSPROXY from its source code, follow these steps:

git clone https://github.com/c2FmZQ/tlsproxy.git
cd tlsproxy
go generate ./...
go build -o tlsproxy

Docker Image

You can use the official Docker image from Docker Hub. Here's an example command:

docker run \
  --name=tlsproxy \
  --user=1000:1000 \
  --restart=always \
  --volume=${CONFIGDIR}:/config \
  --volume=${CACHEDIR}:/.cache \
  --publish=80:10080 \
  --publish=443:10443 \
  --env=TLSPROXY_PASSPHRASE="<passphrase>" \
  c2fmzq/tlsproxy:latest

The proxy reads the configuration from ${CONFIGDIR}/config.yaml.

:warning: The ${TLSPROXY_PASSPHRASE} environment variable is crucial as it's used to encrypt the TLS secrets.

Precompiled Binaries

Precompiled binaries for various platforms are available on the release page.

Verifying Signatures

It is highly recommended to verify the authenticity of downloaded binaries and container images.

Container Image:

To verify the authenticity of a container image, use cosign:

cosign verify \
  --certificate-identity-regexp='^https://github[.]com/c2FmZQ/tlsproxy/[.]github/workflows/release[.]yml' \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
  c2fmzq/tlsproxy:latest

Alternatively, if you have the public key:

cosign verify --key keys/cosign.pub c2fmzq/tlsproxy:latest

Release Binary:

To verify the authenticity of a release binary, first import the c2FmZQ-bot.pub key:

curl https://raw.githubusercontent.com/c2FmZQ/tlsproxy/main/keys/c2FmZQ-bot.pub | gpg --import

Then, verify the signature (e.g., for tlsproxy-linux-amd64):

gpg --verify tlsproxy-linux-amd64.sig tlsproxy-linux-amd64

3. Configuration

TLSPROXY is configured using a YAML file, typically named config.yaml. This file defines how the proxy behaves, including backend services, authentication methods, and security settings.

The examples directory contains full configuration files for various use cases.

config.yaml Structure

The main configuration options are:

• acceptTOS: (Required) Boolean. Indicates acceptance of the Let's Encrypt Terms of Service. Must be true for Let's Encrypt to function.
• email: (Optional) String. Your email address, used by Let's Encrypt for important notifications.
• httpAddr: (Optional) String. The address where the proxy listens for HTTP connections (e.g., ":80" or ":10080"). Essential for Let's Encrypt's http-01 challenge.
• tlsAddr: (Required) String. The address where the proxy listens for TLS connections (e.g., ":443" or ":10443").
• enableQUIC: (Optional) Boolean. Enables QUIC protocol support. Defaults to true if compiled with QUIC support.
• ech: (Optional) Object. Configures Encrypted Client Hello (ECH).
• acceptProxyHeaderFrom: (Optional) List of CIDRs. Enables PROXY protocol for connections from specified IP ranges.
• hwBacked: (Optional) Boolean. Enables hardware-backed cryptographic keys (e.g., with a TPM).
• cacheDir: (Optional) String. Directory for storing TLS certificates, OCSP responses, etc. Defaults to a system cache directory.
• defaultServerName: (Optional) String. Server name to use when SNI is not provided by the client.
• logFilter: (Optional) Object. Controls what gets logged (connections, requests, errors).
• groups: (Optional) List of Group objects. Defines user groups for access control.
• backends: (Required) List of Backend objects. Defines the services TLSPROXY will forward traffic to.
• oidc: (Optional) List of ConfigOIDC objects. Defines OpenID Connect identity providers.
• saml: (Optional) List of ConfigSAML objects. Defines SAML identity providers.
• passkey: (Optional) List of ConfigPasskey objects. Defines Passkey managers.
• pki: (Optional) List of ConfigPKI objects. Defines local Certificate Authorities.
• sshCertificateAuthorities: (Optional) List of ConfigSSHCertificateAuthority objects. Defines local SSH Certificate Authorities.
• tlsCertificates: (Optional) List of TLSCertificate objects. Specifies pre-existing TLS certificates to use.
• bwLimits: (Optional) List of BWLimit objects. Defines named bandwidth limit groups.
• webSockets: (Optional) List of WebSocketConfig objects. Defines WebSocket endpoints.

See the GoDoc for complete and up-to-date documentation.

Backend Configuration (Backend Object)

Each Backend object defines a service and its behavior:

• serverNames: (Required) List of strings. DNS names for this service.
• mode: (Required) String. Controls how the proxy communicates with the backend. Valid values include TCP, TLS, TLSPASSTHROUGH, QUIC, HTTP, HTTPS, LOCAL, CONSOLE.
• addresses: (Optional) List of strings. Backend server addresses (e.g., 192.168.1.10:80).
• documentRoot: (Optional) String. Directory for serving static files (only if addresses is empty).
• clientAuth: (Optional) Object. Configures TLS client authentication.
  • acl: (Optional) List of strings. Restricts client identities (email, subject, DNS, URI).
  • rootCAs: (Optional) List of strings. CA names or PEM-encoded certificates for client verification.
  • addClientCertHeader: (Optional) List of strings. Specifies which client certificate fields to add to X-Forwarded-Client-Cert header.
• sso: (Optional) Object. Configures Single Sign-On for the backend.
  • provider: String. Name of an OIDC or SAML provider.
  • rules: List of SSORule objects. Defines path-matching rules for SSO enforcement.
  • htmlMessage: String. HTML message displayed on permission denied screen (not escaped).
  • setUserIdHeader: Boolean. Sets x-tlsproxy-user-id header with user's email.
  • generateIdTokens: Boolean. Generates ID tokens for authenticated users.
  • localOIDCServer: Object. Configures a local OpenID Provider.
• exportJwks: (Optional) String. Path to export the proxy's JSON Web Key Set.
• alpnProtos: (Optional) List of strings. ALPN protocols supported by this backend.
• backendProto: (Optional) String. Protocol for forwarding HTTPS requests to the backend (e.g., http/1.1, h2, h3).
• insecureSkipVerify: (Optional) Boolean. Disables backend server TLS certificate verification (use with caution).
• forwardServerName: (Optional) String. ServerName to send in TLS handshake with backend.
• forwardRootCAs: (Optional) List of strings. CA names or PEM-encoded certificates for backend verification.
• forwardTimeout: (Optional) Duration. Connection timeout to backend servers.
• forwardHttpHeaders: (Optional) Map of strings. HTTP headers to add to forwarded requests.
• forwardECH: (Optional) Object. ECH parameters for connecting to the backend.
• pathOverrides: (Optional) List of PathOverride objects. Defines different backend parameters for specific path prefixes.
• proxyProtocolVersion: (Optional) String. Enables PROXY protocol on this backend (v1 or v2).
• sanitizePath: (Optional) Boolean. Sanitizes request path before forwarding (defaults to true).
• serverCloseEndsConnection: (Optional) Boolean. Closes TCP connection when server closes its end.
• clientCloseEndsConnection: (Optional) Boolean. Closes TCP connection when client closes its end.
• halfCloseTimeout: (Optional) Duration. Timeout for half-closed TCP connections.

SSORule Object

The SSORule