Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.2)
  3. Reference Materials for Mule ESB 3
  4. = Reference Materials for Mule ESB 3
  5. Configuration Reference

  6. SSL and TLS Transports Reference

SSL and TLS Transports Reference

Introduction

SSL and TLS are alternative names for the same transport. (For simplicity, this page will refer to it only as SSL, but everything here applies to TLS as well.) This transport allows sending or receiving messages over SSL connections. SSL is a layer over IP and used to implement many other reliable protocols such as HTTPS and SMTPS. However, you may want to use the SSL transport directly if you require a specific protocol for reading the message payload that is not supported by one of these higher level protocols. This is often the case when communicating with legacy or native system applications that don’t support web services.

Namespace and Syntax

XML namespace:

xmlns:ssl="http://www.mulesoft.org/schema/mule/ssl"
xmlns:tls="http://www.mulesoft.org/schema/mule/tls"

XML Schema location:

http://www.mulesoft.org/schema/mule/ssl http://www.mulesoft.org/schema/mule/ssl/3.2/mule-ssl.xsd
http://www.mulesoft.org/schema/mule/tls http://www.mulesoft.org/schema/mule/tls/3.2/mule-tls.xsd

Connector syntax:

<ssl:connector name="tcpConnector" receiveBufferSize="1024" receiveBacklog="50" sendTcpNoDelay="false"
                reuseAddress="true" clientSoTimeout="0" serverSoTimeout="0" socketSoLinger="0"
                keepSendSocketOpen="false" keepAlive="true" dispatcherFactory-ref="dispatcherBean">
    <tcp:PROTOCOL-TYPE/>
    <ssl:client path="clientKeystore" storePassword="swordfish" class="JKS"/>
    <ssl:key-store path="keystore" class="JKS" keyPassword="swordfish" storePassword="sturgeon" algorithm="SHA"/>
    <ssl:server class="JKS" algorithm="SHA" explicitOnly="false" requireClientAuthentication = "false" />
    <ssl:protocol-handler type="com.mycompany.protocols"/>
</ssl:connector>

PROTOCOL-TYPE defines how messages in Mule are reconstituted from the data packets. The protocol types are:

<tcp:direct-protocol payloadOnly="true" rethrowExceptionOnRead="true"/>

<tcp:eof-protocol payloadOnly="true" rethrowExceptionOnRead="true"/>

<tcp:length-protocol payloadOnly="true" maxMessageLength="1024" rethrowExceptionOnRead="true"/>

<tcp:xml-protocol rethrowExceptionOnRead="true"/>

<tcp:xml-eof-protocol rethrowExceptionOnRead="true"/>

<tcp:streaming-protocol rethrowExceptionOnRead="true"/>

<tcp:safe-protocol payloadOnly="true" maxMessageLength="1024" rethrowExceptionOnRead="true"/>

<tcp:custom-class-loading-protocol classLoader-ref="classLoaderBean" payloadOnly="true" maxMessageLength="1024" rethrowExceptionOnRead="true"/>

<tcp:custom-protocol class="com.mycompany.MyProtocol" rethrowExceptionOnRead="true"/>

If no protocol is specified, safe-protocol is used.

Endpoint syntax:
You can define your endpoints 2 different ways:

  1. Prefixed endpoint:

    <ssl:inbound-endpoint host="localhost" port="65433"/>

  2. Non-prefixed URI:

    <inbound-endpoint address="ssl://localhost:65433"/>

See the sections below for more information.

Considerations

SSL is one of the standard communication protocols used on the Internet, and supports secure communication both across the internet and within a local area network. The Mule SSL transport uses native Java socket support, adding no communication overhead to the classes in java.net, while allowing many of the advanced features of SSL programming to be specified in the Mule configuration rather than coded in Java.

Use this transport when communicating using low-level SSL connections. To determine when this is appropriate, you can use the following decision tree:

  • Communicating with an external service that uses low-level unsecured TCP connections? If so, use the TCP protocol.

  • Are you communicating with a flow or service always located in the same Mule application instance? If so, consider use the VM transport.

  • Is it important that messages be persisted until they can be processed? If so, consider using a persistent transport like JMS or File.

  • Are there advantages to a higher-level protocol built on top of TCP, for instance, the request-response features of HTTP, or the store-and-forward features of Email? If so, use the transport for that protocol instead.

  • Is performance the primary concern and it is not important that messages be delivered in the proper order or that the sender is notified if any are lost? If so, use the lighter-weight UDP transport instead.

  • Should messages be secured? If so, use the SSL transport.

