The purpose of this tutorial is to show how you can deploy a secure Fuse Message Broker broker in the OSGi container, where one or more of the broker's endpoints has SSL/TLS enabled. Unlike an insecure broker, you cannot deploy a secure broker simply by dropping its XML configuration file into the hot deploy directory, as described in Hot Deployment in Deploying into the OSGi Container. This is because a secure broker must be accompanied by X.509 certificates and their keys. It is necessary, therefore, to package the broker configuration file together with its certificates and keys in a single OSGi bundle.
This tutorial explains how to use the Maven build tool to create an OSGi bundle containing the secure broker's configuration and its accompanying certificates and keys. After deploying the broker into the OSGi container, you test it using the sample JMS clients from the standalone Fuse Message Broker distribution (which you can obtain from the ESB download page).
The following prerequisites are needed for this tutorial:
Maven installation—Maven is a free, open source build tool from Apache. You can download the latest version from http://maven.apache.org/download.html (minimum is 2.2).
Internet connection—whilst performing a build, Maven dynamically searches external repositories and downloads the required artifacts on the fly. In order for this to work, your build machine must be connected to the Internet.
Fuse Message Broker installation—the standalone installation of Fuse Message Broker has some demonstration code that is not available in Fuse ESB. Download and install Fuse Message Broker 5.5.1-fuse-00-08 from fusesource.com.
To configure SSL/TLS security for a broker deployed in the OSGi container, perform the following steps:
The maven-archetype-quickstart archetype creates a generic Maven
project, which you can then customize for whatever purpose you like. To generate a
Maven project with the coordinates,
org.fusesource.example:esb-security, enter the following
command:
mvn archetype:create -DarchetypeArtifactId=maven-archetype-quickstart -DgroupId=org.fusesource.example -DartifactId=esb-security
The result of this command is a directory,
ProjectDir/esb-security
![[Note]](imagesdb/note.gif) | Note |
|---|---|
Be careful not to choose a group ID for your artifact that clashes with the group ID of an existing product! This could lead to clashes between your project's packages and the packages from the existing product (because the group ID is typically used as the root of a project's Java package names). |
You must customize the POM file in order to generate an OSGi bundle, as follows:
Follow the POM customization steps described in Modifying an Existing Maven Project in Deploying into the OSGi Container.
In the configuration of the Maven bundle plug-in, modify the bundle instructions to import additional Java packages, as follows:
<project ... > ... <build> ... <plugin> <groupId>org.apache.felix</groupId> <artifactId>maven-bundle-plugin</artifactId> <extensions>true</extensions> <configuration> <instructions> <Bundle-SymbolicName> ${project.artifactId} </Bundle-SymbolicName> <Import-Package>org.apache.activemq.xbean, org.apache.activemq.spring, org.apache.activemq.broker, org.apache.activemq.security, org.apache.activemq.jaas, org.apache.activemq.pool, org.apache.activemq.camel.component, org.apache.camel.component.jms, *</Import-Package> </instructions> </configuration> </plugin> </plugins> </build> ... </project>
| Note |
|---|---|
Not all of these packages are required by the current tutorial. It is convenient, however, to add all of the packages required by the subsequent tutorials at this point. |
The broker requires the following keystore files:
Key store containing broker's own certificate and private key—used to identify the broker during an SSL handshake.
Trust store containing CA certificate—used to verify that a received client certificate is correctly signed (strictly speaking, the trust store file is only needed by the broker, if the
transport.needClientAuthoptions is set totrueon the broker URI).
For this tutorial, you can use the demonstration certificates provided with the
standalone version of Fuse Message Broker. In the Maven project, create the following
conf directory to store the broker's keystore files:
ProjectDir/esb-security/src/main/resources/confCopy the broker.ks and broker.ts files from the Fuse Message Broker
standalone conf directory,
ActiveMQInstallDir/confconf directory that you just created.
![[Warning]](imagesdb/warning.gif) | Warning |
|---|---|
The demonstration broker key store and broker trust sture 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 in Fuse Message Broker Security Guide. |
To configure the broker, create the following spring directory to
store Spring XML files:
ProjectDir/esb-security/src/main/resources/META-INF/springIn the spring directory that you just created, use your favorite text
editor to create the file, broker-spring.xml, containing the following
XML configuration:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core-5.4.0.xsd">
<broker xmlns="http://activemq.apache.org/schema/core" brokerName="simple-spring">
<sslContext>
<sslContext
keyStore="classpath:conf/broker.ks"
keyStorePassword="password"
trustStore="classpath:conf/broker.ts"
trustStorePassword="password"
/>
</sslContext>
<transportConnectors>
<transportConnector name="openwire" uri="ssl://localhost:61001"/>
</transportConnectors>
</broker>
</beans>Note the following key aspects of the broker configuration:
The Openwire network connector is configured to use SSL,
ssl://localhost:61001.The key store and trust store file locations and passwords are specified by the broker's
sslContextelement.
Use Maven to build the broker bundle. Open a command prompt, switch the current
directory to ProjectDir/esb-security
mvn install
This command builds the broker bundle and installs it in your local Maven repository.
If you have not already done so, start up the Apache ServiceMix console (and container instance) by entering the following command in a new command prompt:
servicemix
To deploy and activate the broker bundle, enter the following console command:
karaf@root> osgi:install -s mvn:org.fusesource.example/esb-security
The preceding command loads the broker bundle from your local Maven repository. You might need to configure the Mvn URL handler with the location of your local Maven repository, if the broker bundle cannot be found (see Mvn URL Handler in Deploying into the OSGi Container).
To test the broker configured in the OSGi container, you are going to use the example consumer tool and producer tool supplied with the standalone version of Fuse Message Broker.
Configure the consumer and the producer clients to pick up the client trust store.
Edit the Ant build file,
ActiveMQInstallDir/example/build.xmljavax.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.
To connect the consumer tool to the ssl://localhost:61001 endpoint
(Openwire over SSL), change directory to
ActiveMQInstallDir/example
ant consumer -Durl=ssl://localhost:61001 -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:61001 for subject $subject = TEST.FOO
[java] Connecting to URL: ssl://localhost:61001
[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 shutdownTo connect the producer tool to the ssl://localhost:61001 endpoint,
open a new command prompt, change directory to example and enter the
following command:
ant producer -Durl=ssl://localhost:61001 -Dmax=100
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 ...To uninstall the broker bundle, you need to know its bundle ID,
BundleID, in which case you can uninstall it by
entering the following console command:
karaf@root> osgi:uninstall BundleIDIf you are unsure of the broker's bundle ID, list the installed bundles using the
osgi:list command, as follows:
karaf@root> osgi:list
Which should produce output like the following:
...
[ 231] [Active ] [ ] [ ] [ 60] camel-jms (2.4.0.fuse-00-00)
[ 232] [Active ] [ ] [ ] [ 60] activemq-camel (5.4.0.fuse-00-00)
[ 245] [Installed ] [ ] [ ] [ 60] esb-security (1.0.0.SNAPSHOT)From the preceding output, you can see that the esb-security bundle
has the bundle ID, 245.
 |  |  |
 |
