Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (4.1)
  3. Security

  4. TLS Configuration

Configure TLS with Keystores and Truststores

Standard Support for Mule 4.1 ended on November 2, 2020, and this version of Mule reached its End of Life on November 2, 2022, when Extended Support ended.

Deployments of new applications to CloudHub that use this version of Mule are no longer allowed. Only in-place updates to applications are permitted.

MuleSoft recommends that you upgrade to the latest version of Mule 4 that is in Standard Support so that your applications run with the latest fixes and security enhancements.

TLS is a cryptographic protocol that provides communications security for your Mule app. TLS offers many different ways of exchanging keys for authentication, encrypting data, and guaranteeing message integrity. This topic describes TLS as supported by Mule and how to configure TLS in Mule apps.

Mule Runtime 4 (Mule 4) supports Transport Layer Security (TLS) 1.1/1.2.

The tls:context Element

The tls:context element is used for all connectors that support TLS. For example, you can configure TLS in HTTP (server and client), FTPS (client), Email (client) or Sockets (client) connectors, among others.

If a connector supports TLS, Studio shows either:

  • A TLS/SSL tab on that connector’s Global Elements Properties.

  • A field TLS Configuration on the General tab of that connector’s Global Element Properties.

The TLS-Enabled Server and Client

A TLS-enabled server contains a private key and a public certificate:

  • The private key never leaves the server.

  • The public certificate is exposed through TLS.

TLS-enabled clients verify that they trust the server by validating the public certificate against their own set of trusted certificates.

To use TLS communications security in Mule 4, import certificates and private keys into a keystore file. Truststore files are also keystores that by convention include only public certificates of trusted servers.

While there’s a default Java truststore, there is no default Java keystore in the standard JRE distribution. Add your own keystore to the TLS context. You likely already have corporate certificates for your client apps and don’t need to create them. Often, these certificates work with the JRE truststore, so no setup is required in the TLS context.

A well-known Certificate Authority (CA) can generate certificates, or you can generate a certificate locally without external approval (self-signed certificate). A truststore contains certificates from trusted CAs that the client uses to verify a certificate presented by the server.

Keystores and Truststores

The tls:trust-store and tls:key-store elements in a Mule configuration can reference a specific certificate and key, but if you don’t provide values for tls:trust-store, Mule uses the default Java truststore. Java updates the default trust store when you update Java, so getting regular updates is recommended to keep well-known CA certificates up-to-date.

Truststore and keystore contents differ depending on whether they are used for clients or servers:

  • For servers: the truststore contains certificates of the trusted clients, the keystore contains the private and public key of the server.

  • For clients: the truststore contains certificates of the trusted servers, the keystore contains the private and public key of the client.

Adding both a keystore and a truststore to the configuration implements two-way TLS authentication also known as mutual authentication.

The keystore contains one or two passwords:

  • password accesses the entire keystore file.

  • keyPassword accesses the server’s private key inside the keystore.

Client Configuration

If the tls:context is empty (no tls:key-store or tls:trust-store defined), then the default values of the JVM are used, which usually include a truststore with certificates for all the major certifying authorities.

If the client requires a certificate from the server that it is trying to connect to, then add the tls:trust-store element. Set path to the location of the truststore file that contains the certificates of the trusted servers.

If the server validates certificates from the clients, then the tls:key-store element should be added with path set to the location of the keystore file that contains the private/public keys of the client.

Server Configuration

The tls:context must contain a tls:key-store element to listen for a request using a secure connection such as HTTPS. Set path to the location of the keystore file that contains the private/public keys of the server.

If the server needs to validate certificates from clients, add a tls:trust-store element and set path to the location of the trust store file that contains the certificates of the trusted clients.

Mule supports many types of keystores, including:

  • JCEKS

  • PKCS12

  • JKS

Specify your keystore type in the JRE.

To fully configure TLS for a Mule app:

  1. Generate a keystore and a truststore, using the Java Keytool from Oracle.

  2. Configure TLS globally for client or server in Mule.

  3. Optional: Specify Protocols and Cipher Suites.

Generate a Keystore

