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

 
alt

Daniel Nashed

 

Domino CertMgr external CA integration - Example HashiCorp

Daniel Nashed  19 December 2021 08: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.


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

Links

    Archives


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