JMS Client SSL Configuration
This section describes how to use SSL in your Universal Messaging Provider for JMS applications. Universal Messaging supports various wire protocols including SSL enabled sockets and HTTPS.
Once you have created an SSL enabled interface for your realm you need to ensure that your client application passes the required SSL properties either on the connection factory or via system properties used by your JSSE-enabled JVM. The Universal Messaging download contains some sample Java keystore files that will be used in this example.
The first such keystore is the client keystore, called client.jks, which can be found in your installation directory, under the /server/Universal Messaging/bin directory. The second is the truststore called nirvanacacerts.jks, which is also located in the /server/Universal Messaging/bin directory.
Custom SSL Properties
Using the sample keystores, you can set custom SSL attributes on JMS as follows:
Setting the SSL Attributes on the JNDI Context
In your properties object the following properties will set SSL attributes on the JNDI Context.
env = new Properties();
env.setProperty("java.naming.factory.initial",
"com.pcbsys.nirvana.nSpace.NirvanaContextFactory");
env.setProperty("java.naming.provider.url", rname);
env.setProperty("nirvana.ssl.keystore.path",
%INSTALLDIR%\client\Universal Messaging\bin\client.jks);
env.setProperty("nirvana.ssl.keystore.pass", password);
env.setProperty("nirvana.ssl.keystore.cert", certAlias);
// Certificate alias for the client to use when connecting to an interface
// with client validation enabled
env.setProperty("nirvana.ssl.truststore.path",
%INSTALLDIR%\client\Universal Messaging\bin\nirvanacacerts.jks);
env.setProperty("nirvana.ssl.truststore.pass", password);
env.setProperty("nirvana.ssl.protocol", "TLS");
Setting the SSL Attributes on the Connection Factory
You can set the SSL attributes using the same Properties object like this:
connectionFactory.setProperties(env);
Connection con = connectionFactory.createConnection();
You can set the SSL attributes using the available setters:
connectionFactory.setSSLStores(String keyStorePath, String keyStorePass,
String trustStorePath, String trustStorePass);
connectionFactory.setSSLStores(String keyStorePath, String keyStorePass,
String certificateAlias, String trustStorePath, String trustStorePass);
connectionFactory.setSSLProtocol(String protocol);
connectionFactory.setSSLEnabledCiphers(String[] enabledCiphers);
Connection con = connectionFactory.createConnection();
Setting the SSL Attributes on the Connection
Connection con = connectionFactory.createConnection(keyStorePath, keyStorePass,
keyStoreCert, trustStorePath, trustStorePass, cipherSuite, protocol)
JSSE SSL System Properties
The following system properties are used by the jsse implementation in your JVM. You can specify the SSL properties by passing the following as part of the command line for your JMS application:
-Djavax.net.ssl.keyStore=%INSTALLDIR%\client\Universal Messaging\bin\client.jks
-Djavax.net.ssl.keyStorePassword=password
-Djavax.net.ssl.trustStore=%INSTALLDIR%\client\Universal Messaging\bin\nirvanacacerts.jks
-Djavax.net.ssl.trustStorePassword=password
where :
javax.net.ssl.keyStore is the client keystore location
javax.net.ssl.keyStorePassword is the password for the client keystore
javax.net.ssl.trustStore is the CA keystore file location
javax.net.ssl.trustStorePassword is password for the CA keystore
As well as the above system properties, if you are intending to use https, your JMS applications will require the following system property to be passed in the command line:
-Djava.protocol.handler.pkgs="com.sun.net.ssl.internal.www.protocol"
As well as the above, the RNAME used by the JMS application must correspond to the correct type of SSL interface, and the correct hostname and port that was configured earlier.
In JMS, the RNAME corresponds to a JNDI reference. The example JMSADmin application can be used to create a sample file based JNDI context, where the RNAME is specified as the content of the TopicConnectionFactoryFactory reference. Once your SSL interface is created you can simply change this value in your JNDI context to be the RNAME you require your JMS applications to use.
Using Universal Messaging Client System Properties
Instead of the JSSE system properties, you can use the Universal Messaging client system properties to configure secure communication with Universal Messaging realms. The Universal Messaging client system properties configure only the connections to Universal Messaging realms and have no impact on the connections established to other endpoints, unlike the JSSE system properties. If both Universal Messaging client and JSSE system properties are configured, when you create a session to a Universal Messaging realm, the Universal Messaging client properties take precedence.
To configure secure communication in your own applications, set the following system properties:
-Dcom.softwareag.um.client.ssl.keystore_path=
%INSTALLDIR%\client\Universal Messaging\bin\client.jks
-Dcom.softwareag.um.client.ssl.keystore_password=password
-Dcom.softwareag.um.client.ssl.certificate_alias=alias
-Dcom.softwareag.um.client.ssl.truststore_path=
%INSTALLDIR%\client\Universal Messaging\bin\nirvanacacerts.jks
-Dcom.softwareag.um.client.ssl.truststore_password=password
-Dcom.softwareag.um.client.ssl.enabled_ciphers=AES-128,AES-192,AES-256
-Dcom.softwareag.um.client.ssl.ssl_protocol=TLS
where:
com.softwareag.um.client.ssl.keystore_path is the client keystore location
com.softwareag.um.client.ssl.keystore_password is the password for the client keystore
com.softwareag.um.client.ssl.certificate_alias is the alias of the certificate in the client keystore that is sent to the server if client certificate authentication is required
com.softwareag.um.client.ssl.truststore_path is the CA keystore file location
com.softwareag.um.client.ssl.truststore_password is the password for the CA keystore
com.softwareag.um.client.ssl.enabled_ciphers is a comma-separated list of ciphers from which the client is allowed to choose for secure communication
com.softwareag.um.client.ssl.ssl_protocol is the protocol that is used for secure communication