Lotus Notes FAQ Visit Our Sponsor!

Does Domino Support Wildcard SSL Certificates?

Thanks to Joe Walters for putting up this detailed description of how to set this up:

Configuring a wildcard certificate with Domino is very similar to configuring a single-host SSL certificate.˙ So, most of the process below you'll already be familiar with if you've ever set up SSL on Domino.˙ Here's how I would configure a new wildcard certificate in my test environment.˙ I'll include some caveats and comments at the end, so save your questions. :-)

My scenario:

I have a Domino 7.0.x server, Kakadu/WashU, running on Windows Server 2003.˙ It's Program directory is C:\Lotus\Domino and it's Data directory is D:\Lotus\Domino\Data.˙ I want to configure an SSL certificate for Kakadu, but I know later, I'll be asked to configure SSL certificates on other Domino servers, so I opt to implement a wildcard certificate. ˙

To save some time and hassle later, I picked an unused local drive letter (V:) and mapped a drive to Kakadu's D: drive (from a windows cmd prompt, I type net use V: \\kakadu\d$). ˙

Creating a Key Ring File:

The first thing I need to do to configure any SSL certificate in Domino is create a key ring file.˙

I open the Domino Server Certificate Administration (CERTSRV.NSF) database on Kakadu (at this point, you may have to escape out of the About Database document), then click on Create Key Ring.


The key ring file is used to store the certificates and it ultimately needs to reside in the Domino server's data directory.˙ (This is where my mapped drive helps me out a little.) ˙

In the Key Ring File Name: field, I enter the path to where I want my key ring file to reside (in my Domino server's data directory, via my locally mapped V: drive).

Next, I enter a password and confirm it.˙ (Document and secure this password somewhere.˙ Do this now.˙ If you're like me, you won't remember it five minutes from now.)

I then select the Key Size I want to use for my key ring.˙ There's no reason for me not to choose 1024 for a more secure encryption strength.

Everything's been normal SSL configuration to this point.˙ But now, in the Common Name field, I need to use the wildcard notation instead of the fully qualified domain name (FQDN) of my server, as I normally would.˙ My Domino server's FQDN is actually kakadu.wustl.edu, so the proper wildcard notation should be *.wustl.edu.

The rest of the fields (organization, Organizational Unit, City or Locality,˙ State or Province, and Country) should be filled in just as you would if you were configuring a single server SSL certificate.

When I've finished filling out this form, I click the Create Key Ring button at the bottom.


A dialog box pops up indicating I've successfully created my key ring file.˙ I click OK and at this point, if I were to go out to Kakadu's Domino data directory, I would see my .kyr file (wildcard1024.kyr).˙ I should also see a wildcard1024.sth file in the data directory.˙ The .kyr file is password-protected in a binary format (not encrypted).˙ The .sth file is the Stash file, and it stores the password to the .kyr file so the server can use it unattended.


Generating a CSR:

Now that I have a key ring file to store my certificates, I need to generate a CSR (Certificate Signing Request).˙ Still in certsrv.nsf, I now click on Create Certificate Request.


A Create Server Certificate Request form opens, and I confirm that the Key Ring File Name path includes the full path to the key ring file I created previously.˙ All of this auto-filled for me, so I just click the Create Certificate Request button.˙


Now a Certificate Request Created dialog box will pop up.˙ Here you'll need to copy to the clipboard everything you see in the bottom window including the -----BEGIN NEW CERTIFICATE REQUEST----- text at the beginning and the -----END NEW CERTIFICATE REQUEST----- text at the end.˙ (I suggest you paste this into a text file for temporary safe keeping as well.˙ You can safely delete it once you've finished the whole process.)˙ Click OK once you've copied the certificate to the clipboard.


Acquire your Wildcard SSL Certificate from a Third-Party Certificate Authority:

Now that you have a CSR, you can go to a third-party SSL provider's website to get a wildcard certificate.˙ Each provider's process will be a little bit different, but they will all want four things from you.

1) You need to be the owner of the domain name for which you want to get the wildcard certificate, so be prepared to provide some type of proof to the third-party CA that you're authorized to request the certificate.

2) You'll also need to provide some type of proof that your organization is a legitimate one.

3) You'll need to have the CSR you generated a moment ago.

4) Lastly, you'll need to pay for the certificate.˙ If you have a credit card, preferably a company card, this is definitely the easiest way to go.˙ I've had to pay for certificates with a purchase order in the past and the delay was irritating.˙ In fact, some CAs may not accept anything but a credit card anyway.

In this example, I'm purchasing my wildcard certificate from Digicert, but the process is very similar between Verisign, Thawte, Digicert, and I imagine most other third-party CAs.

Installing the Wildcard Certificate into your Key Ring file:

