Chapter 5 Using SSL in Java Clients

Creating HTTP and HTTPS connections in Java applications

You can create HTTP connections in Java applications using the HTTP protocol handling code built in to the Java Developer's Kit, and HTTPS connections using the HTTPS protocol handler provided with EAServer.

HTTP connections

The standard Java virtual machine provides HTTP connectivity with these classes in java.net package:

• URL allows you to use Uniform Resource Locator strings for HTTP connections and other protocol connections that can be represented by URLs.
• URLConnection represents a connection to a server and resource indicated by a URL.
• HttpURLConnection extends URL with additional methods that are specific to the HTTP protocol.

For details on these classes, see the JDK documentation. The following code shows a typical example. This code opens a connection, retrieves the data (text is assumed), and prints it:

URL url = new URL("http://www.sybase.com/");
URLConnection conn = url.openConnection();
conn.connect();
InputStreamReader content 
    = new InputStreamReader(conn.getInputStream());
for (int i=0; i != -1; i = content.read())
{
    System.out.print((char) i);  
} 

HTTPS connections

The procedure for creating HTTPS connections is similar to that for HTTP connections, except that you must install EAServer's HTTPS protocol handler in the Java virtual machine and configure SSL parameters before opening a connection.

   System requirements Standalone clients using the EAServer HTTPS implementation must be run with JDK 1.2 or later. Servlets, JSPs, and Java components using HTTPS must run in an EAServer that uses JDK 1.2 or later. EAServer's HTTPS protocol handler uses the same SSL implementation as used by Java and C++ IIOP clients and requires a full client runtime install. For information on system requirements, see "Requirements".

Installing the HTTPS protocol handler

The EAServer HTTPS protocol handler can be installed two ways:

• By configuring the java.protocol.handler.pkgs Java system property, making it the default handler for all HTTPS URLs. This is the recommended approach if you do not need to use another vendor's HTTPS protocol handler in addition to the EAServer implementation.
• By calling one of the java.net.URL constructors that takes a java.net.URLStreamHandler as a parameter. This approach must be used if you must use more than one HTTPS protocol handler in one EAServer or in one client application.

Configuring the default protocol handlers

The java.protocol.handler.pkgs Java system property configures the Java virtual machine default URL protocol handlers. To use the EAServer handlers, you must add com.sybase.jaguar.net to the list. For more information on this property, see the documentation for java.net.URL in JDK 1.2 .

In a client application, specify this property on the command line; for example:

jre -Djava.protocol.handler.pkgs=com.sybase.jaguar.net ...

For an EAServer, set the JVM options property using the All Properties tab in the Server Properties dialog box:

You can specify more than one package by separating package names with a | (pipe) character, but you can configure only one handler per protocol.

Specifying protocol handlers at runtime

If you must use more than one HTTPS protocol handler in one EAServer or in one client application, you must call one of the java.net.URL constructors that takes a java.net.URLStreamHandler as a parameter. The specified java.net.URLStreamHandler instance overrides the default handler for the protocol specified by the URL. For example, to specify the EAServer HTTPS handler, use code like this:

import java.net.*;
import com.sybase.jaguar.net.JagURLStreamHandlerFactory;
import com.sybase.jaguar.net.HttpsURLConnection;

....

String URL = "https://localhost:8081/index.html";

// The URL stream handler factory is required to create a stream
// handler.
JagURLStreamHandlerFactory fact = new JagURLStreamHandlerFactory();

// Extract the protocol from the front of the URL string
String protocol = url_string.substring(0, url_string.indexOf(":"));

// If the protocol is HTTPS, use the EAServer HTTPS handler. Otherwise,
// use the default handler
java.net.URL url;
if (protocol.equals("https"))
{
    url = new URL((URL)null, url_string,
        fact.createURLStreamHandler(protocol));
} else
{
    url = new URL(url_string);
}

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

1. Configure or install the EAServer HTTPS protocol handler as described in "Installing the HTTPS protocol handler".
2. 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();
   

3. 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 );
     }
   

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

SSL properties

Table 5-2 lists the properties that can be set and retrieved with the HttpsURLConnection getSSLProperty, getGlobalProperty, setSSLProperty, and setGlobalProperty methods. Global properties are set and read with the getGlobalProperty and setGlobalProperty methods. Global properties affect all HTTPS connections, not just the HttpsUrlConnection instance on which they are set. The right column in Table 5-2 lists which methods are valid for each property.

Some properties, if not set or set incorrectly, cause the connection to invoke an SSL callback method. You can install a callback to respond to these cases with the callbackImpl global property. If you do not install an SSL callback, the default callback implementation aborts the connection attempt.

com.acme.AcmeSSLCallback

Choosing a security characteristic

To use SSL, you must specify the name of an available security characteristic as the value for the qop property. 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.

Chapter 11, "Security Configuration Tasks" 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.

Copyright © 2002 Sybase, Inc. All rights reserved.