As shown in the examples below, the SSL transport can be used to

  • Create a SSL server

  • Send messages to a SSL server

The use of SSL with Java is described in detail in the JSSE Reference Guide. In particular, it describes the keystores used by SSL, how the certificates they contain are used, and how to create and maintain them.

Features

The SSL module allows a Mule application both to send and receive messages over SSL connections, and to declaratively customize the following features of SSL (with the standard name for each feature, where applicable):

  • The timeout for blocking socket operations. This can be declared separately for client and server operations. (SO_TIMEOUT)

  • How long to keep the socket open to allow pending sends to complete. (SO_LINGER)

  • Whether to send available data immediately rather than buffering it. (TCP_NODELAY)

  • Whether to reuse a socket address immediately (SO_REUSEADDR)

  • Whether to use keep-alive to detect when a remote system is no longer reachable (SO_KEEPALIVE).

  • The size in bytes of the network buffer (SO_SNDBUF).

  • The number of pending connection requests to allow.

  • Whether to close a client socket after sending a message.

In addition, since TCP and SSL are stream-oriented and Mule is message-oriented, some application protocol is needed to to define where each message begins and ends within the stream. The table below lists the built-in protocols, describing:

  • The XML tag used to specify them

  • Any XML attributes

  • How it defines a message when reading

  • Any processing it does while writing a message

XML tag Options Read Write Notes

<tcp:custom-class-loading-protocol>

rethrowExceptionOnRead, payloadOnly , maxMessageLength, classLoader-ref

Expects the message to begin with a 4-byte length (in DataOutput.writeInt() format)

Precedes the message with a 4-byte length (in DataOutput.writeInt() format)

Like the length protocol, but specifies a classloader used to deserialize objects

<tcp:custom-protocol>

rethrowExceptionOnRead, class, ref

varies

varies

Allows user-written protocols, for instance, to match existing TCP services.

<tcp:direct-protocol>

rethrowExceptionOnRead, payloadOnly

All currently available bytes

none

There are no explicit message boundaries.

<tcp:eof-protocol>

rethrowExceptionOnRead, payloadOnly

All bytes sent until the socket is closed

none

<tcp:length-protocol>

rethrowExceptionOnRead, payloadOnly , maxMessageLength

Expects the message to begin with a 4-byte length (in DataOutput.writeInt() format)

Precedes the message with a 4-byte length (in DataOutput.writeInt() format)

<tcp:safe-protocol

rethrowExceptionOnRead, payloadOnly , maxMessageLength Expects the message to begin with the string "You are using SafeProtocol" followed by a 4-byte length (in DataOutput.writeInt() format)

Expects the message to be preceded by the string "You are using SafeProtocol" followed by a 4-byte length (in DataOutput.writeInt() format)

Precedes the message with the string "You are using SafeProtocol" followed by a 4-byte length (in DataOutput.writeInt() format)

Somewhat safer than the length protocol because of the extra check. This is the default if no protocol is specified.

<tcp:streaming-protocol

rethrowExceptionOnRead

All bytes sent until the socket is closed

none

<tcp:xml-protocol>

rethrowExceptionOnRead

A message is an XML document that begins with an XML declaration

none

The XML declaration must occur in all messages

<tcp:xml-eof-protocol>

rethrowExceptionOnRead

A message is an XML document that begins with an XML declaration, or whatever remains at EOF

none

The XML declaration must occur in all messages

Protocol attributes:

name values default value notes

class

The name of the class that implements the custom protocol

See below for an example of writing a custom protocol

classLoader-ref

A reference to a Spring bean that contains the custom classloader

maxMessageLength

the maximum message length allowed

0 (no maximum )

A message longer than the maximum causes an exception to be thrown.

payloadOnly

true

If true, only the Mule message payload is sent or received. If false, the entire Mule message is sent or received.

Protocols that don’t support this attribute always process payloads

ref

A reference to a Spring bean that implements the custom protocol

rethrowExceptionOnRead

Whether to rethrow exception that occur trying to read from the socket

false

Setting this to "false" avoids logging stack traces when the remote socket is closed unexpectedly

SSL endpoints can be used in one of two ways:

  • To create an SSL server that accepts incoming connections, declare an inbound ssl endpoint with an ssl:connector. This creates an SSL server socket that will read requests from and optionally write responses to client sockets..

  • To write to an SSL server, create an outbound endpoint with an ssl:connector. This creates an SSL client socket that will write requests to and optionally read responses from a server socket.

