stunnel: FAQ

Stunnel FAQ

Troubleshooting

"Could not find your SSL library installation dir" when running configure

The first posibility is that you have not installed an SSL library, either OpenSSL or SSLeay. In that case you should download and compile one of them. OpenSSL can be found at www.openssl.org.

The other possibility is that you installed your SSL library in a non-standard place. Use the --with-ssl directive when running configure to tell it where this directory is.

Configure is not finding my TCP Wrapper installation

You probably have it in a non-standard place, i.e. somewhere that gcc cannot find it on its own. Lets say you had your tcp wrappers installed in /opt/tcpd_7.6. To help gcc find your include files and libraries, you should set three environment variables as follows: 
 
CFLAGS="$CFLAGS     -I/opt/tcpd_7.6/include"
CPPFLAGS="$CPPFLAGS -I/opt/tcpd_7.6/include"
LDFLAGS="$LDFLAGS   -L/opt/tcpd_7.6/lib"
export CFLAGS CPPFLAGS LDFLAGS
And then re-run configure. This is the generic way to have configure find specific libraries, and is not specific to stunnel itself.

What to do when stunnel fails

Firstly, the most important things to try when you are having trouble running stunnel is to:
  • run with full debug mode debug = 7
  • if running the daemon, run it in the foreground foreground = yes
Doing this gives you the best chance of catching the errors in the log on the screen.

I do not have the openssl binary / Cannot make stunnel.pem!

If you do not have the openssl program (for example you are using the pre-compiled version of stunnel on a Windows machine) then you need to generate an stunnel.pem file in some other manner. You can find a spare Unix workstation that does have OpenSSL installed, for example.

When I run stunnel, it just sits there, it does not listen for requests!

You are probably missing the [service] definition in your config. For example: 
pid        = /stunnel.pid
setuid     = nobody
setgid     = nobody
debug      = local6.err
foreground = no
client     = yes

[mysyslog]
accept     = localhost:syslog
connect    = logging:syslogs
Without that [mysyslog] line, stunnel assumes you want to operate in inetd-style mode.

I get the error "Wrong permissions on stunnel.pem"

I get the error 
stunnel[PID]: Wrong permissions on /path/to/stunnel.pem
on my stunnel server or on stunnel client using client-side certificates.

The stunnel.pem file contains your key (private data) and certificate (public data). In order for stunnel to start automatically without requiring a password, the key is created without a password. This means that anyone who can read this file can compromise your SSL security. This file must be readable only by root, or the user who runs stunnel.

Use the chmod command to fix permissions on this file, ala

chmod 600 /path/to/stunnel.pem

FTP over stunnel does not work

Stunnel cannot be used for the FTP daemon because of the nature of the FTP protocol which utilizes multiple ports for data transfers. There are SSL aware FTP servers available.

Alternatively you could use a different protocol. All versions of SSH include a program called scp which works like rcp. Recent versions of OpenSSH include a program called sftp which has an ftp-like feel.

Stunnel does not work with Windows with strong crypto

Try installing the High Encryption Pack and all other service packs.

Stunnel does not work with Windows 2000 (Outlook Express)

The error looks like the following: 
SSL_accept:error:140760F8:SSL routines:SSL23_GET_CLIENT_HELLO:unknown protocol
SSL_accept:error:1409B0AB:SSL routines:SSL3_SEND_SERVER_KEY_EXCHANGE:missing tmp rsa key
One day after the official release of Windows 2000 a number of "Critical Updates" were released. At least one of them fixes the problem, probably the "128bit encryption pack update".

It is not determined if this applies to merely Outlook, or Windows 2000 in general, however it is a good idea to update your machine.

How do I configure Outlook to use SSL?

To use POP with SSL in Outlook (tested with 2000, 98, and Outlook Express, should work with other versions), simply select the checkbox under the "Incoming mail (POP3)" section that says "This server requires a secure connection (SSL)". These options are all located on the advanced tab in the account properties. Make sure that the port it changes to when you check the box is correct (should be 995 by default).

Stunnel fails with a "PRNG not seeded" error message