This procedure describes how to generate the keystore and perform the other tasks mentioned in this procedure.

  1. Generate a keystore that exposes your server’s credentials. For example:

    keytool -genkey -alias serverkey -keyalg RSA -keystore mykeystore.jks

    Respond to the keytool prompts. The following output shows example responses:

    • Enter keystore password: mule123

    • Re-enter new password: mule123

  2. Respond to prompts to enter other values. You can enter arbitrary values. The following output shows example responses:

    • What is your first and last name? [Unknown]: max

    • What is the name of your organizational unit? [Unknown]: MuleSoft

    • What is the name of your organization? [Unknown]: MuleSoft Inc

    • What is the name of your City or Locality? [Unknown]: San Francisco

    • What is the name of your State or Province? [Unknown]: CA

    • What is the two-letter country code for this unit? [Unknown]: 01

  3. In response to the following prompt, enter yes.

    Is CN=kahn, OU=MuleSoft, O=MuleSoft Inc, L=San Francisco, ST=CA, C=01 correct? [no]: yes

  4. Respond to the following prompt. For example, use the same password by entering RETURN.

    Enter key password for <serverkey> (RETURN if same as keystore password):

  5. Enter the command to export a self-signed certificate authenticating the public key.

    keytool -export -alias serverkey -keystore httplistener.jks -file server_cert.cer

  6. Respond to the prompt to enter the password you set up for the KeyStore associated with the certificate.

    Enter keystore password: mule123

  7. Alternatively, instead of exporting just a self-signed certificate, generate both a certificate from Certificate Authorities and a self-signed certificate using a single command:

    keytool -genkeypair \
    -keystore httplistener.jks \
   -dname "CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown" \
   -keypass mule123 \
   -storepass mule123 \
   -keyalg DSA \
   -sigalg SHA1withDSA \
   -keysize 1024 \
   -alias mulekey \
   -ext SAN=DNS:localhost,IP:127.0.0.1 \
   -validity 9999

    The generated keystore contains a private key and a public certificate. This certificate is self signed so it is not be trusted by clients unless you share the public certificate with them.

    Keytool generates certificates using the DSA algorithm by default. You can instead specify it to use the RSA algorithm.

  8. Export the server’s certificate from the keystore to share with clients. For example, enter the command to export a self-signed certificate authenticating the public key.

    keytool -export -alias serverkey -keystore mykeystore.jks -file server_cert.cer

  9. Respond to the prompt to enter the password you set up for the keystore.

    The standard JDK distribution does not include a keystore by default, so you generate your own.

    If you also want to get the certificate signed by a Certification Authority (CA), you export your certificate in the standard CSR format. You specify the name you want to give to your certificate file. You send the CSR file to the CA and follow their instructions to obtain their signature. After you have obtained the CA’s signature, you can import the signed certificate file.

    The alias you assign when importing must not be linked to any existing key or the process fails.

Generate a Truststore

The standard JRE distribution includes a default trust store with certificates for several major certificate authorities (CA’s) which is used by default in the 'tls:trust-store' element, but you can generate your own if you want greater security or if you use self-signed certificates.

To create a trust store, you can use the Oracle Java keytool.

The client trusts the server if a chain of trust can be established, either directly to the server (in case its certificate is in the truststore) or through a signing CA whose certificate is present in the truststore; otherwise, the connection fails. A trust store must be defined when using self-signed certificates.

Configure TLS in Mule 4

To enable TLS for Mule apps, configure the tls:context element in the Mule XML configuration file in one of three ways:

Whichever method you use, we recommend you review the information in Edit XML to Configure TLS to understand how the attributes of tls:context function.

Edit XML to Configure TLS

The tls:context element defines TLS communication in a Mule app. Unless you have a special requirement, configure TLS globally and then apply it to each specific use, such as listening for or sending HTTPS requests.

Globally Define a TLS Element

The tls:context element defines a configuration for TLS, which can be used from both the client and server sides. The element can be referenced by other configuration objects of other modules or defined as a nested element of one of them.

Include at least one of the nested elements: key-store and trust-store.

<tls:context name="customContext">
    <tls:trust-store path="trustStore" password="mulepassword"/>
    <tls:key-store path="clientKeystore" keyPassword="mulepassword"
password="mulepassword"/>
 </tls:context>

Optional Attributes of the tls-context Element

Optionally, specify the protocol and cipher suite to enable them:

  • enabledProtocols: The protocols in the the global TLS configuration

  • enabledCipherSuites: The cipher suites in global TLS configuration

These values are used if there is nothing specified in the global TLS configuration, or if the values are enabled in a global TLS configuration, as described in Optional: Specify Protocols and Cipher Suites.

Attributes of the trust-store Element

The password attribute is required if you specify a path. Otherwise, the attributes are optional.

  • path: The path to the file that contains the trust store

  • type: The type of the trust store. Default = JKS

  • password: The trust store password (required if you specify path)

  • algorithm: The algorithm the trust store uses. Default = SunX509

  • insecure: Boolean that determines whether or not to validate the truststore. If set to true, no validation occurs. The default value is false.

Setting insecure to true renders connections vulnerable to attack. Use it only for prototyping or testing. Never use it in production environments.

Attributes of the key-store Element

The attributes other than path are optional.

  • path: The path to the file that contains the keystore (required)

  • type: The type of the keystore (default JKS)

  • password: The keystore password

  • keyPassword: The key manager password, which is the password for the private key inside the keystore

  • algorithm: The algorithm used in the keystore. The default value is SunX509.

Use Design Center to Configure TLS

You can configure TLS for your app in Design Center. For example, to configure TLS in HTTP Listener:

  1. Log into Design Center.

  2. Open the project.

  3. Open HTTP Listener.

  4. In the Configuration tab, click Edit.

  5. In the TLS tab, fill in the TLS Configuration fields as described above.

  6. Optionally, fill in the Enabled Protocols and Enabled Cipher Suites fields as described in Optional: Specify Protocols and Cipher Suites.

