TLSPROXY

<details> <summary>Table of Contents</summary>

• 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

</details>

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: (Optio