Connecting to Multiple Realms Using SSL

This Section describes how to connect to multiple Universal Messaging realms using SSL when different certificate hierarchies are used on each respective realm. The information below applies to any of the various wire protocols (see Communication Protocols and RNAMEs) that Universal Messaging supports, such as SSL enabled sockets (nsps) and HTTPS (nhps). Note that the example programs contained in the Universal Messaging package will all work with SSL enabled on the realm server.

The certificate requirements differ depending on whether the realms require client certificate authentication or not. Let us assume that we want to connect to 2 realms over nsps, realmA and realmB. RealmA has interface nsps0 which uses a certificate signed by CA1, while RealmB has interface nsps0 which uses a certificate signed by CA2. The next few paragraphs describe what needs to be done for each possible configuration.

The Universal Messaging Client API supports both custom SSL properties that can be set per UM session, and JSSE and Universal Messaging client properties that can be set via system properties.

When using custom SSL properties that are set on the session level, you can set keystore/trustore and other SSL properties for each of your connections.

When using JSSE, only 1 keystore file/keystore password and 1 truststore file/truststore password can be used. In order to achieve your goal you will then have to create a combined keystore and / or a combined truststore depending on your configuration.

Setting SSL properties directly is done using the session attributes. Before initializing the session, ensure that your session attributes for each session are set with the correct keystore and truststore information. You can also set the alias of the certificate to use when client certificate authentication is enabled on the interface you are connecting to (see Client SSL Configuration for more info). If you are using JMS then you will need to set the SSL properties directly on the connection factory or on the create connection overload method provided as part of the connection factory implementation (see JMS Client SSL Configuration for more info).

In the case where client certificate authentication is not required by both realms, your application needs to use a combined truststore / truststore password only using the -DCAKEYSTORE and -DCAKEYSTOREPASSWD parameters.

All well known Root CAs are already included in the JRE cacerts file which can be found in jre\lib\security\cacerts . Unless you have manually changed that keystore's password the default password is changeit. You have to use these values for your -DCAKEYSTORE and -DCAKEYSTOREPASSWD parameters.

Two choices are available for this configuration. Either you add CA2's certificate to the JRE cacerts file or you create a combined keystore with CA2's certificate and CA1's certificate.You have to use these values for your -DCAKEYSTORE and -DCAKEYSTOREPASSWD parameters.

In this instance you have to create a combined truststore file that contains both the CA1 and CA2 certificates. In order to do this export your CA certificates from their current JKS store files then create a new JKS file and import them. You can do this using the JDK keytool command line utility. Finally you have to use these values for your -DCAKEYSTORE and -DCAKEYSTOREPASSWD parameters.

In the case where client certificate authentication is required by both realms, your application needs to use a combined keystore / keystore password and a combined truststore / truststore password using the -DCKEYSTORE, -DCKEYSTOREPASSWD, -DCAKEYSTORE and -DCAKEYSTOREPASSWD parameters respectively.

With regards to the truststore, all well known Root CAs are already included in the JRE cacerts file which can be found in jre\lib\security\cacerts . Unless you have manually changed that keystore's password the default password is changeit. You have to use these values for your -DCAKEYSTORE and -DCAKEYSTOREPASSWD parameters.

With regards to the keystore, you need to create a combined keystore that contains both client certificates and then point the -DCKEYSTORE parameter to its path as well as set the -DCKEYSTOREPASSWD to the password of that combined keystore. In order to create a combined keystore, export the certificates and private keys in PKCS#12 format and then import them as trusted certificates in the same keystore file. You can do this using the JDK keytool command line utility.

The easiest way for this configuration option is to create a single JKS file that contains the CA1 certificate, the CA1 signed client certificate, the CA2 certificate and the CA2 client certificate. You then have to use the same values for CKEYSTORE, CAKEYSTORE and CKEYSTOREPASSWD, CAKEYSTOREPASSWD respectively.

Again the easiest way for this configuration option is to create a single JKS file that contains the CA1 certificate, the CA1 signed client certificate, the CA2 certificate and the CA2 client certificate. You then have to use the same values for CKEYSTORE, CAKEYSTORE and CKEYSTOREPASSWD, CAKEYSTOREPASSWD respectively.

The CKEYSTORE, CKEYSTOREPASSWD, CAKEYSTORE and CAKEYSTOREPASSWD system properties (deprecated) 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 want 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, the following system properties must be set:

-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

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

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 provided, 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

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.enabled_ciphers is a comma-separated list of ciphers from which the client is allowed to choose for secure communication