Managing Cryptographic Material

The DirX Audit installation requires certificates and keys for securing both incoming and outgoing connections. This chapter provides a brief guide to managing the cryptographic material.

How DirX Audit uses Cryptography

When a party establishes a secure connection, it must be able to build a certificate chain from the known trust anchors and from the certificate(s) presented by the other party.
The resulting certificate chain must be valid and trustworthy in order to prove the authenticity of the other party. If the party lacks some certificate to achieve this goal, it can’t prove the authenticity of the other party and should abort the connection.

Providing an appropriate set of trusted certificates that act as the trust anchors is therefore paramount for making connections secure. Note that secure connections are assumed by default and the configuration procedure requires following cryptographic material:

  • The server key and certificate for the DirX Audit Message Broker and DirX Audit Message Broker admin console, so that the DirX Audit Message Broker can authenticate itself to the JMS clients (for example, the collectors and the DirX Audit plugins) and administrators can use secure connection to the admin console.

  • Trusted certificates for the DirX Audit Manager, DirX Audit Manager Classic, DirX Audit Server REST services and jobs when using LDAP or OIDC authentication over a secure channel. These certificates must form a trusted certificate chain to authenticate the configured LDAP Server or OIDC provider.

  • Trusted certificates for the DirX Audit Manager Classic and jobs when using the authorization with DirX Access over a secure channel. These certificates must form a trusted certificate chain to authenticate the configured DirX Access Server.

  • Trusted certificates for the LDAP and JMS Server Collectors and history synchronization jobs. These certificates must form a trusted certificate chain to authenticate the configured collectors and jobs.

If a service offers a non-secure endpoint, a client of the service can use it. However, secure channels must be preferred when personally identifiable information (PII) is transferred: clients should be configured to connect to secure endpoints and services should offer only secure endpoints to avoid accidental leaks of sensitive information from using a non-secure channel.

About Java Keystores

There are several formats for representing cryptographic material. DirX Audit uses Java KeyStore (JKS) and requires all the cryptographic material to be supplied in this form.

The JKS format allows storing multiple entries of various types in a single file and therefore can serve as a universal general-purpose cryptographic material container. Entries are referred via aliases. A private entry (an entry that contains a private key) can be protected with a password. The entire file can employ password protection as well.

As noted above, a keystore file can contain both certificates, which are public keys with additional information that verifies their origin and conditions for use, and private keys.
A keystore file that only contains certificates is often called a truststore to distinguish it from keystores dedicated to hold sensitive data. A truststore is usually used as the source of trust anchors; as such, the file provides no sensitive information (all of the certificates are public), but its content determines which endpoints are trusted and so it must be protected from unauthorized modifications. Keystores that contain private keys are sensitive data in all cases and thus must be kept private.

In DirX Audit, we use the term keystore for a keystore file that contains private (server) keys and required certificates – this file is used by servers like DirX Audit Message Broker and
the term truststore for a keystore file that contains public certificates and the required trust chain, up to the certificate authority (CA) – this file is used by clients like collectors and authenticator and authorization policy enforcement points (PEPs).

Preparing Cryptographic Material

There are many suitable tools for creating Java keystores. The Java installation itself contains a tool called keytool which is sufficient to complete the most common tasks, although this command line tool does not offer the same ease of use as other third-party tools, some of which provide a graphical user interface.

Feel free to use your favorite tool for creating the JKS file for the DirX Audit configuration. This guide shows just a few examples of using keytool. See the keytool help and documentation for all the details, including outstanding examples of typical tasks (https://docs.oracle.com/en/java/javase/11/tools/keytool.html).

To set up the test environment, you will need to create your own CA and testing certificates and then use the created CA to sign these certificates. The generated certificates will be added to a keystore that will be used by the Configuration Wizard when a keystore is needed. The complete trust certification chain (CA certificate and signed generated certificates) will then be added to a truststore that will be used by the Configuration Wizard when a truststore is needed.

To set up your production environment, you will typically get the CA certificate and generated certificates. You will then only need to add them into the keystores and trustores if they are not already in the required (JKS) format.

The next sections describe these preparation tasks.

Creating a Certificate Authority

In order for a certificate to be trusted, the certificate must be signed by a well-known and accepted CA. However, involving a well-known CA for a testing environment might not be acceptable for many reasons; for example, the costs of the certificates. The solution is to make and use your own CA for use within the testing environment.

The following command creates a keystore file ca.jks that contains the entry with the alias ca. The entry contains a new RSA private key and a self-issued certificate with the DN set to CN=CA, O=Demo and with the validity period of 3,650 days (approximately 10 years). Passwords are entered on prompt and the tool’s defaults apply for other settings.

keytool -genkeypair -keystore ca.jks -alias ca -keyalg RSA
   -dname CN=CA,O=Demo -ext bc:c -validity 3650

We need to export the CA public certificate in the PEM format for later use. The following commands perform the actions required to have a CA certificate in a file:

keytool -keystore ca.jks -alias ca -exportcert -rfc > ca.pem

Creating and Signing the Server Key, Certificate and Keystore

The following command creates a keystore file server.jks that contains the server key. The server identification must be properly set in the certificate and typically matches the hostname of the machine hosting the desired service, for instance:

keytool -genkeypair -keystore server.jks -alias server -keyalg RSA
   -dname CN=server.demo.org,O=Demo

The server certificate then needs signing by a CA in order to be trusted when the CA is trusted. First, we need to create the certificate request and then to sign this certificate with our CA. The certificate is then exported into PEM format. For the request, we must set
the correct hostname of the machine hosting the desired service. In this case, it’s server.demo.org. The validity is set to 1,825 days (approximately 5 years). We will use the CA created in the previous step in this example. The following commands perform the actions required to have a CA-signed server certificate in a file:

keytool -keystore server.jks -certreq -alias server > server.csr

keytool -keystore ca.jks -gencert -alias ca
   -ext ku:c=dig,keyEncipherment,keyAgreement
   -ext san=dns:server.demo.org
   -validity 1825
   -rfc -infile server.csr > server.pem

The server.pem file now contains the CA-signed server certificate, which must be imported into the server keystore. To achieve this result, a chain must be composed by chaining the ca.pem and server.pem files. Use this command on Windows:

copy ca.pem+server.pem chain.pem

Or this command on a UNIX system:

cat ca.pem server.pem > chain.pem

The chain for importing is now ready in chain.pem and can be imported with a single command:

keytool -keystore server.jks -importcert -alias server
   -file chain.pem

The tool presents the CA certificate, if not imported into the keystore, and asks whether it is trusted; if agreed, the input is imported. Finally, server.jks contains the server key and certificate signed with the testing CA.

Of course, this scenario can be modified. For instance, if there is an existing CA that can handle the CSR, it is enough to send the CSR file and then import the reply, leaving out some of the steps. It might be necessary to include additional extensions in some of the steps in order to achieve the desired result, especially when dealing with an existing CA that may have specific requirements.

Beware of a minor bug that is currently in keytool: error messages are displayed on the standard output instead of the error output, so if a command that redirects the standard output to a file (like the examples just given that store a PEM file), the error message can end up appearing in the file instead of the display. In this case, the user can see no sign of a problem, although the output is invalid. When redirecting the output of keytool, check the output. If it contains an error message, try to correct the problem first to get the correct output.

Creating the Server-Client Truststore

While the keystore created in the previous step can be used by the server itself, we need to create a truststore for the clients that will connect to this server that contains all of the public certificates of the server and its trust chain. In our example, it’s only the server certificate and the CA certificate as this is the final root one.

To import the CA certificate (stored in the file ca.pem):

keytool -keystore client.jks -importcert -alias ca -file ca.pem

To import the server certificate (stored in the file server.pem):

keytool -keystore client.jks -importcert -alias server
   -file server.pem

Importing Certificates in Different Formats

A more typical scenario assumes that the input for a keystore already exists, but in a different format (for example, PKCS #12 or CER) and must be imported to a Java keystore. The following command examples show how to use keytool for these import tasks.

A whole PCKS #12 keystore my-store.p12 can be imported into a Java keystore client.jks using this command:

keytool -importkeystore
   -srckeystore my-store.p12 -srcstoretype PKCS12
   -destkeystore client.jks

A certificate from file cert-file.cer can be imported into a Java keystore client.jks under the alias my-cert using this command:

keytool -importcert
   -alias my-cert -file cert-file.cer
   -keystore client.jks

You can use tools like openssl to convert other formats.

Importing Certificates into the Java CA Store

It may also be necessary in some cases to import a certificate into the general Java CA store instead of into a custom truststore; for example, when setting up the secure connection to DirX Access Server configured in the DirX Audit authorization settings. You need to import it into the Java truststore cacerts file located in jre_install_path/lib/security/.

You can use the following keytool command to import the CA certificate dxaca.pem into the target JRE truststore cacerts:

keytool -keystore full_file_path/cacerts -importcert -alias cert.dirxaccess -file full_file_path/dxaca.pem

Updating Cryptographic Material

You may need to update the cryptographic material, for example to replace expired keys.

If the standard Java KeyStore (JKS) is used, update its content only. No Configuration Wizard action is required.

If the original keystore and truststores locations (file names and paths) and passwords are preserved, follow these steps (no Configuration Wizard action is required):

If the original keystore and truststores locations or passwords are modified, follow the steps below. Some of them require Configuration Wizard to perform core- and tenant-specific actions.

  • Prepare the new keystore and truststores. Keep the original passwords. See the section “Preparing Truststores and Keystores for SSL Configuration” in the DirX Audit Installation Guide for more information.

  • Stop all DirX Audit Server, DirX Audit Message Broker and Apache Tomcat, hosting DirX Audit Manager, system services.

  • Replace the stores (JKS files). Keep the original locations and passwords.

  • Perform the following cryptographic material related step with Configuration Wizard for core configuration, if relevant: