How are trusted roots used?

Trusted roots are mainly designed for “root CA certificates”.

Root certificates have multiple use cases in certstore.nsf. The main use case is to be the root certificate you trust. The certificate chain is usually provided by the remote server. They might send the root as well, but the root needs to be in the local trust store to validate it.

Trusted roots are used to complete the chain when you import certificates or also in the ACME flow (for example Let’s Encrypt) when you get the leaf certificate and the chain without the root from the ACME provider. Storing intermediate certificates in the same way is allowed and you get the warning to show that this is not a root certificate. They still work and they are used to auto complete chains in all certificate flows. But they are not actively involved in trust operations. That’s why you get a warning.

The trusted roots in cerstore.nsf replace the additional root certificate in kyr-files for TLS credentials which are used for example when validating client certificates (HTTPS) or LDAPS outgoing connections. They can be selected as trusted roots. In Trusted Roots in the Certificates/Keys tab.

In addition trusted roots from certstore.nsf can be used in OIDC configurations (idpcat.nsf) and also as trusted roots for CScan/ICAM in cscancfg.nsf.

What does this warning mean: “Last cert in chain is NOT self signed - No root found”

Only complete certificate chains can be validated end to end. If the last certificate in the chain is missing, CertMgr cannot know how many certificates are missing in the chain. If only the last certificate in the chain is missing (root), the certificate is perfectly OK.

Browsers and other devices use their local trusted store to validate the certificate chain with the local trust store copy of the root certificate. It is still recommended to store the full chain so that Domino can send the complete chain.

CertMgr always tries to auto complete the chain on any import operation, to ensure the certificate chain is complete.

In most cases only the root is missing. This isn’t a problem, but the best practice is to ensure the root is part of the TLS Credentials document.

Why is there a warning “Not a root certificate” when an intermediate certificate imported as a trusted root?

Trusted roots are mainly intended to be stored to trust the certificate chain. They can be also used to complete the certificate chains. on import. Therefore it is supported to import intermediate certificates.

The information is just a warning that this isn’t a root certificate which is not used for any trust operation. The chain is always built from the certificate (leaf) with the provided certificate chain. Only the local root is used to trust the certificate chain.

How can I tell CertMgr to try to auto complete the chain when I added the trusted root to certstore.nsf meanwhile?

There is no direct UI operation to re-import. But you can leverage the manual flow functionality.

  • Copy the complete PEM data of your certificate
  • Change the Certificate provider to Manual and note which other provider you had selected
  • Paste the PEM data into the certificate field in the Manual tab
  • Submit the request
  • Wait for the request to be processed and set the Certificate provider back to the original value

Where do I add the trusted roots for an outgoing secure LDAP (LDAPS) connection?

The TLS Credentials entry specified in the server document is used for outgoing TLS connections. Specify roots to be trusted in the Trusted Roots section of the Security/Keys tab in this TLS Credentials document.

The trusted roots available are picked from the Trusted roots in certstore.nsf.

Is creating a TLS credential from scratch using the CertStore “better” than Importing a TLS certificate from a KYR file or does it not matter?

Technically there is no “better” the certificates are the same and they are always stored in PEM format. You can see them in clear text in the TLS Credentials document.

Certstore only supports the KYR file for import only. One of the design goals was to replace the “KYR file format” with the standard PEM format. KYR is an old IBM format using two files. The KYR file itself is encrypted and the encryption key is stored in the STH file.

The .sth file is just encoded and you can run a simple perl script to decode it. When CertMgr reads a .kyr file it will always get the password from the .sth file with the same name. You don’t need to specify it.

HCL recommends to use CertMgr and don’t use KYR files any more. But the new TLS Cache has been implemented to be fully compatible to the old KYR cache and they are both enabled by default. The TLS cache will be asked first. Only if not key is found, the old KYR file cache is asked.

How do I know if the HTTP task is using the TLS credentials in the Cert Store or still using the KYR file specified in the Internet site?

The TLS Cache takes care of finding TLS Credentials. The lookup can be either by DNS name, which is the new preferred way to specify them. So you replace the kyr file name with the DNS name. The new cache also understands KYR file names and uses them as a tag for lookup.

But then the TLS credentials document needs to have the kyr-file name set (which is optional in the TLS Credentials document and intended for this use case). The right way is to always specify a DNS name. The new TLS Cache understands DNS names including wildcard certificates and supports multiple SANs.

The KYR file entry in server doc/internet site are just used as the trigger and the first lookup. When the client supports SNI the TLS Cache will take care to find the right TLS Credentials key entry based on the SANs (Subject Alternate Names) in the certificates.

To enable logging use the following setting:

set config CERTSTORE_CACHELOG=1

This is not a CertStore but TLS Cache log parameter. The parameter is dynamic and you should always set it via “set config”.

