stunnel – an SSL encryption wrapper

The stunnel program is designed to work as an SSL encryption wrapper between remote client and local (inetd-startable) or remote server. It can be used to add SSL functionality to commonly used inetd daemons like POP2, POP3, and IMAP servers without any changes in the programs’ code. Stunnel uses the OpenSSL library for cryptography, so it supports whatever cryptographic algorithms are compiled into the library.

Stunnel can benefit from FIPS 140-2 validation of the OpenSSL FIPS Object Module, as long as the building process meets its Security Policy . A scanned FIPS 140-2 Validation Certificate document is available for download on the NIST web page . The Windows binary installer is compiled with FIPS 140-2 support. The FIPS mode of operation is no longer enabled by default since stunnel 5.00.

stunnel Features

Portability (Threading Models)

• PTHREAD (Posix)
• FORK (traditional Unix)
• UCONTEXT (userlevel)
• WIN32

Performance and Scalability

• Load sharing among multiple backend servers
• External session cache (for clusters)
• Compression (for limited bandwidth)

Support for OpenSSL Security Features

• Certificate-based access control
• CRL and OCSP certificate revocation
• SNI (Server Name Indication) support for name-based virtual servers
• PFS (Perfect Forward Secrecy) with DH and ECDH key agreement
• FIPS mode (for compliance)
• Configuration of hardware engines

Features Specific to Unix Platform

• Local mode (running services designed for inetd) with optional pseudo-terminal allocation
• chroot (additional security)
• setuid/setgid (additional security)
• Logging to syslog
• Libwrap (TCP Wrappers) access control
• Transparent proxy on selected platforms
• EGD (Entropy Gathering Daemon) client
• Unix socket support

Features Specific to Windows Platform

• GUI
• Saving cached peer certificate chains to files
• Windows service mode

Other Features

• Redirection of SSL client connections on authentication failures
• IPv6 support
• Protocol negotiation for cifs, connect, imap, nntp, pgsql, pop3, proxy, and smtp
• Delayed resolver (for dialup connections and remote hosts with dynamic IP addresses)
• Graceful configuration file reloading
• Graceful log file reopening
• Ident access control

Running stunnel in inetd mode

(This does not apply to Windows machines)

You can invoke stunnel from inetd . Inetd is the unix ‘super server’ that allows you to launch a program (for example the telnet daemon) whenever a connection is established to a specified port.

Lets say we want to have stunnel listen on our machine on port 9999 to support a fictitious protocol called foobar . We’d add the following line to the file /etc/inetd.conf

foobar stream tcp nowait root  /usr/local/bin/stunnel stunnel

(if you installed stunnel in a different location than /usr/local/bin , use that path instead) and add the following line to /etc/services :

foobar	9999/tcp		# The foobar service

You must then send the inetd process a SIGHUP . Find the process id for the inetd process by one of the following commands:

ps -ef | grep inetd
ps -axj | grep inetd

and then type kill -HUP _ process_id _ .

You may be able to use killall -HUP inetd on some Unix versions (for example linux, *BSD, IRIX) to save yourself from looking up the process id.

Note: Some unix variants have a killall command that kills all processes on the machine. That’s not the killall you’re looking for…

The /usr/local/etc/stunnel.conf configuration file for inetd mode must not include a [service] line. For example:

cert = ...
...

# Do not include
#  [someservicename]
connect = logging:syslogs

If you have a [service] line, then stunnel will fork into the background to do it’s job, and will not work with inetd.

Note: Running in daemon mode is much preferred to running in inetd mode. Why?

• SSL needs to be initialized for every connection.
• No session cache is possible.
• inetd mode requires forking, which causes additional overhead. Daemon mode will not fork if you have stunnel compiled with threads.

Running stunnel in daemon mode

Lets say we want to have stunnel listen on our machine on port 9999 to support a fictitious protocol called foobar .

First we’d add the following line to /etc/services :

foobar       9999/tcp                # The foobar service

Stunnel configuration file needs at least the section name and accept option. For example:

cert = ...
...

[foobar service]
accept = foobar
...

Running stunnel with TCP wrappers

You do not need to use the tcpd binary to wrap stunnel (although you could). You can can compile in support for TCP wrappers when you compile stunnel itself.

The configure program should be able to determine if the libwrap library ( -lwrap ) and headers are available in standard locations.

You must put entries in /etc/hosts.allow to specify which machines should be allowed access to stunnel . These are of the form:

service1: goodhost.example.com .trusteddomain.example.com
service2: otherhost.example.com 192.168.0.1

Service name is the name of service that was put in square brackets in stunnel.conf .

Stopping stunnel

If stunnel is running in daemon mode, you can stop it simply by kill ing it. Stunnel accepts the following signals, all of which tell it to log the signal and terminate: TERM, QUIT, INT .

Running stunnel as a service under windows

Stunnel can run as a native service under Windows. To install stunnel as a service execute:

stunnel -install

in the directory where stunnel.conf is available.

Stunnel is a free software authored by Michal Trojnara. Although distributed under GNU GPL version 2 or later with OpenSSL exception, stunnel is not a community project. Developers retain the copyright of the source code !

Source && Download