...making Linux just a little more fun!
One of Stunnel's most common uses is encrypting communications between POP or IMAP mail servers and e-mail clients. Both of these protocols require users to authenticate themselves with a username and a password. In the majority of cases, these usernames and passwords are the same ones as they would use for logging into the machine locally or remotely via SSH. Without using Stunnel to encrypt this data, anyone intercepting the transmission could now log into your server and gain elevated privileges much easier than a local exploit would require.
The source code is released under the GNU General Public License and, as such, is freely available for download and installation. The current version (which at time of going to press was 4.05) can be downloaded from ftp://stunnel.mirt.net/stunnel/. To compile and install Stunnel, download the source code tarball from here and then execute the following commands:
$ tar zxf stunnel-4.XX.tar.gz $ cd stunnel-4.XX $ ./configure $ make $ make install (as root)
stunnel.pem). Some pre-built binary packages may include a certificate-key pair, some may generate one as part of the installation procedure and others may leave it up to the user to generate one.
The easiest way of generating a certificate-key pair is by using a script provided with Stunnel's source code. If you're compiling from the tarball, just issue the following additional commands in the source directory:
$ cd tools $ make stunnel.pemI have decided to put the specific details outside the scope of this article, but if you are interested in the actual details then have a look at the
Makefilein the "tools" directory.
This method can be used to encrypt any similar service where SSL-enabled clients exist and are readily available. Most e-mail clients are SSL-enabled for POP3, IMAP and SMTP, most internet clients (web browsers) are enabled for HTTPS, etc.
Once Stunnel is installed and you have generated a certificate-key pair, you are only a simple configuration file away from using Stunnel to encrypt your communications. A simple one that would encrypt POP3 and IMAP communications would be:
# Sample stunnel configuration file for POP3/IMAP # Provide the full path to your certificate-key pair file cert = /usr/local/etc/stunnel/stunnel.pem # lock the process into a chroot jail chroot = /usr/local/var/run/stunnel/ # and create the PID file in this jail pid = /stunnel.pid # change the UID and GID of the process for security reasons setuid = nobody setgid = nobody # Configure our secured POP3 and IMAP services [pop3s] accept = 995 connect = 110 [imaps] accept = 993 connect = 143
Using this configuration, any encrypted connection coming in on port 995 (POP3s) will be decrypted and forwarded to the local service (POP3) on port 110. When the local POP3 service responds, it will be encrypted by Stunnel and transmitted back through port 995. Similarly for IMAPs on port 993.
Stunnel operates as a daemon service by default, so to start it off with this configuration we can simply execute:
stunnel-secure-email.confis the text file containing the above configuration; ensure you change the paths so that they are correct for your system.
We can set up Stunnel to start during boot-up by placing the appropriate
command in the
rc.local file that is usually contained in
/etc/rc.d/. This file is the last file executed during a system
boot and it is generally used by system administrators for their own
initialisation stuff. When placing commands in this script, use fully
qualified paths such as:
[ For Debian and similar distros without an 'rc.local', the procedure varies slightly: modify a copy of "/etc/init.d/skeleton" (named, e.g., "/etc/init.d/stunnel") to run the above and create a link to it from the appropriate runlevel (usually /etc/rc2.d/). -- Ben ]
Stunnel can also be used with (
preferred. You can find further details in Stunnel's man page.
This method can be used to encrypt any service where neither the server nor the client are SSL-enabled. Common examples include CVS, MySQL, etc.
In the example with POP3 and IMAP above, we were only concerned with providing the server with SSL encryption as the clients generally have this built in. However, neither the standard MySQL server nor client have SSL capabilities - but we can still use Stunnel to provide this.
It involves using a Stunnel daemon on both the server's machine and the client's machine. The configuration for the server side is similar to the one we used above for POP3/IMAP. The default MySQL port is 3306, and since no port is reserved for secure MySQL connections, I will use 3307:
# Sample stunnel configuration file for securing MySQL (server side) # Provide the full path to your certificate-key pair file cert = /usr/local/etc/stunnel/stunnel.pem # lock the process into a chroot jail chroot = /usr/local/var/run/stunnel/ # and create the PID file in this jail pid = /stunnel.pid # change the UID and GID of the process for security reasons setuid = nobody setgid = nobody # Configure our secured MySQL server [mysqls] accept = 3307 connect = 3306I can now start the Stunnel daemon on the server machine with:
$ stunnel stunnel-mysql-server.confwhere
stunnel-mysql-server.confis a text file containing the above configuration. We also need to set up an Stunnel daemon on the client machine with the following configuration:
# Sample stunnel configuration file for securing MySQL (client side) # Provide the full path to your certificate-key pair file cert = /usr/local/etc/stunnel/stunnel.pem # lock the process into a chroot jail chroot = /usr/local/var/run/stunnel/ # and create the PID file in this jail pid = /stunnel.pid # change the UID and GID of the process for security reasons setuid = nobody setgid = nobody # enable client mode client = yes # Configure our secured MySQL client [mysqls] accept = 3306 connect = 22.214.171.124:3307You'll notice that I have used a new option:
client = yes- this enables "client mode" which lets Stunnel know that the remote service uses SSL. Our local Stunnel daemon will now listen for connections on the local MySQL port (3306), encrypt them and forward them to our MySQL server machine (say 126.96.36.199) where another Stunnel is listening on port 3307. The remote Stunnel will decrypt the transmission and forward it to the MySQL server listening on port 3306 of the same machine. All responses will be sent back through the same encrypted channel.
Save the client configuration as
start off Stunnel with:
$ stunnel stunnel-mysql-client.confand then you can connect to the remote MySQL server through the encrypted channel by connecting to the local Stunnel daemon (which is listening on MySQL's 3306 port):
$ mysql -h 127.0.0.1 -u username -p
nobody(some systems might need
setgid). Ensure your chrooted directory is writable by the
nobodyuser and/or the
Stunnel runs in the background by default and doesn't show any error
messages. This means you won't know if it worked or not from the command
line! You can check that the process is running by searching the output of
$ ps -ef | grep stunnel nobody 21769 1 0 09:12 ? 00:00:00 /usr/local/sbin/stunnel ./stunnel-mysql-server.conf
Stunnel can also be instructed to run in the foreground by adding the following command to the configuration file (above the service configuration):
foreground = yes
As with all services, the best method of diagnosing problems is through the service's log messages. You can enable Stunnel's logging facilities by adding the following commands to the configuration file (above the service configuration):
debug = 7 output = /tmp/stunnel.log
If you are running in the foreground for testing/debugging, then you might prefer to send the log messages to standard out:
debug = 7 output = /dev/stdout
The following websites may also prove useful:
As always, I appreciate any feedback on this or previous articles and suggestions/requests for future ones. You'll find my e-mail address by clicking on my name at the beginning of the article.
Barry O'Donovan graduated from the National University of Ireland, Galway
with a B.Sc. (Hons) in computer science and mathematics. He is currently
completing a Ph.D. in computer science with the Information Hiding Laboratory, University
College Dublin, Ireland in the area of audio watermarking.
Barry has been using Linux since 1997 and his current flavor of choice
is Fedora Core. He is a member of the Irish
Linux Users Group. Whenever he's not doing his Ph.D. he can usually be
found supporting his finances by doing some work for Open Hosting, in the pub with friends or running in the local
Barry has been using Linux since 1997 and his current flavor of choice is Fedora Core. He is a member of the Irish Linux Users Group. Whenever he's not doing his Ph.D. he can usually be found supporting his finances by doing some work for Open Hosting, in the pub with friends or running in the local park.