STUNNEL(8)


NAME
stunnel - SSL encryption wrapper for standard network daemons

SYNTAX

inetd mode
stunnel daemon [parameters...]
stunnel [address:]port daemon [parameters...]

daemon mode
stunnel @hostname:port
stunnel [address:]port @hostname:port

DESCRIPTION
The stunnel program is designed to work as SSL encryption wrapper between remote client and local (inetd-startable) or remote server. The concept is that having non-SSL aware daemons running on your system you can easily setup them to communicate with clients over secure SSL channel.
stunnel can be used to add SSL functionality to commonly used inetd daemons like POP-2, POP-3 and IMAP servers without any changes in the programs' code. The same applies for standalone daemons like NNTP and SMTP. It cannot be used for FTP daemon because of the nature of FTP protocol which utilizes multiple ports for data transfers. There are available SSL enabled versions of FTP and telnet daemons, however.
stunnel is based on SSLeay, free implementation of SSL protocol developed by Eric Young <eay@cryptsoft.com> and Tim Hudson <tjh@cryptsoft.com>.

USAGE
stunnel can work in two modes: inetd or standalone, it can also perform two types of tunneling: local and remote. This gives four combinations of the command line, covered above in SYNTAX section. All are described below.

INETD MODE

Wrapping other inetd daemon
In order to wrap particular inetd service you will need to change inetd configuration file, usually /etc/inetd.conf. Assume that you have the following line starting POP-3 server: 
pop-3  stream  tcp  nowait  root  /usr/sbin/qpopper  qpopper -s

To run POP-3 server with SSL support add the following line to
the /etc/inetd.conf:

spop3  stream  tcp  nowait  root  /usr/sbin/stunnel  qpopper -s

INETD MODE

Wrapping remote server
Wrapping standalone servers is done by supplying the server's hostname and listening port in the command line, starting with '@' character: 
pop-3  stream  tcp  nowait  root /usr/sbin/stunnel  @hostname:port
The hostname parameter can be given either as IP address or canonical name. It can be localhost or any remote machine of course. The port can be either port number or service name from /etc/services file. Following example shows how to set up a wrapper for a news server: 
snews  stream  tcp  nowait  root /usr/sbin/stunnel  @news.company.com:nntp

STANDALONE MODE

Wrapping inetd daemons
In standalone mode stunnel is started from system boot files and accepting connections from remote clients. You can still wrap only inetd daemons. The syntax is: 
[address:]port daemon [parameters...]
The last parameters are the daemon to wrap and its parameters. The port parameter is port stunnel will listed on. On systems with multiple interfaces you should specify address of the interface stunnel will listen on. The default is to listen on all available interfaces.

STANDALONE MODE

Wrapping remote server
In this mode stunnel will run as standalone daemon listening on given port and tunneling all incoming connections to a remote server. The syntax is: 
[address:]port @hostname:port
The hostname parameter is described in section INETD MODE, subsection Wrapping remote servers. The port and optional address parameters are described above, in section about wrapping inetd daemons in standalone mode.

COMMON SSL PORTS
You will also need definitions of SSL services in your /etc/services file. Some commonly used SSL services are listed below: 
https      443/tcp        # HTTP over SSL
ssmtp      465/tcp        # SMTP over SSL
snews      563/tcp        # NNTP over SSL
ssl-ldap   636/tcp        # LDAP over SSL
simap      993/tcp        # IMAP over SSL
spop3      995/tcp        # POP-3 over SSL

CERTIFICATES
Each SSL enabled daemon needs to present a valid X.509 certificate to the peer. It also needs a private key to decrypt the incoming data. The easiest way to obtain a certificate and a key is to generate the with free SSLeay package. You can find more information on certificates generation on pages listed below.
When starting a daemon stunnel will try to load the certificate and key from the same file, whose name is the daemon's name with .pem extension. For example, with the above example of inetd service, stunnel will look for file qpopper.pem. When tunelling connections to remote servers, stunnel will look for file port.pem, e.g. nntp.pem. Default directory for certificate files is /usr/local/ssl/certs.
Two things are important when generating certificate-key pair for stunnel. The private key cannot be encrypted, because the server has no way to obtain password from the user. To produce an unencrypted key add -nodes option when running req command from SSLeay kit.
Order of contents of the .pem file is also important. It should contain unencrypted private key first, then a signed certificate (not certificate request). There should be also empty lines after certificate and private key. Plaintext certificate information appended on the top of generated certificate should be discarded. So the file should look like this: 
-----BEGIN RSA PRIVATE KEY-----
[encoded key]
-----END RSA PRIVATE KEY-----
[empty line]
-----BEGIN CERTIFICATE-----
[encoded certificate]
-----END CERTIFICATE-----
[empty line]

LIMITATIONS
stunnel ignores any client certificates presented by the peer, that could be used for authentication by underlying daemons.

SEE ALSO
tcpd (8), inetd (8)
http://www.psy.uq.oz.au/~ftp/Crypto/ SSLeay FAQ
http://www.camb.opengroup.org/RI/www/prism/wwwj/ overview of SSL certification using SSLeay package

AUTHORS
Michal Trojnara <mtrojnar@ddc.daewoo.com.pl>
Adam Hernik <adas@infocentrum.com>
Pawel Krawczyk <kravietz@ceti.com.pl>
" last updated 20.05.1998