Usage

To use SSL endpoints, follow the following steps:

  1. Add the MULE SSL namespace to your configuration:

  2. Define one or more connectors for SSL endpoints.

Create an SSL server

To act as a server that listens for and accepts SSL connections from clients, create an SSL connector that inbound endpoints will use:

<ssl:connector name="sslConnector"/>

Send messages to an SSL server

To send messages on an SSL connection, create a simple TCP connector that outbound endpoints will use:

<tcp:connector name="sslConnector"/>

  1. Configure the features of each connector that was created.

    • Begin by choosing the protocol to be used for each message that will be sent or received.

    • For each polling connector, choose how often it will poll and how long it will wait for the connection to complete.

    • Consider the other connector options as well. For instance, if it is important to detect when the remote system becomes unreachable, set keepAlive to true.

  2. Create SSL endpoints.

    • Messages will be received on inbound endpoints.

    • Messages will be sent to outbound endpoints.

    • Both kinds of endpoints are identified by a host name and a port.

By default, SSL endpoints use the request-response exchange pattern, but they can be explicitly configured as one-way. The decision should be straightforward:

Message flow Connector type Endpoint type Exchange Pattern

Mule receives messages from clients but sends no response

ssl:connector

inbound

one-way

Mule receives messages from clients and sends response

ssl:connector

inbound

request-response

Mule sends messages to a server but receives no response

ssl:connector

outbound

one-way

Mule sends messages to a server and receives responses

ssl:connector

outbound

request-response

Example Configurations

SSL connector in flow

<ssl:connector name="serverConnector" payloadOnly="false">
    <tcp:eof-protocol /> ❹
    <ssl:client path="clientKeystore"/>
    <ssl:key-store path="serverKeystore"/>
</tcp:connector> ❶


<flow name="echo">
    <ssl:inbound-endpoint host="localhost" port="4444" > ❷
    <ssl:outbound-endpoint host="remote" port="5555" /> ❸
</flow>

SSL connector in service

<ssl:connector name="connector" payloadOnly="false">
    <tcp:safe-protocol />  ❺
    <ssl:client path="clientKeystore"/>
    <ssl:key-store path="serverKeystore"/>
</ssl:connector>  ❶

<model name="echoModel">
    <service name="echo">
        <inbound>
            <ssl:inbound-endpoint host="localhost" port="4444" /> ❷
        </inbound>
        <outbound>
            <pass-through-router>
                <ssl:outbound-endpoint host="remote" port="5555" /> ❸
             </pass-through-router>
        </outbound>
    </service>
</model>

This shows how to create an SSL server in Mule. The connector at ❶ defines that a server socket will be created that accepts connections from clients. Complete mule messages are read from the connection (direct protocol) will become the payload of a Mule message (since payload only is false). The endpoint at ❷ applies these definitions to create a server at port 4444 on the local host. The messages read from there are then sent to a remote ssl endpoint at ❸.
The flow version uses the eof protocol (❹), so that every byte sent on the connection is part of the same Mule message. The service version uses the safe protocol (❺), so that multiple messages can be sent on the SSL connection, with each being preceded by a header that specifies its length. Note that both connectors specify separate keystores to be used by the client (outbound) and server (inbound) endpoints.

Configuration Options

SSL Connector attributes

Name Description Default

clientSoTimeout

the amount of time (in milliseconds) to wait for data to be available when reading from a TCP server socket

system default

keepAlive

Whether to send keep-alive messages to detect when the remote socket becomes unreachable

false

keepSendSocketOpen

Whether to keep the the socket open after sending a message

false

receiveBacklog

The number of connection attempts that can be outstanding

system default

receiveBufferSize

This is the size of the network buffer used to receive messages. In most cases, there is no need to set this, since the system default will be sufficient

system default

reuseAddress

Whether to reuse a socket address that’s currently in a TIMED_WAIT state. This avoids triggering the error that the socket is unavailable

true

sendBufferSize

The size of the network send buffer

system default

sendTcpNoDelay

Whether to send data as soon as its available, rather than waiting for more to arrive to economize on the number of packets sent

false

socketSoLinger

How long (in milliseconds) to wait for the socket to close so that all pending data is flused

system default

serverSoTimeout

the amount of time (in milliseconds) to wait for data to be available when reading from a client socket

system default

SSL Connector child elements and their attributes

Name Description

client

Configures the client keystore

`Client’s attributes:

Name Description

path

location of the client keystore

storePassword

Password for the client keystore

class

the type of keystore used
Name Description

key-store

Configures the server keystore

`key-store’s attributes:

