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


1Uwe Brahm  23.07.2021 11:53:20  Important: In Domino V12 certstore.nsf is the recommended way for TLS/SSL server certificates

Hi Daniel,

Thanks for shining some more light onto the importance of using the all new certmgr from now on with Domino 12.

Three Questions:

1) I see warning or error messages after my importing all of our *.kyr files and now the system reports for Http e.g.::

TLSCache-HTTP: Cannot add host entry [] to cache -- Maximum number of entries reached (13)

Similar messages can be seen as I have also IMAP and DIIOP enabled on my servers

TLSCache-imap: Error adding hostname for TLS Credential for server []

2) Is it save to remove the *.kyr files from the servers' data directory after importing them?

3) If the answer for 2) is yes, should/can I remove the filenames of my *.kyr from the site configuraton documents?



2Daniel Nashed  24.07.2021 16:20:41  Important: In Domino V12 certstore.nsf is the recommended way for TLS/SSL server certificates

Hi Uwe,

Oooh .. this is a bug!

The TLS cache calculates the number of host enrties needed.

There are two fields in the TLS Credentials document "Hostname" and "HostnameIDN".

The IDN field should be only filled when at least one IDN is used. But it turns out that the form in some cases writes a textlist with an empty entry into the document.

An empty string in a textlist still has one entry. If you have multiple SANs the number of host entries is too small and not all entries are loaded into the cache.

A work-around is to remove the empty HostNameIDN field from the document.

The 13 entries in your case are the 3 TLS Credentials documents + 10 which is always added on top.

So this will only occur if you have multiple TLS Credentials for one server with many SANs and this odd behavior of the form adding the empty string.

The fix should be to always use the "Hostname" field for calculating the entries.

In my TLS Credentials documents I have a mix of documents which are correct and some that have this empty field.

It looks like it is happening for manual operations or imported keys. All my ACME created documents look good.

There is already a SPR. So no support ticket needed.

-- Daniel



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