7.5. Configuring JSSE System Properties

Overview

Java Secure Socket Extension (JSSE) provides the underlying framework for the SSL/TLS implementation in Red Hat JBoss A-MQ. In this framework, you configure the SSL/TLS protocol and deploy X.509 certificates using a variety of JSSE system properties.

JSSE system properties

Table 7.2, “JSSE System Properties” 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 7.2. JSSE System Properties

System Property NameDescription
javax.net.ssl.keyStoreLocation 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):
  1. $JAVA_HOME/lib/security/jssecacerts
  2. $JAVA_HOME/lib/security/cacerts
javax.net.ssl.trustStorePasswordPassword 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.debugTo switch on logging for the SSL/TLS layer, set this property to ssl.
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.

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.redhat.Client:
java -Djavax.net.ssl.trustStore=truststores/client.ts com.redhat.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-6.2.1.redhat-084/conf/broker.ks
         -Djavax.net.ssl.keyStorePassword=password
         -Djavax.net.ssl.trustStore=C:/Programs/FUSE/fuse-message-broker-6.2.1.redhat-084/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-6.2.1.redhat-084/conf/broker.ks
         -Djavax.net.ssl.keyStorePassword=password
         -Djavax.net.ssl.trustStore=/local/FUSE/fuse-message-broker-6.2.1.redhat-084/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-6.2.1.redhat-084/conf/client.ts"
);
System.setProperties(systemProps);