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


Daniel Nashed


How to create exportable TLS Credentials with Domino 12.0.1

Daniel Nashed  25 November 2021 06:59:57

CertMgr Domino 12.0.1 introduces export/import functionality. You can import existing PEM, PKCS12 and kyr files.

If you mark them to be exportable during import or create an exportable key, you can export it later.

This works with manual and also ACME (Let's Encrypt) flows.

How does this work?

In Domino 12.0 the certstore.nsf introduced a secure encryption for private keys with the CertMgr server and all servers listed in "Servers with access".

The internal format is PEM. But it can be only decrypted for the configured servers -- The private key cannot be exported!

In Domino 12.0.1 an exportable key can be created or imported.

This private key is stored separately in encrypted PEM format (exportable key field in Security/Keys tab).

The PEM private key is encrypted with AES 256 using a pass phrase.
A secure password/pass phrase is required for all create and export operations.

The export functionality supports PEM and PKCS12. Both are using up to date AES 256 encryption.

Some older applications (specially Java) are not supporting those more modern formats.
There is a notes.ini parameter to switch back to the the older,less secure encryption via notes.ini PKCS12_EXPORT_LEGACY=1.
This notes.ini parameter would be needed on the client for a legacy export.

By the way: OpenSSL 3.0 comand-line also uses the same new encryption by default. And if you try to export/convert with OpenSSL 3.0 you need a -legacy option.


The new functionality is only available if you have a Notes 12.0.1 client installed. The functionality is implemented in the template in combination with a new C-API call in the Notes client.

Let's create a private key and use it in a manual flow.

1. The private key is created and encrypted in internal format to be used by the CertMgr server and the "Servers with access". and also with an encrypted exportable PEM formatted key.

You can create RSA or ECDSA keys in the same way.

Image:How to create exportable TLS Credentials with Domino 12.0.1

2. Now that the key is created in an exportable format, you can either use it in an ACME flow.

Or you can use it in a manual flow as shown below.

When you switch to manual, CertMgr creates a CSR, when you submit the request.

Image:How to create exportable TLS Credentials with Domino 12.0.1

3. Once the operation completes, you find the CSR in the TLS Credentials document.

A "Copy CSR" action shows up to allow to copy the CSR to the CA of your choice.

4. When your CA signed the request, you can paste the certificate using the "Paste Certificate" action and "submit" the request again.

Before submitting the request make sure to select the servers which should be able to use the new TLS Credentials document.


The pasted certificate should contain the leaf certificate and all intermediate or root certificates, which are not in the certstore.nsf trust roots list.

In case the root and intermediate certificates are among the trusted roots, the chain is automatically completed!

This also works if your certificate list is not sorted in "leaf" to "root" order!
Also duplicated or not matching intermediate certs are filtered out automatically.

The logic finds the leaf certificate for your private key and can handle the certificate chain for you.

This auto chain completion and sorting functionality is already available in Domino 12.0 and now also works with the new export/import functionality.

Image:How to create exportable TLS Credentials with Domino 12.0.1

After submitting the request your ready to use TLS Credentials document should look like this.

Image:How to create exportable TLS Credentials with Domino 12.0.1

The TLS Cache introduced in Domino 12.0 will automatically detect new or updated TLS Credentials and reloads the cache.

Additional tip: In Domino 12.0.1 you can check loaded TLS Credentials via

load certmgr -showcerts


The export/import functionality completes the existing functionality and is a great improvement in Domino 12.0.1.

The C-API call used in the template is in a script lib and could be used for own integration projects.

The call also uses the auto chain completion and auto chain sorting!



    • [HCL Domino]
    • [Domino on Linux]
    • [Nash!Com]
    • [Daniel Nashed]