Make sense of the javakeystores used by CA Directory dxcertgen utility

Products

CA Directory

Issue/Introduction

Everytime a new DSA that needs to communicate using SSL/TLS is introduced in a CA Directory implementation, a new certificate with its private key for that DSA is required locally and sometimes on another machine that partictes in the overall Directory Information Tree implementation. To save a CA Directory administrator from having to go to a Certificate Vendor to obtain this certificate, CA Directory has provided the dxcertgen so that it will create a self-signed Certificate Authority and further use it to create/sign the certificate needed by the DSAs.

Historically, for security reason the private key that is associated with this Certificate Authority is removed upon the completion of the "dxcertgen certs". As a result, everytime a new DSA is introduced, a new Certificate Authority certificate and private key is recreated new and render the certificates that were signed by the previous Certificate Authority invalid. To address this inconvenience, a newer version of the dxcertgen that uses a "javakeystores" is introduced to allow the Certificate Authority certificate and private key to survive after the completion of the "dxcertgen certs" command and hence the next time the "dxcertgen certs" is invoked again, it can reuse the same Certificate Authority certificate and private key and allow previously distributed certificates to remain valid.

This article is meant to help clarify some of the misunderstanding of the dxcertgen utility as not all administrators were able to commit the efforts to sort out the all-emcompassing information documented in the CA Directory documentation set.

Environment

Release: 14.1
Component: CA Directory

Cause

Resolution

Enable javakeystores to Allow Reuse of the Certificate Authority Certificate and Private Key

The execution of the "dxcertgen certs" now inspect its runtime enviroment when it is invoked. It checks whether the JAVA_HOME environment variable is set to the directory where a jre is installed. If not, it continues to behave the traditional manner without attempting to reuse the Certificate Authority certificate and private key.

In short, to enable the usage of the config/ssld/javakeystores, you will need to first install a supported JRE. and set the JAVA_HOME environment variable accordingly. Preferrably, you also want to put the $JAVA_HOME/bin at the front of the environment variable PATH.

First Execution of the "dxcertgen certs"

When a Directory Server is first installed, it comes with the config/ssld/javakeystores and two key store files, cacerts and clientcerts, under it. The first time "dxcergen certs" is executed with the javakeystores enabled, we will see output similar to:

C:\Program Files\CA\Directory\dxserver\config\ssld>dxcertgen certs
Setting root certificate and public/private keys for signing...
! Exporting certificate 'dxcertgen' from C:\Program Files\CA\Directory\dxserver\config\ssld\javakeystores\cacerts...
! alias 'dxcertgen' not found
Generating public and private key pair...
! Generating key pair for 'dxcertgen' in C:\Program Files\CA\Directory\dxserver\config\ssld\javakeystores\cacerts...
! Exporting certificate 'dxcertgen' from C:\Program Files\CA\Directory\dxserver\config\ssld\javakeystores\cacerts...
Generating an x509 v3 certificate...
Signing certificate with trusted root CA's private key...
! Importing certificate 'dxcertgen' into C:\Program Files\CA\Directory\dxserver\config\ssld\javakeystores\cacerts...
! Importing certificate 'dxcertgen' into C:\Program Files\CA\Directory\dxserver\config\ssld\javakeystores\clientcerts...
Writing root certificate to trusted.pem...

Generating DXserver personalities from server files...
Skip generating personality certificate for XXXXXXXX-monitoring-management-ui as its existing certificate is not issued by CN=DXCertGenCA,O=DXCertGenPKI,C=AU
Skip generating personality certificate for XXXXXXXX-management-ui as its existing certificate is not issued by CN=DXCertGenCA,O=DXCertGenPKI,C=AU

Generating a new personality certificate for UNSPSC1...
! Generating a 2048-bit RSA public/private key pair...
..............+++++
...........+++++
Generating an x509 v3 certificate...
Signing certificate with trusted root CA's private key...
! Writing personality certificate to C:\Program Files\CA\Directory\dxserver\config\ssld\personalities\unspsc1.pem...

Generating a new personality certificate for ...

