Contact Us 1-800-596-4880
  1. Homepage
  2. HTTP Connector (0.3.7)

  3. TLS Configuration

All Connectors

TLS Configuration

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.

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>

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

The 'tls:trust-store' and 'tls:key-store' elements must reference existing certificates. If you don’t provide any values for the trust-store, default Java certificates are used. To generate your own certificates, you can do so by following the steps below using the Java Keytool.

Generating a Keystore

  1. To generate a keystore that exposes your server’s credentials, run the command:

    keytool -genkey -alias serverkey -keyalg RSA -keystore server.jks
    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' argument.

  2. You are prompted for additional details, along with the store password and key password.

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

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

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

To generate a trustStore, run this command:

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

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

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.

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.

HTTPS Examples 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 are used, which likely already includes 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.

HTTPS Examples 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" />
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: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>

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

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

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

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

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

See Also