Knowledgebase:
Import pre-signed Certificate and Key for MarkLogic HTTPS App Server
12 October 2022 08:11 AM

Summary

This Knowledgebase article outlines the necessary steps required in importing an existing (pre-signed) Certificate into MarkLogic Server and configuring a MarkLogic Application Server to utilize that certificate.

Existing (Pre-signed) Certificate vs. Certificate Request Generated by MarkLogic

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.

The section in MarkLogic's online documentation on Creating a Certificate Template covers the steps required to generate a certificate template from within MarkLogic Server: http://docs.marklogic.com/guide/security/SSL#id_35140

  

Steps to Import Pre-Signed Certificate and Key into MarkLogic

1) Create a Certificate Template 

Create a new Certificate Template with the fields similar to your existing Pre-Signed Certificate

For example, your current Certificate file - presigned.marklogic.com.crt

[amistry@engrlab18-128-026 PreSignedCert]$ openssl x509 -in ML.pem -text 
Certificate:
    Data:
        Version: 1 (0x0)
        Serial Number: 7 (0x7)
    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:12:33 2015 GMT
            Not After : Nov 29 04:12:33 2017 GMT
        Subject: C=US, ST=NJ, L=Princeton, O=DemoLab Corporation, OU=Engineering, CN=presigned.engrlab.marklogic.com
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (1024 bit)
 
 
For above Certificate we will create below Custom Template in Admin GUI -> Configure-> Security -> Certificate Template  Create Tab as below.
We will save our new template as - "DemoLab Corporation Template"
 
 
 Template.jpg

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

2) Create an HTTPS App Server

Please follow Procedures for Enabling SSL on App Servers except for the "Creating Certificate Template" part as we have created the Template to match our existing pre-signed Certificate. 

3) Verify Pre-signed Certificate and Private Key file 

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

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

(stdin)= 2ddd2ca48ad2eb4eba082f5da3fd33ab

* Generate and display the private key checksum

[admin@siteaa ~]# openssl rsa -noout -modulus -in key.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. 

Advisory: Private Key's with a key length of 1024 and less are now considered insecure. When generating a Private Key you should ensure a key length of 2048 or higher is used.

4) Install Pre-signed Certificate and Key file to Certificate Template using Query Console

Now since Certificate was pre-signed, MarkLogic does not have a key that goes along with that Pre-signed Certificate. We will install Pre-signed Certificate and Key into MarkLogic using below XQuery in Query Console.

Note: Query Must be run against Security Database. 

Please change the Certificate Template-Name, and Certificate/Key File location in below XQuery 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";

(: 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 := "/cert.pem"
let $path-to-key := "/key.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>)
)

 Above will associate our pre-signed Certificate and Key into Template created earlier, which is linked to HTTPS App Server.

Important note: pki:insert-trusted-certificates can also be used in place of pki:insert-host-certificate in the above example.

(14 vote(s))
Helpful
Not helpful

Comments (0)