LibraryLink ToToggle FramesPrintFeedback

Configuring JSSE System Properties

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 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]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.

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.3.0.0/conf/broker.ks
         -Djavax.net.ssl.keyStorePassword=password
         -Djavax.net.ssl.trustStore=C:/Programs/FUSE/fuse-message-broker-5.3.0.0/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.3.0.0/conf/broker.ks
         -Djavax.net.ssl.keyStorePassword=password
         -Djavax.net.ssl.trustStore=/local/FUSE/fuse-message-broker-5.3.0.0/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]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.

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.3.0.0/conf/client.ts"
);
System.setProperties(systemProps);