TLSCache-Log-http: CacheLookupRequest -> Host/Tag: [*.nashcom.de] RSAHashAlgs: 0x0, ECDSAHashAlgs: 0x0, Key: 1, Cert: 1, OCSP: 1 TrustPolicy: 1 DNList: 0
TLSCache-Log-http: CacheLookupResult: [*.nashcom.de] -> [ECDSA NIST P-256] Flags: 0x0, RSAHashAlgs: 0x1, ECDSAHashAlgs: 0x1, DefaultAssigned: 0 -> Err: 0x0
TLSCache-Log-http: CacheLookupRequest -> Host/Tag: [nashcom.de] RSAHashAlgs: 0x78, ECDSAHashAlgs: 0x78, Key: 1, Cert: 1, OCSP: 1 TrustPolicy: 1 DNList: 0
TLSCache-Log-http: CacheLookupResult: [nashcom.de] -> [ECDSA NIST P-256] Flags: 0x0, RSAHashAlgs: 0x78, ECDSAHashAlgs: 0x78, DefaultAssigned: 0 -> Err: 0x0

In addition with Domino 12.0.1 and higher there is a new CertMgr command to show the TLS Credentials your server uses.

tell certmgr show certs

This should give you a good understanding of the certificates used by your server.

Note: certmgr might not run on your server. The servertask is only required on one server in the domain and takes care of all certificate operations. CertMgr on additional servers run in client mode and would only replicate the database and pull the replica from CertMgr server if not present.

In this case you can show the current information loaded into the cache via:

load certmgr -showcache

The result should look like the following

Subject key identifier    Key info     Expiration   KeyFile/Tag            Host names (SANs)
------------------------------------------------------------------------------------------------------------------------------------------------------
30D8 7A17 9BA0 CA6E ...   RSA 4096      59,0 days   keyfile.kyr            *.nashcom.de nashcom.de
07BB 3F58 13D7 4322 ...   NIST P-256    52,6 days   nashcom.de.ecdsa       *.nashcom.de nashcom.de
C71F CF82 4508 E456 ...   RSA 4096      53,0 days   rsa_domino_lab_net     *.domino-lab.net
32BA 66E5 CC03 1E00 ...   NIST P-256    69,0 days   wild-csi-ecdsa         *.csi-domino.com
CD47 55CF 76C3 E3CF ...   RSA 4096      88,9 days   wild-csi-rsa           *.csi-domino.com
19BB B3AA 5D90 7A6C ...   NIST P-256    60,7 days                          jupiter.csi-domino.com

Do Internet sites which had the KYR file specified no longer need to do so?

The recommended way to specify TLS Credentials is to use a DNS name instead of the KYR file name. However the KYR file name can be still used as a “tag” and can be used for a 1:1 assignment like in previous releases. The recommended way is to specify a DNS name instead.

If I try to import a PEM file it complains that “Cannot import without a private key”. I have the private key, but how do you specify the key to use?

The PEM, PKCS12 (p12/pfx) formats allow to include the private key. The private key must be part of the imported file.

The import is a client side operation. This means the key, cert and chain is checked on the client and stored encrypted in the TLS Credentials document. After the key has been encrypted, the private key cannot be read by the client any more.

The key is encrypted for the CertMgr server and all servers specified in “Servers with access:” in the moment of this import operation.

If the private key is protected with a password in the import file (PEM or PCKS12) you must specify the password.

When importing a KYR file, it asks for the current password, but it doesn’t validate that password when storing the credentials.

KYR file imports use the password from the corresponding .sth file. The password specified in the dialog is only used for PEM and PKCS12.

Why do I get the error “The encrypted data has been modified or the wrong key was used to decrypt it”

Please refer to the following technote for possible reasons.

CertMgr error: The encrypted data has been modified or the wrong key was used to decrypt it

One well known reason is that you modified the Servers with access: after an import operation. Create exportable keys and importing keys and certificates are client side operations which can’t re-encrypt the key once stored.

In contrast all server side flows can re-encrypt the private key on CertMgr server.

Note: There is a known defect in the Notes 14.0 client which will be fixed in 14.0 FP1. TLS Credentials import operations and also creating exportable keys are affected.

To import TLS Credentials please use a 12.0.1/12.0.2 client until 14.0 FP1 ships.

Do I need to restart my Internet tasks when a TLS Credentials document changes

Once certstore.nsf is in place all internet tasks (HTTP, SMTP, POP3, IMAP, LDAP) and also other applications based on the Domino stack use the new TLS Cache automatically. Because the TLS cache is initialized at startup of the process, you have to start it once after the database is created/replicated to the server.

From then on the TLS Cache is immediately updated on the fly as soon a change is made to a relevant TLS Credentials document for a server. A dedicated thread on each process takes care of managing the cache. The cache reload is highly optimized and ensures the cache is always available.

How can I migrate all my KYR files to TLS Credentials documents.

Cert manage has a command to import a single KYR file and also all configured KYR files on a server. Each KYR file will only imported once.

As soon the TLS credentials are created, the existing *.kyr files and *.sth files should be removed from the server to avoid old KYR files would be used, if the new TLS Cache can’t find a matching key.