Certificate Management and Installation with OpenSSL - Personal Certificates

Back to the guides index

Index Of Guides

Generating and Installing Your Certificates And Keys In Apache

This section assumes you already have mod_ssl installed. If you don't, go grab a copy now.

Apache mod_ssl has lots of handy makefiles to do most of the key and certificate management for you. We'll be making use of these.

Key Generation

Be wherever you apache config lives (eg /etc/httpd/conf/), and check that the mod_ssl Makefile is there. Then, generate a key using:
make genkey
This should generate a key, and install it in ssl.key/ - check that this is read and write only to root before continuing.

CSR Generation

Be wherever you apache config lives (eg /etc/httpd/conf/), and check that the mod_ssl Makefile is there. You need to have already generated your key (see above). Then, generate your CSR (certificate signing request) using:
make certreq
This should prompt you for the fields to go in your certificate, generate a CSR, and put it in ssl.csr/
No, go send this CSR to your CA, and wait for them to send back the certificate.

Certificate Instalation

When you get your certificate back, you need to install it and your CA certificate in Apache. At the same time, you probably want to also install the CA certificate use with OpenSSL
Be wherever you apache config lives (eg /etc/httpd/conf/). Copy both your CA certificate and your server certificate into ssl.crt/ . You now need to generate the hashes for these certificates, so mod_ssl can find them. Go into the ssl.crt directory, and run:
make update
This will generate the symlinks as needed.
Note: some apache installs come with some sample certificates in their ssl.crt/ directory. You should get rid of these before you install your own certificates.

Generating and Installing Your Certificates And Keys In The UW-IMAP Server

Note On Permissions

With most SSL enabled servers, you have the key and the certificate in seperate files. You keep the key secret, but the certificate can be in a world readable, since you'll be sending it to anyone who asks.

With the UW-Imap server, things are different. You have one file, imapd.pem, which contains both the certificate and the private key. As such, you need to ensure that this file is only accessable by the imap server, and is not world readable. Since the default location for this file is certs/, you might be tempted to make it world readable - don't!

File Location

As with most things in the UW-Imap server, this is controlled at build time. As mentioned above, it uses only one file for SSL, which contains both the certificate and the private key. This file should be PEM formatted (---BEGIN FOO--- / base 64 data / ---END FOO---).

The default location for this file is <ssl-base-dir>/certs/ (see here), and the default file name is imapd.pem.

Generating / Adding Keys and Certificates

Most installs of the server will generate a key and a self signed certificate. Go check if this is the case.

If you don't already have a key, generate one. Go to where the server expects to find it's files (see above), and run:
openssl genrsa -out imapd.pem <key_size>
Probably with a 1024 bit key size. This will create you the key. Note the lack of -des3 or similar - we don't want our key password protected.

Ensure that your key doesn't have a password. You can't prime the UW-IMAP server with a private key password in the way that you can with Apache. As such, you'll have to rely on file permissions to keep it safe.

If your build has created you a certificate, then delete it now. Simplest was is to load the file into a text editor, and trash the certificate section (from ---BEGIN CERTIFICATE--- through to ---END CERTIFICATE--).

Now, generate a certificate signing request for your key, and send it off to your certificate authority. A guide to doing this can be found here. While you wait for your certificate back, ensure your machine trusts your chosen CA. Instructions on installing CA certificates are here.

When the certificate returns, cut and paste it into the same file as the key. You should end up with something looking like:

  rest of key encoded here
  rest of certificate encoded here

Now for a small caveat - this all assumes your certificate was signed by a root certificate authority. In some cases, the CA which signed your certificate is not a root CA, but is a CA signed by a CA (or signed by a CA who was signed by a CA who is a root CA, etc.) This is often known as a chained certificate, or a ca-bundle.

What makes things tricky is that the remote client will look at your certificate, and try to verify it against the root CAs it knows about. If there is an intermediate CA between you and the CA the client knows about, it will need this certificate to sucessfully verify your certificate. As such, the server needs to not only provide clients with its own certificate, but also those of the intermediate CAs.

In the UW-IMAP server, this is achieved by appending all intermediate certificates to the file containing your own certificate, with the highest-level certificate last. (The root certificate is not required, as the client already has it.) With this information added, your imapd.pem now looks like this:

  rest of key encoded here
  rest of certificate encoded here
  rest of intermediate certificate used to sign previous one encoded here
  (i.e. the certificate of your CA, which is itself signed by a root CA)

Controlling Authentication

To control what authentication is offered for different connection types (unencrypted, SSL, TLS etc), see the UW-IMAP FAQ, especially the few sections around 3.18.

Multi-homing and SSL/TLS

With the server, it is possible to server up different certificates for different IPs on a multihomed machine. However, unlike http (but just like https, and most other SSL things), you can't have multiple certificates for the same IP address. This is because the SSL or TLS negotiation happens straight off, before there is a chance to tell the machine what virtual host on that IP you're after. So, you'll need to use on IP for each different certificate you'll be serving (most typically, to handle two different DNS names).

Instead of having imapd.pem and ipop3d.pem combined certificate and key files, you'll want one per IP. These should be imapd-xxx.xxx.xxx.xxx.pem, where xxx.xxx.xxx.xxx is the IP address that'll go with the certificate. Just have one file, named appropriately for each IP, and the right thing should magically just happen.

Anything Else

The server source comes with the SSLBUILD file, normally in /docs/ directory. It ought to give you information on more advanced things you might want to do.

Serving Your Certificates To Browsers

Firtly, be aware that you may need two versions of your certificate, one in PEM format and one in DER format. You can convert between them using OpenSSL.

IE expects to get its certificate in DER format, with a mime type of application/x-x509-ca-cert - newer versions may also accept PEM.
Netscape expects to get its certificate in PEM format, also with a mime type of application/x-x509-ca-cert - newer versions may also accept DER.
Opera should happilly accept either PEM or DER, just as long as it comes with a mime type of application/x-x509-ca-cert

If you use apache, you want to add the following to your /etc/mime.types:
       application/x-x509-ca-cert      crt
Then, ensure your certificates have the ".crt" extention on them.

To install the certificate, the user just needs to point their browser at the certificate. Their browser will then take them through the process of installing it.

Some Tips for working with IIS and certificates

Note: This section is not intended to be a replacement for Microsoft documentation, but instead a reminder for people who have already read it.

The IIS certificate features are pretty limited, so you should use the mmc "Certificates" snap-in for most stuff.

Before doing anything, make sure Windows trusts all the CAs you're going to work with. It can get very confused, and often gives useless error messages, if you try to import certificates from unknown or untrusted CAs.

Windows generally only likes to work with PKCS12 formatted keys and certificates. See this section on how to generate them. Be sure to put both the certificate and the key in the same file, otherwise you'll end up having to start again.

To import or export certificates and keys, run mmc.exe, pick File then Add/Remove Snap-In. Ensure Console Root is active, select Add, then pick Certificates (not Certificate Authority though).

If you want to manage your certificates, then select My user account. If you want to manage IIS's certificates, then select Computer account. In either case, then pick local computer.

Once your certificate is installed, fire up the IIS Administrator, and select properties on your site. Select the Directory Security tab, then select Server Certificates under Secure Communications. Follow the evil wizzard, and hope for the best....

Checking what Certificate You Are Serving

Note: This section might look a little scary, but needn't be!

So, you've set up (or had set up for you) a SSL based system. Something isn't working quite right. Client software is giving errors about invalid certificates or something like that, but failing to tell you anything useful. Just how do you find out exactly what certificate is being sent down the wire?

OpenSSL to the rescue - the magic and rarely mentioned s_client part will do all of this for you. It will quite happily report all the information in the session initiation, including dumping out all the certificates and other helpful things. For anything fancy (verifying against certain CAs, client authentication etc), check the "s_client" man page. However, if all you want to do is see the certificates, use one of:

openssl s_client -connect <server>:<port> -showcerts
openssl s_client -connect <server>:<port> -showcerts -CApath <path-to-certificates>

This command will return lots of information. The main things are: The first few lines where it reports if it could verify the supplied certificate. "verify return:1" means it could, "verify error:num=19:self signed certificate in certificate chain" "verify return:0" means it doesn't trust the CA used. Following this you'll find a chain of certificates, from the server certificate back to the CA, which can be cut, pasted and saved for future checks (eg with openssl x509 -in <file.pem> -noout -text). In the first certificate reported, look for the "s:/" line, and check the "CN=" part. If the bit following this doesn't match your server's host name, clients will get a host name verify error.

While the above is very brief, the man page is quite helpful, so check there for more details.

Guides Index
Written By: Nick Burch    Last modified: Tuesday, 12-Dec-2006 15:33:52 GMT
These pages are from http://www.gagravarr.org/writing/openssl-certs/
Creative Commons License This work is licensed under a Creative Commons License.