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 supports both custom SSL properties that can be set per UM session and JSSE 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 Custom SSL Properties on a Session
Setting SSL properties directly is done using the session attributes. Before initialising 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).
Setting SSL Properties using JSSE
Client certificate authentication NOT required
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.
1. Both CA1 and CA2 are well known Root Certificate Authorities
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.
2. CA1 is a well known Root Certificate Authority but CA2 is not (or vice versa)
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.
3. CA1 and CA2 are not well known Root Certificate Authorities
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.
Client certificate authentication required
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.
1. Both CA1 and CA2 are well known Root Certificate Authorities
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.
2. CA1 is a well known Root Certificate Authority but CA2 is not (or vice versa)
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.
3. CA1 and CA2 are not well known Root Certificate Authorities
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.
Environment Settings
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
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.