Creating SHA-2 4096 SSL Certificates for Domino

I’ve been doing a lot of work recently re-creating SSL certificates for customers who have SHA-1 or who want stronger certificates, mostly because so many sites are now failing validation in standard browsers because of SHA-1.  IBM have published several pieces of documentation on how to do this but I wanted to share my bullet list on the quickest and simplest way I have found .  It’s not hard there are just lots of new steps.

Firstly you need to know that SHA-2 support only really started with 9.0.1 FP3.  That means the Domino Admin client you are going to use to do this work must be at that level (yes there are hotfixes for FP2 but go with the latest Fix Pack on your client).

You also need to know that NO Domino 8.5x server will be able to use the keyfile you create, it simply doesn’t have the cryptographic understanding to decode SHA-2.

Finally if you use the CA process to generate internet certificates you will need to upgrade the server running that process to 9.0.1 FP3 too.

Oh and you’re also not going to be using the Domino Server Certificate database to do this at all.

  1. Download 9.0.1 and FP3 for Domino Administrator and upgrade your client. Fix pack 3 is in Fix Central and 9.0.1 is on the IBM download site (CIQ91EN)
  2. Download the latest “lite” version of OpenSSL from here and install it on your Windows machine where you have Domino Administrator running.  I installed it in c:\openssl for example
  3. Download the kyrtool from here and copy the executable to your Notes program directory
  4. Set the environment variable for OpenSSL by typing in a command prompt
    Set OpenSSL_Conf=c:\openssl\bin\openssl.cfg (or whatever your path is)
  5. Now we create our keypair using OpenSSL.  From C:\OpenSSL\bin directory type
    “openssl genrsa -out server.key 4096”
    obviously you can use any name if you don’t want to use server.key and you don’t have to create a 4096 strength keypair.  When finished you should have a file in that directory called server.key
  6. Now you have your keypair you need to create a CSR to send to the certificate authority
    openssl req -new -sha256 -key server.key -out server.csr
    the server.key name must match what you created in step 5 so if you used a different name there you need to use that name here. Similarly your server.csr filename can be anything you like.  When you enter this command be prepared to answer all the questions about the certificate you want generated including the common name etc.  The CSR this generates will be uploaded to your CA (Verisign, GoDaddy, Thawte, whoever) and your SSL certificate created based on the answers you give to those questions.
  7. Now we need to create a keyring file ready to add to certificate into when the CA sends it back.  Go to your Notes program directory and run the kyrtool
    kyrtool  create -k c:\notes\data\keyring.kyr -p <passwordyouwanttouse>
    again the keyring.kyr file can be called anything you like.  Once run you should have both a keyring.kyr and keyring.sth files in your data directory
  8. By now your CA should have sent you your certificate as well as some trusted and intermediate root certificates for their issuer.  We are going to create a single text file that contains the server.key we generated in step 5, the SSL certificate the CA just sent us (usually a .crt or .pem file) and any intermediate or root certificates the CA needs us to use.  Doing this is very simple.  Go to your c:\openssl\bin directory (the one where your server.key file was created) and enter
    type server.key server.crt intermediate.crt root.crt >server.txt
    note all the filenames will be specific to whatever you were sent by your CA.  If you were sent a single bundle then you would use server.key bundlename.crt for instance
  9. To verify your server.txt is created successfully your can validate it using the kyrtool.  Go back to your c:\notes program directory and type
    kyrtool verify <path to server.txt>
  10. Now we import our server.txt will all the certificates into our newly created keyring file we created in step 7
    kyrtool import all -k c:\notes\data\keyring.kyr -i c:\openssl\bin\server.txt
    again your filenames and paths may vary depending on what you chose

And that’s it.  You now have a keyring (kyr) file and stashed password file (sth) you can copy to you Domino 9.x servers and use.  If you want to validate the keys are correctly in the file then you can again use the kyrtool

kyrtool show keys -k c:\notes\data\keyring.kyr  AND

kyrtool show certs -k c:\notes\data\keyring.kyr

IBM’s documentation on the process and the supported platforms is here and here

12 thoughts on “Creating SHA-2 4096 SSL Certificates for Domino

  1. In a similar position, a lot of third party certifcate providers (GoDaddy for example) are no longer supporting SHA-1 on renewed or new SSL certs.

    One note. You don’t have to upgrade your Admin client for the steps above from 2-10 (it actually works fine on any 8.5.3 client, haven’t tested any earlier). I don’t think it actually needs the admin client installed either, just a notes client.

    The instruction to upgrade the client from IBM relates to installing the certs using an updated server certficate admin database, (which I haven’t seen published yet)

    The keyfiles just need to reside on a 9.0.1 FP3 server.

    • Thanks. Any chance you can get IBM to fix their documentation then because that’s very unclear (re. Admin client version , I assumed kyrtool needed the updated DLLs).

      Similarly the FAQ clearly says that the keyring will work on Domino 9.0 or later not 9.0.1 FP3

      “Q1: Can I import the SHA-2 cert on a Domino 9.x server and then use that keyring on a Domino 8.5.x server?
      No. Domino 8.5.x lacks the cryptographic infrastructure for SHA-2. This means if you import the cert using 9.x and the Interim Fix and and KYRTool described above, you can use that keyring on a Domino 9.0 or above server, but not on a Domino server pre-Domino 9.0.

  2. Thanks for this!
    In step 7, shouldn’t the command be:
    “kyrtool create -k c:\notes\data\keyring.kyr -p “?
    As always, thanks for thinking of everyone and posting this!

  3. In step 7 you forgot to supply the command ‘create’ for the kyrtool, the correct statement is :
    kyrtool create -k c:\notes\data\keyring.kyr -p

  4. Gab, thanks for sharing this! Do wildcard certs work any better now than in previous versions of Domino? It was a very complex process last time around…I’m not looking forward to that again!

    • Wildcards shouldn’t be a problem at all – I use them all the time but yes if the issue was created the request using the Server Certificate Requests database, well we don’t use that anymore. Wildcards are great esp if you’re using Internet Site docs because you can only have one keyfile port SSL port and that way multiple hostnames can use it.

      Do you remember what caused all your pain last time?


      • Ah, that is good news!

        I believe there were 2 issues that caused the process to take days rather than minutes: One issue was definitely the certificate request process (we already had the SSL wildcard certificate). I think the second issue may have been that our certificate provider had 3 root certificates rather than the usual (I assume) 2 roots, and it took some time to get them in there just right.

        Also, of course, our provider gave us a certificate suitable for IIS or something other than what IBM expects, so the certificate had to be converted. I remember having to find a work-around for the work-around during that process as well. 😉

  5. Hello Gabriel – I have created several SHA-2 2048 SSL Certificates for Domino with the Server Certificate Admin (certsrv.nsf) database. I works fine here.

  6. Remember to Right-click command prompt, and choose Run As Administrator. Then you can run the kyrtool commands.

Comments are closed.