Stunnel HOWTO

Installation

This section gives you basic information on how to run the stunnel program in client and server mode.

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 would 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 is not the killall you are 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 its job, and will not work with inetd.

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

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 would 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 killing 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.

Authentication

A full description of how certificates work is beyond the scope of this FAQ. For that, go read the SSL Certificates HOWTO. Here I will try to explain how certs work with stunnel itself.

Quick certificate overview

Every stunnel server has a private key. This is contained in the pem file which stunnel uses to initialize its identity. PEM stands for 'privacy enhanced mail' which is now much more liberally used as a key format.

An SSL server should also present a certificate. On Unix stunnel generates a self-signed certificates by default during the installation. It is possible to have your key signed by a third party (Certificate Authority) instead if you wish.

What is a certificate?

When an SSL client connects to an SSL server, the server presents a certificate, essentially an electronic piece of proof that machine is who it claims to be. This certificate is signed by a 'Certificate Authority' (hereafter a CA) -- usually a trusted third party like Verisign. A client will accept this certificate only if:

It is also possible for an SSL client to present a certificate, called a client certificate or peer certificate, although the methods for generating them are all the same.

Do I need a valid certificate?

Stunnel does need a pem file, regardless whether or not the data is used. You can simply use the automatically generated one one if you don not actually need to present this key.

If you are only using stunnel in client mode (i.e. it connects to an SSL server, it does not act as an SSL server) then you most likely do not need to present a valid certificate at all, and can skip this chapter entirely. Just use the pem that that comes with the distribution. It is most likely not asked for by the remote end, nor verified.

If you use stunnel in client mode and the remote SSL server does require client/peer certificates, then you do need one, and should read the instructions below.

Generating the stunnel certificate and private key (pem)

In rder to generate certificate and corresponding private key, simply do a

make cert

This will run the following commands:

How can I get rid of a passphrase on my key?

If you have a key that has a key, and you are tired of inputting it each time you start stunnel, then do the following:

$ **openssl rsa -in _original.pem_ -out _new.pem_**  

This gets rid of the passphrase from the key, leaving it completely unprotected. However it also strips out the other bits of the .pem file, namely the certificate and the DH params. So, copy these bits from the original.pem and paste them at the end of new.pem, namely

-----BEGIN CERTIFICATE-----
gUgePf2CbIMcIkWln8Ujse5WHe42wPFhwVM4Fwdkvy8WD6QoroYzJDzrcu1L15nF
...
uigItwLjZ4QluVJehYUc3wVJeYtYXPyXyFAJzrKSJ81I
-----END CERTIFICATE-----
-----BEGIN DH PARAMETERS-----
MEYCQQDG73XqnJcZizotIRB3OEAyTr4wAULyYgfFjIWTK3FuLaqYSonfAbxZQ8wU
SJnF/+yUvMcVHuuePqSOf3KT7VRLAgEC
-----END DH PARAMETERS-----

Problems with self-signed certificates

Anyone can make a self-signed certificate. It is a totally valid SSL certificate. However most SSL clients (e.g. Netscape, IE) wish to verify the identity of the organization that signed the certificate. These SSL clients often have a hard-coded list of organizations (Certificate Authorities) that sign keys after doing background checks, etc.

Since the key and certificate you just generated are not in the hard-coded list that your SSL client uses, you will get either an error or warning message when attempting to connect to your stunnel daemon.

Do I need to have a Certificate Authority sign my public key?

If you wish to interact with 3rd party clients (Netscape, IE, etc) that have hard coded lists of acceptable Certificate Authorities, and you do not want annoying dialog boxes popping up for the user on the first (or all) connections, then yes, you will have to have your key signed by a valid Certificate Authority.

If you have control of both the SSL client and the SSL server (say you are tunneling PPP from one location to another with stunnel at both ends) then you can either

neither of which requires getting your keys signed by a CA.

How can I have my key signed by a CA?

Create your private key manually as follows:

openssl req -new -days 365 -nodes -config stunnel.cnf -out certreq.pem -keyout stunnel.pem

This creates your RSA private key in stunnel.pem and your Certificate Request in certreq.pem. You must send this Certificate Request to the CA you wish to use, including whatever other information they may need.

After processing your information (and check) they will send you back a certificate which is of the form

-----BEGIN CERTIFICATE-----
certificate data here
-----END CERTIFICATE-----

This is your certificate. You need to append this certificate, as well as any intermediate certificates between you and the certificate authority root, to your stunnel.pem file, and then you are good to go.

Can I set up my own CA instead?

Absolutely. Doing so is beyond the scope of this document, however. A number of URLs are listed at the bottom of this page that may be helpful.

The important thing you must do is make sure that your CA certificate is available to the remote machine. If the remote machine is running stunnel, then that means including this CA certificate in one of the possible trusted certificate locations available.

How does stunnel check certificates?

Stunnel has 3 methods for checking certificates, which are controlled by the verify option:

verify = 1
Verify the certificate, if present. * If no certificate is presented by the remote end, accept the connection. * If a certificate is presented, then * If the certificate valid, it will log which certificate is being used, and continue the connection. * If the certificate is invalid, it will drop the connection.
verify = 3
Require and verify certificates against locally installed certificates.

Where do I put all these certificates?

You can put trusted certificates in files and directories as follows.

Where can I get a copy of official CA certificates?

The following pages contain copies of various Certificate Authority (for example Thawte) certificates which were snagged from web browsers, etc.

How do I import/trust a certificate into Outlook/Outlook Express/IE/etc

No, this isn not actually stunnel specific, but it is a common question. Craig Boston suggests:

Save the X.509 cert to a text file (the one you created from the test CA I guess), name it something.cer, and try copying it to the windows box and double-clicking it. If all goes well, you should see the certificate, if so, click "Install Certificate", override the defaults (don not let it automatically choose where to put it) and install it in your root certificate store. Outlook should hopefully then stop complaining. One way to test is to copy the server certificate over and check the "Certificate Path" tab to see if everything checks out.

How do I convert a PKCS12 certificate to PEM form?

openssl pkcs12 -in file.p12 -out file.pem

See the openssl manual page for more information.

Our supporters:
Go to the top