Name Description

path

location of the server keystore

storePassword

Password for the server keystore

class

the type of server keystore used

keyPassword

Password for the private key

algorithm

algorithm used by the server keystore
Name Description

server

Configures the server trust store

`server’s attributes:

Name Description

class

the type of keystore used for the trust store

algorithm

algorithm used by the trust stor

factory-ref

A TrustManagerFactory configured as a Spring bean

explicitOnly

If true, do not use the server keystore when a trust store is unavailable. Defaults to false.

requireClientAuthentication

If true, all clients must authenticate themselves when communicating with a Mule SSL server endpoint. Defaults to false.
Name Description

protocol-handler

Defines a list of Java packages in which protocol handlers are found

`protocol-handler’s attributes:

Name Description

property

The list of packages.

For more details about creating protocol handlers in Java, see http://java.sun.com/developer/onlineTraining/protocolhandlers.

Configuration Reference

Element Listing

SSL Transport

The SSL transport can be used for secure socket communication using SSL or TLS. The Javadoc for this transport can be found here.

Connector

Connects Mule to an SSL socket to send or receive data via the network.

Inbound endpoint

Attributes of <inbound-endpoint…​>

Name Type Required Default Description

host

string

no

port

port number

no

Child Elements of <inbound-endpoint…​>

Name Cardinality Description

Outbound endpoint

Attributes of <outbound-endpoint…​>

Name Type Required Default Description

host

string

no

port

port number

no

Child Elements of <outbound-endpoint…​>

Name Cardinality Description

Endpoint

Attributes of <endpoint…​>

Name Type Required Default Description

host

string

no

port

port number

no

Child Elements of <endpoint…​>

Name Cardinality Description

Schema

The schema for the SSL module appears here. Its structure is shown below.

Namespace "http://www.mulesoft.org/schema/mule/ssl"

Targeting Schemas (1):

mule-ssl.xsd

Targeting Components:

4 global elements, 4 local elements, 3 complexTypes, 1 attribute group

Schema Summary

mule-ssl.xsd

The SSL transport can be used for secure socket communication using SSL or TLS.
Target Namespace:

http://www.mulesoft.org/schema/mule/ssl

Defined Components:

4 global elements, 4 local elements, 3 complexTypes, 1 attribute group

Default Namespace-Qualified Form:

Local Elements: qualified; Local Attributes: unqualified

Schema Location:

http://www.mulesoft.org/schema/mule/ssl/3.3/mule-ssl.xsd; see XML source

Imports Schemas (4):

mule-schemadoc.xsd, mule-tcp.xsd, mule.xsd, xml.xsd

Imported by Schema:

_mule-all-included.xsd

All Element Summary

client

The client key store.
Type: mule:tlsClientKeyStoreType
Content: empty, 4 attributes
Defined: locally witnin connector element in mule-ssl.xsd; see XML source

connector

Connects Mule to an SSL socket to send or receive data via the network.
Type: anonymous complexType (extension of tcp:tcpConnectorType)
Content: complex, 16 attributes, attr. wildcard, 11 elements
Subst.Gr: may substitute for element mule:abstract-connector
Defined: globally in mule-ssl.xsd; see XML source
Includes: definitions of 4 elements
Used: never

endpoint

Type: globalEndpointType
Content: complex, 13 attributes, attr. wildcard, 16 elements
Subst.Gr: may substitute for element mule:abstract-global-endpoint
Defined: globally in mule-ssl.xsd; see XML source
Used:never

inbound-endpoint

Type: inboundEndpointType
Content: complex, 13 attributes, attr. wildcard, 16 elements
Subst.Gr: may substitute for element mule:abstract-inbound-endpoint
Defined: globally in mule-ssl.xsd; see XML source
Used:never

key-store

The key store information, including location, key store type, and algorithm.
Type: mule:tlsKeyStoreType
Content:empty, 7 attributes
Defined: locally witnin connector element in mule-ssl.xsd; see XML source

outbound-endpoint

Type: outboundEndpointType
Content: complex, 13 attributes, attr. wildcard, 16 elements
Subst.Gr: may substitute for element mule:abstract-outbound-endpoint
Defined: globally in mule-ssl.xsd; see XML source
Used:never

protocol-handler

Configures the global Java protocol handler by setting the java.protocol.handler.pkgs system property.
Type: mule:tlsProtocolHandler
Content: empty, 1 attribute
Defined: locally witnin connector element in mule-ssl.xsd; see XML source

