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