Contact Us 1-800-596-4880

TLS Configuration

The TLS Configuration element is independent of any module or transport. For now the only module that supports it is the new HTTP connector, but it is designed so that it can be used by other modules in the future. You can also create this element through the UI of the HTTP Connector’s Global configuration element, on the TLS/SSL 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, both are optional:

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

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.

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 implement two way TLS authentication, also known as mutual authentication.

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" />
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>
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.

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