Using KeyStore Explorer to generate CA Root and end-user (SSL) certificates for MarkLogic Server
23 April 2020 10:28 AM
This Knowledgebase article demonstrates how you can use the KeyStore Explorer tools to generate a CA Root Certificate and end-user certificates for use with MarkLogic Server (for Application Servers which are SSL enabled) and for SSL based client authentication within your applications.
KeyStore Explorer can be downloaded from http://keystore-explorer.org/
Start KeyStore Explorer and select Create a new KeyStore or if you have already had a keystore you can use Open an existing KeyStore
For the KeyStore type select JKS
Generating a Root Certificate Authority
The first step is to create a valid Root Certificate Authority that will be used to sign all end-user or intermediate CA certificates
Right-click within the KeyStore workspace to open the context menu and select the Generate Key Pair option from the menu
Select RSA as the Algorithm and select a Key Size (typically 2048)
After clicking on OK, most of the certificate details will already be pre-populated but you can change the Signature Algorithm, Validity and Serial Number as required.
Click on the Edit Name button
Complete the Certificate Subject details as necessary (in the example above, we're providing a Common Name, an Organization Unit and an Organization Name), then click OK to save these details. You will see these are now listed under the Name field for the certificate.
Click on the Add Extensions button
For a Certificate Authority the Basic Constraints and Key Usage extensions are required.
Click the Green + button
Select the Key Usage Extension
Select the Certificate Signing and CRL Sign attributes. With these selected, click OK
Click the Green + button again and this time, select the Basic Constraints Extension
Check the Subject is a CA box and click OK
Verify that both the Key Usage and the Basic Constraints Certificate Extensions are now listed and click OK
Click OK to complete the Root CA certificate generation
Assign an Alias to the newly created key
Enter a password to protect the private key
At this point the Root CA Certificate has been created
Importing the Root Certificate Authority into MarkLogic
Before you can import the Root Certificate into MarkLogic you will first need to export it from the KeyStore Explorer tool in the correct format.
Right click on the Root CA entry in the KeyStore and select Export -> Export Certificate Chain
Select X.509 as the Export Format and check the PEM checkbox, if you have only a single Root CA certificate select Head Only otherwise select Entire Chain
Specify the filename for the exported file; in the example we are using /tmp/rootca.cer (this filename and path will be used later in this article to insert the trusted certificate into MarkLogic Server).
Click Export to save the Root CA certificate to a file
And click OK to dismiss the confirmation prompt
From the Query Console run the following xquery code against the Security Database:
You should see an xs:unsignedLong is returned by the call to pki:insert-trusted-certificates if the certificate has been inserted successfully.
You can check the Certificate Authorities details in the MarkLogic Admin UI on port 8001 (Configure > Security > Certificate Authorities) to ensure the Root CA certificate was added; the certificate will be listed under the Organization Name that was specified when you created the certificate
Using the Root Certificate Authority to Sign End-User Certificates
To use Certificate based authentication within MarkLogic you will need to generate and sign certificates using a Root CA certificate such as the one generated by following the steps above.
In Keystore Explorer, right click on the Root CA Certificate that you will be using for signing the user certificate and select Sign > Sign New Key Pair
As with the root certificate, the user certificate should use the same RSA Algorithm
As with the Root Certificate most attributes are pre-populated and can be left with the configured settings.
Much like the Root CA, the Name needs to be completed for a basic user certificate.
Enter Name details as required:
Fill in the Common Name, Organization Unit and Organization Name fields and click OK
Click OK generate the user certificate
Enter the Alias and click OK
Specify a password for protecting the Private Key and click OK to generate the keypair
Click OK to dismiss the confirmation prompt
You should now see both a root certificate (rootca) and a user certificate (user1)
Exporting the User certificate for Certificate Based Authentication
There are a number of different application methods that may use certificate based authentication with MarkLogic, such as web browser access, MLCP, DHF and XCC applications.
Java based applications will be able to use the KeyStore file generated by the KeyStore Explore tool using the Java
Accessing MarkLogic using a web browser requires the Certificate and Private Key to be imported into the web browser using the PKCS#12 format.
The following steps show how to export the User certificate and key into the correct format for importing to a web browser.
Select the user certificate in the KeyStore, right-click and select Export > Export Key Pair
Enter a password for the PKCS#12 file, specify a filename and path (in this example, we're using
Click OK to dismiss the confirmation prompt
Using openssl to create separate Certificate and Private Key files from a keypair
Some applications may require that a separate Certificate and Private Key file are specified, in this case the easiest way to do this is to export a PKCS#12 file as described above and use the OpenSSL tool to split out the separate Certificate and Private Key components.
The example below outputs the private key and certificates from a PKCS#12 keypair using the openssl tool and these can be used to create the necessary files using a text editor: