<tls:context name="customContext">
<tls:trust-store path="trustStore" password="mulepassword"/>
<tls:key-store path="clientKeystore" keyPassword="mulepassword"
password="mulepassword"/>
</tls:context>
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. 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. |
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:
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" />
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. |
If you’re using the HTTP Connector for a 2-way TLS authenticated connection, the client certificate is exposed using the inbound property You can access the client principal through: |
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:
|
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 |
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 |
Required |
keyPassword |
The key manager password (password for the private key inside the key store) |
Required |
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.
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