HTTPS Transport Reference

As of Mule 3.6 and later, the HTTP endpoint-based connector and transport has been replaced by an operation-based HTTP connector.

The legacy endpoint-based connector will be removed in a future version. See HTTP Connector for more information about the HTTP operation-based connector and how to migrate your projects to it.

The Secure HTTP transport provides support for exposing applications over HTTP and making HTTP client requests 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 keystore 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 the MULE_HOME/conf directory if to be used across 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 your mule configuration file:

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

If the keystore was in the <MY MULE APP>/src/main/resources directory then you can just specify the 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

Property	Description
tls-client	Configures the client key store with the following attributes: 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 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 attributes: 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 keystore keyAlias: The alias of the key to use
tls-server	Configures the trust store. The attributes are: path: The location (which will be resolved relative to the current classpath and file system, if possible) of the trust store that contains public certificates of trusted servers 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	Configures the global Java protocol handler. It has one attribute, property, which specifies the `java.protocol.handler.pkgs` system property.

tls-client

Configures the client key store with the following attributes:

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
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 attributes:

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 keystore
keyAlias: The alias of the key to use

tls-server

Configures the trust store. The attributes are:

path: The location (which will be resolved relative to the current classpath and file system, if possible) of the trust store that contains public certificates of trusted servers
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

Configures 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/current/mule.xsd
        http://www.mulesoft.org/schema/mule/https http://www.mulesoft.org/schema/mule/https/current/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 server 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.

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 server. 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 in 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