Configuring Mulesoft TrustStore

Configuring the TrustStore is a required step when deploying Mulesoft agents with TLS to connect to the Traceable Platform Agent (TPA) securely. Whether your deployment uses a single certificate or a chain of certificates, the TrustStore ensures the Mulesoft agent can validate the server's certificate and establish a secure connection. This guide walks you through the steps to set up the TrustStore with a certificate chain and optionally disable client-side TLS validation if needed.

Additionally, this topic consolidates information about configuring TLS settings for the agent.

Before You Begin

Before starting the configuration, ensure you have the following:

1. Access to Certificates:

   • The server certificate (domain.crt).

   • The private key for the server certificate (domain.key).

   • Any intermediate certificates (leaf.pem, intermediate.pem).

   • The root certificate (root.pem).

2. OpenSSL Installed:

   • Verify that openssl is installed on your system. This is required to generate the PKCS12 file.

3. Keytool Utility:

   • Ensure keytool is available for converting the PKCS12 file into a Java Keystore.

4. Administrative Access:

   • You need administrative permissions to modify and deploy the Mulesoft agent configuration.

5. Determine Applicability:

   • Confirm that you are using TLS with a chain of certificates to connect to the TPA. If not, you can skip this guide.

Steps to Configure the TrustStore

Step 1 — Create the TrustStore

Follow the appropriate sub-step based on your certificate type.

For a Single Certificate

• What you are doing:
  Importing the root or self-signed certificate into a Java Keystore using the keytool utility.

• Why this is important:
  The Java Keystore stores trusted certificates, allowing the Mulesoft agent to validate the server's identity and establish secure communication.

Command:

keytool -import -alias serverkey -keystore client_truststore.jks -file root_ca.crt -storetype JKS

For a Chain of Certificates

1. Combine the certificates into a single file (chain.cert.pem), starting with the server certificate and ending with the root certificate:

   • What you are doing:
     Creating a chained PEM file that includes all certificates required to establish a chain of trust.

   • Why this is important:
     A single file ensures the TrustStore can validate the complete chain of certificates, from the server (leaf) certificate to the root certificate.

   Command:

   cat domain.crt leaf.pem intermediate.pem root.pem > chain.cert.pem

2. Convert the chained PEM file into a PKCS12 file:

   • What you are doing:
     Packaging the certificate chain and private key into a secure PKCS12 file.

   • Why this is important:
     The PKCS12 format is required to convert certificates into a Java Keystore.

   Command:

   openssl pkcs12 -export -inkey domain.key -in chain.cert.pem -out cert-chain.pkcs12

3. Import the PKCS12 file into a Java Keystore:

   • What you are doing:
     Converting the PKCS12 file into a Java Keystore format.

   • Why this is important:
     Java applications like the Mulesoft agent require certificates to be stored in a Keystore for TLS connections.

   Command:

   keytool -importkeystore -srckeystore cert-chain.pkcs12 -srcstoretype PKCS12 -destkeystore client_truststore.jks

Step 2 — Integrate the TrustStore into Mulesoft Configuration

1. Place the TrustStore File:

   • What you are doing:
     Copying the TrustStore file into the appropriate directory for the Mulesoft policy.

   • Why this is important:
     The Mulesoft agent needs to know where to find the TrustStore for certificate validation.

   Command:

   cd traceable-mule-policy/traceable/src/main
   cp client_truststore.jks resources/truststore/

2. Update the Policy Template:

   • What you are doing:
     Replacing the placeholder in the template.xml file with the actual TrustStore file path and password.

   • Why this is important:
     Ensures the agent uses the correct TrustStore for validating the TPA's server certificate.

   Example configuration:

   <tls:trust-store path="truststore/client_truststore.jks" password="<truststore_password>" type="jks"/>

3. Deploy the Mulesoft Policy:

   • What you are doing:
     Deploying the updated Mulesoft policy to apply the TrustStore configuration.

   • Why this is important:
     Deploying the policy ensures the Mulesoft agent uses the updated TrustStore for TLS communication.

   Command:

   cd traceable-mule-policy
   # Use your environment-specific command to deploy the policy.
   # For example:
   # mvn deploy  (if using Maven)
   # or refer to your organization's deployment guidelines.

Optional: Disabling Client-Side Validation

In scenarios where client-side TLS validation is not required (e.g., for testing), you can disable it by updating the TLS context. This approach is not recommended for production environments.

Example Configuration:

<tls:context name="clientTlsContext">
  <tls:trust-store insecure="true"/>
</tls:context>

What you are doing:
You are configuring the Mulesoft agent to bypass server certificate validation during TLS communication.

Why this is important:
This can be useful for testing purposes or troubleshooting certificate issues. However, it should not be used in production as it compromises the connection's security.