Thursday, May 30, 2013

Setting Up TLS (SSL) for IBM HTTP Server with Domino 9 - Part 1

In the last post I went through the steps to install and set up the IBM HTTP Server with Domino 9.

In this and the following post we'll go through the steps to enable TLS (SSL) which really is the reason to use the IBM HTTP Server with Domino in the first place.

There are really only two steps to this:

Step 1 - Get your SSL keys
Step 2 - Configure IHS to use your keys

But first...About SSL

If you've not gone through this process before, let me lay it out for you.  SSL keys are a form of Public/Private key security where there is one "key" (which is really just a number) that is known to everyone - a.k.a the Public key - and there is an associated Private Key that is only know to the holder.

For web servers this means you request a Private Key from an issuing authority.  They verify your request to varying degrees and then give you your Private key.  When a web browser visits your site and requests to encrypt traffic over SSL/TLS, your web server provides your Private Key (all encrypted of course) and your web browser will use the Public Key of the certificate issuer to verify that the Private Key your server is providing is, in fact, valid according to the Public Key of the issuer.  The two keys are mathematically related and so must "add up" somehow to be verified and then the keys are used to encrypt the netwrok traffic between the client and your web server. (Yeah I wouldn't use this as a technical description of SSL if I were you.)

The requirement in all of this is that your web browser must know who the issuer is and have their Public Key available to verify your Private Key.

It is your job to make sure all of this is set up correctly on your web server.

Step 1 - Get your SSL keys

How do you make your keys available on IHS?  IKeyMan!

"Huh?  Is that super hero movie coming out before or after Man of Steel?"

Nope.  IKeyMan is a "special" program used by IBM to manage an SSL keys database on your hard drive.  That's where you have to have your keys for your server to access them.

First thing you need to do is run the ikeyman.bat file to start the program.

Now that you've started IKeyMan you'll want to create an SSL request which will then be sent to your SSL issuer.

Make a new keys database to hold your key information.  I found that in order to work I needed to locate my keys DB outside of the Domino folders just like they say in the Domino documentation but NOT as they indicate in the domino.conf file.  However it appears Darren Duke was able to locate his database right in the folder.  More information is better.

Now that you have a database to hold your keys...create an SSL Certificate request...

Now you send the resulting file to your issuer and give them money.  I use GoDaddy because they are reasonably priced and since I've been using them for years the inertia is there so I doubt I'll switch anytime soon.  There are cheaper places and more expensive places but you have to make that choice depending on your budget and needs.  Each company offers slightly different services coupled with essentially the same certificates.  You'll also pay more for some of the marquee names in the business.

When they are done processing your credit card, etc. they'll make your new certificate available to you which you will download and then insert into your keys database using IKeyMan again.

Finally you need to make sure that the Certificate Issuer's Public Keys are also stored in your keys db.

There is a clever Populate button in the Signer Certificates that you can use to add one or all of a standard set of trust authorities.  On mine I just added 'em all for good measure.

What if your SSL certificate issuer is NOT listed?  Then you have to download their certificates (they'll tell you which ones you need and provide them in a variety of formats...I typically just use the topmost versions) and then you have to "Add" those issuers Root and Intermediate certificates (their Public Keys) into your keys database.

Finis!  You now have an SSL keys database on your hard drive where it can be accessed by your server and that keys database contains your Private Key (from your SSL certificate vendor) as well as the Public Keys of your vendor.

BTW ... there is a Self-Signed SSL certificate option available if you want to do some SSL testing without spending money.

In Part 2 I discuss how to edit the domino.conf file for SSL use.