 |  | | Apr 21, 2021
(updated Aug 7, 2021)
By Lance Zakin, HCL CASA, CAAD
Notes and Domino
NotesMail - HCL BP | This article provides instructions how to configure a SSL certificate on websites running on a Domino 12/11/10/9 web server. SSL certificates can be used with Domino to protect one website (standard protection), protect multiple websites (UCC/SAN SSL) or protect all subdomains (Wildcard SSL). In early 2015, web browsers such as Google Chrome stopped honoring SHA-1-dependent TLS certificates due to security concerns. | |
|
And SSL providers started only offering SHA-2 certificates. The Domino Server Certificate Admin database does not allow importing SHA-2 certificates. Because of this limitation, OpenSSL and KYRTool are now used for generating the keyfile with a SSL Provider (CA) SHA-2 certificate. Note: Domino 12 includes a new native feature called Certificate Manager, a server task (CertMgr), which can optionally be used instead of steps below for easier SSL maintenance. The Certificate Store DB (certstore.nsf) has replaced the legacy Domino Server Certificate Admin DB (certsrv.nsf). The new ACME feature allows free SSL certifcates and automated certificate renewals with Let's Encrypt SSL provider. The web page you are reading is using this free and automated SSL renewal feature with a TLS certificate and ECDSA (NIST P-384 curve name) encryption which is the newer and equal if not better than RSA (4096 key size) encryption. And web pages using ECDSA (NIST P-384) load faster when compared to RSA (4096).
1. Download and install Win64 OpenSSL Light. Note: The instructions below have been tested with Win64 OpenSSL v1.1.1k Light.
2. Download and install 32-bit KYRTool for Windows from a download site below:
A. Copy the kyrtool.exe file to your Notes program folder on a Windows desktop. Note: Since Domino 10 this program is included in the server program folder.
Skip to step 7 if you already generated a certificate signing request (CSR) via a 3rd party web server (i.e. Apache, IIS) and acquired an SSL/TLS certificate from a SSL provider (CA). i.e. GoDaddy
3. Generate RSA private key using OpenSSL. Start "Win64 OpenSSL Command Prompt".
Win64 OpenSSL Command Prompt: openssl genrsa -out server.key 4096
Win64 OpenSSL Command Prompt: type server.key
4. Generate a certificate signing request (CSR) using OpenSSL. Start "Win64 OpenSSL Command Prompt".
Win64 OpenSSL Command Prompt: set OPENSSL_CONF=
Win64 OpenSSL Command Prompt: openssl req -newkey rsa:4096 -keyout server.key -out server.csr
Win64 OpenSSL Command Prompt: type server.csr
5. Acquire an SSL/TLS certificate from a SSL provider (CA). i.e. GoDaddy
Copy the certificate request (server.csr) from above into a SSL provider (CA) web form and select a SHA-2 algorithm (SHA-256, SHA-384, SHA-512). You will receive a PEM or CRT certificates seen below. Note: You may also receive some of the CA's intermediate root certificates.
Command Prompt: type server.pem
[or]
Command Prompt: type server.crt
6. Concatenate the server's private key (server.key) and the certificates into a single file. See example below.
Command Prompt: type server.key server.crt intermediate.crt root.crt > server.txt
SKIP TO STEP 9.
7. Skip to step 8 if you have a PEM or CRT file. Otherwise, start "Win64 OpenSSL Command Prompt". Export the certificate from the PFX file [using the SSL cert password] to a PEM file using the command below. The command below will prompt for the SSL cert password (aka import password). Note: The folder path will vary due to user performing this task, so this is an example. A PFX file, also known as PKCS #12 , is a single password protected certificate archive that contains the entire certificate chain plus the matching private key. Essentially it is everything that any server will need to import a certificate and private key from a single file.
Win64 OpenSSL Command Prompt: openssl pkcs12 -in c:\users\lzakin\wildcard_com.pfx -out c:\users\lzakin\server.pem -nodes -chain
8. Open the PEM or CRT file in notepad and save as a txt file. i.e. c:\users\lzakin\server.txt
9. Verify the txt file using the KYRTool. Open a command prompt in the Notes program folder and use the command below. Note: The folder path will vary due to user performing this task, so this is an example. It should display "Successfully read 2048 bit RSA private key" and 5 more informational lines.
Command Prompt: kyrtool.exe verify "c:\users\lzakin\server.txt"
10. Create a new keyring file. Open a command prompt in the Notes program folder and use the command below.
Command Prompt: kyrtool "=c:\Program Files (x86)\hcl\notes\notes.ini" create -k "c:\Program Files (x86)\hcl\notes\data\keyring.kyr" -p password
11. Import the keypair and SSL provider (CA) signed certificate. Open a command prompt in the Notes program folder and use the command below. Note: Is should display at least 3 lines which include words "Successfully read" and "succeeded".
Command Prompt: kyrtool "c:\Program Files (x86)\hcl\notes\notes.ini" import all -k "c:\program files (x86)\hcl\notes\data\keyring.kyr" -i "c:\users\lzakin\server.txt"
12. Optional: Examine the resulting keyring file.
Command Prompt: kyrtool "c:\Program Files (x86)\hcl\notes\notes.ini" show keys -k "c:\program files (x86)\hcl\notes\data\keyring.kyr"
Command Prompt: kyrtool "c:\Program Files (x86)\hcl\notes\notes.ini" show certs -k "c:\program files (x86)\hcl\notes\data\keyring.kyr"
13. Rename the keyring.kyr and keyring.sth file to the key file name configured in the Domino Directory Internet Site document or Server document. i.e. MyKeyFile.kyr, MyKeyFile.sth
14. Remote into the Domino web server and open the Domino server data folder. Backup the existing key files if this is a SSL renewal. i.e. MyKeyFile_OLD.kyr, MyKeyFile_OLD.sth
15. Copy the KYR and STH keyring files from the Notes data folder on your desktop to the Domino server data folder.
16. Issue console command below on Domino server.
Domino Command: restart task http
Reference Sources
Generating a keyring file with a third party CA SHA-2 cert using OpenSSL and KYRTool on a Windows workstation
Previously, Domino servers used the Domino Server Certificate Admin database to manage keyrings and server certificates. However, this database does not allow for importing SHA-2 certificates. It is now recommended to only use SHA-2 certificates for SSL due to security concerns. Because of this limitation with the Server Certificate Admin database, OpenSSL and KYRtool are now used for generating the keyfile with a third party CA SHA-2 certificate.
Generating a keyring file with a self-signed or third-party certificate
To set up SSL on your server, you need a key ring containing a server certificate from an Internet certificate authority. You can use a self-signed certificate or one from a third-party certificate authority (CA). A server certificate is a binary file that uniquely identifies the server. The server certificate is stored on the server's hard drive and contains a public key, a name, an expiration date, and a digital signature. The key ring also contains root certificates used by the server to make trust decisions. Use OpenSSL (available on the Internet) and KYRTool (installed with Domino) to generate a keyring file for Domino servers to use. For instructions, see the article Generating a keyring file for Domino on the HCL Software Support site.
Installing and Running the Domino keyring tool
This command line tool can be used to view keyring files, create keyring files, and import certificates of all kinds into keyring files. It uses the Notes C API and can be run against any 8.5.x or 9.x IBM Notes/Domino installation, but can only be used with SHA-2 certiifcates in 9.x, and can only be used to import and delete trusted roots with interim fix 9.0 IF6 or 9.0.1 FP2 IF1.
| B |