server

The server trust store.
Type: mule:tlsServerTrustStoreType
Content:empty, 8 attributes
Defined: locally witnin connector element in mule-ssl.xsd; see XML source

Complex Type Summary

globalEndpointType

Content: complex, 13 attributes, attr. wildcard, 16 elements
Defined: globally in mule-ssl.xsd; see XML source
Used: at 1 location

inboundEndpointType

Content: complex, 13 attributes, attr. wildcard, 16 elements
Defined: globally in mule-ssl.xsd; see XML source
Used: at 1 location

outboundEndpointType

Content: complex, 13 attributes, attr. wildcard, 16 elements
Defined: globally in mule-ssl.xsd; see XML source
Used: at 1 location

Attribute Group Summary

addressAttributes

Content: 2 attributes
Defined: globally in mule-ssl.xsd; see XML source
Includes: definitions of 2 attributes
Used: at 3 locations

XML schema documentation generated with DocFlex/XML RE 1.8.5 using DocFlex/XML XSDDoc 2.5.0 template set. All content model diagrams generated by Altova XMLSpy via DocFlex/XML XMLSpy Integration.

Javadoc API Reference

The Javadoc for this module can be found here: SSL

Maven

<dependency>
  <groupId>org.mule.transports</groupId>
  <artifactId>mule-transport-ssl</artifactId>
  <version>3.2.0</version>
</dependency>

Extending this Transport

When using TCP to communicate with an external program, it may be necessary to write a custom Mule protocol. The first step is to get a complete description of how the external program delimits messages within the TCP stream. The next is to implement the protocol as a Java class.

  • All protocols must implement the interface org.mule.transport.tcp.TcpProtocol, which contains three methods:

    • Object read(InputStream is) reads a message from the TCP socket

    • write(OutputStream os, Object data) writes a message to the TCP socket

    • ResponseOutputStream createResponse(Socket socket) creates a stream to which a response can be written.

  • Protocols which process byte-streams rather than serialized Mule messages can inherit much useful infrastructure by subclassing org.mule.transport.tcp.protocols.AbstractByteProtocol This class

    • implements createResponse

    • handles converting messages to byte arrays, allowing subclasses to implement only the simpler method writeByteArray(OutputStream os, byte[] data)

    • provides methods safeRead(InputStream is, byte[] buffer) and safeRead(InputStream is, byte[] buffer, int size) that handle the situation where data is not currently available when doing non-blocking reads from the TCP socket

Suppose we want to communicate with a server that has a simple protocol: all messages are terminated by >>>. The protocol class would look like this:

package org.mule.transport.tcp.integration;

import org.mule.transport.tcp.protocols.AbstractByteProtocol;

import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;

public class CustomByteProtocol extends AbstractByteProtocol
{

    /**
     * Create a CustomByteProtocol object.
     */
    public CustomByteProtocol()
    {
        super(false); // This protocol does not support streaming.
    }

    /**
     * Write the message's bytes to the socket,
     * then terminate each message with '>>>'.
     */
    @Override
    protected void writeByteArray(OutputStream os, byte[] data) throws IOException
    {
        super.writeByteArray(os, data);
        os.write('>');
        os.write('>');
        os.write('>');
    }

    /**
     * Read bytes until we see '>>>', which ends the message
     */
    public Object read(InputStream is) throws IOException
    {
        ByteArrayOutputStream baos = new ByteArrayOutputStream();
        int count = 0;
        byte read[] = new byte[1];

        while (true)
        {
            // if no bytes are currently avalable, safeRead()
            // will wait until some arrive
            if (safeRead(is, read) < 0)
            {
                // We've reached EOF.  Return null, so that our
                // caller will know there are no
                // remaining messages
                return null;
            }
            byte b = read[0];
            if (b == '>')
            {
                count++;
                if (count == 3)
                {
                    return baos.toByteArray();
                }
            }
            else
            {
                for (int i = 0; i < count; i++)
                {
                    baos.write('>');
                }
                count = 0;
                baos.write(b);
            }
        }
    }
}

Notes

TCP and SSL are very low-level transports, so the usual tools for debugging their use, for instance, logging messages as they arrive, might not be sufficient. Once messages are being sent and received successfully, things are largely working. It may be necessary to use software (or hardware) than can track messages at the packet level, particularly when a custom protocol is being used. Alternatively, you can debug by temporarily using the direct protocol on all inbound endpoints, since it will accept (and you can then log) bytes as they are received.