Client SSL Configuration
This section describes how to use SSL in your Universal Messaging client applications. Universal Messaging supports various wire protocols (see
Communication Protocols and RNAMEs) including SSL enabled sockets and HTTPS. The example programs contained in the Universal Messaging package will all work with SSL enabled on the realm server.
This guide explains client SSL configuration on Java. Guides for C++ and C# are also available.
Once you have created an SSL enabled interface for your realm (see the description of how to do this in the section "Creating an SSL network interface" of the Enterprise Manager documentation), you need to ensure that your client application passes the required SSL properties either via custom setters on the session attributes 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 client/<umserver>/bin directory. The second is the client truststore called nirvanacacerts.jks, which is also located in the client/<umserver>/bin directory. On Windows, these files exist once you run the 'Server/<umserver>/Create Demo SSL Certificates' shortcut.
If you would like to add your own client certificates please see the section "How to generate certificates" of the Enterprise Manager documentation.
Using Custom SSL Properties
Using the sample keystores, you can use the following steps to set the SSL properties on a session.
1. Construct your session attributes object:
nSessionAttributes sessionAttributes = new nSessionAttributes(rname);
2. Set your required SSL attributes using these methods:
attribs.setKeystore(String keyStorePath, String keyStorePassword)
attribs.setKeystore(String keyStorePath, String keyStorePassword,
String certificateAlias);
// Certificate alias specifies which certificate the client can use
// if client validation is enabled on the interface being connected to
attribs.setTruststore(String trustStorePath, String trustStorePassword);
So your session attributes should look like this:
attribs.setKeystore(%INSTALLDIR%\client\<umserver>\bin\client.jks, password);
attribs.setTruststore(%INSTALLDIR%\client\<umserver>\bin\nirvanacacerts.jks,
password);
In addition to this you are also able to set a list of enabled cipher strings the client can use and the SSL protocol:
attribs.setEnabledCiphers(String[] enabledCiphers);
attribs.setSSLProtocol(String protocol);
3. Construct your session with the constructed session attributes:
nSession session = nSessionFactory.create(attribs);
session.init();
Using JSSE SSL System Properties
Using the example keystores, the following system properties are required by the Universal Messaging sample apps and must be specified in the command line as follows:
Important:
The CKEYSTORE, CKEYSTOREPASSWD, CAKEYSTORE, and CAKEYSTOREPASSWD system properties are deprecated.
-DCKEYSTORE=%INSTALLDIR%\client\<umserver>\bin\client.jks
-DCKEYSTOREPASSWD=password
-DCAKEYSTORE=%INSTALLDIR%\client\<umserver>\bin\nirvanacacerts.jks
-DCAKEYSTOREPASSWD=password
where:
CKEYSTORE (deprecated) is the client keystore location
CKEYSTOREPASSWD (deprecated) is the password for the client keystore
CAKEYSTORE (deprecated) is the CA keystore file location
CAKEYSTOREPASSWD (deprecated) is password for the CA keystore
The above system properties are used by the Universal Messaging sample apps, but are mapped to system properties required by a JSSE-enabled JVM by the utility program 'com.pcbsys.foundation.utils.fEnvironment', which all sample applications use. If you do not wish to use this program to perform the mapping between Universal Messaging system properties and those required by the JVM, you can specify the SSL properties directly. To do this in your own applications, set the following system properties:
-Djavax.net.ssl.keyStore=%INSTALLDIR%\client\<umserver>\bin\client.jks
-Djavax.net.ssl.keyStorePassword=password
-Djavax.net.ssl.trustStore=%INSTALLDIR%\client\<umserver>\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, both the Universal Messaging sample apps and your own 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 (see
Communication Protocols and RNAMEs) used by your client application must correspond to the correct type of SSL interface, and the correct hostname and port that was configured earlier.
Using the Universal Messaging Client System Properties for Secure Communication
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
JMS Clients
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.