Knowledgebase:
Using KeyStore Explorer to generate CA Root and end-user (SSL) certificates for MarkLogic Server
23 April 2020 10:28 AM

Introduction

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/

Getting Started

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 javax.net.ssl.keyStore properties

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 /tmp/user1_rootca_.p12) and click Export

Click OK to dismiss the confirmation prompt


You will now be able to import the PKCS#12 file into your web browser.

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:

$ openssl pkcs12 -in /tmp/user1_rootca_.p12
Enter Import Password:
MAC verified OK
Bag Attributes
    friendlyName: user1 (rootca)
    localKeyID: 54 69 6D 65 20 31 35 33 34 32 37 33 38 30 37 31 30 33
Key Attributes: 
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
-----BEGIN ENCRYPTED PRIVATE KEY-----

Further reading

(11 vote(s))
Helpful
Not helpful

Comments (0)