5.5. Tutorial II: SSL/TLS Security

Overview

This tutorial shows you how to enable an SSL/TLS endpoint on the broker and how to configure the example JMS consumer and producer clients so that they can connect to the secure endpoint.

Tutorial steps

To configure SSL/TLS security for a broker deployed in the OSGi container, perform the following steps:
  1. the section called “Install the consumer and producer JMS clients”.
  2. the section called “Install sample broker keystore files”.
  3. the section called “Configure the broker”.
  4. the section called “Encrypt the passwords”.
  5. the section called “Start the container”.
  6. the section called “Configure the consumer and the producer clients”.
  7. the section called “Run the consumer with the SSL protocol”.
  8. the section called “Run the producer with the SSL protocol”.

Install the consumer and producer JMS clients

If you have not already installed the consumer and producer JMS clients, install them now.
The Apache ActiveMQ distribution is provided in the InstallDir/extras directory in an archive format. Uncompress and extract the archive to a convenient installation location, ActiveMQInstallDir (the consumer and producer clients can be accessed by running ant targets under the ActiveMQInstallDir/examples/openwire/swissarmy directory).

Install sample broker keystore files

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.needClientAuth options is set to true on the broker URI).
For this tutorial, you can use the demonstration certificates provided with the Apache ActiveMQ distribution, in ActiveMQInstallDir.
Copy the broker.ks and broker.ts files from the Apache ActiveMQ distribution's conf directory, ActiveMQInstallDir/conf, to the InstallDir/etc directory of JBoss A-MQ.
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 Appendix A, Managing Certificates.

Configure the broker

Before editing, make a backup copy of the InstallDir/etc/activemq.xml file. Use your favorite text editor to edit the file, InstallDir/etc/activemq.xml, adding the bolded XML fragments: 
<?xml version="1.0" encoding="UTF-8"?>
<beans ...>

    <broker xmlns="http://activemq.apache.org/schema/core"
            brokerName="${broker-name}"
            dataDirectory="${data}"
            start="false">
        ...
        <sslContext>
            <sslContext
                keyStore="${karaf.base}/etc/broker.ks"
                keyStorePassword="password"
                trustStore="${karaf.base}/etc/broker.ts"
                trustStorePassword="password"
                />
        </sslContext>
        
        <transportConnectors>
 <transportConnector name="ssl" uri="ssl://0.0.0.0:61617?transport.enabledProtocols=TLSv1,TLSv1.1,TLSv1.2&amp;maximumConnections=1000"/>
        </transportConnectors>
    </broker>

</beans>
Note the following key aspects of the broker configuration:
  • The Openwire network connector is configured to use SSL, ssl://localhost:61617?....
  • The enabled protocols are specified explicitly, using the transport.enabledProtocols option. This setting effectively disables the SSLv3 protocol, which must not be used because of the POODLE security vulnerability.
  • The key store and trust store file locations and passwords are specified by the broker's sslContext element.
Warning
If you are planning to enable SSL/TLS security, you must ensure that you explicitly disable 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.

Encrypt the passwords

(Optional) If you prefer not to expose passwords in plaintext in the etc/activemq.xml file, you can optionally use a Jasypt encrypted property placeholder to obscure the passwords. For example, you can create a etc/credentials-enc.properties properties file, with contents like the following: 
keystore.password=ENC(Cf3Jf3tM+UrSOoaKU50od5CuBa8rxjoL)
truststore.password=ENC(eeWjNyX6FY8Fjp3E+F6qTytV11bZItDp)
For instructions on how to generate the encrypted passwords in this file, see Section 2.3, “Using Encrypted Property Placeholders”.
Set the JASYPT_ENCRYPTION_PASSWORD environment variable to the value of the master password (which was used to generate the encrypted passwords), as follows: 
export JASYPT_ENCRYPTION_PASSWORD=MasterPass
You must also configure the Jasypt encrypted property placeholder by adding the following bean definitions to the etc/activemq.xml file (which replaces the existing plain Spring property placeholder, of org.springframework.beans.factory.config.PropertyPlaceholderConfigurer type): 
<?xml version="1.0" encoding="UTF-8"?>
<beans ...>
  ...
  <bean id="environmentVariablesConfiguration" class="org.jasypt.encryption.pbe.config.EnvironmentStringPBEConfig">
      <property name="algorithm" value="PBEWithMD5AndDES" />
      <property name="passwordEnvName" value="JASYPT_ENCRYPTION_PASSWORD" />
  </bean>

  <bean id="configurationEncryptor" class="org.jasypt.encryption.pbe.StandardPBEStringEncryptor">
      <property name="config" ref="environmentVariablesConfiguration" />
  </bean> 

  <bean id="propertyConfigurer" class="org.jasypt.spring31.properties.EncryptablePropertyPlaceholderConfigurer"> 
      <constructor-arg ref="configurationEncryptor" /> 
      <property name="location" value="file:${karaf.base}/etc/credentials-enc.properties"/> 
      <property name="properties">
          <bean class="io.fabric8.mq.fabric.ConfigurationProperties"/>
      </property>
  </bean>
  ...
