Marklogic: SSL enablement in Marklogic server

Enabling SSL in the Marklogic server

Every business want to secure their application from hackers. To secure the application first step is to ensure the all the server communications are secured. Our application also need to be enabled the SSL. As I am new to the SSL, I don’t have much idea about this security. By following this steps simply we can enable the SSL in marklogic server.

MarkLogic will allow you to use an existing certificate or will allow you to generate a Certificate Request. The key difference between above two lies in who generates public-private keys and other fields in the certificate.

For a Pre-Signed Certificate: In this instance, the keys already exist outside of MarkLogic Server, and 3rd party tool would have populated CN (Common Name) and other subject fields to generate Certificate Request File (.csr) containing a public key.

For a Certificate Request Generated by MarkLogic: In this instance, new keys are generated by MarkLogic Server (it does this while creating the new template), while CN and other fields are added by the MarkLogic Server Administrator (or user) through the web-based MarkLogic admin GUI during New Certificate Template creation.

Among two methods we have to use the Pre-signed certificate.

Step1:

Get the appropriate certificate and private key for the marklogic server host. As we are using trusted certificate we need to keep the private key in the marklogic server along with the certificate.

Step2:

Download the Certificate Authority details from the certificate and upload the same in the Marklogic server in the adminPage -> Security -> Certificate Authorities -> import.

Step3:

You can find the list of all the certificate authorities will be shown in the CA list in the marklogic server

Step4:

Create a new Certificate Template “SAMPLE” with the fields similar to your existing Pre-Signed Certificate. Its not necessary to follow the same. But you can extract this information from the certificate and fill it.

User the below command to print the certificate details in text

              openssl x509 -in ML.pem -text 

Note - Above fields are placeholders only for signed Certificate, and MarkLogic mainly uses above fields to generate Certificate Signing Request (.csr). For Certificate request generated by 3rd party tool, it does NOT matter if template field matches exactly with final signed Certificate or not.

Once we have Signed Certificate imported, App Server will use the Signed Certificate, and the SSL Client will only see field values from the Signed Certificate (even if they are different from Template Config page ).

Step5:

In our case we need to enable the SSL for HTTP server. Enabling the SSL in the HTTP server just follow these steps to ensure basic SSL enablement.

·       Select the ssl certificate template – we can use the “SAMPLE” certificate template

·       Select TRUE for require client certificate

·       Select the CA in the show option

Step 6:

Copy the certificate.crt and privateKey.key into the linux server(/tmp/) where marklogic installed and the certificate should the domain name as the host name.

Step 7:

Prior to installing a pre-signed certificate and private key the following verification should be performed to ensure that both certificate and key are valid and are in the correct format. 

* Generate and display the certificate checksum using the OpenSSL utility. If below command is not working for .crt then try with .pem. you can find the command to convert the .crt to .pem from google.

[admin@sitea ~]# openssl x509 -noout -modulus -in certificate.crt | openssl md5

(stdin)= 2ddd2ca48ad2eb4eba082f5da3fd33ab

* Generate and display the private key checksum

[admin@siteaa ~]# openssl rsa -noout -modulus -in privateKey.key | openssl md5

(stdin)= 2ddd2ca48ad2eb4eba082f5da3fd33ab

The checksum from both commands should return identical values, if the values do not match or if you are prompted for additional information such as the private key password then the certificate and private keys are not valid and should be corrected before proceeding.

Note: Proceeding to the next step without verifying the certificate and the private key could lead to the MarkLogic server being made inaccessible. 

Step 8:

As marklogic don’t have option to load the key file along with the certificate we need to use query console to do the same. By executing below query we are installing the certificate and key in the certificate template.

Execute below query in QConsole with security database selected.

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";

(: Update Template name for your environment :)

let $templateid := pki:template-get-id(pki:get-template-by-name("TemplateName"))

(: Path on the MarkLogic host that is readable by the MarkLogic server process (default daemon) :)

(:   File suffix could also be .txt or other format :)

let $path-to-cert := "/tmp/certificate.crt"

let $path-to-key := "/tmp/privatekey.key"

return

pki:insert-host-certificate($templateid,

  xdmp:document-get($path-to-cert,

    <options xmlns="xdmp:document-get"><format>text</format></options>),

  xdmp:document-get($path-to-key,

    <options xmlns="xdmp:document-get"><format>text</format></options>)

)

Step 9:

Once the query ran successfully we are ready to test the SSL in our appserver. We already enabled the SSL in the appserver port number 8011 then you can try below url in your browser. If you are able to access the any document from the DB using this link then HTTPS is enabled for your Marklogic http server.

https://hostName:8011/v1/documents?uri=/sample.xml

Above steps I have created for my project. If there is any disconnect in the steps or any improvements needed please comment below.

I have implemented the SSL in my project using below reference. Used the same document as a reference for this post.

https://help.marklogic.com/Knowledgebase/Article/View/297/0/import-pre-signed-certificate-and-key-for-marklogic-https-app-server