Domino on Linux/Unix, Troubleshooting, Best Practices, Tips and more ...


Daniel Nashed


Important: In Domino V12 certstore.nsf is the recommended way for TLS/SSL server certificates

Daniel Nashed  22 July 2021 07:41:53

Domino 12 introduces a new architecture for certificate management that provides improved flexibility, functionality, and security.

Due to those enhancements and details in the SNI handling, the older kyr cache can't handle lookups for DNS names.

The improved mapping can only work with the new TLS Cache which has been introduced in Domino V12 with many improvements -- the main features are listed below.

This means in consequence that SNI (Server Name Indication) and client certificate authentication will only work using the new functionality described below.

So for proper SNI handling and for client certificate authentication you have to reconfigure using the new functionality.

HCL strongly recommends to move to the new functionality in Domino V12 in general!
Once you updated to Domino V12 you will see the following log message when starting HTTP:

TLSCache-HTTP: The Certificate Store database (certstore.nsf) is not available on this server. Consider running the CertMgr task to create this database to enable enhanced TLS certificate management.
Cert Manager is not loaded or configured

It really makes a lot of sense to move to the new functionality also for many other reasons.

Let me outline again the main improvements and also show how to import kyr files
  • Securely storing TLS Credentials (key + leaf cert + intermediates + root cert) in certstore.nsf)
  • Domain wide easy to use, modern UI database
  • It's not just for ACME/Let's Encrypt operations! It also supports manual certificate import and relieves you from using command-line tools like OpenSSL and kyrtool.
  • Easier trusted root central management without the need to look into kyr files. There is a separate view and form for trusted roots in certstore.nsf
  • Support for ECDSA and RSA keys in parallel
  • Full support for SAN name lookups
  • Full support for wildcard certificate lookups
  • On the fly update of TLS Credentials when the database changes

Here are the steps needed to get started with cerstore.nsf and how to import your existing kyr files automatically.

The new task has been really designed to make certificate operations easier. This includes the migration to the new functionality.

For more details check the OpenNTF session and slides i blogged about earlier and which is available as a joint session from OpenNTF and the HCL Software Academy.

Here is a screen shot to show part of the new UI.
I am using CertMgr since Domino V12 was released on my production servers with ECDSA and RSA keys.
And also with Let's Encrypt integration with my DNS provider Hetzner.

If using Let's Encrypt the certificates auto renew after 60 days and are available immediately thanks to the new TLS Cache.

Image:Important: In Domino V12 certstore.nsf is the recommended way for TLS/SSL server certificates

1. Configure CertMgr

To configure CertMgr, choose one Domino 12 or higher server (Win64 or Linux64) as the CertMgr server. This server is often the domain administration server.

Run  the following command on that server to create the certstore.nsf database and initialize the CertMgr task:

load certmgr

Add CertMgr to the servertasks notes.ini parameter or schedule it to run in a program document to ensure that it always runs.

2. Configure certstore.nsf on Web servers

Run load certmgr on Domino 12 Web servers in the domain.

The certmgr task automatically connects to the CertMgr server and creates a replica of the certstore.nsf database on the Web servers.

The CertMgr on these servers operates as a CertMgr client and replicates certstore.nsf automatically with the CertMgr server.

After certstore.nsf is present on a server, the TLS cache is loaded automatically when you start any internet server task like HTTP.
Any update to the certstore.nsf database on a server dynamically reloads the TLS cache.

3. Import existing kyr files

Use CertMgr to import TLS Credentials for existing kyr files.

To import all kyr files for a server run:

load certmgr -importkyr all

This command creates a TLS credentials document for each configured kyr file (server doc and internet sites if configured).

You can also import individual kyr files:

load certmgr -importkyr my-server.kyr

Support for trusted roots

The import functionality is only intended for the TLS Credentials (key, leaf certificate, intermediate certificates and the matching trusted roots).

Client certificate authentication requires the trusted root of the issuing CA for all client certificates which are intended to be authenticated.

Importing selected trusted roots is intended as a manual one time operation to review trusted roots which are still required.

You can export trusted roots with the kyrtool command line tool in the following way:

Windows example:

cd /d d:/domino/data

c:/domino/bin/kyrtool.exe show roots -v -k keyfile.kyr

Linux/AIX example:

cd /local/notedata

/opt/hcl/domino/bin/kyrtool show roots -v -k keyfile.kyr

For details how to import trusted roots and assign them to TLS Credentials check the following help topic:

Here is an example imported trusted root which you can just assign to a TLS Credentials document.

Image:Important: In Domino V12 certstore.nsf is the recommended way for TLS/SSL server certificates



    • [IBM Lotus Domino]
    • [Domino on Linux]
    • [Nash!Com]
    • [Daniel Nashed]