TCPS Connector

The TCPS connector enables OpenJMS clients to connect to the OpenJMS server using SSL (Secure Socket Layer).

To use the TCPS connector:

  1. JSSE must be installed.
  2. A certificate keystore must be created for the OpenJMS server.
  3. The OpenJMS server's public key must be imported into each client's keystore.
  4. openjms.xml must be configured.
  5. Configure client authentication (optional).

Downloading and installing JSSE

You can skip this step if you are running JDK 1.4 or higher, as JSSE is included in the JDK.

Download the Java Secure Socket Extensions (JSSE) package, version 1.0.2 or later, from http://java.sun.com/products/jsse/ .

After extracting JSSE, choose one of the following ways to make it available to OpenJMS:

  • Make JSSE an installed extension
  • Set the JSSE_HOME environment variable

Making JSSE an installed extension

JSSE can be made an installed extension by copying all three JAR files (jcert.jar, jnet.jar, and jsse.jar) to the $JAVA_HOME/jre/lib/ext directory.

Setting the JSSE_HOME environment variable

With this option, a new environment variable JSSE_HOME is set in the OpenJMS environment script. The variable contains the absolute path to the directory where the JSSE binary distribution is installed.

To configure the OpenJMS environment on Windows, edit the %OPENJMS_HOME%\bin\setenv.bat batch file, and add the following: 

rem The following line is optional, and is only required if JDK 1.2 or JDK 1.3 
rem is being used, and JSSE wasn't installed as an extension
set JSSE_HOME=<insert JSSE directory path here>

To configure the OpenJMS environment on Unix, edit the $OPENJMS_HOME/bin/setenv.sh script, and add the following: 

# The following line is optional, and is only required if JDK 1.2 or JDK 1.3 
# is being used, and JSSE wasn't installed as an extension
JSSE_HOME=<insert JSSE directory path here>

Creating the OpenJMS server certificate keystore

To create the OpenJMS server certificate keystore, enter the following:

Windows 

cd %OPENJMS_HOME%\config
%JAVA_HOME%\bin\keytool -genkey -alias openjms -keyalg RSA -keystore openjms.keystore

Unix 

cd $OPENJMS_HOME/config
$JAVA_HOME/bin/keytool -genkey -alias openjms -keyalg RSA -keystore openjms.keystore

After executing the command, you will first be prompted for the keystore password. The default password used by OpenJMS is "openjms", although you can enter any password you like. The keystore password needs specified in openjms.xml.

Importing the server public key

In order for the server to authenticate itself to OpenJMS clients, its public key needs to be imported into each client's certificate keystore.

To export the OpenJMS server's public key, and import it into a client's certificate keystore, enter the following:

Windows 

%JAVA_HOME%\bin\keytool -export -rfc -keystore openjms.keystore \
       -alias openjms -file openjms.public-key

%JAVA_HOME%\bin\keytool -import -rfc -keystore client.keystore \
       -alias openjms -file openjms.public-key

Unix 

$JAVA_HOME/bin/keytool -export -rfc -keystore openjms.keystore \
       -alias openjms -file openjms.public-key

$JAVA_HOME/bin/keytool -import -rfc -keystore client.keystore \
       -alias openjms -file openjms.public-key

Configuring openjms.xml

In order to activate the TCPS connector, a <Connector> element needs to be added to <Connectors> section of the $OPENJMS_HOME/config/openjms.xml file, with a scheme of type "tcps". E.g: 

  <Connectors>
    <Connector scheme="tcps">
      <ConnectionFactories>
        <ConnectionFactory name="TCPSConnectionFactory"/>
      </ConnectionFactories>
    </Connector>
  </Connectors>

If the keystore location or password is different to that above, they will need to be specified in the <TcpsConfiguration> element. E.g: 

  <TcpsConfiguration port="3035"
                     keyStore="${openjms.home}/config/openjms.keystore"
                     keyStorePassword="openjms"
                     needClientAuth="false"/>

Client authentication

By default, clients aren't required to authenticate themselves with the server. This can be changed by setting the needClientAuth attribute of TcpsConfiguration to "true". Each valid client's public key must be imported into the OpenJMS server's certificate keystore.

Creating OpenJMS client certificate keystores

To create certificate keystores for OpenJMS clients enter the following:

Windows 

%JAVA_HOME%\bin\keytool -genkey -alias client -keyalg RSA -keystore client.keystore

Unix 

$JAVA_HOME/bin/keytool -genkey -alias client -keyalg RSA -keystore client.keystore

After executing the command, you will first be prompted for the keystore password. You can enter any password you like - this password needs to be specified by clients.

Importing client public keys

To export a client's public key, and import it into the OpenJMS server's certificate keystore, enter the following:

Windows 

%JAVA_HOME%\bin\keytool -export -rfc -keystore client.keystore \
        -alias client -file client.public-key

%JAVA_HOME%\bin\keytool -import -rfc -keystore openjms.keystore \
        -alias client -file client.public-key

Unix 

$JAVA_HOME/bin/keytool -export -rfc -keystore client.keystore \
        -alias client -file client.public-key

$JAVA_HOME/bin/keytool -import -rfc -keystore openjms.keystore \
        -alias client -file client.public-key

See Also

The following references provide detailed descriptions of the configuration elements related to the TCPS connector: