Chapter 5: Using SSL in Java Clients

EAServer’s HttpsURLConnection class

EAServer provides the com.sybase.jaguar.net.HttpsURLConnection class to support HTTPS connectivity. This class extends java.net.URLConnection and implements all methods of java.net.HttpURLConnection. HttpsURLConnection provides these additional methods specifically for SSL support:

A setSSLProperty method with signature:

void setSSLProperty (String prop, String value) throws
  CtsSecurity.InvalidPropertyException,
  CtsSecurity.InvalidValueException

Call this method to set the SSL properties described in “SSL properties”.

A setSSLProperties method with signature:

void setSSLProperty (java.util.Properties props) throws
  CtsSecurity.InvalidPropertyException,
  CtsSecurity.InvalidValueException

This method is the same as setSSLProperty, but allows you to set multiple properties with one call.

A getSSLProperty method with signature:
```
String[] setSSLProperty (String prop) throws
  CtsSecurity.InvalidPropertyException
```
Call this method to retrieve the SSL properties described in “SSL properties”.
A setGlobalProperty method with signature:
```
void setGlobalProperty (String prop, String value) throws
  CtsSecurity.InvalidPropertyException,
  CtsSecurity.InvalidValueException
```
Call this method to set the global SSL properties described in “SSL properties”. Properties set with this method affect the handling of all HTTPS connections, not just the current one.
A getGlobalProperty method with signature:
```
String[] getGlobalProperty(String prop) throws
  CtsSecurity.InvalidPropertyException;
```
Call this method to retrieve the global SSL properties described in “SSL properties”.
A getSessionInfo method with signature:
```
CtsSecurity.SSLSessionInfo getSessionInfo() throws CtsSecurity.SSLException
```
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 IDL interface. getSessionInfo throws an a SSLException instance if SSL is not used on the connection.

Creating HTTPS connections

Configure or install the EAServer HTTPS protocol handler as described in “Installing the HTTPS protocol handler”.
Create URL and URLConnection instances. If connecting to an EAServer, specify the address of an HTTPS listener that supports the desired level of security. For example:
```
URL url = new URL("https://myhost:8081/index.html");
URLConnection conn = url.openConnection();
```

Verify that the object returned by URL.openConnection is of class com.sybase.jaguar.net.HttpsURLConnection, then set SSL properties for the connection. “SSL properties” describes the SSL properties that can be set. At a minimum, you must specify the qop and pin properties, as well as the certificateLabel property if using mutual authentication. For example:

if (conn instanceof HttpsURLConnection)
{
  HttpsURLConnection https_conn =     (HttpsURLConnection) conn;
  try
  {
    https_conn.setSSLProperty( "qop","sybpks_intl" ); 
    https_conn.setSSLProperty( "pin", "secret");
    https_conn.setSSLProperty(
           "certificateLabel", "John Smith");
  } 
  catch ( CtsSecurity.InvalidPropertyException ipe )
  {
    System.err.println( ipe );
  }
  catch ( CtsSecurity.InvalidValueException ive )
  {
    System.err.println( ive );
  }

Open the connection, for example:
```
conn.connect();
```

Once the connection is open, you can perform any valid operation for a connection that uses java.net.HTTPUrlConnection. You can also call the getSessionInfo method to retrieve a CtsSecurity.SSLSessionInfo instance that allows you to verify the SSL connection parameters. For example:

java.net.URLConnection conn;
... deleted code that constructed URLConnection ...
if (conn instanceof HttpsURLConnection)
{
  HttpsURLConnection https_conn =     (HttpsURLConnection) conn;
  CtsSecurity.SSLSessionInfo sessInfo = 
    https_conn.getSessionInfo();

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.

View this book as PDF