SSL Configuration

When setting up secure JMX connections over SSL/TLS, you can configure the stream-jmx either to simply trust the server's certificate (one-way SSL) or to perform mutual authentication (two-way SSL). This guide will cover both scenarios:

1. One-way SSL (using a truststore).
2. Two-way SSL (using both a keystore and a truststore).

• Access to the JMX server that requires SSL.
• Certificates from the JMX server (public certificate or a trusted CA certificate).
• Optionally, a client certificate and a private key (if two-way SSL is required).

To secure communication between the JMX stream-jmx and server, SSL certificates are used to verify identities and encrypt data. Depending on the level of security required, you might use one of the following:

• One-way SSL: The stream-jmx verifies the server's identity using a truststore.
• Two-way SSL (Mutual Authentication): Both stream-jmx and server verify each other using their respective keystores and truststores.

You need to obtain the server's public SSL certificate or the CA certificate used to sign the server's certificate. There are several ways to get the certificate:

• Using openssl:

  openssl s_client -showcerts -connect <server>:<port> </dev/null

   
  • Replace <server> with the hostname or IP address of the endpoint
  • Replace <port> with the port number of the endpoint

  Extract and save the certificate:

  • After running the command, you'll see a block of text starting with -----BEGIN CERTIFICATE----- and ending with -----END CERTIFICATE-----.
  • Copy the full block (including the BEGIN and END lines) and save it to a file (e.g., server1.crt).

• From the server administrator: Ask for the server's SSL certificate or the CA certificate.

In addition to the server's certificate, you need a client certificate and private key that the server can trust.

• Client Certificate: If required, your organization or server admin will provide a certificate.
• If the certificate is in a format like .pem, .crt, or .key, you can convert it to a keystore format (JKS) using tools like keytool or openssl.

The truststore is used to store the certificates that the stream-jmx trusts. In this case, it will contain the server's SSL certificate or the CA certificate used to sign it.

1. If you don't have an existing truststore, create one using keytool:

   keytool -import -alias <server-alias> -file <server-cert-file.crt> -keystore <truststore.jks> -storepass <truststore-password>

    
   • Replace <server-alias> with a unique alias (e.g., jmx-server).
   • Replace <server-cert-file.crt> with the server's certificate file.
   • Replace <truststore.jks> with the path to your truststore file (or a new truststore file).
   • Replace <truststore-password> with a password for the truststore.

   Example:

   keytool -import -alias server1 -file server1.crt -keystore myTruststore.jks -storepass changeit
   keytool -import -alias server2 -file server2.crt -keystore myTruststore.jks -storepass changeit

After importing, you can verify that the truststore contains the correct certificate:

keytool -list -keystore <truststore.jks> -storepass <truststore-password>

This will display a list of all certificates in the truststore.

The keystore is used to store the client's private key and client certificate. The server will use this to verify the client's identity.

1. If your client certificate is in separate .crt and .key files, you may need to convert them into a keystore format (JKS). You can use openssl to combine the certificate and private key into a single file and then import it into the keystore.

Convert a PEM certificate and key to a .p12 file:

openssl pkcs12 -export -in client-cert.crt -inkey client-key.key -out client.p12 -name client-cert

Once you have a .p12 file, import it into a JKS keystore:

keytool -importkeystore -deststorepass <keystore-password> -destkeystore <keystore.jks> \
        -srckeystore client.p12 -srcstoretype PKCS12 -srcstorepass <p12-password> -alias client-cert

• Replace <keystore-password> with the password for the new keystore.
• Replace <client.p12> with the path to the .p12 file.
• Replace <keystore.jks> with the new keystore file.
• Replace <p12-password> with the password you set during the PKCS12 export.

You can verify that the keystore contains the correct private key and certificate:

keytool -list -keystore <keystore.jks> -storepass <keystore-password>

Now, you need to configure your stream-jmx JVM to use the appropriate truststore (and keystore, if using two-way SSL).

If the server has set com.sun.management.jmxremote.registry.ssl=true, add application argument cp:com.sun.jndi.rmi.factory.socket=javax.rmi.ssl.SslRMIClientSocketFactory to match server configuration. Do not add com.sun.management.jmxremote.registry.ssl=true for client-side configuration.

Configure your JVM to use the truststore when making the JMX connection:

-Djavax.net.ssl.trustStore=<path_to_truststore.jks>
-Djavax.net.ssl.trustStorePassword=<truststore-password>
-Djavax.net.ssl.trustStoreType=JKS
-Dcom.sun.management.jmxremote.ssl=true
-Dcom.sun.management.jmxremote.ssl.need.client.auth=false

• javax.net.ssl.trustStore: Path to your truststore (e.g., truststore.jks).
• javax.net.ssl.trustStorePassword: Password for the truststore.
• com.sun.management.jmxremote.ssl.need.client.auth=false: Indicates no client authentication is needed (i.e., one-way SSL).

If the JMX server requires the client to authenticate itself using a client certificate, you'll need to configure both the keystore and truststore:

-Djavax.net.ssl.keyStore=<path_to_keystore.jks>
-Djavax.net.ssl.keyStorePassword=<keystore-password>
-Djavax.net.ssl.trustStore=<path_to_truststore.jks>
-Djavax.net.ssl.trustStorePassword=<truststore-password>
-Djavax.net.ssl.keyStoreType=JKS
-Djavax.net.ssl.trustStoreType=JKS
-Dcom.sun.management.jmxremote.ssl=true
-Dcom.sun.management.jmxremote.ssl.need.client.auth=true

• javax.net.ssl.keyStore: Path to the client's keystore file (e.g., keystore.jks).
• javax.net.ssl.keyStorePassword: Password for the keystore.
• com.sun.management.jmxremote.ssl.need.client.auth=true: This enables two-way SSL, meaning the client must authenticate itself with a certificate.

To debug SSL issues, you can enable SSL debugging in the JVM. This will print detailed information about the SSL handshake, certificates, and any errors.

Add the following option to your Java command:

-Djavax.net.debug=ssl

Example:

-Djavax.net.ssl.trustStore=<path_to_truststore.jks>
-Djavax.net.ssl.trustStorePassword=<truststore-password>
-Dcom.sun.management.jmxremote.ssl=true
-Djavax.net.debug=ssl

This will output detailed logs about the SSL/TLS handshake process, which can be helpful if you encounter issues connecting to the JMX server.

Look out for any certificate validation issues (such as expired or untrusted certificates). In case you need to access a server with an expired SSL certificate, you can disable SSL certificate validation by adding stream-jmx CLI argument -ssl.