Chapter 5 Using SSL in Java Clients

Using SSL in Java applications

Java application clients create SSL connections using the same native implementation used by C++ and ActiveX clients.

Requirements

SSL support in the Java client ORB requires a complete C++ client installation, including the SSL support libraries. SSL also requires the client-side Security Manager GUI and the $JAGUAR_CLIENT_ROOT/DB directory that contains the client-side security database. The client installation must also be correctly configured to load the native EAServer client libraries when you run your application. See the EAServer Installation Guide for more information. The following environment variable settings are required at runtime:

JAGUAR_CLIENT_ROOT must specify the full path to the EAServer client runtime installation directory.
On Windows platforms, PATH must include the EAServer client dll subdirectory.
On UNIX platforms, the system's shared library search path (LD_LIBRARY_PATH on Solaris) must include the EAServer client lib subdirectory.
CLASSPATH must include the EAServer client runtime classes. Specify the full path to the easclient.jar and easj2ee.jar files, or include the classes in these JAR files in a JAR that you build yourself.

WARNING!

Make sure you select the C++ Runtime and SSL Runtime options when installing the EAServer client runtime. SSL support in Java applications requires the files installed by these options.

Establishing a secure session

To ensure a secure session between your Java application and EAServer, you must configure SSL settings before using one of the standard techniques to instantiate proxies for the EAServer components.

You can configure the settings required for SSL connections using two techniques:

By setting ORB properties The required SSL settings must be known in advance, and your application can connect only to servers that use certificates issued by a known, trusted certificate authority.
By using the SSLServiceProvider interface The SSLServiceProvider interface allows your application to determine what options are available at runtime. In addition, you can supply a callback class with methods that supply settings as needed and respond to exceptional cases. For example, the client ORB invokes callback methods if the application specified an invalid certificate password or if a connection is made to a server that uses certificate issued by an unknown certificate authority.

Applications that run without user interaction typically configure SSL settings with the ORB properties. Interactive applications typically use the SSLServiceProvider interface and install a callback. When a callback is installed, you can rely on user interaction in the callback methods to configure necessary settings. For example, if the certificate password has not been supplied, the ORB invokes the getPin callback method.

Once you have correctly configured the required SSL settings, use the standard technique to instantiate proxies, as described in "Creating CORBA-Compatible Java clients" in the EAServer Programmer's Guide. Proxies are created in a secure session as long as the server supports the requested level of security.

Using the SSLServiceProvider interface

The CtsSecurity.SSLServiceProvider interface provides setGlobalProperty and getGlobalProperty methods to set and retrieve the SSL properties listed in Table 5-1. After initializing an ORB instance, you can instantiate a proxy for the SSLServiceProvider interface with the ORB.resolve_initial_references method, as shown below:

import CtsSecurity.*;

SSLServiceProvider sslServProv =
        SSLServiceProviderHelper.narrow
        (orb.resolve_initial_references 
        ("SSLServiceProvider"));

You can then call the setGlobalProperty method to set properties, as in the example below:

prov.setGlobalProperty("qop", "sybpks_intl");

Properties set with the SSLServiceProvider interface affect all ORB instances used by the application. However, if an equivalent property has been set for an ORB instance, the ORB property value takes precedence.

You can retrieve property values using the getGlobalProperty method. For example:

String availQop[] = prov.getGlobalProperty("availableQop");
String qopDesc[] = prov.getGlobalProperty("availableQopDesc");

getGlobalPropertyMethod returns an array of strings. When retrieving properties that take a single value, the value is returned in an array of length 1.

These methods are also documented in the generated Interface Repository documentation for the CtsSecurity::SSLCallback interface. The generated documentation is linked to your EAServer's main HTML page.

SSL properties

Table 5-1 lists the ORB and SSLServiceProvider properties that govern the use of SSL. In addition, you need to connect to a server address that can support your chosen level of security, as described in "Secure server addresses".

Some properties, if not set or set incorrectly, cause the ORB to invoke an SSL callback method. If you do not install an SSL callback, the default callback implementation aborts the connection attempt.

