I have written an in-house howto for configuring Tomcat to support SSL/HTTPS connections made by servlets. I have obtained permission to give the document to the tomcat project community. I am placing the document under the APL. No liability is accepted for any damages incurred through the use of this document.
By following the procedure in this document, I have successfully configured a (fairly simple) servlet that I wrote to use HTTPS instead of HTTP without changing a single line of code. I figured that others might also find that useful.
If you find the document useful - great. If you find any errors - fix them. If you make any improvements, it would be good if you could drop me a copy of the updated document.
Cheers
--------------------------------------------------------------------------------
Aaron Knauf
Systems Integrator
Genie Systems Ltd
Auckland, New Zealand
Ph. +64-9-573 3310 x812
email: [EMAIL PROTECTED]
http://www.geniesystems.com
--------------------------------------------------------------------------------
HTTPS Configuration Howto for Servlets under Tomcat.
Author - Aaron Knauf, Genie Systems Ltd ([EMAIL PROTECTED])
Date - 20001107
Version - 0.1
Abstract
This document explains how to install and configure the Sun Java Secure Sockets
Extension so that servlets can make HTTPS calls under the Jakarta Tomcat servlet
engine. This Howto is based on version 1.0.2 of the JSSE. Other versions may or
may not work.
Introduction
When making HTTPS calls to servlets hosted by Tomcat, no Tomcat-specific
configuration or functionality is necessary if Tomcat is configured to integrate
with a web-server such as IIS or Apache. The web server supplies the necessary
SSL communications functionality.
In order for servlets to be aware of the SSL communication, Tomcat 3.2 or better
must be used, with the Apache Java Protocol 1.3 or better for connection to the
web server. Without these versions, details of certificate properties and other
SSL/HTTPS specific information is not available to the servlet.
Note that as of Tomcat release 3.2, the Jakarta Isapi Redirector supports only
AJP1.2.
In order for servlets themselves to initiate HTTPS/SSL encrypted connections, the
the Sun JSSE extension must be installed as a 'java installed extension'.
Although it is possible for the servlet to bundle this extension, this requires
more complex configuration of Tomcat itself and is considered (by me) to be an
inferior solution.
This document covers installation and configuration of the JSSE as a java
installed extension so that servlets can initiate HTTPS/SSL connections.
JSSE Installation
After downloading the JSSE, extract the three jar files (jcert.jar, jnet.jar and
jsse.jar) from the archive and place them in the <JAVA_HOME>/lib/ext directory.
Edit the <JAVA_HOME>/lib/security/java.security file and locate the following
section:
--------------------------------------------------------------------------------
#
# List of providers and their preference orders (see above):
#
security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.rsajca.Provider
--------------------------------------------------------------------------------
Edit the section to include a third security provider line, as follows:
--------------------------------------------------------------------------------
#
# List of providers and their preference orders (see above):
#
security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.rsajca.Provider
security.provider.3=com.sun.net.ssl.internal.ssl.Provider
--------------------------------------------------------------------------------
Tomcat Configuration
The following modification must be made to the tomcat startup file. (This assumes
that tomcat is configured to run as a service.)
Edit the <TOMCAT_HOME>/conf/wrapper.properties and locate the following line
(which should be located at the end of the file):
--------------------------------------------------------------------------------
wrapper.cmd_line=$(wrapper.javabin) -classpath $(wrapper.class_path)
$(wrapper.startup_class) -config $(wrapper.server_xml) -home $(wrapper.tomcat_home)
--------------------------------------------------------------------------------
Edit this line to say the following:
--------------------------------------------------------------------------------
wrapper.cmd_line=$(wrapper.javabin)
-Djava.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol
-classpath $(wrapper.class_path) $(wrapper.startup_class)
-config $(wrapper.server_xml) -home $(wrapper.tomcat_home)
--------------------------------------------------------------------------------
(Note that this should all appear on one line. The line is wrapped here for
readability.)
Restart the tomcat service.
A Note On Servlet Coding
In order for a servlet to make an HTTPS connection to a web server, it must use
a java.net.URL object. The URL object attempts to load a URLConnection based
on the protocol specified to the URL object. If the protocol specified is HTTP,
a clear text connection is made, using a URLConnection capable of understanding
the HTTP protocol. If HTTPS is the specified protocol, then a URLConnection
capable of understanding the encryption and handshaking required for HTTPS is
instantiated.
If the connection to the remote server is established using some other mechanism,
then the dynamic loading of the appropriate URLConnection will not work. If the
protocol specified to the URL is hard coded to either HTTP or HTTPS, then this
will preclude the use of any other protocol. If the port is hard coded in the
URL, the URLConnection will attempt to read the specifed protocol from the
specified port, possibly resulting in an attempt to negotiate encryption settings
with a plain text server, or an attempt to read plain text data from an SSL socket.
In any of the above cases, the servlet will require code changes in order to use
HTTPS communications. The moral of the story is to ensure that any URLs used in
your servlets are either dynamically determined, or specified in a config file.
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
