Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.5)
  3. Reference
  4. Transports Reference

  5. HTTPS Transport Reference

HTTPS Transport Reference

Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can migrate to the latest Mule version.

The Secure HTTP transport provides support for exposing applications over HTTP and making HTTP client request from Mule flows to external services as part of event flows. Mule supports secure inbound, secure outbound, and secure polling HTTP endpoints. These endpoints support all common features of the HTTP spec, such as ETag processing, cookies, and keepalive. Both HTTP 1.0 and 1.1 are supported.

HTTPS Connector

This connector provides Secure HTTP connectivity on top of what is already provided with the Mule [HTTP Transport]. Secure connections are made on behalf of an entity, which can be anonymous or identified by a certificate. The key store provides the certificates and associated private keys necessary for identifying the entity making the connection. Additionally, connections are made to trusted systems. The public certificates of trusted systems are stored in a trust store, which is used to verify that the connection made to a remote system matches the expected identity.

Setting Up a HTTPS Server

In order to setup a HTTPS server with Mule a few first steps need to be performed. First a keystroke must be created, this can be done using the keytool provided by Java. You can find this in the bin directory of the Java installation. Once located you can then execute the following command to create a keystore:

keytool -genkey -alias mule -keyalg RSA -keystore keystore.jks

This will create a file in the local directory called keystore.jks. Ideally, this should be created in MULE_HOME/conf directory if to be used accross multiple applications or can be put into the <MY MULE APP>/src/main/resources directory if being used within a single application.

Once the keystore is in place the following needs to be added to you Mule configuration file:

<https:connector name="httpsConnector">
     <https:tls-key-store path="keystore.jks" keyPassword="<Your Password>" storePassword="<Your Password>"/>
 </https:connector>

If the key store was in the <MY MULE APP>/src/main/resources directory then you can just specify that name in the path. Otherwise, if the keystore was located in the MULE_HOME/conf directory then you will have to specify "${mule.home}/conf/keystore.jks" as the path.

Configuration Reference

Property Description

tls-client

Configures the client key store with the following attribute:

  • path: The location (which will be resolved relative to the current classpath and file system, if possible) of the keystore that contains public certicates and private keys for identification.

  • storePassword: The password used to protect the keystore.

  • class: The type of keystore used (a Java class name).

tls-key-store

Configures the direct key store with the following attribute:

*path: The location (which will be resolved relative to the current classpath and file system, if possible) of the keystore that contains public certificates and private keys for identification. * class: The type of keystore used (a Java class name). * keyPassword: The password used to protect the private key. * storePassword: The password used to protect the keystore. * algorithm: The algorithm used by the keyspace. * keyAlias: The alias of the key to use.

tls-server

Configures the trust store. The attirbutes are:

  • path: The location (which will be resolved relative the current classpath and file system, if possible) of the trust store that contains public certificate of trusted server.

  • storePassword: The password used to protect the trust store.

  • class: The type of trust store used (a Java class name).

  • algorithm: The algorithm used by the trust store.

  • factory-ref: Reference to the trust manager factory.

  • explicitOnly: Whether this is an explicit trust store.

  • requireClientAuthentication: Whether client authentication is required.

tls-protocol-handler

Configure the global Java protocol handler. It has one attribute, property, which specifies the java.protocol.handler.pkgs system property.

For example:

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:spring="http://www.springframework.org/schema/beans"
      xmlns:https="http://www.mulesoft.org/schema/mule/https"
    xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
        http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.0/mule.xsd
        http://www.mulesoft.org/schema/mule/https http://www.mulesoft.org/schema/mule/https/3.0/mule-https.xsd">

    <https:connector name="httpConnector">
        <https:tls-client path="clientKeystore" storePassword="mulepassword"/>
        <https:tls-key-store path="serverKeystore" keyPassword="mulepassword" storePassword="mulepassword"/>
        <https:tls-server path="trustStore" storePassword="mulepassword"/>
    </https:connector>

    <https:endpoint name="clientEndpoint" host="localhost" port="60202"
                    connector-ref="httpConnector" />
</mule>

Polling Connector

The polling connector allows Mule to poll an external HTTP sever and generate events from the result. This is useful for pull-only web services. This connector provides a secure version of the PollingHttpConnector. It includes all the properties of the HTTPS connector plus the following optional attributes:

Attribute Description

pollingFrequency

The time in milliseconds to wait between each request to the remote http server.

checkEtag

Whether the Etag header from the remote server is processed if the header is present.

discardEmptyContent

Whether Mule should discard any messages from the remote server that have a zero content length. For many services, a zero length would mean there was no data to return. If the remote HTTP server does return content to say that the request is empty, users can configure a content filter on the endpoint to filter these messages out.

For example, after defining the HTTP namespace in the header, you could configure the polling connector like this:

<http:polling-connector name="PollingHttpConnector" pollingFrequency="2000" />

HTTPS Endpoints

