Article Type: Tips and Tricks

This knowledgebase discusses the solution to deploy SAN or Wildcard Certificate in 3 node (or more) cluster.

Certificate Types and MarkLogic Default Config

Certificate Types

In general, When browsers connect to a Server using HTTPS, they check to make sure your SSL Certificate matches the hostname in the address bar. There are three ways for browsers to find a match:

a). The hostname (in the address bar) matches the Common Name in the certificate's Subject.

b). The hostname matches a Wildcard Common Name. Please take a look at an example at the end of the article.

c). The hostname is listed in the Subject Alternative Name (SAN) field as part of X509v3 extensions. Please find an example at the end of the article.

The most common form of SSL name matching is for the SSL client to compare the server name it is connected to with the Common Name (CN field) in the server's Certificate. It's a safe bet that all SSL clients will support exact common name matching.

MarkLogic allows this common scenario (a) to be configured from Admin GUI, and we will discuss the Certificate featuring (b) and (c) deployment further.

Default Admin GUI-based Configuration 

By default, MarkLogic generates a Temporary Certificate for all the nodes in the group for the current cluster when a Template is assigned to MarkLogic Server (the Exception is when the Template is assigned through XQuery ).

The Temporary Certificate generated for each node has hostname as the CN field for its respective Temporary Certificate—designed for common Scenarios (a).

We have two paths to install a signed Certificate in MarkLogic.

1) Generate Certificate request, get it signed by CA, import through Admin GUI

or 2) Generate Certificate request + Private Key outside of MarkLogic, get Certificate request signed by CA, import Signed Cert + Private Key using Admin script

Problem Scenario

In both of the above cases, while Installing/importing a Signed Certificate, MarkLogic will look to replace the Temporary Certificate by comparing the CN field of the Installed Certificate with the Temporary certificate CN field.

Now, if we have a WildCard Certificate (b) or SAN Certificate (c), our Signed Certificate's CN field will never match the Temporary Certificate's CN field; hence, MarkLogic will not remove Temporary Certificates MarkLogic will continue using Temporary Certificates.

After installing SAN or wildcard Certificates, we may encounter AppServer that still uses the temporarily installed Certificate ( which was not replaced while installing SAN/wildcard Certificate).

Use below XQuery against Security DB to remove all Temporary Certificates. XQuery needs uri lexicon to be enabled (default enabled). [Please change the Certificate Template-Name in the XQuery below to reflect values from your environment.] 
 

xquery version "1.0-ml";

import module namespace pki = "http://marklogic.com/xdmp/pki""  at "/MarkLogic/pki.xqy";
import module namespace admin = "http://marklogic.com/xdmp/admin""  at "/MarkLogic/admin.xqy";
      

let $hostIdList := let $config := admin:get-configuration()
                   return admin:get-host-ids($config)
                     
for $hostid in $hostIdList
return
  (: FDQN name matching Certificate CN field value :)
  let $fdqn := "TestDomain.com"

  (: Change to your Template Name string :)
  let $templateid := pki:template-get-id(pki:get-template-by-name("YourTemplateName"))

  for $i in cts:uris()
  where 
  (   (: locate Cert file with Public Key :)
      fn:doc($i)//pki:template-id=$templateid 
      and fn:doc($i)//pki:authority=fn:false()
      and fn:doc($i)//pki:host-name=$fdqn
  )
  return <h1> Cert File - {$i} .. inserting host-id {$hostid}
  {xdmp:node-insert-child(doc($i)/pki:certificate, <pki:host-id>{$hostid}</pki:host-id>)}
  {
      (: extract cert-id :)
      let $certid := fn:doc($i)//pki:certificate/pki:certificate-id
      for $j in cts:uris()
      where 
      (
          (: locate Cert file with Private key :)
          fn:doc($j)//pki:certificate-private-key/pki:template-id=$templateid 
          and fn:doc($j)//pki:certificate-private-key/pki:certificate-id=$certid
      )
      return <h2> Cert Key File - {$j}
      {xdmp:node-insert-child(doc($j)/pki:certificate-private-key,
        <pki:host-id>{$hostid}</pki:host-id>)}
      </h2>
  } </h1>

