Requirements
To implement SHA-2 certificates on a Domino server you need the following:
- Domino server version 9.0.1 FP3 or higher
The server we will install the certificate on. - Notes client (preferably admin client) version 9.0.1 FP3 or higher
Used for generation of the certificate. - kyrtool.exe
The new keyring tool for generating Domino keyring files - OpenSSL for Windows
Preparations
Install OpenSSL for Windows
OpenSSL can be downloaded from the following site:
https://slproweb.com/products/Win32OpenSSL.html
You can download the 32 or the 64 bit version (up to you). The "light" version is good enough.
The installation is straight forward. After the installation set the som needed environment variables using the following commands:
C:\CertFolder>set OPENSSL_CONF=c:\OpenSSL-Win64\bin\openssl.cfg
C:\CertFolder>set RANDFILE=C:\Users\ove\Desktop\.rnd
For convenience you can also add the OpenSSL install folder to your PATH.
Download kyrtool.exe
Kyrtool.exe is especially written to handle SHA-2 certificates on a Domino 9.0.1 FP3+ server. You need to download the tool from the page below.http://www-933.ibm.com/support/fixcentral/swg/selectFixes?parent=ibm~Lotus&product=ibm/Lotus/Lotus+Domino&release=9.0.1.2&platform=All&function=fixId&fixids=KYRTool_9x_ClientServer
Copy the downloaded file to the program directory for your Notes client. The program needs the Notes DLL's to work.
Procedure
Generate a keyring file
We need a keyring file to store the keys and certificates.
Note that even if you could create this file on your Domino server the server may crash when trying. Use your Notes client!
Command:
C:\IBM\Notes>kyrtool create -k C:\CertFolder\<keyring file name.kyr> -p <keyring password>
Generate a "key" for the server
Use OpenSSL to generate a key that identifies your server.
Command:
C:\CertFolder>c:\OpenSSL-Win64\bin\openssl.exe genrsa -out <keyfilename>.key 4096
Generating RSA private key, 4096 bit long modulus
............................................................................................................................++
..........................................................................................++
e is 65537 (0x10001)
After the key is created you can watch it's content.
Command:
C:\CertFolder>type <keyfilename>.key
-----BEGIN RSA PRIVATE KEY-----
MIIJKgIBAAKCAgEAwygi8FlxJOsKlVS/4AbVZpvY3TQ+hEAEsCqZu9yVg9Je7fUo
1h159HleuANfyms1tCg8nYCblXa+lj42pYgz+IfdcoyUuuv7E6vZAm7PDNBeTjN/
xD/PbXeh6HCWPPHznYxv/dE1YSck4b4BtjqH5AG6512LBmqLq8nSDFDi7E7e5Hwa
...
...
2VCtlxqeztqM66LkqDL4QWmazvrSdLiSxmJn8gr9tpM4CkpUiYvaq9pqB6kQ241n
QBrnngktGz6t06xvcjRz3PKhZkGS2jXJ79dMn+JV34WlZNC6vyzwBymJuwDppeEa
jVBhLeSJvYiZenjOfBscxZp8YxmFALzk4QKUhFLgIYeRkgNp/tt41XAb1oIPKAgm
Hks1Xrl1UOhOCcpsQjMkDVIB1U9VxQG1pE2pEigzoHDxicEqrq1U6w/6kjb9SQ==
-----END RSA PRIVATE KEY-----
Create a certificate signing request (CSR)
Command:C:\CertFolder>c:\OpenSSL-Win64\bin\openssl.exe req -new -sha256 -key <keyfilename>.key -out <keyfilename>.csr
Details for your certificate are required. You need to provide at least the following:
D:\IBM>d:\ibm\domino\kyrtool import all -k d:\IBM\v-man.kyr -i d:\IBM\star_v-man_no.pem
- Country code
- Locality name (city)
- Organization name
- Common name (server fully qualified host name)
- Email address (common email address for company)
Generate a signed certificate for the CSR
The is the part where you buy a certificate from a Certificate Authority (like DigiPlex, RapidSSL or Verisign). Most often they let you decide on a suitable certificate. You must then pay for the certificate before they let you generate a certificate by:
- Specify the server where the certificate is to be used (Domino)
- Pasting in the CSR
The generation may take a while, so be patient...
When the certificate is ready for download also remember to download the root and intermediate certificates for your new certificate. They are needed in the keyring file to form the trust chain.
Try to download the certificates in PEM format (*.pem). Preferably all the certificates in one file.
Add the certificates to the generated keyring file
Collect all the certificates and the key file in the same txt-file
The simplest way to make the keyring work is to install all certificates at the same time. To accomplish this we need to add all the certificates and key (the one we generated for the server) to a file.
The certificates are nothing else than a text-file, so use Notepad++ or similar to add them all to the same file. The following files must be present:
- The server key
- The signed certificate
The certificate you got from the Certificate Authority. - The intermediate certifiate
Note that there may be more than one of these... - The trusted root certificate
Add the key/certificates to the keyring file
Install the key/certificates to the keyring file using the following command:
C:\CertFolder>d:\ibm\notes\kyrtool import all -k C:\CertFolder\<keyring>.kyr -i C:\CertFolder\<filename_for_all_certs.txt>NOTE! Use absolute paths or you will get a "file not found" error!
You should see the following output:
Using keyring path 'C:\CerfFolder\<keyring>.kyr'
Successfully read 4096 bit RSA private key
SECIssUpdateKeyringPrivateKey succeeded
SECIssUpdateKeyringLeafCert succeeded
Verify the content of the keyring
To verify the content of the keyring file enter the following commands.To list the certificates:
C:\CertFolder>c:\ibm\notes\kyrtool.exe show certs -k C:\CertFolder\<keyring>.kyr
To list the keys:
C:\CertFolder>C:\ibm\notes\kyrtool.exe show keys -k C:\CertFolder\<keyring>.kyr
Both commands will list the certificates/keys.
Install the certificate on a Domino server
Activate HTTPS for server
By default Domino does not accept requests on the HTTPS port (443). You can activate this by setting the field "SSL port status" to "Enabled" in the server document, in the pane "Ports - Internet ports - Web".After this change the Domino server has to be restarted.
Copy the keyring file to the Domino data directory
Copy the keyring file you created to the Domino data directory. Remember to also copy the "<keyring>.sth" file. This file stores the password for the keyring file and is needed for the certificate to work.
Edit the internet site document
This procedure assumes that you have activated "Internet sites" for the server in the server document.
Edit the internet site document that will use this certificate.
- Enter the name of the keyring file in the "Key file name" field under the "Security" pane.
- Add the fully qualified host name and the IP address to the field "Host names or addresses mapped to this site".
Note that for SSL/HTTPS to work each site that use SSL/HTTP need to be assigned a unique IP address.
When done editing, restart the HTTP task using the following command:
restart task http
Test your implementation using your web browser (of course).
Good luck!
