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
We'd add the following line to the file
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
foobar 9999/tcp # The foobar serviceYou must then send the
SIGHUP. Find the process id for the
inetdprocess by one of the following commands:
ps -ef | grep inetd ps -axj | grep inetdand 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
Note: Some unix variants have a
killall command that kills
all processes on the machine. That's not the
/usr/local/etc/stunnel.conf configuration file for
inetd mode must not include a
cert = ... ... # Do not include # [someservicename] connect = logging:syslogsIf 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
9999to support a fictitious protocol called
First we'd add the following line to
foobar 9999/tcp # The foobar serviceStunnel configuration file needs at least the section name and
acceptoption. For example:
cert = ... ... [foobar service] accept = foobar ...
Running stunnel with TCP wrappers
configure program should be able to determine if the libwrap
-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.1Service name is the name of service that was put in square brackets in
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 -installin the directory where
stunnel.confis available. SSL Certificates HOWTO. Here I'll try to explain how certs work with stunnel itself.
Quick certificate overview
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's a certificate?
- The certificate presented matches the private key being used by the remote end.
- The certificate has been signed correctly by the CA.
- The client recognizes the CA (or the specific certificate) as trusted.
Do I need a valid certificate?
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)
make certThis will run the following commands:
openssl req -new -x509 -days 365 -nodes -config stunnel.cnf -out stunnel.pem -keyout stunnel.pem
This creates a private key, and self-signed certificate. The arguments mean:
- -days 365
- make this key valid for 1 year, after which it's not to be used any more
- Generate a new key
- Generate an X509 certificate (self sign)
- Don't put a password on this key.
- the OpenSSL configuration file to use
- where to put the SSL certificate
- put the key in this file
This command will ask you the following questions:
Question Example Answers Country name PL, UK, US, CA State or Province name Illinois, Ontario Locality Chicago, Toronto Organization Name Bill's Meats, Acme Anvils Organizational Unit Name Ecommerce Division Common Name (FQDN) www.example.com
Important Note: The Common Name (FQDN) should be the hostname of the machine running stunnel. If you can access the machine by more than one hostname some SSL clients will warn you that the certificate is being used on the wrong host, so it's best to have this match the hostname users will be accessing.
openssl gendh 2048 >> stunnel.pem
This generates Diffie-Hellman parameters, and appends them to the pem file.
openssl x509 -subject -dates -fingerprint -in stunnel.pem
This command merely prints out information about your certificate to the screen.
How can I get rid of a passphrase on my key?
$ openssl rsa -in original.pem -out new.pemThis 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
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 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
- Not verify certificates at all
- Verify certificates against locally installed certs
How can I have my key signed by a CA?
openssl req -new -days 365 -nodes
-config stunnel.cnf -out certreq.pem -keyout stunnel.pem
This creates your RSA private key in
and your Certificate Request in
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.pemfile, and then you're good to go.
Can I set up my own CA instead?
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?
- Don't Verify Certificates
- If no
verifyargument is given, then stunnel will ignore any certificates offered and will allow all connections.
- 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 = 2
- Require and verify certificates
Stunnel will require and verify certificates for every SSL connection. If no certificate or an invalid certificate is presented, then it will drop the connection.
- verify = 3
- Require and verify certificates against locally installed certificates.
Where do I put all these certificates?
- Single file with many trusted SSL certificates
You can create a single file with as many certificates as you want. Just concatenate the certificates together and save the file. Use the
CAfileoption to specify your certificate. This file will be of the form:
-----BEGIN CERTIFICATE----- certificate #1 data here -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- certificate #2 data here -----END CERTIFICATE-----
- Each certificate in it's own file
You can put each certificate you wish to allow in it's own file in the directory specified with the
CApath = certificate_diroption.
The certificates in this directory must be saved with specific filenames. The filename used is actually a hash of the certificate itself. This allows stunnel to quickly determine if the certificate is in that directory without reading every single file.
To determine the filename you should use, you can use the
c_hashprogram that comes with OpenSSL (in the
prompt$ c_hash some_certificate.pem a4644b49.0 => some_certificate.pemSo, in the above case you'd rename the file to
Note: it is a zero, not the letter 'O', after the dot in the filename.
If you do not have the
c_hashprogram you can run the appropriate OpenSSL command to determine the hash value:
prompt$ openssl x509 -hash -noout -in some_certificate.pem a4644b49Note: The
OpenSSLcommand does not include the trailing '
.0', so append it yourself.
For all of the above methods, one sure-fire way to determine where stunnel is looking for your certificates is to trace the stunnel process when it runs and see what files it's trying to open. If you have strace (or ptrace, par, etc.) you can try running it like:
prompt$ strace stunnel ....and look for all the
statcommands. Those will tell you which files it's looking for. For example you may see output like this:
open("/usr/local/ssl/localCA/cacert.pem", O_RDONLY) = 3 stat("/usr/local/ssl/certs/f73e89fd.0", 0xbffff41c) = -1 ENOENT (No such file or directory)by which you see where it's looking for the
cacert.pemfile and the hash of the certificate it wants to find.
Where can I get a copy of official CA certificates?
How do I import/trust a certificate into Outlook/Outlook Express/IE/etc
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't 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.