Article Type: Solution

Certificates are used in the authentication process by:

1. A MarkLogic Application Server configured to use SSL (HTTPS).
    
2. Any web client connecting to a MarkLogic application server over HTTPS (in the case of SSL client authentication).

Consider the following example:

$openssl x509 -in CA.pem -text -noout
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 18345409437988140316 (0xfe97fcaf8a61b51c)
    Signature Algorithm: sha1WithRSAEncryption
        Issuer: C=US, ST=CA, L=San Carlos, O=MarkLogic Corporation, OU=Engineering, CN=MarkLogic CA
        Validity
            Not Before: Nov 30 04:08:31 2015 GMT
            Not After : Nov 29 04:08:31 2020 GMT
        Subject: C=US, ST=CA, L=San Carlos, O=MarkLogic Corporation, OU=Engineering, CN=MarkLogic CA

In this example, when viewing the Trusted CA Subject field, the CA Certificate name will be listed with the organisation name "MarkLogic Corporation" (O=MarkLogic Corporation), which is on MarkLogic's list of certificate authorities.

You can view the complete list of currently configured Trusted Certificate Authorities by logging into the MarkLogic Administration Application Server (on port 8001) and viewing the status page: Configure -> Security -> Certificate Authorities.

Trusted CA Certificate without Organization name (O=)

In some cases, there are legitimate Trusted CA Certificates which do not contain any further information about the Organization responsible for the certificate.

The example below shows a sample self-signed root CA (DemoLab CA), which highlights this scenario:

$openssl x509 -in DemoLabCA.pem  -text -noout
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 12836463831212471403 (0xb22447d80f91b46b)
    Signature Algorithm: sha1WithRSAEncryption
        Issuer: CN=DemoLab CA
        Validity
            Not Before: Nov 30 05:23:13 2015 GMT
            Not After : Nov 29 05:23:13 2020 GMT
        Subject: CN=DemoLab CA

If this Certificate were to be loaded into the MarkLogic, no name would appear under the list of <em>Certificate Authorities</em>in the list provided through the administration Application Server at Configure -> Security -> Certificate Authorities

In the above example, it would be difficult to use the certificate validated by DemoLab CA (and to use DemoLab CA as our Trusted Certificate Authority) as MarkLogic will only list certificates associated with an Organization.

To workaround this issue, we can configure MarkLogic to use the certificate through scripting with Query Console.

1) Loading the CA using Query Console

Start using a call to pki:insert-trusted-certificates to load the Trusted CA into MarkLogic.  The sample Query Console code below demonstrates this process (Please ensure this query is executed against the Security database)
 

xquery version "1.0-ml";

import module namespace pki = "http://marklogic.com/xdmp/pki"" at "/MarkLogic/pki.xqy";
 
pki:insert-trusted-certificates(
  xdmp:document-get("/OurCertificateLocation/DemoLabCA.pem",
  <options xmlns="xdmp:document-get">
    <format>text</format>
  </options>)
)