Fuse Message Broker - Security Guide - Configuring JSSE System Properties

Configuring JSSE System Properties

Overview

Java Secure Socket Extension (JSSE) provides the underlying framework for the SSL/TLS implementation in Fuse Message Broker. In this framework, you configure the SSL/TLS protocol and deploy X.509 certificates using a variety of JSSE system properties.

Table 1.2 shows the JSSE system properties that can be used to configure SSL/TLS security for the SSL (Openwire over SSL), HTTPS (Openwire over HTTPS), and Stomp+SSL (Stomp over SSL) transport protocols.

Table 1.2. JSSE System Properties

System Property Name	Description
`javax.net.ssl.keyStore`	Location of the Java keystore file containing an application process's own certificate and private key. On Windows, the specified pathname must use forward slashes, `/`, in place of backslashes, `\`.
`javax.net.ssl.keyStorePassword`	Password to access the private key from the keystore file specified by `javax.net.ssl.keyStore`. This password is used twice: To unlock the keystore file (store password), and To decrypt the private key stored in the keystore (key password). In other words, the JSSE framework requires these passwords to be identical.
`javax.net.ssl.keyStoreType`	(Optional) For Java keystore file format, this property has the value `jks` (or `JKS`). You do not normally specify this property, because its default value is already `jks`.
`javax.net.ssl.trustStore`	Location of the Java keystore file containing the collection of CA certificates trusted by this application process (trust store). On Windows, the specified pathname must use forward slashes, `/`, in place of backslashes, `\`. If a trust store location is not specified using this property, the SunJSSE implementation searches for and uses a keystore file in the following locations (in order): `$JAVA_HOME/lib/security/jssecacerts` `$JAVA_HOME/lib/security/cacerts`
`javax.net.ssl.trustStorePassword`	Password to unlock the keystore file (store password) specified by `javax.net.ssl.trustStore`.
`javax.net.ssl.trustStoreType`	(Optional) For Java keystore file format, this property has the value `jks` (or `JKS`). You do not normally specify this property, because its default value is already `jks`.
`javax.net.debug`	To switch on logging for the SSL/TLS layer, set this property to `ssl`.

Warning

	Warning
The default trust store locations (in the `jssecacerts` and the `cacerts` directories) present a potential security hazard. If you do not take care to manage the trust stores under the JDK installation or if you do not have control over which JDK installation is used, you might find that the effective trust store is too lax. To be on the safe side, it is recommended that you always set the `javax.net.ssl.trustStore` property for a secure client or server, so that you have control over the CA certificates trusted by your application.

The default trust store locations (in the jssecacerts and the cacerts directories) present a potential security hazard. If you do not take care to manage the trust stores under the JDK installation or if you do not have control over which JDK installation is used, you might find that the effective trust store is too lax.

To be on the safe side, it is recommended that you always set the javax.net.ssl.trustStore property for a secure client or server, so that you have control over the CA certificates trusted by your application.

Setting properties at the command line

On the client side and in the broker, you can set the JSSE system properties on the Java command line using the standard syntax, -DProperty=Value. For example, to specify JSSE system properties to a client program, com.progress.Client:

java -Djavax.net.ssl.trustStore=truststores/client.ts com.progress.Client

To configure a broker to use the demonstration broker keystore and demonstration broker trust store, you can set the SSL_OPTS environment variable as follows, on Windows:

set SSL_OPTS=-Djavax.net.ssl.keyStore=C:/Programs/FUSE/fuse-message-broker-5.5.1-fuse-00-xx/conf/broker.ks
         -Djavax.net.ssl.keyStorePassword=password
         -Djavax.net.ssl.trustStore=C:/Programs/FUSE/fuse-message-broker-5.5.1-fuse-00-xx/conf/broker.ts 
         -Djavax.net.ssl.trustStorePassword=password

Or on UNIX platforms (Bourne shell):

SSL_OPTS=-Djavax.net.ssl.keyStore=/local/FUSE/fuse-message-broker-5.5.1-fuse-00-xx/conf/broker.ks
         -Djavax.net.ssl.keyStorePassword=password
         -Djavax.net.ssl.trustStore=/local/FUSE/fuse-message-broker-5.5.1-fuse-00-xx/conf/broker.ts 
         -Djavax.net.ssl.trustStorePassword=password
export SSL_OPTS

You can then launch the broker using the bin/activemq[.bat|.sh] script

	Note
	The `SSL_OPTS` environment variable is simply a convenient way of passing command-line properties to the `bin/activemq[.bat\|.sh]` script. It is not accessed directly by the broker runtime or the JSSE package.

Setting properties by programming

You can also set JSSE system properties using the standard Java API, as long as you set the properties before the relevant transport protocol is initialized. For example:

// Java
import java.util.Properties;
...
Properties systemProps = System.getProperties();
systemProps.put(
    "javax.net.ssl.trustStore",
    "C:/Programs/FUSE/fuse-message-broker-5.5.1-fuse-00-xx/conf/client.ts"
);
System.setProperties(systemProps);

Comments powered by Disqus

Contents
Search