LibraryToggle FramesPrintFeedback

SSL/TLS Tutorial

Overview

This tutorial demonstrates how to connect to a broker through the SSL protocol (Openwire over SSL) and through the HTTPS protocol (Openwire over HTTPS). For simplicity, the tutorial uses the demonstration certificates (key stores and trust stores) provided with initial installation of Fuse Message Broker. These demonstration certificates must not be used in a live production system, however.

Prerequisites

Before you can build and run the sample clients, you must have installed the Apache Ant build tool, version 1.6 or later (see http://ant.apache.org/).

The OpenWire examples depend on the sample producer and consumer clients located in the following directory:

FuseInstallDir/fuse-message-broker-Version/example

Sample consumer and producer clients

For the purposes of testing and experimentation, Fuse Message Broker provides a sample consumer client and a sample producer client in the example subdirectory. You can build and run these clients using the consumer and the producer Ant targets. In the following tutorial, these sample clients are used to demonstrate how to connect to secure endpoints in the broker.

Set the broker environment

Create a script that sets the broker's JSSE system properties using the SSL_OPTS environment variable. On Windows, create a setSslOpts.bat script with the following contents:

set SSL_OPTS=-Djavax.net.ssl.keyStore=MessageBrokerRoot/conf/broker.ks
         -Djavax.net.ssl.keyStorePassword=password
         -Djavax.net.ssl.trustStore=MessageBrokerRoot/conf/broker.ts 
         -Djavax.net.ssl.trustStorePassword=password

On UNIX, create a setSslOpts.sh script with the following contents:

SSL_OPTS=-Djavax.net.ssl.keyStore=MessageBrokerRoot/conf/broker.ks
         -Djavax.net.ssl.keyStorePassword=password
         -Djavax.net.ssl.trustStore=MessageBrokerRoot/conf/broker.ts 
         -Djavax.net.ssl.trustStorePassword=password
export SSL_OPTS
[Warning]Warning

The demonstration broker key store and broker trust store are provided for testing purposes only. Do not deploy these certificates in a production system. To set up a genuinely secure SSL/TLS system, you must generate custom certificates, as described in Managing Certificates.

Configure the broker

Add the ssl and https transport connectors to the default broker configuration file (conf/activemq.xml), as follows:

<beans ...>
    ...
    <broker ...>
        <sslContext>
            <sslContext keyStore="file:${activemq.base}/conf/broker.ks"
                        keyStorePassword="password"
                        trustStore="file:${activemq.base}/conf/broker.ts"
                        trustStorePassword="password"/>
        </sslContext>
        
        <transportConnectors>
    	        <transportConnector name="ssl" uri="ssl://localhost:61617"/>
            <transportConnector name="https" uri="https://localhost:8443"/>
            ...
        </transportConnectors>
        ...
    </broker>
    ...
</beans>

Configure the consumer and the producer clients

Configure the consumer and the producer clients to pick up the client trust store. Edit the Ant build file, example/build.xml, and add the javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword JSSE system properties to the consumer target and the producer target as shown in the following example:

<project ...>
    ...
    	<target name="consumer" depends="compile" description="Runs a simple consumer">
        ...
        		<java classname="ConsumerTool" fork="yes" maxmemory="100M">
            			<classpath refid="javac.classpath" />
            			<jvmarg value="-server" />
        		    <sysproperty key="activemq.home" value="${activemq.home}"/>
        		    <sysproperty key="javax.net.ssl.trustStore"
                                 value="${activemq.home}/conf/client.ts"/>
        		    <sysproperty key="javax.net.ssl.trustStorePassword"
                                 value="password"/>
            			<arg value="--url=${url}" />
            ...				
        		</java>
    </target>

    	<target name="producer" depends="compile" description="Runs a simple producer">
        ...
        		<java classname="ProducerTool" fork="yes" maxmemory="100M">
            			<classpath refid="javac.classpath" />
            			<jvmarg value="-server" />
        		    <sysproperty key="activemq.home" value="${activemq.home}"/>
        		    <sysproperty key="javax.net.ssl.trustStore"
                                 value="${activemq.home}/conf/client.ts"/>
        		    <sysproperty key="javax.net.ssl.trustStorePassword"
                                 value="password"/>
            			<arg value="--url=${url}" />
            ...		
        		</java>
    	</target>
    ...
</project>

In the context of the Ant build tool, this is equivalent to adding the system properties to the command line.

Run the broker

Open a new command prompt and run the setSslOpts.[bat|sh] script to initialize the SSL_OPTS variable in the broker's environment. Now run the default broker by entering the following at a command line:

activemq

The default broker automatically takes its configuration from the default configuration file.

[Note]Note

The activemq script automatically sets the ACTIVEMQ_HOME and ACTIVEMQ_BASE environment variables to FuseInstallDir/fuse-message-broker-Version by default. If you want the activemq script to pick up its configuration from a non-default conf directory, you can set ACTIVEMQ_BASE explicitly in your environment. The configuration files will then be taken from $ACTIVEMQ_BASE/conf.

Run the consumer with the SSL protocol

To connect the consumer tool to the ssl://localhost:61617 endpoint (Openwire over SSL), change directory to example and enter the following command:

ant consumer -Durl=ssl://localhost:61617 -Dmax=100

You should see some output like the following:

Buildfile: build.xml
init:
compile:
consumer:
     [echo] Running consumer against server at $url = ssl://localhost:61617 for subject $subject = TEST.FOO
     [java] Connecting to URL: ssl://localhost:61617
     [java] Consuming queue: TEST.FOO
     [java] Using a non-durable subscription
     [java] We are about to wait until we consume: 100 message(s) then we will shutdown

Run the producer with the HTTPS protocol

To connect the producer tool to the https://localhost:8443 endpoint (Openwire over HTTPS), open a new command prompt, change directory to example and enter the following command:

ant producer -Durl=https://localhost:8443

In the window where the consumer tool is running, you should see some output like the following:

     [java] Received: Message: 0 sent at: Thu Feb 05 09:27:43 GMT 2009  ...
     [java] Received: Message: 1 sent at: Thu Feb 05 09:27:43 GMT 2009  ...
     [java] Received: Message: 2 sent at: Thu Feb 05 09:27:43 GMT 2009  ...
     [java] Received: Message: 3 sent at: Thu Feb 05 09:27:43 GMT 2009  ...

Enable SSL logging in the consumer

To enable SSL logging in the consumer, edit the Ant build file, example/build.xml, and set the javax.net.debug system property as follows:

<project ...>
    ...
    	<target name="consumer" depends="compile" description="Runs a simple consumer">
        ...
        		<java classname="ConsumerTool" fork="yes" maxmemory="100M">
            ...				
            <sysproperty key="javax.net.debug" value="ssl"/>
            ...				
        		</java>
    </target>
    ...
</project>

Now run the consumer tool using the same command as before:

ant consumer -Durl=ssl://localhost:61617 -Dmax=100

You should see some output like the following:

...
     [java] setting up default SSLSocketFactory
     [java] use default SunJSSE impl class: com.sun.net.ssl.internal.ssl.SSLSocketFactoryImpl
     [java] class com.sun.net.ssl.internal.ssl.SSLSocketFactoryImpl is loaded
     [java] keyStore is : ../conf/client.ks
     [java] keyStore type is : jks
     [java] keyStore provider is :
     [java] init keystore
     [java] init keymanager of type SunX509
     [java] ***
     [java] found key for : client
     [java] chain [0] = [
     [java] [
     [java]   Version: V1
     [java]   Subject: CN=Unknown, OU=client, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
     [java]   Signature Algorithm: MD5withRSA, OID = 1.2.840.113549.1.1.4
...
Comments powered by Disqus