Configuring a SSL Connection for the MongoDB agent (4309289)

Configuring a SSL Connection for the MongoDB agent

How to configure a SSL connection for the MongoDB agent

The below instructions cover common steps used to configure a TLS/SSL connection from the MongoDB Agent client. For full information on secure connections and server-side configuration, refer to the TLS/SSL Configuration for Clients section of the MongoDB documentation for your database version.

A full treatment of TLS/SSL keys, certificates, and certificate authorities (CA) is beyond the scope of this document. The following instructions assume familiarity with TLS/SSL concepts and tools. Client and certificate authority certificates must be available prior to proceeding.

In order to use SSL, your MongoDB server must include SSL support and allow SSL connections. There are various configurations options for client connections. Refer to the MongoDB documentation and verify that the current MongoDB server configuration parameters support the desired authentication.

The Foglight agent, in its capacity as a database client, requires access to a private key, its signed certificate, and the signing CA’s certificate. The client key and certificate must be imported into a keystore, and the CA certificate must be imported into a separate truststore.

One example method for generating a JKS keystore for use with Foglight utilizes openssl and keytool. Set the key and certificate filenames, alias name, and keystore password as appropriate.

openssl pkcs12 \
        -export \
        -in $CERT_NAME.crt \
        -inkey $CERT_NAME.key \
        -name $CERT_NAME \
        -out temp-keystore.p12 \
        -passout pass:$KEYPASS

keytool -importkeystore \
        -srckeystore temp-keystore.p12 \
        -srcstoretype PKCS12 \
        -srcstorepass $KEYPASS \
        -destkeystore $KEYSTORE \
        -deststoretype JKS \
        -deststorepass $KEYPASS

Regardless of how the keystore is constructed, it must list the client certificate as a 'PrivateKeyEntry', indicating that it also contains the private key, not just the signed certificate.

Separately, import the CA certificate into a truststore:

keytool -importcert \
        -keystore $TRUSTSTORE \
        -alias $CA_NAME \
        -file $CA_NAME.crt \
        -keypass $TRUSTPASS \
        -storepass $TRUSTPASS \
        -storetype JKS \ -noprompt

The default JRE keystore is saved in [FglAM_HOME]/jre/[version]/jre/lib/security/cacerts, after importing the CA certificate here, copy this file to an alternate path so it doesn't get replaced after an upgrade (e.g. [FglAM_HOME]/truststore/)

In order to use SSL, your MongoDB server must include SSL support and allow SSL connections.

Next, edit the baseline.jvmargs.config file in the /state/default/config directory and add the following parameters with file paths and passwords appropriate for your system.

vmparameter.0 = "-Djavax.net.ssl.keyStore=/path/to/keystore";
vmparameter.1 = "-Djavax.net.ssl.keyStorePassword=changeit";
vmparameter.2 = "-Djavax.net.ssl.trustStore=/path/to/truststore";
vmparameter.3 = "-Djavax.net.ssl.trustStorePassword=changeit";

The following are suggested commands to import the files:

* Have a backup of your current keystore/truststore files in advance.

Import a root or intermediate CA certificate (if different that what already exist) to an existing Java truststore (keystore):

keytool -import -trustcacerts -alias somerootalias -file ca_cert.pem -keystore truststorestore.jks
keytool -import -trustcacerts -alias anotheralias -file intermediate_if_any.pem -keystore truststorestore.jks

Import a signed primary certificate & key to an existing Java keystore:

- combined.pem: is the combined of the cert + key in a single pem file

keytool -import -trustcacerts -alias yourdomain_or_dnsname_alias -file combined.pem -keystore yourkeystore.jks

Or if you have the pkcs12 file for the certs:

Import pkcs12 into keystore:
keytool -importkeystore -srckeystore yoursource.p12 -srcstoretype PKCS12 -destkeystore keystore.jks -deststoretype JKS

Import pkcs12 into truststore:
keytool -importkeystore -srckeystore yourCAsource.p12 -srcstoretype PKCS12 -destkeystore truststore.jks -deststoretype JKS

 

How to Specify a Keystore Path with Spaces in a JVM Argument

When specifying a path to a keystore in a JVM argument (e.g., -Djavax.net.ssl.keyStore) that contains spaces, it’s important to correctly handle the path formatting to avoid errors.

Steps for Correct Formatting:

1. Use Forward Slashes (/) in the Path (Recommended):

   • Forward slashes are universally supported and avoid the need to escape backslashes.
   • Enclose the entire path in quotes, and escape the quotes around the path.

   Example:

   vmparameter.0 = "-Djavax.net.ssl.keyStore=\"C:/Foglight Agent Manager/keystorename\""

2. Use Backslashes (\\) for Windows-style Paths:

   • If you prefer using backslashes, make sure to escape each backslash (\\) and escape the quotes around the path.

   Example:

   vmparameter.0 = "-Djavax.net.ssl.keyStore=\"D:\\Foglight Agent Manager\\keystorename\""

Key Points:

• Always use quotes around paths with spaces.
• Use escaped quotes (\") to properly handle the path inside the argument string.
• Escape backslashes (\\) if using Windows-style paths with backslashes.

vmparameter.0 = "-Djavax.net.ssl.keyStore=\"C:/Foglight Agent Manager/keystorename\"";
vmparameter.1 = "-Djavax.net.ssl.keyStorePassword=changeit";
vmparameter.2 = "-Djavax.net.ssl.trustStore=\"C:/Foglight Agent Manager/truststore/cacerts\"";
vmparameter.3 = "-Djavax.net.ssl.trustStorePassword=changeit";

 

Then, restart the FglAM and continue with the agent configuration, setting the “Use TLS/SSL?” option in the Agent Properties to true. If the client certificate is not configured specifically for the FglAM host, you can also set the “Allow Invalid Cert Hostname?” option to true to allow the certificate to be used anyway.

 

There are cases where the given cert.pem file contains also the private key cert in it. In those cases it is required to break down the file into two separate files one will be certificate.pem and the other will be privatekey.pem in order to be able to run the openssl command as suggested to create the temporary keystore. The default truststore (cacerts) ships with multiple well known 3rd party CA certificates for convenience but using the -Djavax.net.ssl.trustStore parameter overrides the default trust store for the JRE that runs the FglAM. If additional CA certificates are required, use the default cacerts as a starting point; import the additional CA certificates into cacerts and make a copy of this file as the custom trust store to take advantage of the existing CA certificates. --------------- The default JRE keystore is saved in [FglAM_HOME]/jre/[version]/jre/lib/security/cacerts, after importing the CA certificate here, copy this file to an alternate path so it doesn't get replaced after an upgrade (e.g. [FglAM_HOME]/truststore/) The default for the Embedded FglAM is not cacerts but rather \state\default\certificates\certificate.store and it does not have a password enforced. Add the certificates manually to cacerts.