Import pre-signed Certificate and Key for MarkLogic HTTPS App Server
12 October 2022 08:11 AM
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
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
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"
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
* Generate and display the private key checksum
[admin@siteaa ~]# openssl rsa -noout -modulus -in key.key | openssl md5
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.
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.