Daniel Nashed's Blog

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:

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 Certificate 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.

https://learn.hashicorp.com/tutorials/vault/pki-engine


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

https://www.vaultproject.io/api/secret/pki#sign-verbatim

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.

TIP: 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 --> https://blog.nashcom.de/nashcomblog.nsf/dx/domino-v12-acme-for-company-cas-using-smallstep.htm).

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 (https://cert-manager.io/docs/) 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.


Feedback?

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


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

Function 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.maxredirects= 5
      webRequest.PreferJSONNavigator = True
     
      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

End Function


Sub 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 = True
      doc.PastedPem = HashiCorpReqeust (URL, Token, doc.CSR(0))

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

End Sub

• Comments [2]