Free MuleSoft CONNECT Keynote & Expo Pass Available!

Register now+
Nav

About TLS Configuration

Mule Runtime 4.x supports Transport Layer Security (TLS) 1.1/1.2. 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.

You configure the tls:context element in the Mule XML configuration file to set up TLS. This 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.

Keystores and Truststores

A TLS enabled server needs to have a private key and a public certificate. The private key never leaves the server. The public certificate is exposed through TLS. TLS enabled clients can then verify that they trust the server by validating that certificate against a set of their own.

You import certificates and private keys into a keystore file that Mule uses. Trust store files are also key stores that by convention include only public certificates of trusted servers.

While there’s a default Java trust store, there is no default Java key store in the standard JRE distribution, so you must add your own 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 trust store, so no set up 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 trust store contains certificates from trusted CAs that the client uses to verify a certificate presented by the server.

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 a values for the trust-store, Mule uses the default Java trust store. 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.

Mule supports many types of key stores, including the following ones:

  • JCEKS

  • PKCS12

  • JKS

The key store type is configurable at the JRE level.

To generate a key store or trust store, or both, you can use the Java Keytool from Oracle. For more information, see Oracle documentation:

https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html

Generating 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 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.

  2. 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

  3. 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.

Generating a Trust Store

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.

Configuring TLS

Adding a trust store or a key store to a TLS configuration will have a different impact depending on the kind of usage:

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

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

Adding both a key store and a trust store to the configuration, therefore, implicitly implements two-way TLS authentication, also known as mutual authentication.

The keystore might contain two passwords. One of them can access the entire keystore file. The other (keyPassword) can access the server’s private key, which is inside this file.

Configuration for Clients

If the tls:context is empty (no key-store or trust-store defined), then the default values of the JVM are used, which likely already include a trust store 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 the <tls:trust-store> element must be added. Set the path field set 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 also added with the path field set to the location of the keystore file that contains the private/public keys of the client.

Configuration for Servers

The tls:context is required to contain a tls:key-store element to listen for a request using a secure connection (such as HTTPS). You set the path field to the location of the key store file that contains the private/public keys of the server.

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

Protocols and Cipher Suites

When a TLS communication takes place between two systems, a negotiation determines which protocol and cipher suite are used.

You can configure protocols and cipher suites in the Mule /conf directory in $MULE_HOME. $MULE_HOME is the directory where your Mule installation resides, for example /opt/mule-4.0. Select one of two files for fine-tuning the configuration by manually setting which cipher suites and protocols Mule will use:

  • 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.

The list of protocols and cipher suites that you set in these configuration files can then be constrained locally by what is set up in an individual tls:context element if those parameters are defined.

Only those protocols and cipher suites enabled on both ends can be used.

If you do not configure protocols and cipher suites, the default Java environment protocol and cipher suites are used.

You can then specify a subset of the configured or default values in the tls:context element for use by TLS. You configure the protocols and cipher suites in the enabledProtocols and enabledCipherSuites in the tls:context element.

In the tls:context element, you cannot reference protocols or cipher suites here that are not included in your global TLS configuration file or defaults. In the tls:context element, you can set enabledProtocols and enabledCipherSuites to the value default. In this case, 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 impact the readability of your XML code. To improve readability, keep these names in an external properties file in your Mule project and refer to it.

You can then reference your properties using the following syntax:


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

XML Reference for TLS

This following tls:context element and attributes define TLS communication in a Mule app. You typically define a TLS configuration globally and reuse it. You refer to the global definition to apply it to a specific use, such as listening for or sending HTTPS requests.

Globally Defined 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).

You can include two nested elements: key-store and trust-store. Including one is required.


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

Attributes of the tls-context Element

The attributes are optional.

  • enabledProtocols: The protocols named in the the global TLS configuration to enable

  • enabledCipherSuites: The cipher suites named in global TLS configuration to enable

Attributes of the trust-store Element

The attributes other than the path attribute are optional.

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

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

  • password: The trust store password

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

  • insecure: Boolean that determines whether or not to validate the trust-store. If set to true, no validation occurs. Default = false

Setting 'insecure' to 'true' renders connections vulnerable to attacks and is recommended only for prototyping and testing purposes.

Attributes of the key-store Element

The attributes other than the path attribute 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 key store. Default = SunX509

TLS Configuration Examples

The following examples show how to set up TLS in the Mule XML configuration file.

Example: Configuring TLS for a Client

The following example secures an FTPS client by setting up a trust store:


          
       
1
2
3
4
5
6
7
<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

The following example secures an HTTP listener by setting up a key store:


          
       
1
2
3
4
5
6
7
<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

The following example sets up two-way, or mutual, authentication, described later in this document, for an HTTP listener.


          
       
1
2
3
4
5
6
7
8
<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

Using the insecure property, described later in this document, you can disable validations for prototyping and development. Not recommended for use otherwise.


          
       
1
2
3
<tls:context>
    <tls:trust-store path="tls/ssltest-cacerts.jks" password="changeit" insecure="true"/>
</tls:context>

Example: Adding Additional Cipher Suites and Protocol Restrictions

The following example shows how to enable a specific protocol and cipher suite.


          
       
1
2
3
<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>

Using the Studio or Design Center UI to Configure TLS

You can configure TLS in Studio and Design Center. For example, in Design Center, you can set up TLS in the HTTP listener configuration in a flow design:

design center tls setup

For example, in Studio you can set up a global TLS configuration from a connector configuration, such as HTTP:

studio tls setup