(skipped)...

Done.

Here we see that a Certificate Authority, named as dxcertgen, certificate and its private key is generated and stored in the cacerts store under the javakeystores subdirectory. It also shows that the certificate is stored in the clientcerts store.

More Execution of the "dxcertgen certs"

Since the javakeystores is only enabled when the proper JAVA_HOME environment is set, if you ever run the "dxcergen certs" without it, it will fall back to the traditional behavior of the "dxcertgen certs" where it creates a new pair of Certificate Authority certificate and private key and update the trusted.pem using the new certificate. However, you can actually re-run the "dxcertgen certs" after setting the JAVA_HOME correctly.

Behavior of the "dxcertgen certs" and What to Do After

Evertyime the "dxcertgen certs" is invoked, regardless of whether the javakeystores is enabled. It first goes through all the dxi files under the config/server subdirectory and also validates all the configuration files. At the end, it gathers a set of DSAs, local or remote, and generates and signs the certificate/private key for each of the DSAs and store them as PEM files under the config/ssld/personalities subdirectory. In the process it overwrite any existing PEM files that share the same file name.

In addition, it updates the trusted.pem with the Certificate Authority certificate. Therefore, if you ever accidentally run the "dxcertgen certs" accidentally without enabling the javakeystores. By simply set the JAVA_HOME properly, rerun the "dxcertgen certs" then the trusted.pem with be recovered from that mistake.

Even though each run of the "dxcertgen certs" will generate new personality pem file for each of the local and remote DSAs, so long as the trusted.pem remains the same, there is no need to rush into redistributing the new pem files to the remote machines as the communication channels only relies on the validity of the certificate presented by a DSA and the DSA continues to possess the valid pair of certificate and private key. In the long run, you may still want to distribute the pem files just to simplify the management of all the involved machines.

Please note that each run of the "dxcertgen certs" does create and restart the validity of the DSA certificates.

Establish a Central Certificate Server to Simplify the Management of these Certs?

As a suggestion, you may want to identify a "certificate server" to simplify the management of the certifcates needed for your implementation. It is really up to you to decide how you want to manage it.

Within an exterprise environment, you may have multiple independent clusters of CA Directory where you need to manage. Still to simplify the management of all the needed certificates, you may want to identify a single "certificate server" to do the dxcertgen and likely to manage all the DSA configuration and file distribution. This "certificate server" does not really need to have any DSA up and running, it just needs to have all the dxi files and other configuration files across all your clusters and be the only server where you run the "dxcertgen certs" with the javakeystores enabled.

Then there are two scenarios you need to observe:

actions that cause the trusted.pem get updated, this includes running "dxcertgen certs" that creates the inital Certifcate Authority or similar, and "dxcertgen importca".

This is when you need to distribute the trusted.pem to all other Directory server and to restart all the DSAs that require the new Certificate Authority certificates in the trusted.pem.
Since we are assuming javakeystores is enabled, the run of "dxcertgen certs" does not update trusted.pem

Under this scenario, you will only need to distribute the required files to the Directory servers that need them and overtime to distribute all the personalities files to all the machines as some of the certificates can become expired.

The Security Under the Hood

The out-of-the-box cacerts is secured using the default store password of "changeit", the default store password of clientclients is "passphrase" and private key of the dxcertgen is protected using the password "passphrase" well. All these including even the alias name dxcertgen can all be customized. It is only that one will need to provide all these in the option when issuing the dxcertgen command. Please see the product document for details

DXcertgen Tool -- Generate and Work with Certificates

In particular, the following is a list that shows what can be customized:

-a rootalias : default dxcertgen
-C cert-ks-password : default passphrase - clientcerts keystore password
-P rootcert-pk-ks-password : default passphrase - password that protect the "rootalias/dxcertgen" private key
-S rootcert-ks-password : default changeit - cacerts keystore password
-c cert-ks-path : default DXHOME/config/ssld/javakeystores - directory that contains the clientcerts keystore
-s rootcert-ks-path : default DXHOME/config/ssld/javakeystores - directory that contains the cacerts keystore