Enable SSL for JMS connections in JBoss EAP 5

Solution Verified - Updated

Environment

  • Red Hat JBoss Enterprise Application Platform (EAP)
    • 5.x
  • JBoss Messaging

Issue

  • Enable SSL for JMS network communication.
  • Use mutual (2-way) SSL for JMS.

Resolution

JMS communication over the network is not encrypted by default.  To enable wire-level encryption follow these steps:

  1. Remove <JBOSS_HOME>/server/<profile>/deploy/messaging/remoting-bisocket-service.xml.
  2. Copy <JBOSS_HOME>/docs/examples/jms/remoting-sslbisocket-service.xml to <JBOSS_HOME>/server/<profile>/deploy/messaging.
  3. Open <JBOSS_HOME>/server/<profile>/deploy/messaging/remoting-sslbisocket-service.xml and change the "name" of the MBean whose "display-name" is "SSL Bisocket Transport Connector" to "jboss.messaging:service=Connector,transport=bisocket".  This will ensure that all the standard JMS connection factories use this transport.

The next steps are subject to change based on how the SSL certificates are set up.  The following steps are for self-signed certs.  Execute the following commands from <JBOSS_HOME>/bin (alter the path as needed based on what profile you are using).

The first step is to create a new keystore for the server:

keytool -genkey -alias messaging-server -keyalg RSA -validity 365 -keystore ../server/default/deploy/messaging/messaging-server.keystore

The passwords used when creating this keystore will need to be used appropriately in the "KeyStorePassword" and "KeyPassword" attributes of the "jboss.messaging:service=SocketBuilder,type=SSL" MBean in remoting-sslbisocket-service.xml.

Then export the keystore's certificate so that clients can then import it into their own keystore:

keytool -export -alias messaging-server -file messaging-server.cer -keystore ../server/default/deploy/messaging/messaging-server.keystore

Any client connecting to this server will need to import the messaging-server.cer into their own keystore (which, of course, implies that they have a keystore into which they can import the certificate).  If the client doesn't have a keystore then create it:

keytool -genkey -alias messaging-client -keyalg RSA -validity 365 -keystore messaging-client.keystore

Then import the messaging-server.cer into the truststore:

keytool -importcert -alias messaging-server -file messaging-server.cer -keystore messaging-client.keystore

Then tell the client to trust the certificates in this keystore via this command line parameter:

-Djavax.net.ssl.trustStore=messaging-client.keystore

Much of this work can be avoided if the server's certificate is signed by a trusted certificate authority (e.g. Verisign).  All the certificate authorities trusted by the JVM can be inspected by executing this command:

keytool -list -v -keystore $JAVA_HOME/jre/lib/security/cacerts
Mutual (2-way) SSL

Enabling mutual, or 2-way SSL requires just a few more steps.

The first step is to add this attribute to the "jboss.messaging:service=SocketBuilder,type=SSL" MBean in remoting-sslbisocket-service.xml:

<attribute name="ClientAuthMode">need</attribute>

This tells the server to expect the client to present a trusted certificated when it connects.  If the client is using a self-signed certificate then that certificate must be manually inserted into the server's keystore and trusted.  Continuing with the previous example, execute the following command to export the client's certificate:

keytool -export -alias messaging-client -file messaging-client.cer -keystore messaging-client.keystore

Then import the client's certificate into the server's keystore:

keytool -importcert -alias messaging-client -file messaging-client.cer -keystore ../server/default/deploy/messaging/messaging-server.keystore

Then tell the server to trust the client's certificate with this command line parameter:

-Djavax.net.ssl.trustStore=../server/default/deploy/messaging/messaging-server.keystore

The client must also be changed so that it submits its own certificate when connecting.  Add these command line parameters in addition to the previous one:

-Djavax.net.ssl.keyStore=messaging-client.keystore
-Djavax.net.ssl.keyStorePassword=<keystorePass>

The last step involves telling the server itself to submit its own certificate when making JMS connections.  This is only necessary if JMS connections take part in XA transactions and XA transaction recovery is required to ensure integrity.  This is required because the XA transaction recovery manager actually makes socket-based JMS connections to the JBoss Messaging broker behind the scenes during recovery.  Add these command line parameters to the server to ensure recovery works as expected:

-Djavax.net.ssl.keyStore=../server/default/deploy/messaging/messaging-server.keystore 
-Djavax.net.ssl.keyStorePassword=<keystorePass>
SBR
Product(s)
Components
Category
Tags

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.