Return-Path: Mailing-List: contact tomcat-dev-help@jakarta.apache.org; run by ezmlm Delivered-To: mailing list tomcat-dev@jakarta.apache.org Received: (qmail 54491 invoked from network); 7 Nov 2000 02:35:34 -0000 Received: from unknown (HELO vincent.akl.nz.geniesystems.com) (210.55.186.222) by locus.apache.org with SMTP; 7 Nov 2000 02:35:34 -0000 To: tomcat-dev@jakarta.apache.org Subject: A HOWTO document for making HTTPS connections from servlets hosted by tomcat X-Mailer: Lotus Notes Release 5.0.5 September 22, 2000 Message-ID: From: "Aaron Knauf" Date: Tue, 7 Nov 2000 15:37:44 +1200 X-MIMETrack: Serialize by Router on vincent/akl/nz/geniesystems(Release 5.0.5 |September 22, 2000) at 11/07/2000 03:37:46 PM MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=_mixed 000E9AEFCC256990_=" X-Spam-Rating: locus.apache.org 1.6.2 0/1000/N --=_mixed 000E9AEFCC256990_= Content-Type: multipart/alternative; boundary="=_alternative 000E9AEFCC256990_=" --=_alternative 000E9AEFCC256990_= Content-Type: text/plain; charset="us-ascii" 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: aaronk@geniesystems.com http://www.geniesystems.com -------------------------------------------------------------------------------- --=_alternative 000E9AEFCC256990_= Content-Type: text/html; charset="us-ascii"
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: aaronk@geniesystems.com
http://www.geniesystems.com
-------------------------------------------------------------------------------- --=_alternative 000E9AEFCC256990_=-- --=_mixed 000E9AEFCC256990_= Content-Type: text/plain; name="HTTPS-Howto.txt" Content-Disposition: attachment; filename="HTTPS-Howto.txt" Content-Transfer-Encoding: quoted-printable HTTPS Configuration Howto for Servlets under Tomcat. Author - Aaron Knauf, Genie Systems Ltd (aaronk@geniesystems.com) Date - 20001107 Version - 0.1 Abstract This document explains how to install and configure the Sun Java Secure Soc= kets Extension so that servlets can make HTTPS calls under the Jakarta Tomcat se= rvlet 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 inte= grate with a web-server such as IIS or Apache. The web server supplies the neces= sary SSL communications functionality. In order for servlets to be aware of the SSL communication, Tomcat 3.2 or b= etter 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 o= nly AJP1.2. In order for servlets themselves to initiate HTTPS/SSL encrypted connection= s, 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 requ= ires more complex configuration of Tomcat itself and is considered (by me) to be= an=20 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.ja= r and jsse.jar) from the archive and place them in the /lib/ext dire= ctory. Edit the /lib/security/java.security file and locate the follo= wing section: ---------------------------------------------------------------------------= ----- # # List of providers and their preference orders (see above): # security.provider.1=3Dsun.security.provider.Sun security.provider.2=3Dcom.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=3Dsun.security.provider.Sun security.provider.2=3Dcom.sun.rsajca.Provider security.provider.3=3Dcom.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 /conf/wrapper.properties and locate the following l= ine (which should be located at the end of the file): ---------------------------------------------------------------------------= ----- wrapper.cmd=5Fline=3D$(wrapper.javabin) -classpath $(wrapper.class=5Fpath) = $(wrapper.startup=5Fclass) -config $(wrapper.server=5Fxml) -home $(wrap= per.tomcat=5Fhome) ---------------------------------------------------------------------------= ----- Edit this line to say the following: ---------------------------------------------------------------------------= ----- wrapper.cmd=5Fline=3D$(wrapper.javabin)=20 -Djava.protocol.handler.pkgs=3Dcom.sun.net.ssl.internal.www.protocol=20 -classpath $(wrapper.class=5Fpath) $(wrapper.startup=5Fclass)=20 -config $(wrapper.server=5Fxml) -home $(wrapper.tomcat=5Fhome) ---------------------------------------------------------------------------= ----- (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 bas= ed 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 understan= ding 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 mech= anism, then the dynamic loading of the appropriate URLConnection will not work. I= f the protocol specified to the URL is hard coded to either HTTP or HTTPS, then t= his 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 se= ttings 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 t= o use HTTPS communications. The moral of the story is to ensure that any URLs us= ed in your servlets are either dynamically determined, or specified in a config f= ile.= --=_mixed 000E9AEFCC256990_=--