diff --git a/docs/getting-started/flags.md b/docs/getting-started/flags.md index 6446d886d1..07c4e6489b 100644 --- a/docs/getting-started/flags.md +++ b/docs/getting-started/flags.md @@ -88,7 +88,7 @@ metrics endpoints, and profiling. ### Landlock -See [Security & TLS Configuration]({{< ref "tls.md" >}}) for details on +See [Security & TLS Configuration]({{< ref "general.md" >}}) for details on Landlock sandboxing. | Flag | Description | Availability | @@ -118,7 +118,7 @@ See [PROXY Protocol]({{< ref "proxy-protocol.md" >}}) for details on modes and T | `--target-status URL` | Address to target for status checking downstream healthchecks. Defaults to TCP healthcheck if not passed. | | `--proxy-protocol` | Enable PROXY protocol v2 with connection info only (equivalent to `--proxy-protocol-mode=conn`). | | `--proxy-protocol-mode MODE` | PROXY protocol v2 mode: `conn`, `tls`, or `tls-full`. Mutually exclusive with `--proxy-protocol`. | -| `--unsafe-target` | Do not limit target to localhost, `127.0.0.1`, `[::1]`, or UNIX sockets. See [Security]({{< ref "tls.md" >}}). | +| `--unsafe-target` | Do not limit target to localhost, `127.0.0.1`, `[::1]`, or UNIX sockets. See [Security]({{< ref "general.md" >}}). | ### Access Control @@ -172,7 +172,7 @@ See [Socket Activation]({{< ref "socket-activation.md" >}}) for `systemd:NAME` a | Flag | Description | |------|-------------| -| `--unsafe-listen` | Do not limit listen to localhost, `127.0.0.1`, `[::1]`, or UNIX sockets. See [Security]({{< ref "tls.md" >}}). | +| `--unsafe-listen` | Do not limit listen to localhost, `127.0.0.1`, `[::1]`, or UNIX sockets. See [Security]({{< ref "general.md" >}}). | | `--override-server-name NAME` | Override the server name used for hostname verification. | | `--proxy URL` | Connect to target over given proxy (HTTP CONNECT or SOCKS5). Must be a proxy URL. | | `--disable-authentication` | Disable client authentication, no certificate will be provided to the server. | diff --git a/docs/security/general.md b/docs/security/general.md new file mode 100644 index 0000000000..5b77489fbe --- /dev/null +++ b/docs/security/general.md @@ -0,0 +1,135 @@ +--- +title: Landlock & TLS +description: Landlock sandboxing, TLS protocol settings, cipher suites, address restrictions. +weight: 10 +--- + +An overview of Ghostunnel's TLS settings, and some info on Landlock sandboxing. + +## TLS Configuration + +Ghostunnel enforces a minimum TLS version of **TLS 1.2**. Earlier versions are +not supported. TLS 1.3 is supported and will be negotiated when both sides +support it. + +### Cipher Suites + +The following cipher suites are enabled by default, in order of preference: + +**AES-GCM:** +- `TLS_AES_128_GCM_SHA256` (TLS 1.3) +- `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256` +- `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` +- `TLS_AES_256_GCM_SHA384` (TLS 1.3) +- `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384` +- `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` + +**ChaCha20-Poly1305:** +- `TLS_CHACHA20_POLY1305_SHA256` (TLS 1.3) +- `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305` +- `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305` + +All suites use authenticated encryption (AEAD). CBC-mode ciphers are not +enabled. ECDSA suites are listed before RSA to prefer ECDSA when both +certificate types are available. + +To check which cipher suite and protocol version were negotiated for a +connection: + +```bash +openssl s_client -connect localhost:8443 \ + -cert client-cert.pem -key client-key.pem -CAfile cacert.pem \ + /dev/null | grep -E 'Protocol|Cipher' +``` + +In TLS 1.3, cipher suite selection is handled by Go's [`crypto/tls`][crypto-tls] +and cannot be configured by the application. The TLS 1.3 suites listed above are always +available when TLS 1.3 is negotiated. The configurable cipher suite list only +affects TLS 1.2 connections. + +### Curve Preferences + +In server mode, key exchange prefers the following elliptic curves: + +1. **X25519**: fast, constant-time, widely supported +2. **P-256 (secp256r1)**: hardware-accelerated on most platforms + +### Client Authentication + +In server mode, Ghostunnel requires and verifies client certificates by +default (`RequireAndVerifyClientCert`). This can be disabled with +`--disable-authentication`, in which case no client certificate is requested. + +The status port (`--status`) is optional and does not require client +certificates. It is typically consumed by monitoring systems that may not +have client certs. Like other addresses, it defaults to localhost and is not +exposed to the network unless explicitly configured otherwise. + +## Address Restrictions + +Listen and target addresses are restricted to localhost and UNIX sockets by +default, to prevent accidental exposure of plaintext traffic. + +### Server mode + +The `--target` address must be one of: +- `localhost:PORT` +- `127.0.0.1:PORT` +- `[::1]:PORT` +- `unix:PATH` + +To forward to a remote host, pass `--unsafe-target`. The connection between +Ghostunnel and the backend is unencrypted, so exposing it beyond localhost +risks leaking plaintext traffic. + +### Client mode + +The `--listen` address must be one of: +- `localhost:PORT` +- `127.0.0.1:PORT` +- `[::1]:PORT` +- `unix:PATH` +- `systemd:NAME` +- `launchd:NAME` + +To accept connections from remote hosts, pass `--unsafe-listen`. The listen +side of client mode accepts plaintext connections, so exposing it beyond +localhost risks unauthorized access to the proxied service. + +## Landlock sandboxing + +*Available since v1.8.0. Enabled by default since v1.9.0.* + +On Linux, Ghostunnel uses [Landlock][landlock] to restrict its own process +privileges after startup. Landlock is a kernel-level access control mechanism +that limits which files and network ports a process can access. + +### How It Works + +After parsing flags and loading certificates, Ghostunnel builds a minimal set +of Landlock rules based on the flags it was given: + +- **File access**: Read-only access to certificate files, CA bundles, and OPA + policy bundles (and their parent directories, to support file rotation). + Read-write access to `/dev`, `/var/run`, `/tmp`, `/proc` for syslog and temp files. +- **Network access**: Bind access for `--listen` and `--status` ports. Connect + access for `--target`, `--metrics-graphite`, `--metrics-url`, and SPIFFE + Workload API ports. DNS (TCP/53) is always allowed. + +### Best-Effort Mode + +Landlock is applied in best-effort mode. If the kernel does not support +Landlock (network rules require Linux 6.7+), Ghostunnel logs a warning and +continues without sandboxing. + +### Disabling Landlock + +*Available since v1.9.0.* + +Landlock can be disabled with `--disable-landlock` if it causes issues with +your deployment. This is not recommended. Landlock is also automatically +disabled when PKCS#11 is in use, since PKCS#11 modules are opaque shared +libraries that may require access to arbitrary files and sockets. + +[crypto-tls]: https://pkg.go.dev/crypto/tls +[landlock]: https://docs.kernel.org/userspace-api/landlock.html