Using KeyStore Explorer to generate CA Root and end-user (SSL) certificates for MarkLogic Server
23 April 2020 10:28 AM
|
|
IntroductionThis 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 StartedStart 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 AuthorityThe 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 MarkLogicBefore 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 CertificatesTo 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 AuthenticationThere 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 keypairSome 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:
Further reading
| |
|