You are likely not on a system that has /dev/urandom, and OpenSSL is not able to gather enough entropy to create strong SSL sessions. Option include, in rough order of preference:
  • Use PRNGd (Portable Random Number Generator Daemon) available here. This is an EGD compatible random number generator. It gathers entropy from system commands and feeds them to the OpenSSL RNG, and thus will never block waiting for more random data. Point to your PRNGd socket with EGD = /path/to/sock argument to stunnel.
  • Use EGD (Entropy Gathering Daemon) available here. EGD was the first widely used RNG that got its entropy from system commands. Unfortunately EGD can block (ie hang) until it gathers enough entropy. (For this reason PRNGd is preferred over EGD.) Point to your EGD socket with EGD = /path/to/sock argument to stunnel.
  • If you are running Solaris, snag the SUNWski patch, which will create /dev/random for you. Simply ln -s random /dev/urandom and OpenSSL (and thus stunnel) will find entropy for you automatically.
    This patch has been reported to be available as part of the following patches, YMMV: 105710-01, 106754-01, 106755-01, 106756-01.
    On Solaris 8 you could install patch 112438 to get /dev/random and /dev/urandom devices.
  • In the worst case you can create a file or files with random data (for example copy sections of your running kernel to a file) and use them to seed the data. See the stunnel manual page RANDOMNESS section for the full list of which files are searched and in which order. It is important to remember that these random data files may be overwritten unless RNDoverwrite = no option is used.

Secure Password Authentication error with Outlook and POP

When I try to use pop with Outlook I get the following error:

Unable to logon to the server using Secure Password Authentication. Account: 'example.net', Server: 'mail.example.net', Protocol: POP3, Server Response: '.', Port: 995, Secure(SSL): Yes, Error Number: 0x800CCC18

You told Outlook to use Secure Password Authentication, but your POP server does not support it. Since you use stunnel, your password is not ever in the clear anyway, so you can just turn off Secure Password Authentication.

Help! I run on Linux with threads, but stunnel keeps forking off processes anyway!

Linux threads have entries in the process table. A threaded stunnel daemon will have n+1 entries in /proc, where n is the number of current threads. It is not an error.

If you have arguments against this way of implementing threads, talk to Linus. Linux threads are damned fast as they are, so you are not likely to convince him to change things.

Stunnel also spawns its libwrap client processes at startup, as libwrap code is not thread-safe.

Stunnel hangs for a while accepting connections

You probably have TCP Wrapper support compiled into stunnel, and are having DNS problems. TCP Wrappers do reverse lookups of the incoming IP address. If you have a bad server in /etc/resolv.conf each failed query takes time to expire. DNS fail-over causes severe slowdown of stunnel. We suggest any or all of the following:
  • Fix your /etc/resolv.conf
  • Make sure your machines have reverse DNS entries. It is just a good practice anyway.
  • Try accessing a closer name server first in your resolv.conf
  • Consider running a caching nameserver on your local host and pointing to it first
If the problem does not go away, you may want to try compiling stunnel without TCP Wrappers and see if the problem is still there and troubleshoot further.

Stunnel is complaining that there are too many open files and is refusing new connections

This is an OS-dependent issue. You probably have a hard limit of the number of file descriptors that can be open by processes. Increase this number to a more acceptable level. Stunnel may use anywhere from one to four file descriptors per connection depending on how you use it.

For a quick glance at how to change this parameter on Solaris, go here.

My connections are slow, slow, slow

One option might be to turn on the TCP NODELAY option on both ends. On the server, include the following options: 
socket = l:TCP_NODELAY=1
and on the client include: 
socket = r:TCP_NODELAY=1

Are there any special problems with stunnel and IE?

It is a well known problem with Internet Explorer and several other products. They do not send close_notify message before TCP FIN packet violating SSLv3 and TLSv1 protocols. It is also a security problem: Microsoft applications are vulnerable to truncation attacks. Is Microsoft able to implement anything properly?

Currently stunnel implements ugly 10-seconds timeout to work with Microsoft... I hate it, but several peple need it.

See RFC 2246 chapter 7.2.1. for details.

I am running out of processes/file descriptors on Solaris

In 2.3 in earlier this requires poking the kernel. In Solaris 2.4+, this can be accomplished by adding the following lines to /etc/system: 
* set hard limit on file descriptors
set rlim_fd_max = 4096
* set soft limit on file descriptors
set rlim_fd_cur = 1024

TCP Wrappers do not work as expected

If you are using stunnel in a chroot environment, you need to include the /etc/hosts.allow and /etc/hosts.deny files within that environment. So say your stunnel.conf had the following: 
chroot = /path/to/chroot/
Then you need to create /path/to/chroot/etc and put your hosts.allow and hosts.deny files there: 
mkdir /path/to/chroot/etc
cp /etc/hosts.allow /etc/hosts.deny /path/to/chroot/etc
Make sure that you change these files, not the global /etc/hosts.{allow.deny} files.

My web browser cannot talk to stunnel

If you get the following error message in stunnel:

2003.01.18 17:46:07 LOG3[6093:32770]: SSL_accept: 1407609C: error:1407609C:SSL routines:SSL23_GET_CLIENT_HELLO:http request

then your stunnel runs in server mode (without client = yes) and your web browser is connecting to it as if it is a normal webserver, ala http://example.com/.

