Add a Manual Keyring to the Certification Store

Mindwatering Incorporated

Author: Tripp W Black

Created: 06/29/2021 at 08:50 PM


Domino Upgrades / Installations
Software (Re)Configuration

Some certificates are 90 day LetsEncrypt, which we migrated from the old Nashed app, and our "sidekick" app.

However, others are traditional certificates with domain/certificate registrars. They have multiple names, and only some run on HCL Domino -- are Domino-based web sites.
They were created from an OpenSSL CSR and mydomain.key files, bought at the SSL registrar, and the mydomain.crt file(s) are converted/migrated to the traditional Domino keyring mydomain.kyr, via the IBM Keyman utility.

Option 1 - Task using KYR file:
How do we import the traditional certificates and with their keys inside the kyr files?

If you just create a document and fill out the fields, you will not be able to add the private mydomain.kyr key file. You will always see an "invalid private key" message.
To fix, remove this manually created document, via the Delete button. We have to do an import.

The process to do the import properly is:

A. Prerequisites:
1a. Confirm the name of the kyr file to import. e.g. mydomain.kyr .
1b. Confirm the file is in the /local/notesdata folder, on the "primary" Domino Certification Manager server. The primary server is the one running the Certificate Manager (certmgr) service.
(We haven't tried this on a "secondary" Certificate Store replica which is not running the certmgr service.)

You do not have to shutdown the already running certmgr task.

B: Implementation:
1. On the primary server. issue the certmgr import command in the Domino console.
a. Domino Administrator client --> --> Server (tab) --> Status (sub-tab).
b. Click the green Live button (top right).
c. In the Domino Command field, enter the following command, and click Send.
> load certmgr -importkyr mydomain.kyr

Watch the output. It should look like this:
06/29/2021 08:11:04 PM Remote console command issued by Tripp Black/Mindwatering: load certmgr -importkyr mydomain.kyr
06/29/2021 08:11:04 PM CertMgr: Imported KeyRing file [mydomain.kyr]
06/29/2021 08:11:04 PM CertMgr: KeyRing file import result - Success: 1, Already exist: 0, Error: 0
06/29/2021 08:11:04 PM CertMgr: Shutdown

That's it. A new certificate document is created in the Certificate Store application.
2. If desired, edit the newly created document and add the CSR.

C. Renewal a Year Later:
Verify the root and chain are still valid. If the chain is the same, we can paste just the new certificate. Otherwise, we can paste all of them, or all but the root.
(If not pasting the root, the root should be selected on the Security/Keys tab.)

1. Open/edit the TLS Credential that has been renewed.
2. Click the Manual tab.
3. Under the label "Paste - Certificates & Roots (PEM)", paste the contents of the domain.crt file received from the registrar.
The PEM file being pasted should be in the order of the server crt/PEM first, and then the signing bundle
4. Save and close, hit Submit, and wait about 30 seconds, for certmgr task to automatically update the TLS Credential document.
As of Domino 12.0.2, we noticed that the certificate update cleared the common name (CN) field on the TLS doc within the cert store document. We did not add it, and the new cert was available within seconds.

Option 2: Import using the Private KEY, CRT, and PEM (root and intermediary) Files:

A. Create a combined pem file with the following in this order (top to bottom):
domain-chain.pem (contains the intermediate, and then the top root)

$ pwd
$ cat domain.key domain.crt domain-chain.pem > combinedimport.pem
$ mv combinedimport.pem /local/notesdata/

B. In the Domino administrator console
Admin client --> Server (tab) --> Server console (left menu)
Click Live button

Enter the following command:
> load certmgr -importpem combinedimport.pem

According to the HCL Domino 12.02 documentation the order of the key, crt, and chain cts is not important. However, we have success with this "standard" order.
For security reasons, the combinedimport.pem file is automatically removed from the /local/notesdata folder.

Afterwards, you can view the newly created TLS document in the Certificate Store (certstore.nsf) app.
In order for the new certificate to go into effect, we had restart the http service.
> tell http quit
< wait until we see the HTTP shutdown message >
> load http

previous page