Above will remove all Temporary Certificates (including Template CA) and their private-key, leaving only Installed Certificate associated with Template, forcing all nodes to use Installed Certificate.

Example: SAN (Subject Alternative Name) Certificate

For 3 node cluster (engrlab-128-101.engrlab.marklogic.com, engrlab-128-164.engrlab.marklogic.com, engrlab-128-130.engrlab.marklogic.com)

$ opensl x509 -in ML.pem -text -noout
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 9 (0x9)
        Signature Algorithm: sha1WithRSAEncryption
        Issuer: C=US, ST=NY, L=NewYork, O=MarkLogic, OU=Engineering, CN=Support CA
        Validity
            Not Before: Apr 20 19:50:51 2016 GMT
            Not After : Jun  6 19:50:51 2018 GMT
        Subject: C=US, ST=NJ, L=Princeton, O=MarkLogic, OU=Eng, CN=TestDomain.com
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
            RSA Public Key: (1024 bit)
                Modulus (1024 bit):
                    00:97:8e:96:73:16:4a:cd:99:a8:6a:78:5e:cb:12:
                    5d:e5:36:42:d2:b8:52:51:53:6c:cf:ab:e4:c6:37:
                    2c:15:12:80:c1:1b:53:29:4c:52:76:84:80:1d:ee:
                    16:41:a6:31:c5:7b:0d:ca:d7:e5:da:d7:67:fe:80:
                    89:9f:0d:bc:46:4f:f0:7e:46:88:26:d5:a0:24:a6:
                    06:d1:fa:c0:c7:a2:f2:11:7f:5b:d5:8d:47:94:a8:
                    06:d9:46:8f:af:dd:31:d5:15:d2:7a:13:39:3e:81:
                    32:bd:5c:bd:62:9d:5a:98:1d:20:0e:30:d4:57:3f:
                    7f:89:e6:20:ae:88:4d:85:d7
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Key Usage: 
                Key Encipherment, Data Encipherment
            X509v3 Extended Key Usage: 
                TLS Web Server Authentication
            X509v3 Subject Alternative Name: 
                DNS:engrlab-128-101.engrlab.marklogic.com, DNS:engrlab-128-164.engrlab.marklogic.com, DNS:engrlab-128-130.engrlab.marklogic.com
    Signature Algorithm: sha1WithRSAEncryption
        52:68:6d:32:70:35:88:1b:70:df:3a:56:f6:8a:c9:a0:9d:5c:
        32:88:30:f4:cc:45:29:7d:b5:35:18:a0:9a:45:37:e9:22:d1:
        c5:50:1d:50:b8:20:87:60:9b:c1:d6:a8:0c:5a:f2:c0:68:8d:
        b9:5d:02:10:39:40:b3:e5:f6:ae:f3:90:31:57:4c:e0:7f:31:
        e2:79:e6:a8:c0:e6:3f:ea:c5:75:67:3e:cd:ea:88:5d:60:d6:
        01:59:3c:dc:e0:47:96:3b:59:4a:13:85:bb:87:70:d0:a2:6b:
        0f:d4:84:1d:d1:be:e8:a5:67:c3:e3:59:05:0d:5d:a5:86:e6:
        e4:9e

Example: Wild-Card Certificate

For 3 node cluster (engrlab-128-101.engrlab.marklogic.com, engrlab-128-164.engrlab.marklogic.com, engrlab-128-130.engrlab.marklogic.com). 

$ openssl x509 -in ML-wildcard.pem -text -noout
Certificate:
    Data:
        Version: 1 (0x0)
        Serial Number: 7 (0x7)
        Signature Algorithm: sha1WithRSAEncryption
        Issuer: C=US, ST=NY, L=NewYork, O=MarkLogic, OU=Engineering, CN=Support CA
        Validity
            Not Before: Apr 24 17:36:09 2016 GMT
            Not After : Jun 10 17:36:09 2018 GMT
        Subject: C=US, ST=NJ, L=Princeton, O=MarkLogic Corporation, OU=Engineering Support, CN=*.engrlab.marklogic.com