Chapter 26 Using HTTP and HTTPS Connections in Java


Creating HTTPS connections

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

Note   System requirements Standalone clients using the Jaguar HTTPS implementation must be run with JDK 1.2 or the version 1.2 JRE. Servlets, JSPs, and Java components using HTTPS must run in a Jaguar server that uses JDK 1.2. Jaguar'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 Jaguar HTTPS protocol handler can be installed two ways:

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 Jaguar 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 a Jaguar server, set the JVM options property using the All Properties tab in the Server Properties dialog box:

Property

Value

com.sybase.jaguar.server.jvm.options

If not already set, set to:

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

If already set, verify that the value includes this option. JVM options must be separated with a comma.

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 run time

If you must use more than one HTTPS protocol handler in one Jaguar server 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 Jaguar 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 Jaguar 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);
}

Jaguar's HttpsURLConnection class

Jaguar 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:

Steps To create HTTPS connections

  1. Configure or install the Jaguar HTTPS protocol handler as described in "Installing the HTTPS protocol handler".

  2. Create URL and URLConnection instances. If connecting to a Jaguar server, 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 operation that is valid 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.


 


Copyright © 2000 Sybase, Inc. All rights reserved.