</beans>
You can then configure the passwords in the sslContext element as follows: 
<?xml version="1.0" encoding="UTF-8"?>
<beans ...>

    <broker xmlns="http://activemq.apache.org/schema/core"
            brokerName="${broker-name}"
            dataDirectory="${data}"
            start="false">
        ...
        <sslContext>
            <sslContext
                keyStore="${karaf.base}/etc/broker.ks"
                keyStorePassword="${keystore.password}"
                trustStore="${karaf.base}/etc/broker.ts"
                trustStorePassword="${truststore.password}"
                />
        </sslContext>
        
        <transportConnectors>
            <transportConnector name="ssl" uri="ssl://0.0.0.0:61617?transport.enabledProtocols=TLSv1,TLSv1.1,TLSv1.2&amp;maximumConnections=1000"/>
        </transportConnectors>
    </broker>

</beans>
For more details about Jasypt encrypted property placeholders, see Section 2.3, “Using Encrypted Property Placeholders”.

Start the container

Change directory to InstallDir/bin and enter the following command: 
./amq
Note
If you have configured encrypted property placeholders, you must set the JASYPT_ENCRYPTION_PASSWORD environment variable to the Jasypt master password value before starting up the container.
If you are using Jasypt encryption, you must ensure that the jasypt-encryption feature is installed in the container. If necessary, install the jasypt-encryption feature with the following console command: 
JBossA-MQ:karaf@root> features:install jasypt-encryption

Configure the consumer and the producer clients

To test the broker configured in the OSGi container, you are going to use the example consumer tool and producer tool supplied with the Apache ActiveMQ installation.
Configure the consumer and the producer clients to pick up the client trust store.
  1. Open the Ant build file, ActiveMQInstallDir/examples/openwire/swissarmy/build.xml, with your favourite text editor.
  2. Delete the existing javax.net.ssl.* system property settings from the consumer target and the producer target. That is, remove the lines highlighted 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.keyStore" value="${javax.net.ssl.keyStore}"/>
                    <sysproperty key="javax.net.ssl.trustStore" value="${javax.net.ssl.trustStore}"/>
                    <sysproperty key="javax.net.ssl.keyStorePassword" value="${javax.net.ssl.keyStorePassword}"/>
                    <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.keyStore" value="${javax.net.ssl.keyStore}"/>
                    <sysproperty key="javax.net.ssl.trustStore" value="${javax.net.ssl.trustStore}"/>
                    <sysproperty key="javax.net.ssl.keyStorePassword" value="${javax.net.ssl.keyStorePassword}"/>
                    <arg value="--url=${url}" />
            ...        
                </java>
        </target>
    ...
</project>
  3. 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 consumer with the SSL protocol

To connect the consumer tool to the ssl://localhost:61617 endpoint (Openwire over SSL), change directory to ActiveMQInstallDir/examples/openwire/swissarmy and enter the following command: 
ant consumer -Duser=admin -Dpassword=admin -Durl=ssl://localhost:61617 -Dmax=100 -Dactivemq.home=../../..
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 (admin:admin)
     [java] Consuming queue: TEST.FOO
     [java] Using a non-durable subscription
     [java] Running 1 parallel threads
     [java] [Thread-2] We are about to wait until we consume: 100 message(s) then we will shutdown

Run the producer with the SSL protocol

To connect the producer tool to the ssl://localhost:61617 endpoint, open a new command prompt, change directory to ActiveMQInstallDir/examples/openwire/swissarmy and enter the following command: 
ant producer -Duser=admin -Dpassword=admin -Durl=ssl://localhost:61617 -Dmax=100 -Dactivemq.home=../../..
In the window where the consumer tool is running, you should see some output like the following: 
[java] [Thread-2] Received: 'Message: 0 sent at: Tue Mar 19 10:07:25 CET 2013  ...' (length 1000)
[java] [Thread-2] Received: 'Message: 1 sent at: Tue Mar 19 10:07:25 CET 2013  ...' (length 1000)
[java] [Thread-2] Received: 'Message: 2 sent at: Tue Mar 19 10:07:26 CET 2013  ...' (length 1000)
[java] [Thread-2] Received: 'Message: 3 sent at: Tue Mar 19 10:07:26 CET 2013  ...' (length 1000)
[java] [Thread-2] Received: 'Message: 4 sent at: Tue Mar 19 10:07:26 CET 2013  ...' (length 1000)