Table 5-1: SSL Properties
Property name for ORB.init	Property name for SSLServiceProvider	Description
com.sybase.CORBA. pin	pin	Always required when using SSL. Specifies the PKCS #11 token PIN. This is required for logging in to a PKCS #11 token for client authentication and for retrieving trust information. This property cannot be retrieved. If not set, set to "any", or set incorrectly, the ORB invokes the getPin callback method.
com.sybase.CORBA. certificateLabel	certificateLabel	Required when using mutual authentication. Specifies the client certificate to use if the connection requires mutual authentication. The label is a simple name that identifies an X.509 certificate/private key in a PKCS #11 token. If the property is not set and the connection requires mutual authentication, the ORB invokes the getCertificateLabel callback method, passing an array of available certificate names as an input parameter.
com.sybase.CORBA. qop	qop	Always required when using SSL. Specifies the name of a security characteristic to use. See "Choosing a security characteristic" for more information.
com.sybase.CORBA. userData	userData	Specifies user data (String datatype). This is an optional property. Client code can set user data during ORB initialization and access it using SSLSessionInfo::getProperty method in the SSL callback implementation. This may be useful as a mechanism to store ORB-level context information that is otherwise not available through the SSLSessionInfo interface.
com.sybase.CORBA. useEntrustID	useEntrustID	Specifies whether to use the Entrust ID or the Sybase PKCS #11 token for authentication. This is a Boolean (true or false) property. If this property is set to false, Sybase PKCS #11 token properties are valid and Entrust-specific properties are ignored. If this property is set to true, Entrust-specific properties are valid and Sybase PKCS #11 token properties are ignored.
com.sybase.CORBA. entrustUserProfile	entrustUserProfile	Specifies the full path to the file containing an Entrust user profile. This property is optional when the Entrust single-login feature is available and required when this feature is not available. If not set, the ORB invokes the getCredentialAttribute callback method.
com.sybase.CORBA. entrustPassword	entrustPassword	Specifies the password for logging in to Entrust with the specified user profile. This property is optional when the Entrust single-login feature is available and required when this feature is not available. If the password is required but not set, or set incorrectly, the ORB invokes the getPin callback method. This property cannot be retrieved.
com.sybase.CORBA. entrustIniFile	entrustIniFile	Specifies the path name for the Entrust INI file that provides information on how to access Entrust. This is required when the useEntrustid property is set to true. If not set, the ORB invokes the getCredentialAttribute callback method.
none	callbackImpl	Name of a Java class that implements the CtsSecurity.SSLCallbackIntf interface. For example: com.acme.AcmeSSLCallback See "Implementing an SSL callback" for more information.
none	availableQop	Retrieve only. A list of available security characteristics. The qop property can be set only to values that appear in this list.
none	availableQopDesc	Retrieve only. A list of descriptions for the available security characteristics, in the same order as listed in the value of the availableQop property.
none	entrustReady	Retrieve only. Returns true if Entrust PKI software is available on the client, false otherwise.

Choosing a security characteristic

To use SSL, you must specify a value for the qop property in ORB properties or by using the SSLServiceProvider interface. Specify the name of an available security characteristic. The characteristic describes the CipherSuites the client uses when negotiating an SSL connection. When connecting, the client sends the list of CipherSuites that it uses to the server, and the server selects a CipherSuite from that list. The server chooses the first CipherSuite in the list that it can use. If the server cannot use any of the available CipherSuites, the connection fails.

"Configuring security profiles" describes the security characteristics that are provided with EAServer. At runtime, you can retrieve a list of characteristics and their descriptions by retrieving the availableQop and availableQopDesc properties.

Set the qop property to sybpks_none to prevent any use of SSL on a connection. This setting can be useful if you have set the property globally for all ORBs using the SSLServiceProvider interface, and you want to override the setting for an individual ORB instance.

Secure server addresses

The client ORB connects only to a server listener that uses an equivalent or greater level of security as requested in the qop setting. If you use the CosNaming or JNDI interfaces to instantiate proxies, the name service URL cannot specify a server address that uses a higher level of security than specified by the qop property. For example, if your server uses the typical port configuration, you can specify port 9000 (no SSL) in the name service URL if the qop specifies mutual authentication. However, you cannot specify port 9002 (mutual authentication) in the name service URL and set the qop to request server-only authentication. When you use ORB.string_to_object to instantiate a SessionManager::Manager proxy, the listener specified by the server address must use a security profile that matches the client's qop setting.

