Using SSL and the HTTPS protocol under Java 2 SDK v1.3

Introduction

Accessing the First American Flood Data Services (FAFDS) soap interface securely over SSL is almost as simple as changing the protocol on the url from http to https. Unfortunately, there are a few more steps involved because by default, the java.net.URL class in SDK v1.3 does not support the https protocol. If you try to construct a URL that starts with https, a java.net.MalformedURLException will be thrown with the message unknown protocol: https.

In order to enable handling of the https protocol, we need to set up SSL support and register a https protocol handler for the URL class. The following notes provide a minimal outline of the steps involved in the process. See the Resources section for more detailed information.

Last Modified $Date: 2005/11/15 00:01:52 $

1. Installing Java Secure Socket Extensions (JSSE) 1.0.2
2. Registering a HTTPS protocol handler
3. General notes
3.1. Alternative installation options
3.2. VeriSign SSL certificate
3.3. Performance issues
4. Resources

1. Installing Java Secure Socket Extensions (JSSE) 1.0.2

Note

JSSE has been integrated into Java 2 SDK v1.4, which means that if you are using SDK v1.4 you do not need to download and install JSSE. In 1.4, the classes previously found in the com.sun.net.ssl package are now located in the javax.net.ssl package.

  • Download and unzip JSSE.
  • Copy all of the jars in the JSSE lib directory to your JDK_HOME/jre/lib/ext/ directory. This is Sun's recommended way to install JSSE as a standard extension to the Java 2 platform.
  • Register the Cryptographic Service Provider that comes with JSSE by adding the line security.provider.n=com.sun.net.ssl.internal.ssl.Provider to the JDK_HOME/jre/lib/security/java.security file (where n is your preferred priority number for this provider.)

When the jars are in place and the provider is registered, SSL support should be available. The next step is to enable the URL class to handle the https protocol. This is done by registering a https protocol handler.

2. Registering a HTTPS protocol handler

Simply add the name of the https handler (com.sun.net.ssl.internal.www.protocol) to the java.protocol.handler.pkgs system property. This can be specified via the command line: java -Djava.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol myApp

Once that is done, the java.net.URL class will recognize the https protocol.

3. General notes

3.1. Alternative installation options

The process as just outlined should minimize the need to change any client code. There are, however, a few alternatives to some of the previous steps that are included here for completeness:

  • Instead of adding the JSSE jars to the JDK_HOME/jre/lib/ext/ directory, you can just specify them in your classpath as necessary.
  • Instead of modifying the java.security file to add the security provider, it can be specified in code: Security.addProvider(new com.sun.net.ssl.internal.ssl.Provider());
  • Instead of specifying the https handler property on the commandline, it also can be specified in code: System.setProperty("java.protocol.handler.pkgs", "com.sun.net.ssl.internal.www.protocol");

3.2. VeriSign SSL certificate

FAFDS uses a VeriSign certificate on its SSL-enabled servers. Because VeriSign is one of the major Certificate Authorities (CA), it is already registered in the default Java security truststore (JDK_HOME/jre/lib/security/cacerts). This means that it should not be necessary to manually import the First American certificate into your local truststore.

3.3. Performance issues

There is substantial overhead involved in the encryption and decryption that occurs during transmission of information across an SSL link. As a result, requests and responses over https may be noticeably slower than over regular http.

4. Resources