Stunnel is a free, open-source proxy that adds TLS encryption to existing clients and servers without changing their code. It runs on Windows, Linux, macOS and other Unix-like systems. Administrators define tunnels, authentication and routing through configuration files.
Two tunnel directions
In server mode, Stunnel accepts encrypted connections, decrypts the traffic and forwards it to an application’s listening address. The application continues handling its ordinary plaintext protocol. The backend can run on the same computer or another host.
Client mode reverses that arrangement. A local application connects to Stunnel’s plaintext listener, and Stunnel establishes a TLS connection to the remote server. Binding that listener to loopback keeps the plaintext endpoint local. A certificate-based server presents its certificate chain and proves possession of its private key. The client can validate the server through trust and identity settings.
Stunnel handles TCP streams through TLS and UDP datagrams through DTLS. Both ends need compatible transport configurations. It does not convert TCP applications into UDP applications. Protocols that negotiate additional dynamic connections, such as FTP, require more than a generic single tunnel.
Service definitions
A configuration file contains global options followed by named service sections. Each section defines its listening address, destination and service-specific settings. One Stunnel process can run several independent tunnels, and an include directory supplies configuration fragments in alphabetical order.
Destinations can use host addresses and ports, with IPv4 and IPv6 support. Unix systems also support Unix-domain sockets. For legacy integrations, Stunnel can launch an inetd-style local program instead of connecting to a network service. It can also accept a socket from an external inetd-style launcher.
Trust models
Stunnel separates certificate-chain validation from identity checks. A client can trust selected certificate authorities while also checking that the server certificate identifies the expected hostname or IP address. Server Name Indication selects a virtual server during the handshake; it does not authenticate that server.
| Authentication method | Credentials and checks |
|---|---|
| Certificate authority trust | A trust file, directory or external store supplies accepted authorities. Stunnel validates the peer’s certificate chain. |
| Certificate pinning | A local trust file holds specific leaf certificates. Stunnel accepts a matching peer certificate. |
| Pre-shared keys | An identity-and-secret file authenticates peers without certificates. Separate client identities can use separate secrets. |
Mutual TLS adds client-certificate authentication to server authentication. Stunnel can also check certificate revocation lists or query OCSP responders. Pinning requires clients to receive replacement pins when the server changes its certificate.
Protocol negotiation
Some services begin with plaintext negotiation before enabling TLS. Stunnel’s protocol handlers perform that exchange for protocols including SMTP, IMAP, POP3, LDAP and PostgreSQL. A dedicated port that expects TLS immediately uses the direct tunnel instead.
The HTTP CONNECT handler reaches a final TLS server through an HTTP proxy. Its settings distinguish the proxy address from the final destination and accept proxy credentials when necessary. Stunnel can also carry SOCKS traffic inside TLS.
Backend selection
A service can name several backend destinations. Round-robin routing distributes connections among them, while priority routing tries them in configuration order. Delayed DNS resolution looks up destinations when connections arrive and uses priority failover.
Server-side SNI routes names to secondary service definitions, which can select different certificates and backends. A backend that understands the HAProxy PROXY protocol can also receive the original client’s address.
Cryptographic policy
Administrators can set minimum and maximum TLS protocols, cipher policies, curves and security levels. The available choices depend on the OpenSSL library and build configuration. Providers or engines can supply external trust stores and hardware-backed private keys through resource identifiers.
Session resumption reuses previous TLS session information on repeat connections. Stunnel offers session tickets, an internal session cache and an external cache for legacy clustered deployments.
Service operations
Stunnel runs in the foreground or background on Unix and provides service and graphical modes on Windows. Startup checks configuration syntax, certificates, keys and listening sockets. Logging can target a file, Unix syslog or standard error, with selectable detail levels and connection identifiers.
Configuration reloads apply service and certificate changes. Some global settings require a restart. Separate controls reopen log files after rotation or report active Unix connections. Unix deployments can drop user and group privileges and restrict filesystem access through a chroot directory.
