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


Daniel Nashed


Domino CertMgr external CA integration - Example HashiCorp

Daniel Nashed  19 December 2021 09:56:26

Image:Domino CertMgr external CA integration - Example HashiCorp

Beginning with Domino 12.0 the new Certificate Management with CertMgr and cerstore.nsf supports the manual flow.
This flow is designed to allow to use any type of external CAs.

Before we look into the integration, here is a short overview of the manual flow:

Image:Domino CertMgr external CA integration - Example HashiCorp
  1. Fill out the TLS Credentials document

    - Set Certificate Provider to "Manual"
    - Specify hostnames (SANs) and other certificate information like organization, common name etc (ACME only uses the SANs -- because this is what they verify)
    - Specify the Key type, size/curve

  2. Submit the request to CertMgr

    - Creates the private key
    - Generates C
    ertificate Signing Request (CSR) based on the private key and encrypts it for the CertMgr server and all servers specified in "Servers with access".

  3. Copy the CSR via "Copy CSR" action and let your external CA process it

  4. CA creates the leaf certificate matching your private key and usually also sends the intermediate certificates.
    Once you got the certificates you can just use the "Paste Certificate" action to paste the certificate chain.

  5. Submit request to CertMgr

    - Sorts and filters the certificate chain
    - Imports the certificates
    - Completes the chain from trusted roots (the external CA needs to be added to the trusted roots
    in certstore.nsf)

Automate the manual flow

When you look at step 3 and step 4 in blue, those two steps can be automated if your CA provides for example a REST interface.

The HashiCorp CA supports CA operations leveraging a modern REST API.

The default operations for their PKI flow isn't what we expect for a secure way to create a TLS Certificate. The standard flow creates the private key and the certificates on the CA side.

This flow could be automated using the new import functionality in 12.0.1 and would not require a server side operation -- But this isn't what we want from security point of view from an integration.

Here is a link how to setup the CA and use the standard HashiCorp flow and how to setup the CA. It also shows the standard flow.

CSR support in HashiCorp CA via REST

I looked into their REST API and they also support passing a CSR directly.
So in our flow above we just submit the CSR and the CA sends back a leaf certificate and chain.

For my simple integration I am just getting the leaf certificate from the REST results and also imported the intermediate CA into the trusted roots.
CertMgr sorts, filters and auto completes certificate chains.

This means if the root and intermediate certificates are there, you only need to take care of the leaf certificate ;-)

Documentation for CSR flow REST API

This integration allows to automate step 3. and 4. of our manual flow.

Once the CSR is created (in a second step also this part could be automated in a script), a simple agent can be used to automate the manual steps.

Below is a simple agent performing the operations including submitting the request again to CertMgr to finalize the TLS Credentials document.

If your CertMgr is set to a shorter interval via notes.ini CERTMGR_INTERVAL=1 (default 30 sec), the whole operation is done almost instantly.

Additional ideas

This is just a simple example for integrations. HashiCorp provides an easy  to use REST API including very flexible authentication and authorization.

Other CAs might have similar options. But for a SmallStep CA it would probably make sense to use build-in ACME flow CertMgr and SmallStep support -- Even the SmallStep CA would also support a similar flow.

(see an earlier posts for details -->

The Microsoft CA provides a command-line interface supporting the CSR flow. But this isn't really what I would expect from an enterprise level CA integration.
A HashiCorp CA or other CAs like the SmallStep CA could operate as a Sub CA in your organization with it's own intermediate certificate derived from the Root CA.

In addition when you look into what other certificate managers integrate with HashiCorp is definitive a great choice :-)

So for example the widely used cert-manager in the container/cloud native world ( also supports HashiCorp.

If you have other applications, Domino CertMgr could be still your central repository for TLS certificates.
The interface is easy to use and provides a flexible export interface for to PEM and PKCS12.

And you can combine it with different type of CAs as show in this example.


I am really interested in which type of use cases you would see in your environment.

Which type of CAs are you using?
Do you have automation for certificate request flows?
How do you control today who is authorized to request a certificate from your corporate CA?

Are there flows inside the organization?

How long does it take to get a TLS certificate today?

Sample Integration Agent for external CAs: HashiCorp

Call HashiCorpCertRequest ("https://hashicorp.nashcom.loc:8200/v1/pki_int/sign-verbatim", "s.KrV1eOMJXGBiCVFG2XXXXCoNSI")

HashiCorpReqeust (URL As String, Token As String, CSR As String) As String

Dim Session As New NotesSession        
Dim data As NotesJSONNavigator
Dim jsonNav As NotesJSONNavigator
Dim e As NotesJSONElement
Dim ret As Variant
Dim webRequest As NotesHTTPRequest
Set webRequest = session.createhttprequest()
      webRequest.PreferJSONNavigator =
Call webRequest.Setheaderfield ("X-Vault-Token", Token)
Call webRequest.Setheaderfield ("Accept", "application/json")
Set data = session.CreateJSONNavigator ("")
Call data.AppendElement (CSR, "csr")
Call data.AppendElement ("240h", "ttl")
Set JsonNav = webrequest.Post (URL, data.Stringify)

If (JsonNav Is Nothing) Then
MessageBox "No JSON returned"
Exit Function
End If
Set e = JsonNav.GetElementByPointer ("/data/certificate")

If (e Is Nothing) Then
MessageBox "No Certificate returned"
Exit Function
End If
      HashiCorpReqeust = e.Value


HashiCorpCertRequest (Url As String, Token As String)

Dim session As New NotesSession
Dim db As NotesDatabase
Dim workspace As New NotesUIWorkspace
Dim uidoc As NotesUIDocument
Dim doc As NotesDocument

Set db = session.CurrentDatabase
Set uidoc = workspace.CurrentDocument
If (uidoc Is Nothing) Then
MessageBox "Please submit request from TLS Credentials document!",48, "CertMgr"
Exit sub
End If
Set doc = uidoc.Document

If ("" = doc.CSR(0)) Then
MessageBox "Please submit manual request first to create a CSR!",48, "CertMgr"
Exit Sub
End If
      uidoc.Editmode =
      doc.PastedPem = HashiCorpReqeust (URL, Token, doc.CSR(

'Set submitted status to import certificate, intermediates and auto complete root
      doc.Status =
Call, False)
' Close the document without prompt
      doc.SaveOptions =
Call uidoc.Reload()
Call uidoc.Close(True)


1Renato Telen  11.01.2022 10:56:59  Domino CertMgr external CA integration - Example HashiCorp

Now that we have Nomad web running on Safelinx it would be quite useful to integrate LetsEncrypt (via certmgr) to Safelinx. Safelinx still uses manual cert process. There is currently voting on HCL to bulid LetsEncrypt automation into Safelinx but HCL response is "it would be a lot of work". Maybe it would be easier to use certmgr for integration. No idea what type of web server Safelinx is using.

2Daniel Nashed  11.01.2022 19:28:47  Domino CertMgr external CA integration - Example HashiCorp

@Renato, you replied to the wrong post ;-)

I have shown how simple it is to integrate with CertMgr and this would work also for SafeLinx and ST.

But I agree that this is something HCL should integrate into the products.

CertMgr is built to be extendable and work with other products.

Implementing Let's Encrypt from scratch or even porting what is in Domino CertMgr would be a lot of work.

IMHO it would make sense to leverage what Domino already has with CertMgr and integrate.

-- Daniel



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