Once you've finished purchasing your wildcard certificate, your CA will let you know how to retrieve your certificate.˙ (Typically, you'll create a login account to their website where you can retrieve them.) ˙

Depending on who you purchase your certificate from, the key ring file may or may not already have Trusted Root and Intermediate certificates installed.˙ So the best bet is to install the Trusted Root and Intermediate certificates, assuming they're not already there.˙ You'll want to install the Trusted Root certificate first, then any Intermediate certificates, and lastly, install your wildcard certificate into the key ring file.

I open the Domino Server Certificate Administration (CERTSRV.NSF) database on Kakadu, then click on Install Trusted Root Certificate into Key Ring.


In the Install Trusted Root Certificate form that opens, I make sure the path to my key ring file is correct (this should autofill for me).˙ A label is required, so I enter a label appropriate to the cert I'm installing.˙ I also select Clipboard for the certificate source, and paste the certificate into the form.˙ Lastly, I clicked the Merge Trusted Root Certificate into Key Ring button.


A confirmation window appears, which reads the certificate data and presents it in a human readable format.˙ Everything looks correct, so I click OK.


In this case, the Trusted Root certificate I just attempted to install was already in the key ring.˙ No problem.˙ I just move on to the install any other trusted root/intermediate certificates I may need.


Again, I select Install Trusted Root Certificate into Key Ring.


And again, I verify the path to my key ring file, enter an appropriate label, paste the certificate into the form, and click the Merge Trusted Root Certificate into Key Ring button


Again, a confirmation pop-up appears and everything looks fine.˙ I click OK.


This time, I see that I did not have this certificate in the key ring yet, so it's good that I did this.˙ Having this intermediate certificate installed completes the certificate chain from the trusted root CA, through the intermediate certificate, and then to my wildcard SSL certificate.


Now I'm finally˙ able to install my wildcard certificate into my key ring file.˙ This time, I choose Install Certificate into Key Ring.


Again, I verify the path to my key ring file.˙ This time, however, I don't need to enter a label.˙ I still select the Clipboard option, paste the certificate into the form, then click the Merge Certificate into Key Ring button.


A confirmation dialog appears, and it's important to verify everything's correct.˙ It all looks good, so I click OK.


WOOHOO!! I've merged a wildcard certificate into my key ring file! Click OK.


Now you can configure domino for SSL as you would before.˙ Configuring SSL via web configuration or internet site documents is no different with wildcard certs than single-server certs.˙ To use the wildcard certificate on a different server, I only need to copy my key ring file (wildcard1024.kyr) and a stash file (wildcard1024.sth) located in Kakadu's data directory to the data directory of another Domino server.

Additional Notes:

Because this is a wildcard certificate, you need to take precautions to keep the certificate secure.˙ Of course, you should be protecting your file system from inappropriate access anyway.
I chose to use the clipboard method to merge certificates into my key ring file.˙ The other option is to specify a file (e.g. TrustedRoot.crt, DigiCertCA.crt and your_domain_name.crt).˙ Both options work equally well.˙ This is a personal preference.
I chose to map a drive to my Domino server's data directory.˙ The reason I did this was to avoid having to later copy my key ring file (wildcard1024.kyr) and stash file (wildcard1024.sth) up to my Domino server.˙ Again, a personal preference thing.˙ If you don't have a windows server, you could possibly mount a samba share, or just do everything with your local Notes client and copy everything up when you're done.˙ Personal preference again.
Now that I have a wildcard certificate, I'll store both the .kyr and .sth files in a highly secured database in Notes for safe keeping.˙ I also document when the certificate will expire in a central change managment database, then add a reminder on my personal calendar to send me a reminder a month or two prior to the expiration date, so I don't have any expiration surprises.
Lastly, the gobbledy gook text above for the certificates is not legit.˙ It's fictitious, but I think the screen shots are a fair representation of the process you'll encounter if you choose to configure a wildcard certificate in Domino.
An extra word of caution:
Depending on your browser, Wildcard certificates may work at only one domain level only.˙ For instance with my *.wustl.edu certificate, I can secure any website whose FQDN is in the format of domainlevel3.wustl.edu (e.g. kakadu.wustl.edu, dipperu.wustl.edu, etc.).˙ Regardless of the browser, these domain names will all have a valid certificate chain.˙ Things get trickier if I try to secure a website whose FQDN is in the format of domainlevel4.domainlevel3.wustl.edu (for instance, www.kakadu.wustl.edu).˙ www. is now a fourth level domain name, and my wildcard is specifically registered as *.wustl.edu, not *.*.wustl.edu.˙ Mind you, the last I checked, Firefox, Opera, and Mozilla had no problems applying a wildcard certificate to multiple levels in this way, but Microsoft IE and Safari throw warnings to the end user when they encounter this.

Applies to Notes Versions: 6
Last Modified: February 25, 2008