For more information on instantiating proxies, see "Creating CORBA-Compatible Java clients" in the EAServer Programmer's Guide.

Implementing an SSL callback

An SSL callback class must implement the CtsSecurity.SSLCallbackIntf interface. The ORB invokes callback methods when required SSL settings have not been configured or a setting has an incorrect value. To install the callback, call SSLServiceProvider.setGlobalProperty to set the callbackImpl property, as in the example below:

sslprov.setGlobalProperty("callbackImpl",
     "Sample.ClientSSL.SSLCallbackExample.SSLCallbackExampleImpl");

The SSLCallbackIntf methods are as follows:

getCertificateLabel Called when the session requires mutual authentication and a certificate label has not been provided in ORB properties or in SSLServiceProvider global properties. The callback receives an array of available certificate labels as an input parameter, and must return one of them or throw an exception to abort the connection attempt.
getCredentialAttribute Called when additional information is required to use an Entrust certificate, such as the path to the Entrust profile file, or the path to the entrust.ini file.
getPin Called when the certificate password has not been specified in ORB or SSLServiceProvider properties, or if the supplied password was incorrect. The implementation should check the "tokenName" property of the SSLSessionInfo instance to determine whether the requested password is for the Sybase certificate database or for an Entrust profile. Your implementation can throw an CtsSecurity.UserAbortedException to abort the connection attempt.

trustVerify Called when the correct PIN for the certificate database has not been set, or if the server has presented a questionable certificate. The callback response determines whether the connection is allowed and, optionally, whether the certificate should be added to the local EAServer client certificate database.

Reason code	Description
CtsSecurity. REASON_TRUSTDBPINNOTSET. value	The password for the certificate database has not been set. Return CtsSecurity.TRUST_FAILED.value to cause the ORB to call the getPin callback method.
CtsSecurity. REASON_TRUSTDBLOGINFAILED. value	The password for the certificate database was incorrect. Return CtsSecurity.TRUST_FAILED.value to cause the ORB to call the getPin callback method.
CtsSecurity. REASON_UNKNOWN_CA. value	The root CA in the server's certificate chain is not listed in the Sybase certificate database.
CtsSecurity. REASON_CHAIN_EXPIRED. value	At least one certificate in the server's certificate chain has expired.
CtsSecurity. REASON_CHAIN_INCOMPLETE. value	Servers certificate chain is incomplete. The ORB cannot complete the chain using the CA certificates in the Sybase certificate database.

You must implement all of these methods in your class. If your implementation of a method does not process the request, throw an org.omg.CORBA.NO_IMPLEMENT exception so that the ORB uses the default response.

For more information about these callback methods, see the documentation for the CtsSecurity::SSLCallback interface in the generated Interface Repository documentation. "Sample Java applications that use SSL" describes the SSL sample applications. These samples include an example SSL callback that interacts with the user.

Retrieving session security information

The CtsSecurity.SSLSession and CtsSecurity.SSLSessionInfo classes allow you to determine whether SSL is used on connections from a proxy to the server, and if so, retrieve the SSL session settings. The code below illustrates the sequence of calls:

... code to set ORB ssl properties, create session,      instantiate proxy myComp ...
SSLSession sslSession =   SSLSessionHelper.narrow(myComp); 
try {
  SSLSessionInfo sslSessionInfo =     sslSession.getSessionInfo();
} catch (CtsSecurity.SSLNotEnabledError e) {
     ... this means the proxy does not use SSL ...
}

You can call SSLSessionHelper.narrow to obtain the session information associated with any CORBA object.

The SSLSessionInfo methods allow you to determine the SSL session properties, such as the server's address, the client certificate in use, the server certificate in use, and so forth. For more information, see the Interface Repository documentation for the CtsSecurity::SSLSessionInfo interface. "Sample Java applications that use SSL" describes the SSL sample applications. These examples show how to retrieve and print the SSL session information.

Sample Java applications that use SSL

Two sample Java applications that use SSL are in the html/classes/Sample/ClientSSL directory of your EAServer installation. The SSLDemo application allows you to configure SSL sessions using ORB properties set on the command line. The application uses the SSLSessionInfo interface to print a description of the SSL session. The SSLCbDemo application uses the SSLServiceProvider interface and an SSL callback class to query the user for SSL settings.