Save your configuration and test.

Use Anypoint Studio to Configure TLS

You can configure TLS for your app in Anypoint Studio (Studio). For example, to configure TLS in HTTP Listener:

  1. Open Studio Center.

  2. Open the project.

  3. Open HTTP Listener.

  4. In the General tab, select an existing configuration or create a new one.

  5. In the HTTP Listener config dialog, select the TLS tab.

  6. In the TLS tab, choose the TLS Configuration type Edit Inline, and supply the values.

  7. Optionally, fill in the Enabled Protocols and Enabled Cipher Suites fields in the Advanced section as described in Optional: Specify Protocols and Cipher Suites.

Save your configuration and test.

Optional: Specify Protocols and Cipher Suites

When a TLS communication takes place between two systems, a negotiation determines which protocol and cipher suite are used. Optionally, administrators can specify the protocols and cipher suites to use, and then app developers can specify which cipher suites and protocols to use in tls:context.

Protocols and cipher suites must be enabled in Mule Runtime and individual apps to be used. If the protocols and cipher suites aren’t enabled in both places, the default Java environment protocol and cipher suites are used.

To configure protocols and cipher suites in the Mule Runtime:

  1. The Mule admin edits the /conf directory in $MULE_HOME. $MULE_HOME points to the directory where your Mule installation resides, for example /opt/mule-4.0. Select the appropriate file where you specify the cipher suites and protocols:

    • tls-default.conf allows fine-tuning when Mule is not configured to run in Federal Information Processing Standards (FIPS) security mode.

    • tls-fips140-2.conf allows fine-tuning when Mule is running in FIPS security mode.

      Open the relevant file and comment or uncomment items in the lists to manually configure the allowed cipher suites and TLS protocols. If you make no changes to these files, Mule allows the configured security manager to select cipher suites and protocols for an app.

  2. The list of protocols and cipher suites that the admin sets in these configuration files can then be constrained locally by what the app developer specifies in an individual tls:context element. The app developer specifies a subset of the configured or default values in the tls:context element for use by TLS. Configure the protocols and cipher suites in enabledProtocols and enabledCipherSuites in the tls:context element.

In the tls:context element, you can only reference protocols or cipher suites that are included in the Mule global TLS configuration file or defaults. In tls:context, set enabledProtocols and enabledCipherSuite for a Mule app to the value default. After these values are set, TLS uses the following protocols and cipher suites:

  • Those configured in your global TLS configuration if it exists

  • The defaults provided by your Java environment if a global TLS configuration does not exist

Cipher suite names can be long and reduce the readability of your XML code. To improve readability, keep these names in an external properties file in your Mule project. You can then reference the properties. For example:

<tls:context name="serverTlsContext" enabledCipherSuites="${myCipherSuites}" >

TLS Configuration Examples

You can set up TLS in a Mule XML configuration file for a client or a server.

Example: Configuring TLS for a Client

This example secures an FTPS client by setting up a truststore:

<ftps:config name="ftps">
    <ftps:connection username="anonymous" password="password" host="localhost" port="21" workingDir="/dev">
        <tls:context >
            <tls:trust-store path="trustStore" password="mulepassword" />
        </tls:context>
    </ftps:connection>
</ftps:config>

Example: Configuring TLS for a Server

This example secures an HTTP listener by setting up a keystore:

<http:listener-config name="nestedConfig">
    <http:listener-connection protocol="HTTPS" host="localhost" port="8081">
        <tls:context>
            <tls:key-store path="tls/ssltest-keystore.jks" keyPassword="changeit" password="changeit"/>
        </tls:context>
    </http:listener-connection>
</http:listener-config>

Example: Configuring TLS for Two-Way Authentication

This example sets up two-way authentication (also called mutual authentication), for an HTTP listener:

<http:listener-config name="nestedConfig">
    <http:listener-connection protocol="HTTPS" host="localhost" port="8081">
        <tls:context>
            <tls:trust-store path="tls/ssltest-cacerts.jks" password="changeit"/>
            <tls:key-store path="tls/ssltest-keystore.jks" keyPassword="changeit" password="changeit"/>
        </tls:context>
    </http:listener-connection>
</http:listener-config>

Example: Disabling TLS Validations

This example uses the insecure property to disable validations for prototyping and development.

Do not use the insecure property in production environments. 
<tls:context>
    <tls:trust-store path="tls/ssltest-cacerts.jks" password="changeit" insecure="true"/>
</tls:context>

Example: Adding Additional Cipher Suites and Protocol Restrictions

This example enables a protocol and cipher suite for an app, assuming a Mule admin has either specified nothing in the global TLS configuration or enabled the cipher suites and protocols being specified here.

<tls:context name="tlsClientContext" enabledProtocols="TLSv1.2" enabledCipherSuites="TLS_DHE_DSS_WITH_AES_128_CBC_SHA256">
    <tls:trust-store path="tls/trustStore" password="mulepassword"/>
</tls:context>

See Also