Configuring a SSL Connection for the MongoDB agent (4309289)

This article provides step-by-step instructions to configure a secure TLS/SSL connection between the MongoDB Agent and a MongoDB server. It assumes familiarity with TLS/SSL concepts and tools such as openssl and keytool.

The Foglight Agent Manager (FglAM) acts as a database client and requires a valid SSL configuration to securely connect to MongoDB. If the JVM does not trust the MongoDB server certificate, the connection will fail with errors such as:

PKIX path building failed: unable to find valid certification path to requested target

1. Create a Keystore:
   

   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

   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/)
   
   
2. Create a Truststore:
   

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

3. Configure JVM Parameters:
   Edit baseline.jvmargs.config and add the following, making sure both the keyStore and trustStore lines are present.

   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";  

4. Restart FglAM:
   Restart the Foglight Agent Manager to apply changes.
   
   
5. Configure Agent Properties:
   Set Use TLS/SSL? to true. If the certificate hostname does not match the FglAM host, set Allow Invalid Cert Hostname? to true.

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.

• If your PEM file contains both certificate and key, split it into certificate.pem and privatekey.pem before using openssl.
• The default truststore (cacerts) includes many well-known CA certificates. You can import additional CA certs and copy the file to a custom location to avoid overwrites during upgrades.
• Embedded FglAM uses \state\default\certificates\certificate.store by default, which has no password. Consider switching to a custom truststore for better control.
• Use keytool or openssl to validate certificate chains and hostname resolution.