If stunnel is supposed to be running as a client, then fix your stunnel.conf. If you do mean to be running as an SSL server then point your browser at https://host:port/ instead of http://host:port/.

Problems tunneling telnet over stunnel with AIX

Contrary to popular belief, telnet is a very complex protocol heavily relying on out-of-band (OOB) data and internal timeouts. It is much better to use OpenSSH than telnet over SSL.

Some users also recommended using telnetd -a or telnetd -R as a workaround.

Eudora keeps saying "error reading network"

It is a timing error in Eudora, not a problem in stunnel. In Eudora, go to "Tools" -> "Options". Scroll down and select "Advanced Network". Increase the "Network Buffer Size" to 8192. Put a check mark in "Cache network info". If you want to increase "Network open timeout" and "Network timeout after" values too, it would not hurt (try 1000). Then try to collect email again. Should work for you.

Another solution reported to work is adding 

options = DONT_INSERT_EMPTY_FRAGMENTS
to stunnel.conf.

Applications

This section gives you some information on how getting to work with other applications.

Can I forward UDP services over stunnel?

As described thus far, no. Stunnel works with SSL, which runs only on TCP. There are ways to forward UDP packets over TCP, and in principle these should be able to work over stunnel.

There are also other programs that do this natively, and could be used standalone or via stunnel, such as Zebedee. If you have any success tunneling UDP over stunnel, please contact the faq maintainer so we can write up a good HOWTO for folks.

Can I use stunnel to communicate across a firewall?

As long as the tcp traffic is allowed to traverse your firewall, absolutely.

You're most likely to convince your firewall administrator to allow secure traffic from inside to outside. In fact, if your firewall is doing NAT, you can probably stunnel out from your machine to an internet machine without any firewall re-configuration.

Specifically, have your firewall administrator allow outbound connections from your machine to the remote (internet) machine on the specific port you wish to connect to.

Be sure to discuss these issues with your administrator. They don't enjoy people penetrating their firewalls without their consent.

Can I use stunnel to securely connect two subnets across the Internet?

Absolutely. There are two options:

Can I use stunnel to protect [insert random protocol here]?

Stunnel should be able to secure any random protocol as long as the protocol satisfies the following requirements:
  1. The protocol is TCP, not UDP.
  2. The protocol doesn't use multiple connections, like ftp.
  3. The protocol doesn't depend on Out Of Band (OOB) data,
  4. Remote site can't use an application-specific protocol, like ssltelnet, where SSL is a negotiated option, save for those protocols already supported by the protocol argument to stunnel.

Miscellaneous

What is Session Cache?

When a client/server connect they establish a session ID which it will try to use later. This session id includes what ciphers they agreed upon, etc.

A client offers to reuse a session ID. If the server recognizes it then they will skip the whole cipher/etc determination phase, which results in smaller overhead. This is called a cache hit. (the session id cache is where these session ids are.)

A session id cache miss means that the client either does not have a session id it can use, or the server does not recognize it. Thus they negotiate ciphers all over again.

What are the offical SSL ports?

These are the officially 'registered' ports for various SSL-ified protocols. note that listing them here doesn't mean that they can be used with stunnel. 
nsiiops      261/tcp   # IIOP Name Service over TLS/SSL
https        443/tcp   # http protocol over TLS/SSL
smtps        465/tcp   # smtp protocol over TLS/SSL (was ssmtp)
nntps        563/tcp   # nntp protocol over TLS/SSL (was snntp)
imap4-ssl    585/tcp   # IMAP4+SSL (use 993 instead)
sshell       614/tcp   # SSLshell
ldaps        636/tcp   # ldap protocol over TLS/SSL (was sldap)
ftps-data    989/tcp   # ftp protocol, data, over TLS/SSL
ftps         990/tcp   # ftp protocol, control, over TLS/SSL
telnets      992/tcp   # telnet protocol over TLS/SSL
imaps        993/tcp   # imap4 protocol over TLS/SSL
ircs         994/tcp   # irc protocol over TLS/SSL
pop3s        995/tcp   # pop3 protocol over TLS/SSL (was spop3)
msft-gc-ssl  3269/tcp  # Microsoft Global Catalog with LDAP/SSL

How do I know which encryption ciphers are available?

The ciphers that are available to stunnel (and usable by the ciphers option) are determined by your OpenSSL library. To list the available ciphers, run the following: 
openssl ciphers -v

How can I delay DNS lookups until connect time?

Add the following to your stunnel configuration file: 
delay = yes

How can I convert a certificate from der format (.cer) to PEM format?

Some institutions that supply certificates will send them to you in der format instead of PEM format. You can use the openssl command line tool to convert from one to the other: 
openssl x509 -in file.cer -inform d -out file.pem