TLS Configuration

TLS 1.0 is no longer a valid protocol due to its significant vulnerabilities.

We encourage all users to use TLS 1.1/1.2.
In order to move away from TLS 1.0, open your relevant configuration file (either 'tls-default.conf' or 'tls-fips140-2.conf') and remove TLSv1 from the enabledProtocols field.

Studio 5.4.3 also allows you to custom configure your TLS configuration for your Studio and API Gateway runtimes by exposing the TLS default settings in a Studio folder.
Please refer to our documentation for configuration instructions.

The TLS Configuration Element

The TLS Configuration element is independent of any module or transport. In Mule 3.7 onwards, it’s supported both by the HTTP Connector and in the Web Service Consumer.

You can create this element through the UI of the HTTP Connector’s Global configuration element, on the TLS/SSL tab, or through the UI of the Web Service Consumer, on the Security tab.

If a connector supports TLS, Studio shows the TLS/SSL tab on that connector’s Global configuration element.

In XML, the basic syntax for the element is the following:

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

You can include a TLS context element in a domain project so that it can be shared amongst multiple projects that are deployed to a same server.

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

Inside it, you can include two nested elements: key-store and trust-store. You don’t need to include both, but at least one of the two must be present:

From the server side: the trust store contains certificates of the trusted clients, the key store contains the private and public key of the server.
From the client side: the trust store contains certificates of the trusted servers, the key store contains the private and public key of the client.

Adding a trust store or a key store to a TLS configuration implicitly implements the corresponding kind of authentication. Adding both a keystore and a trust store to one same config (as in the code example above) implicitly implements two way TLS authentication, also known as mutual authentication.

The keystore may contain two passwords, as one of them can serve for accessing the entire keystore file, whilst the other (keyPassword) may be additionally needed to access the server’s private key, which is inside this file.

Generating Keystores and Truststores

A TLS service needs to have a private key and a public certificate. The private key never leaves the server. The public certificate is exposed through TLS so clients can verify if they trust the server.

Certificates can be generated by a well-known Certificate Authority (CA) or can be generated locally without external approval (self-signed certificates). Certificates generated from Certificate Authorities include digital signatures and are usually accepted as trusted by any client that includes the CA certificate in its repository of trusted certificates (trust store).

For Mule products, certificates and private keys must be imported into Java keystore files. Trust store files are also keystores that by convention only include public certificates of trusted servers.

The 'tls:trust-store' and 'tls:key-store' elements must reference existing certificates. If you don’t provide any values for the trust-store, the default Java trust store is used. The default trust store is updated with the Java version, so it’s recommended that you use an updated Java version to be sure it includes updates to well known CA certificates.

To generate your own certificates, you can do so by following the steps below using Java Keytool.

Generating a Keystore

To generate a keystore that exposes your server’s credentials, run the command:
```
keytool -genkey -alias serverkey -keyalg RSA -keystore server.jks
```

The generated keystore will contain a private key and a public certificate. This certificate is self signed so it will be 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 as in the example above through the '-keyalg RSA' argument.

You will then be prompted for additional details, along with the store password and key password.
Once this is done, you must export the server’s certificate from the keystore so that it can be shared with clients. To do this, use the following command:
```
keytool -export -alias serverkey -keystore server.jks -file server_cert.cer
```

There is no default Java key store in the standard JDK distribution, so you must generate your own certificates in order to use this element.

If you also wish to get signed by a Certification Authority (CA), you must export your certificate in the standard CSR format. To do so you can run this command:

keytool -certreq -keystore server.jks -alias example.com -file certificate_file

Here, '-file' refers to the name you wish to give to your certificate file. Once generated, send the CSR file to the CA and follow their instructions to obtain their signature.

Once you have obtained the CA’s signature, you can import the signed certificate file through the following command:

keytool -import -keystore keystore -alias example.com -file signed_certificate_file

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

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 wish to have greater security or when using self-signed certificates.

To create a trustStore, run the command:

keytool -import -alias serverkey -keystore client_truststore.ts -file server_cert.cer

The client will trust the server if a chain of trust can be established, either directly to the server (in case its certificate is in the trust store) or through a signing CA whose certificate is present in the trust store, failing otherwise. This means that a trust store must be defined when using self-signed certificates.

Global TLS configuration

Besides the ability to set up trust store and key store at 'tls:context' level, you can define some other parameters at a global level for every app you deploy to Mule.

The Mule 'conf' folder located in your $MULE_HOME directory includes two files that allow you to fine-tune the configuration of SSL connectors 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 FIPS security mode)
tls-fips140-2.conf (Allows fine-tuning when Mule is running in FIPS security mode)

