<tls:context name="customContext">
<tls:trust-store path="trustStore" password="mulepassword"/>
<tls:key-store path="clientKeystore" keyPassword="mulepassword"
password="mulepassword"/>
</tls:context>
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:
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
-
Read more about TLS in Wikipedia
-
See how to configure the HTTP Connector
-
See how authentication works in the HTTP Connector
-
Refer to the deprecated HTTPS Transport