# JBoss Messaging Secure Socket Connection Example

$Revision: 2751 $

## Overview

This example shows how to use a secure ConnectionFactory, which creates a SSL socket connection between client and server. The example will use such a ConnectionFactory to create two JMS connections: the first one to send a message to the queue and the second one to read the message from the queue. In both cases, the message will be securely sent over an encrypted connection. The example is considered successful if the client receives without any error the message that was previously sent to the queue.
This example needs to have access to a running JBoss Messaging instance. The JBoss Messaging instance must be installed and started according to the "Installation" paragraph from the release documentation. However, the example will automatically deploy its own queue, unless a queue with the same name is already deployed.
This example also needs to have access to jboss-messaging-client.jar archive that comes with the release bundle. If you run this example from an unzipped installation bundle, the example run script is correctly configured to find the client jar. Otherwise, you must modify example's build.xml accordingly.

## Running the example

1. Set up the JBOSS_HOME environment variable to point to the JBoss instance you deployed JBoss Messaging into. For example, if you deployed JBoss Messaging in C:\jboss-4.2.0.GA\server\messaging\deploy, then your JBOSS_HOME value should be C:\jboss-4.2.0.GA
2. Go to the example's home directory

cd ...\examples\secure-socket

3. Run the example:

ant

The output of a successful run should be similar to:

$ ant Buildfile: build.xml identify: [echo] ############################################################################ [echo] # Running the SECURE SOCKET example # [echo] ############################################################################ [echo] The queue: testQueue sanity-check: init: [mkdir] Created dir: C:\work\src\cvs\jboss-head\jms\docs\examples\secure-socket\output [mkdir] Created dir: C:\work\src\cvs\jboss-head\jms\docs\examples\common\output compile: [javac] Compiling 2 source files to C:\work\src\cvs\jboss-head\jms\docs\examples\common\output [javac] Compiling 1 source file to C:\work\src\cvs\jboss-head\jms\docs\examples\secure-socket\output deploy: [copy] Copying 1 file to C:\jboss-4.2.0.GA\server\messaging\deploy\jboss-messaging.sar [copy] Copying 1 file to C:\jboss-4.2.0.GA\server\messaging\deploy sleep: [echo] Sleeping for 10 seconds ... run: [java] Queue /queue/testQueue exists [java] The message was successfully sent to the testQueue queue [java] Received message: Hello! [java] The example connected to JBoss Messaging version 1.3.0.GA (1.0) [java] ##################### [java] ### SUCCESS! ### [java] ##################### BUILD SUCCESSFUL Total time: 15 seconds

## Configuration details

The example client looks up a specially-configured connection factory ("/SecureConnectionFactory") that is deployed by the example run script. The secure ConnectionFactory relies on a "secured" Remoting Connector to provide the SSL connection. The definition of the required services is specified in the etc/messaging-secure-socket-service.xml deployment descriptor.
The SSLSocketBuilder needs a keystore with a public/private key pair. The example provides one (etc/messaging.keystore) which is deployed with the rest of the artifacts. In case you need to create your own keystore, this is how you do it:

     keytool -genkey -alias messaging.keypair -keyalg RSA -keystore messaging.keystore -validity 3650

By default, the client will try to contact a Certificate Authority to insure the authenticity of the public key it uses to encrypt the communication. However, the example's certificate is self-signed, so no Certificate Authority will recognize it. In order to get the SSL client to trust it and the example to complete successfully, we use a client truststore (/etc/messaging.truststore). In case you need to create your own truststore, this is how you do it:

     keytool -export -alias messaging.keypair -keystore messaging.keystore -rfc -file messaging.cer
     keytool -import -alias messaging.keypair -file messaging.cer -keystore messaging.truststore

In order for the truststore to be recognized, the client's environment must contain the `javax.net.ssl.trustStore` and `javax.net.ssl.trustStorePassword` properties.

## Troubleshooting

### 1. I get "javax.jms.JMSSecurityException: User null is NOT authenticated"

You probably didn't install JBoss Messaging correctly. A fresh JBoss Messaging installation requires changes in the security configuration of a default JBoss instance, specifically a properly configured "messaging" security domain. Follow the instructions from the "Installation" paragraph of the release documentation.