An inbound HTTPS endpoint exposes a flow securely over HTTPS, essentially making it an HTTP sever. If polling of a remote HTTP service is required, this endpoint should be configured with a polling HTTPS connector.

An outbound HTTPS endpoint allows Mule to send requests securely using SSL to external servers or Mule inbound HTTP endpoints using HTTP over SSL protocol.

A global HTTPS endpoint can be referenced by flows.

For more information on configuring HTTP endpoints, see HTTP Transport Reference.

Fine-Tuning SSL Endpoints

The Mule conf folder includes two files that allow you to fine-tune the configuration of SSL endpoints by manually setting which cipher suites Mule can use and which SSL protocols are allowed:

  • 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 FIPS security mode).

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.

Contents of tls-default.conf

# This file allows to restrict SSL behavior in Mule. If the file doesn't exist or a property is not defined,
# default values of the current security provider will be used.
# Cipher suites that will be enabled in SSL. If this property is set, SSL sockets will
# only use cipher suites that are provided in this list and supported by the current security provider.
#enabledCipherSuites=TLS_KRB5_WITH_3DES_EDE_CBC_MD5,        \
#                    TLS_KRB5_WITH_RC4_128_SHA,             \
#                    SSL_DH_anon_WITH_DES_CBC_SHA,          \
#                    TLS_DH_anon_WITH_AES_128_CBC_SHA,      \
#                    TLS_DHE_RSA_WITH_AES_128_CBC_SHA,      \
#                    SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA, \
#                    SSL_RSA_EXPORT_WITH_RC4_40_MD5,        \
#                    SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA,     \
#                    TLS_DHE_RSA_WITH_AES_256_CBC_SHA,      \
#                    TLS_KRB5_WITH_3DES_EDE_CBC_SHA,        \
#                    SSL_RSA_WITH_RC4_128_SHA,              \
#                    TLS_KRB5_WITH_DES_CBC_MD5,             \
#                    TLS_KRB5_EXPORT_WITH_RC4_40_MD5,       \
#                    TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5,   \
#                    SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA, \
#                    TLS_KRB5_EXPORT_WITH_RC4_40_SHA,       \
#                    SSL_DH_anon_EXPORT_WITH_RC4_40_MD5,    \
#                    SSL_DHE_DSS_WITH_DES_CBC_SHA,          \
#                    TLS_KRB5_WITH_DES_CBC_SHA,             \
#                    SSL_RSA_WITH_NULL_MD5,                 \
#                    TLS_DHE_DSS_WITH_AES_256_CBC_SHA,      \
#                    SSL_DH_anon_WITH_3DES_EDE_CBC_SHA,     \
#                    TLS_RSA_WITH_AES_128_CBC_SHA,          \
#                    SSL_DHE_RSA_WITH_DES_CBC_SHA,          \
#                    TLS_DH_anon_WITH_AES_256_CBC_SHA,      \
#                    TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA,   \
#                    SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA, \
#                    SSL_RSA_WITH_NULL_SHA,                 \
#                    TLS_KRB5_WITH_RC4_128_MD5,             \
#                    TLS_RSA_WITH_AES_256_CBC_SHA,          \
#                    SSL_RSA_WITH_DES_CBC_SHA,              \
#                    TLS_EMPTY_RENEGOTIATION_INFO_SCSV,     \
#                    SSL_RSA_EXPORT_WITH_DES40_CBC_SHA,     \
#                    SSL_DH_anon_WITH_RC4_128_MD5,          \
#                    SSL_RSA_WITH_RC4_128_MD5,              \
#                    TLS_DHE_DSS_WITH_AES_128_CBC_SHA,      \
#                    SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA,     \
#                    SSL_RSA_WITH_3DES_EDE_CBC_SHA
# Protocols that will be enabled in SSL. If this property is set, SSL sockets will only use protocols
# that are provided in this list and supported by the current security provider.
#enabledProtocols=SSLv2Hello, \
#                 TLSv1,      \
#                 SSLv3

Contents of tls-fips140-2.conf

# TLS configuration file used when running Mule in FIPS mode. To use this configuration,
# you must set the "mule.security.model" property to "fips140-2" in the wrapper.conf file.
# Sockets will only use cipher suites from this list.
enabledCipherSuites=SSL_RSA_WITH_3DES_EDE_CBC_SHA,         \
                    SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA,     \
                    TLS_RSA_WITH_AES_128_CBC_SHA,          \
                    TLS_DHE_DSS_WITH_AES_128_CBC_SHA,      \
                    TLS_DHE_RSA_WITH_AES_128_CBC_SHA,      \
                    TLS_RSA_WITH_AES_256_CBC_SHA,          \
                    TLS_DHE_DSS_WITH_AES_256_CBC_SHA,      \
                    TLS_DHE_RSA_WITH_AES_256_CBC_SHA,      \
                    TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA,  \
                    TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,   \
                    TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,   \
                    TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA, \
                    TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,  \
                    TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,  \
                    TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,    \
                    TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,     \
                    TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,     \
                    TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,   \
                    TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,    \
                    TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA