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.
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!
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.
Most installs of the server will generate a key and a self signed certificate. Go check if this is the case.
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:
-----BEGIN RSA PRIVATE KEY----- ABCDEF...... rest of key encoded here ....XYZ== -----END RSA PRIVATE KEY----- -----BEGIN CERTIFICATE----- ABCDE...... rest of certificate encoded here ....XYZ= -----END CERTIFICATE-----
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:
-----BEGIN RSA PRIVATE KEY----- ABCDEF...... rest of key encoded here ....XYZ== -----END RSA PRIVATE KEY----- -----BEGIN CERTIFICATE----- ABCDE...... rest of certificate encoded here ....XYZ= -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- ABCDE...... 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) ....XYZ= -----END CERTIFICATE-----
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.
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.
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.
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.
application/x-x509-ca-cert crt
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.
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....
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:
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.
This work is licensed under a
Creative
Commons License.