Chapter 2. OpenWire over SSL
URI syntax
A vanilla SSL URI has the syntax shown in Example 2.1, “Syntax for a vanilla SSL Connection”.
Example 2.1. Syntax for a vanilla SSL Connection
ssl://Host[:Port]?transportOptions
An SSL URI for using NIO has the syntax shown in Example 2.2, “Syntax for NIO Connection”.
Example 2.2. Syntax for NIO Connection
nio+ssl://Host[:Port]?transportOptions
Setting transport options
OpenWire transport options, transportOptions, are specified as a list of matrix parameters. How you specify the options to use differs between a client-side URI and a broker-side URI:
- When using a URI to open a connection between a client and a broker, you just specify the name of the option as shown.
Example 2.3. Setting an Option on a Client-Side TCP URI
tcp://fusesource.com:61616?trace=true - When using a URI to open a broker listener socket, you prefix the option name with
transport.as shown.Example 2.4. Specifying Transport Options for a Listener Socket
tcp://fusesource.com:61616?transport.trace=true - When using a URI to open a broker connection socket, you just specify the name of the option as shown.
Example 2.5. Setting an Option on a Client-Side TCP URI
tcp://fusesource.com:61616?trace=true
Important
In XML configuration, you must escape the
& symbol, replacing it with & as shown.
Example 2.6. Transport Options in XML
?option=value&option=value&...
SSL transport options
In addition to the options supported by the non-secure TCP/NIO transport listed in Table 1.1, “TCP and NIO Transport Options”, the SSL transport also supports the options for configuring the
SSLServerSocket created for the connection. These options are listed in Table 2.1, “SSL Transport Options”.
| Option | Default | Description |
|---|---|---|
enabledCipherSuites | Specifies the cipher suites accepted by this endpoint, in the form of a comma-separated list. | |
enabledProtocols | Specifies the secure socket protocols accepted by this endpoint, in the form of a comma-separated list. If using Oracle's JSSE provider, possible values are: TLSv1, TLSv1.1, or TLSv1.2 (do not use SSLv2Hello or SSLv3, because of the POODLE security vulnerability, which affects SSLv3). | |
wantClientAuth | (broker only) If true, the server requests (but does not require) the client to send a certificate. | |
needClientAuth | false | (broker only) If true, the server requires the client to send its certificate. If the client fails to send a certificate, the server will throw an error and close the session. |
enableSessionCreation | true | (broker only) If true, the server socket creates a new SSL session every time it accepts a connection and spawns a new socket. If false, an existing SSL session must be resumed when the server socket accepts a connection. |
verifyHostName | false | If true, the server will verify the host name. If the check to verify the host name fails during the TLS handshake, the TLS handshake fails with an exception. Setting the option to true mitigates against man-in-the-middle attacks and thus, the option should be set to true in locked down systems. |
Warning
If you are planning to enable SSL/TLS security, you must ensure that you explicitly disable the SSLv3 protocol, in order to safeguard against the Poodle vulnerability (CVE-2014-3566). For more details, see Disabling SSLv3 in JBoss Fuse 6.x and JBoss A-MQ 6.x.
Configuring broker SSL options
On the broker side, you must specify an SSL transport option using the syntax
transport.OptionName. For example, to enable an OpenWire SSL port on a broker, you would add the following transport element:
<transportConnector name="ssl" uri="ssl:localhost:61617?transport.enabledProtocols=TLSv1,TLSv1.1,TLSv1.2" />
Tip
Remember, if you are specifying more than one option in the context of XML, you need to escape the ampersand,
&, between options as &.
Configuring client SSL options
On the client side, you must specify an SSL transport option using the syntax
socket.OptionName. For example, to connect to an OpenWire SSL port, you would use a URL like the following:
ssl:localhost:61617?socket.enabledProtocols=TLSv1,TLSv1.1,TLSv1.2
Verify Host Name
Disabled by default, you can enable the capability of verifying the host name on the client side by using a URL parameter as follows:
ssl:localhost:61616?socket.verifyHostName=true