$MULE_HOME` is the directory where your Mule installation resides, for example /opt/mule-3.4.1.

Open the relevant file and comment or uncomment items in the lists to manually configure the allowed cipher suites and SSL 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.

Examples (for HTTPS)

For the HTTP Request Connector

A request-config element from the new HTTP connector may reference a tls:context element in order to implement HTTPS. If the tls:context is empty (no key-store or trust-store defined), then the default values of the JVM will be 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, with the path field set to the location of the trust store 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.

Globally Defined TLS Element

<tls:context name="clientTlsContext" >
        <tls:trust-store path="trustStoreFile" password="1234"/>
        <tls:key-store path="keyStoreFile" keyPassword="123" password="456"/>
    </tls:context>

    <http:request-config name="globalConfig" protocol="HTTPS" host="localhost" port="8443" tlsContext-ref="clientTlsContext" />

You can also create this element through the UI of the HTTP Connector’s Global configuration element, on the TLS/SSL tab. Select Use Global TLS Config, then click the green plus sign next to TLS Context to create a new TLS element.

Nested TLS Element

<http:request-config name="globalConfig" protocol="HTTPS" host="localhost" port="8443">
        <tls:context>
            <tls:trust-store path="trustStoreFile" password="1234"/>
            <tls:key-store path="keyStoreFile" keyPassword="123" password="456"/>
        </tls:context>
    </http:request-config>

You can also create this element through the UI of the HTTP Connector’s Global configuration element, on the TLS/SSL tab. Select Use TLS Config, then provide values for the fields presented there to set up the trust store and/or the key store.

For the HTTP Listener Connector

A listener-config element from the new HTTP connector may reference a tls:context element in order to configure HTTPS. In this case, the tls:context is required to at least contain a tls:key-store element, with the path field set 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, then a tls:trust-store element should also be added, with the path field set to the location of the trust store file that contains the certificates of the trusted clients.

Globally Defined TLS Element

<tls:context name="serverTlsContext" >
        <tls:trust-store path="trustStoreFile" password="1234"/>
        <tls:key-store path="keyStoreFile" keyPassword="123" password="456"/>
    </tls:context>

    <http:listener-config name="globalConfig" protocol="HTTPS" host="localhost" port="8443" tlsContext-ref="serverTlsContext" />

Nested TLS Element

<http:listener-config name="globalConfig" protocol="HTTPS" host="localhost" port="8443">
        <tls:context>
            <tls:trust-store path="trustStoreFile" password="1234"/>
            <tls:key-store path="keyStoreFile" keyPassword="123" password="456"/>
        </tls:context>
    </http:listener>

If you’re using the HTTP Connector for a 2-way TLS authenticated connection, the client certificate is exposed using the inbound property http.client.cert.

You can access the client principal through: inboundProperties['http.client.cert'].getSubjectDN()

Attributes of the tls-context Element

Attribute

Description

Required

enabledProtocols

Specifies which protocols to enable, out of the list of protocols set in the Global TLS configuration

Optional

enabledCipherSuites

Specifies which cipher suites to enable, out of the list in Global TLS configuration

Optional

Cipher Suite names can be very lengthy, which can have an impact in the readability of your XML code. To keep things neater, you can instead keep your Cipher Suite names in an external properties file in your Mule project and refer to it.

You can then reference your properties via the following syntax:

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

Attributes of the trust-store Element

Attribute

Description

Required

path

Path to the file that contains the trust store.

Required

type

The type of the trust store (default JKS)

Optional

password

The trust store password.

Optional

algorithm

The algorithm used in the trust store (default SunX509)

Optional

insecure

Boolean that determines if validations against the trust-store are to be done at all. If set to true, all certificates are accepted without any validation. If not set, it defaults to 'false'

Optional

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

Attributes of the key-store Element

Attribute

Description

Required

path

Path to the file that contains the key store.

Required

type

The type of the key store (default JKS)

Optional

password

The key store password

Optional

keyPassword

The key manager password (password for the private key inside the key store)

Optional

algorithm

The algorithm used in the key store (default SunX509)

Optional

Protocol & Cipher Suite Behavior

Whenever a TLS communication takes place between two systems, a negotiation determines which protocol and cipher suite will be used out of the list of those that are enabled on both ends. The following logic determines how this list of enabled protocols and cipher suites is defined:

If nothing is configured, you will use the list of protocols and cipher suites that are available by default with your Java environment.
If you have a Global TLS configuration file, the lists you define in its 'enabledProtocols' and 'enabledCipherSuites' property will be used instead.

In your 'tls:context' element, you can include the 'enabledProtocol' and 'enabledCipherSuites' properties and select a subset of the protocols and cipher suites that are included in your global TLS configuration file. You cannot reference protocols or cipher suites here that are not included in your global TLS configuration file (if one is present).

Note that this property supports adding the value "default", which falls back on the default protocols and cipher suites that you configured in your Global TLS configuration or on the default ones of your Java environment, depending on whether the former is present.

TLS Configuration

The TLS Configuration Element

Generating Keystores and Truststores

Generating a Keystore

Generating a Trust Store

Global TLS configuration

Examples (for HTTPS)

For the HTTP Request Connector

Globally Defined TLS Element

Nested TLS Element

For the HTTP Listener Connector

Globally Defined TLS Element

Nested TLS Element

Attributes of the tls-context Element

Attributes of the trust-store Element

Attributes of the key-store Element

Protocol & Cipher Suite Behavior

See Also