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). Please 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 uses JSSE so only 1 keystore file/keystore password and 1 truststore file/truststore password can be used. In order to achieve our goal then we will have to create a combined keystore and / or a combined truststore depending on our configuration.

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 not 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 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, 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 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.