This page depreciated

This FAQ for stunnel is no longer being updated. Please go to the FAQ section on www.stunnel.org instead.

Using certificates with stunnel.

A full description of how certificates work is beyond the scope of this FAQ. Instead we'll explain how they 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 it's identity. (PEM stands for 'privacy enhanced mail' which is now much more liberally used as a key format)

This private key is put in /usr/local/ssl/certs/stunnel.pem by default, however you should check the output of stunnel -h to verify. You can use a non-default keyfile if you wish by supplying the '-p' argument to stunnel.

An SSL server should also present a certificate. Stunnel generates 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?

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

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 as trusted.

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 one that comes with the distribution if you don't actually need to present this key.

If you are only using stunnel in client mode (ie 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.

Genererating the stunnel private key (pem).

The stunnel source comes with an stunnel.pem file. You can use this file if you wish. However it is not suggested. Everyone on the net has access to this pem file, thus everyone has access to this private data. The security of your SSL connection requires that no one else has access to this private data.

Let me repeat:

It is a bad idea to use the stunnel.pem file shipped with stunnel except for testing.

After testing out stunnel, you should generate your own key.

To do so, simply do a

	make cert

This 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
-new: Generate a new key
-x509: Generate an X509 certificate (self sign)
-nodes: Don't put a password on this key.
-config stunnel.cnf: the OpenSSL configuration file to use
-out stunnel.pem: where to put the SSL certificate
-keyout stunnel.pem: 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 512 >> stunnel.pem
```
This generates Diffie-Hellman parameters, and appends them to the pem file. These are only needed if you specifically compile stunnel to use DH, which is not the default.
```
openssl x509 -subject -dates -fingerprint -in stunnel.pem
```
This command merely prints out information about your certificate to the screen.

Problems with a self-signed certificate.

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 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

Not verify certificates at all
or
Verify certificates against locally installed certs

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-----

Append this certificate to your stunnel.pem and you're good to go.

Can I set up my own CA instead?

Absolutely. Note that doing so is beyond the scope of this document, however.

Feel free to send the stunnel FAQ maintainer pointers to good web pages and they will be included here.

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. Details of this are below.

How does stunnel check certificates?

Stunnel has 3 methods for checking certificates, which are controlled by the '-v' option:

Don't Verify Certificates

If no -v # argument is given, then stunnel will ignore any certificates offered and will allow all connections.
-v 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.
-v 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.
-v 3

Require and verify certificates against locally installed certificates.
Stunnel will look in the directory /usr/local/ssl/certs/trusted (or whatever you specify with the -a parameter) for appropriate certificates.

Where do I put all these certificates?

You can put trusted certificates in files and directories as follows (note that defaults can often be overridden by command line flags):

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. The location stunnel looks for this file is /usr/local/ssl/localCA/cacert.pem (/localCA/cacert.pem on Windows) by default. 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 /usr/local/ssl/certs/trusted (/trusted on Windows). You can override this by using the -a certificate_dir option.
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_hash program that comes with OpenSSL (in the /usr/local/ssl/misc directory):
```
	c_hash some_certificate.pem
	a4644b49.0 => some_certificate.pem
```
So, in the above case you'd rename the file to a4644b49.0.
(Note that is a zero, not the letter 'O', after the dot in the filename.)
If you do not have the c_hash program you can run the appropriate OpenSSL command to determine the hash value:
```
	openssl x509 -hash -noout -in some_certificate.pem
	a4644b49
```
Note that the OpenSSL command 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
```
	strace stunnel ....
```
and look for all the open and stat commands. 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.pem file and the hash of the certificate it wants to find.

Useful web pages (not stunnel specific)