You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2012/03/25 21:53:01 UTC
svn commit: r1305110 [8/10] - in /tomcat/site/trunk/docs/tomcat-3.3-doc: ./
appdev/ appdev/sample/ appdev/sample/etc/ appdev/sample/lib/
appdev/sample/src/ appdev/sample/web/ appdev/sample/web/images/ images/
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-security.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-security.html?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-security.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-security.html Sun Mar 25 19:52:59 2012
@@ -0,0 +1,260 @@
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+<!--
+ Copyright 1999-2004 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; I; SunOS 5.7 i86pc) [Netscape]">
+</head>
+<body text="#000000" bgcolor="#FFFFFF" link="#0000FF" vlink="#FF0000" alink="#000088">
+
+<h1>
+Using the Java SecurityManager with Tomcat</h1>
+
+<ul>
+<li>
+<a href="#why">Why use a SecurityManager?</a></li>
+
+<li>
+<a href="#requirements">System Requirements</a></li>
+
+<li>
+<a href="#precautions">Precautions</a></li>
+
+<li>
+<a href="#permissions">Types of Permissions</a></li>
+
+<li>
+<a href="#config">Configuring Tomcat for use with a SecurityManager</a></li>
+
+<li>
+<a href="#start">Starting Tomcat with a SecurityManager</a></li>
+
+<li>
+<a href="#violation">What happens when the SecurityManager detects a Security
+violation?</a></li>
+
+<li>
+<a href="#trouble">Trouble shooting tomcat.policy configuration and Security
+Violations</a></li>
+</ul>
+
+<h3>
+<a NAME="why"></a>Why use a SecurityManager?</h3>
+The Java SecurityManager is what allows a web browser to run an applet
+in its own sandbox to prevent untrusted code from accessing files on the
+local system, connecting to a host other than the one the applet was loaded
+from, etc.
+<p>In the same way the SecurityManager protects you from an untrusted applet
+running in your browser, use of a SecurityManager while running Tomcat
+can protect your server from trojan servlets, JSP's, JSP beans, and tag
+libraries. Or even inadvertent mistakes.
+<p>Imagine if someone who is authorized to publish JSP's on your site inadvertently
+included the following in their JSP:
+<blockquote>
+<pre><% System.exit(1); %></pre>
+</blockquote>
+
+<p><br>Every time that JSP was executed by Tomcat, Tomcat would exit.
+<p>Using the Java SecurityManager is just one more line of defense a system
+administrator can use to keep the server secure and reliable.
+<h3>
+<a NAME="requirements"></a>System Requirements</h3>
+Use of the SecurityManager requires a JVM that supports JDK 1.2.
+<br>
+<h3>
+<a NAME="precautions"></a>Precautions</h3>
+Implementation of a SecurityManager in Tomcat has not been fully tested
+to ensure the security of Tomcat. No special Permissions have been
+created to prevent access to internal Tomcat classes by JSP's, web applications,
+servlets, beans, or tag libraries. Make sure that you are satisfied with
+your SecurityManager configuration before allowing untrusted users to publish
+web applications, JSP's, servlets, beans, or tag libraries.
+<p>Still, running with a SecurityManager is definitely better than running
+without one.
+<br>
+<h3>
+<a NAME="permissions"></a>Types of Permissions</h3>
+Permission classes are used to define what Permissions a class loaded by
+Tomcat will have. There are a number of Permission classes as part
+of the JDK and you can even create your own Permission class for use in
+your own web applications.
+<p>This is just a short summary of the System SecurityManager Permission
+classes applicable to Tomcat. Please refer to the JDK documentation
+for more information on using the below Permissions.
+<p><b>java.util.PropertyPermission</b>
+<br> Controls read/write access to JVM properties such
+as java.home.
+<p><b>java.lang.RuntimePermission</b>
+<br> Controls use of some System/Runtime functions like
+exit() and exec().
+<p><b>java.io.FilePermission</b>
+<br> Controls read/write/execute access to files and
+directories.
+<p><b>java.net.SocketPermission</b>
+<br> Controls use of network sockets.
+<p><b>java.net.NetPermission</b>
+<br> Controls use of multicast network connections.
+<p><b>java.lang.reflect.ReflectPermission</b>
+<br> Controls use of reflection to do class introspection.
+<p><b>java.security.SecurityPermission</b>
+<br> Controls access to Security methods.
+<p><b>java.security.AllPermission</b>
+<br> Allows access to all permissions, just as if you
+were running Tomcat without a SecurityManager.
+<br>
+<h3>
+<a NAME="config"></a>Configuring Tomcat for use with a SecurityManager</h3>
+<b>tomcat.policy</b>
+<p>The security policies implemented by the Java SecurityManager are configured
+in the <b>tomcat.policy </b>file located in the tomcat <code>conf</code> directory.
+The tomcat.policy file replaces any system java.policy file. The
+tomcat.policy file can be edited by hand or you can use the <b>policytool
+</b>application
+that comes with Java 1.2, or later.
+<p>Entries in the tomcat.policy file use the standard java.policy file
+format as follows:
+<table border=0><tr><td><pre>// Example policy file entry
+
+grant [signedBy <signer> [,codeBase <code source>] {
+ permission <class> [<name> [, <action list>]];
+};
+</td></tr></table></pre>
+The <b>signedBy</b> and <b>codeBase </b>entries are optional when granting permissions.
+Comment lines begin with // and end at a new line.
+<p>The codeBase is in the form of a URL and for a file URL can use the
+${java.home} and ${tomcat.home} properties which are expanded out to the
+directory paths defined for them.
+<p>Default tomcat.policy file
+<table border=0><tr><td><pre>// Permissions for tomcat.
+
+// javac needs this
+grant codeBase "file:${java.home}/lib/-" {
+ permission java.security.AllPermission;
+};
+
+// Tomcat gets all permissions
+grant codeBase "file:${tomcat.home}/lib/-" {
+ permission java.security.AllPermission;
+};
+
+grant codeBase "file:${tomcat.home}/classes/-" {
+ permission java.security.AllPermission;
+};
+
+// Example webapp policy
+// By default we grant read access on webapp dir
+// and read of the line.separator PropertyPermission
+grant codeBase "file:${tomcat.home}/webapps/examples" {
+ permission java.net.SocketPermission "localhost:1024-","listen";
+ permission java.util.PropertyPermission "*","read";
+};</td></tr></table></pre>
+
+<p><br>Here is an example where in addition to the above, we want to grant
+the examples web application the ability to connect to the localhost smtp
+port so that it can send mail.
+<table border=0><tr><td><pre>grant codeBase "file:${tomcat.home}/webapps/examples" {
+ permission java.net.SocketPermission "localhost:25","connect";
+ permission java.net.SocketPermission "localhost:1024","listen";
+ permission java.util.PropertyPermission "*","read";
+};</td></tr></table></pre>
+Now what if we wanted to give all contexts not configured by their own
+grant entry some default permissions in addition to what Tomcat assigns
+by default.
+<table border=0><tr><td><pre>grant {
+ permission java.net.SocketPermission "localhost:1024","listen";
+ permission java.util.PropertyPermission "*","read";
+};</td></tr></table></pre>
+Finally, a more complex tomcat.policy file. In this case we are using
+Tomcat as an app server for a number of remote web servers. We want
+to limit what remote web servers can connect to Tomcat by using the Java
+SecurityManager.
+<br>
+<table border=0><tr><td><pre>// Permissions for tomcat.
+// javac needs this
+grant codeBase "file:${java.home}/lib/-" {
+ permission java.security.AllPermission;
+};
+
+// Tomcat with IP filtering
+grant codeBase "file:${tomcat.home}/lib/-" {
+ // Tomcat should be able to read/write all properties
+ permission java.util.PropertyPermission "*","read,write";
+ // Tomcat needs to be able to read files in its own directory
+ permission java.io.FilePermission "${tomcat.home}/-","read";
+ // Tomcat has to be able to write its logs
+ permission java.io.FilePermission "${tomcat.home}/logs/-","read,write";
+ // Tomcat has to be able to write to the conf directory
+ permission java.io.FilePermission "${tomcat.home}/conf/-","read,write";
+ // Tomcat has to be able to compile JSP's
+ permission java.io.FilePermission "${tomcat.home}/work/-","read,write,delete";
+ // Tomcat needs all the RuntimePermission's
+ permission java.lang.RuntimePermission "*";
+ // Needed so Tomcat can set security policy for a Context
+ permission java.security.SecurityPermission "*";
+ // Needed so that Tomcat will accept connections from a remote web server
+ // Replace XXX.XXX.XXX.XXX with the IP address of the remote web server
+ permission java.net.SocketPermission "XXX.XXX.XXX.XXX:1024-","accept,listen,resolve";
+ // Tomcat has to be able to use its port on the localhost
+ permission java.net.SocketPermission "localhost:1024-","connect,accept,listen,resolve";
+};
+
+// Example webapp policy
+// By default we grant read access on webapp dir
+// and read of the line.separator PropertyPermission
+grant codeBase "file:${tomcat.home}/webapps/examples" {
+ permission java.net.SocketPermission "localhost:1024-","listen";
+ permission java.util.PropertyPermission "*","read";
+};</td></tr></table></pre>
+
+<h3>
+<a NAME="start"></a>Starting Tomcat with a SecurityManager</h3>
+Once you have configured the tomcat.policy for use
+with a SecurityManager, Tomcat can be started with the SecurityManager
+in place by adding the "-security" option to bin/startup.bat or bin/startup.
+<br>
+<h3>
+<a NAME="violation"></a>What happens when the SecurityManager detects a
+Security violation?</h3>
+The JVM will throw an AccessControlException or a SecurityException when
+the SecurityManager detects a security policy violation.
+<br>
+<h2>
+<a NAME="trouble"></a>Trouble shooting tomcat.policy configuration and
+Security Violations</h2>
+You can turn on Java SecurityManager debug logging by setting the environmental
+variable:
+<pre>
+ TOMCAT_OPTS=-Djava.security.debug=all
+</pre>
+The debug output will be written to Tomcat's log file, or the console if no log
+file is defined.<br>
+<br><strong>Note:</strong> This gives the most complete debugging information,
+but generates many MB's of output, for less verbose security debug output, use:
+<pre>
+ TOMCAT_OPTS=-Djava.security.debug=access,failure
+</pre>
+Use the following shell command to determine all the security debug options
+available: <tt>java -Djava.security.debug=help</tt><br>
+<br>
+<b>JSP Compile using JVM internal javac fails with AccessControlException
+for RuntimePermission accessClassInPackage sun.tools.javac.</b>
+<p>Check your JAVA_HOME/jre/lib/security/java.security file configuration.
+Comment out the line "package.access=sun.".
+<br>
+<br>
+</body>
+</html>
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-security.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-ssl-howto.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-ssl-howto.html?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-ssl-howto.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-ssl-howto.html Sun Mar 25 19:52:59 2012
@@ -0,0 +1,770 @@
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <meta name="GENERATOR" content="Mozilla/4.77 [en] (X11; U; Linux 2.2.19-6.2.7 i686) [Netscape]">
+ <title>Tomcat and SSL</title>
+<!-- $Id $ -->
+<!--
+ Copyright 1999-2004 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<link rel="stylesheet" href="style.css">
+<style type="text/css">
+ .inlinetd {
+ background-color: #E0E0E0;
+ vertical-align: text-top;
+ border-top: thick black;
+ border-right: thick black;
+ border-bottom: thick black;
+ border-left: thick black;
+ }
+ .inlineth {
+ background-color: #d0d0d0;
+ border-top: thick black;
+ border-right: thick black;
+ border-bottom: thick black;
+ border-left: thick black;
+ }
+ .inlinetable {
+ width: 75%;
+ border: thick;
+ background-color: #000000;
+ }
+ .subsection { margin:20pt; }
+ .note { margin:20pt; padding:5pt; background-color:#e0e0ff; }
+
+ </style>
+</head>
+<body>
+<!-- Banner element, all hail the Project! -->
+<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" >
+<tr>
+ <td ALIGN=LEFT WIDTH="50%"><a href="http://jakarta.apache.org/index.html"><img SRC="images/banner.gif" ALT="The Jakarta Project" BORDER=0 height=48 width=505></a></td>
+
+ <td ALIGN=RIGHT WIDTH="50%"><img SRC="images/tomcat.gif" ALT="The mighty Tomcat - Meow!" BORDER=0 height=71 width=100></td>
+</tr>
+</table>
+
+<h1>
+Tomcat SSL Configuration</h1>
+
+<table border="0" cellpadding="0" cellspacing="0">
+<tr><td colspan="2"><b>Authors:</b><br><br></td></tr>
+<tr>
+ <td>Henri Gomez</td>
+ <td><tt><<a href="mailto:hgomez@slib.fr">hgomez@slib.fr</a>></tt></td>
+</tr>
+<tr>
+ <td>Christopher Cain </td>
+ <td><tt><<a href="mailto:ccain@apache.org">ccain@apache.org</a>></tt></td>
+</tr>
+<tr>
+ <td>Eric Rescorla</td>
+ <td><tt><<a href="mailto:ekr@rtfm.com">ekr@rtfm.com</a>></tt></td>
+</tr>
+</table>
+<br>
+
+<hr>
+
+<h2>
+Table of Contents</h2>
+
+<ul>
+<li>
+<a href="#s1">Introduction to SSL</a></li>
+
+<li>
+<a href="#s2">Tomcat and SSL</a></li>
+
+<li>
+<a href="#s8">Certificates</a></li>
+
+<li>
+<a href="#s3">Building Tomcat with SSL support</a></li>
+
+<li>
+<a href="#s4">Tomcat with Apache and mod_jk</a></li>
+
+<li>
+<a href="#s5">SSL via Apache</a></li>
+
+<li>
+<a href="#s6">SSL Standalone</a></li>
+
+<li>
+<a href="#s9">General Tips on Running SSL</a></li>
+
+<li>
+<a href="#s10">Troubleshooting SSL Standalone</a></li>
+
+<li>
+<a href="#s7">Credits</a></li>
+</ul>
+
+<hr>
+<h2>
+<a NAME="s1"></a>Introduction to SSL</h2>
+SSL, or Secure Sockets Layer, is a technology which allows web browsers and
+web servers to communicate over a secured connection. This means that the data
+being sent is encrypted by one side, transmitted, then decrypted by the other
+side prior to any processing. This is a two-way process, meaning that both the
+server <i>and</i> the browser encrypt all traffic before sending out data.
+<p>
+Another important aspect of the SSL protocol is <em>Authentication</em>. This
+means that during your initial attempt to communicate with a web server over a
+secure connection, that server will present your web browser with a set of
+credentials, in the form of a <em><a href="#s8">Certificate</a></em>, as proof
+that the site is who and what it claims to be. In certain cases, the server may
+also request a certificate from your web browser, asking for proof that
+<em>you</em> are who you claim to be. This is known as <em>Client
+Authentication,</em> although in practice it is used primarily for
+business-to-business (B2B) transactions rather than with typical site users.
+Most SSL-enabled web servers do not request Client Authentication.
+<br>
+<hr>
+
+<h2>
+<a NAME="s2"></a>Tomcat and SSL</h2>
+It is important to note that configuring Tomcat to take advantage of
+secure sockets is usually only necessary when running it as a standalone
+web server. When running Tomcat primarily as a Servlet/JSP container behind
+another web server, such as Apache or Microsoft IIS, it is usually necessary
+to configure the primary web server to handle the SSL connections from users.
+Typically, this server will negotiate all SSL-related functionality, then
+pass on any requests destined for the Tomcat container only after decrypting
+those requests. Likewise, Tomcat will return cleartext responses, which will
+then be encrypted by the primary server before being returned to the user's
+browser. In this environment, Tomcat knows that communications between the
+primary web server and the client are taking place over a secure connection
+(because your application needs to be able to ask about this), but it does
+not participate in the encryption or decryption itself.
+<p>
+Information on configuring Apache for SSL can be found at either the
+<a href="http://www.apache-ssl.org">Apache-SSL</a> pages, or the
+<a href="http://www.modssl.org">apache-mod_ssl</a> project. For information on
+configuring Tomcat to communicate with an SSL-enabled Apache server, see the
+<em><a href="#s4">Tomcat with Apache and mod_jk</a></em> section.
+<BR><BR>
+<B>Note:</B> SSL with Tomcat standalone requires JDK 1.2 or greater.
+<BR>
+<hr>
+
+<h2>
+<a NAME="s8"></a>Certificates</h2>
+In order to implement SSL, a web server must have an associated certificate
+for each external interface (IP address) that accepts secure connections.
+The theory behind certificates is that a server should provide some kind of
+reasonable assurance that its owner is who you think it is, particularly
+before receiving any sensitive information. While a broader explanation of
+certificates is beyond the scope of this document, think of a certificate
+as a digital "driver's license" for an Internet address. It states what
+company a site is associated with, along with some basic contact
+information about the site's owner and/or administrator.
+<p>
+This "driver's license" is cryptographically signed by its issuer, and is
+therefore extremely difficult for anyone else to forge. For sites involved
+in e-commerce, or any other business transaction in which authentication of
+identity is important, a certificate is typically purchased from a well-known
+<em>Certificate Authority</em> (CA) such as VeriSign or Thawte. Such
+certificates can be electronically verified --- in effect, the CA will vouch
+for the authenticity of the certificates that it grants, so you can,
+ostensibly, trust that a given certificate is valid if you trust the CA who
+granted it.
+<p>
+In many cases, however, authentication is not really a concern. An
+administrator may simply want to ensure that the data being transmitted and
+received by the server is private and cannot be snooped by anyone who may be
+eavesdropping on the connection. In such cases one is often tempted to
+use a "self-signed certificate"--one which has been signed only by the
+owner. Such a certificate obviously doesn't provide any guarantee of
+who the certificate owner is; there's nothing stopping me from making myself a certificate claiming to be George W. Bush.
+<p>
+What's less obvious is that using such certificates weakens the
+secrecy of your data as well. The attack works like this: when the
+client attempts to connect to the server the attacker hijacks the
+connection. He sends the client his own self-signed certificate which
+has the same <B>name</B> as that in the server's self-signed certificate.
+The attacker then connects to the real server himself. When the client
+sends data to the server the attacker reads it and then sends it along
+to the real server. This is called a <B>man-in-the-middle</B> attack.
+<p>
+The take-home message is that if you're worried about attackers who
+can write data to the network (this is called an active attack) then
+self-signed certificates won't protect you. If you're worried about
+attackers who can only read data off the network (this is called
+a passive attack) then self-signed certificates work fine. In general,
+you <EM>should</EM> worry about active attack and so self-signed
+certificates aren't that good.
+<p>
+Nevertheless, self-signed certificates are fantastically useful for testing
+and they are easily created with Java's <code>keytool</code> program or
+using OpenSSL.
+<br>
+<hr>
+<h2>
+<a NAME="s3"></a>Building Tomcat with SSL support</h2>
+If you want to build Tomcat with support for SSL, be careful of your
+classpath. I usually clear the <code>CLASSPATH</code> environment variable in
+order to avoid possible conflicts in jars. A common case of conflict is for XML
+parsers (xerces & jaxp). Tomcat required a recent XML parser, such as
+Apache Group's <A HREF="http://xml.apache.org/xerces-j/index.html">Xerces</A>
+or Sun's <A HREF="http://java.sun.com/xml/jaxp.html">JAXP</A>.
+<p>
+You now have two options for building Tomcat with SSL support: Sun's JSSE
+and Claymore Systems's PureTLS. The functionality that they offer is
+roughly equivalent. The primary relevant difference is in licensing:
+PureTLS is open source (BSD-style license) and JSSE is closed source.
+Therefore, if you want to redistribute compiled versions of Tomcat or
+just look at the source of your SSL/TLS implementation you must
+use PureTLS.
+<p>
+At build time (via Ant), Tomcat will automatically build as much SSL support
+as it can. If you have both PureTLS and JSSE in your <CODE>CLASSPATH</CODE>,
+Tomcat will automatically build with support for both. At run time, Tomcat
+will automatically select whatever library is present (if both are present,
+PureTLS will be selected). You can control which implementation is used
+via configuration file.
+<br>
+<hr>
+<h2>
+<a NAME="s4"></a>Tomcat with Apache and mod_jk</h2>
+If you use Apache with SSL (apache-ssl or apache-mod_ssl), the Apache connector
+mod_jk will be able to forward Tomcat SSL information if the JkExtractSSL
+directive is present in your httpd.conf.
+<p>Forwarded SSL Information is:
+<br>
+<table BORDER WIDTH="75%" >
+<tr>
+<td>HTTPS</td>
+
+<td>Apache Redirect to Tomcat from an SSL Area</td>
+</tr>
+
+<tr>
+<td>SSL_SESSION_ID</td>
+
+<td>SSL session ID</td>
+</tr>
+
+<tr>
+<td>SSL_CIPHER</td>
+
+<td>SSL CIPHER used</td>
+</tr>
+
+<tr>
+<td>SSL_CLIENT_CERT</td>
+
+<td>SSL Certificate of client</td>
+</tr>
+</table>
+
+<p>Since apache-ssl and apache-mod_ssl use different environment variables, you
+can adapt SSL variables via the following JK vars:
+<ul>
+<li>
+JkExtractSSL</li>
+
+<li>
+JkHTTPSIndicator</li>
+
+<li>
+JkSESSIONIndicator</li>
+
+<li>
+JkCIPHERIndicator</li>
+
+<li>
+JkCERTSIndicator:</li>
+</ul>
+Here is an example of some directives to include in httpd.conf for use with
+mod_ssl:
+<p><font face="Courier New, Courier, mono"><font size=-1># Should mod_jk
+send SSL information to Tomcat (default is On)</font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1>JkExtractSSL
+On</font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1># What is the
+indicator for SSL (default is HTTPS)</font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1>JkHTTPSIndicator
+HTTPS</font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1># What is the
+indicator for SSL session (default is SSL_SESSION_ID)</font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1>JkSESSIONIndicator
+SSL_SESSION_ID</font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1># What is the
+indicator for client SSL cipher suit (default is SSL_CIPHER)</font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1>JkCIPHERIndicator
+SSL_CIPHER</font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1># What is the
+indicator for the client SSL certificated (default is SSL_CLIENT_CERT)</font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1>JkCERTSIndicator
+SSL_CLIENT_CERT</font></font>
+<p>When using mod_jk with Apache & mod_ssl, it is essential to specify
+"SSLOptions +StdEnvVars +ExportCertData" in the httpd.conf file.
+<br>Otherwise, mod_ssl will not produce the neccessary environment variables
+for mod_jk. (Tilo Christ <tilo.christ@med.siemens.de>).
+<p>Warning, even though mod_jk supports both ajp12 (an old version from
+ApacheJServ) and ajp13, only ajp13 can forward SSL information to Tomcat.
+<br>
+<hr>
+<h2>
+<a NAME="s5"></a>SSL via Apache</h2>
+mod_jk supports the VirtualHost directive of Apache. This is especially
+useful when using Apache mod_ssl with Tomcat.
+<br>The following configuration will easily secure your webapps via Apache SSL
+support (be careful when setting these jk variables outside VirtualHost
+directives):
+<p><font face="Courier New, Courier, mono"><font size=-1>JkWorkersFile
+/etc/httpd/conf/workers.properties</font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1>JkLogFile /var/log/httpd/mod_jk.log</font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1>JkLogLevel warn</font></font>
+<p>The jk redirect stuff can be set in virtual hosts: <virtualhost _default_:443>
+<p><font face="Courier New, Courier, mono"><font size=-1><VirtualHost
+_default_:443></font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1>SSLEngine on</font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1>SSLCipherSuite
+ALL:!ADH:!EXP56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL</font></font>
+<p><font face="Courier New, Courier, mono"><font size=-1># other SSL stuff</font></font>
+<p><font face="Courier New, Courier, mono"><font size=-1>Alias /alesia
+"/var/tomcat/webapps/alesia" </font></font><directory "/var/tomcat/webapps/alesia">
+<br><font face="Courier New, Courier, mono"><font size=-1><Directory
+"/var/tomcat/webapps/alesia"></font></font></directory>
+<br><directory "/var/tomcat/webapps/alesia"><font face="Courier New, Courier, mono"><font size=-1>Options
+Indexes FollowSymLinks </font></font></directory>
+<br><font face="Courier New, Courier, mono"><font size=-1></Directory></font></font>
+<p><font face="Courier New, Courier, mono"><font size=-1>JkMount /alesia/servlet/*
+ajp13</font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1>JkMount /alesia/*.jsp
+ajp13 </font></font><location "/alesia/WEB-INF/">
+<br></location>
+<br><font face="Courier New, Courier, mono"><font size=-1><Location
+"/alesia/WEB-INF/"></font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1>AllowOverride
+None</font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1>Deny from all</font></font>
+<br><font face="Courier New, Courier, mono"><font size=-1></Location></font></font>
+<p><font face="Courier New, Courier, mono"><font size=-1></VirtualHost></font></font><virtualhost _default_:443></virtualhost>
+<br>
+<hr>
+
+<h2>
+<a NAME="s6"></a>SSL Standalone</h2>
+
+In order to configure Tomcat standalone for SSL support, you need to create
+(or import) an SSL certificate. For more information about SSL and
+certificates, you might find the following resources helpful:
+<ul>
+ <li><a href="http://www.openssl.org">OpenSSL</a> (Open Source SSL
+ implementation)
+ <li><a href="http://www.modssl.org">ModSSL</a> (SSL support for Apache)
+ <li><a href="http://www.cryptix.org">Cryptix</a> (Open Source Java crypto
+library)
+</ul>
+<P>
+If you have either PureTLS or JSSE installed, you might as well use that
+for your SSL support. If you have neither installed, you will need to
+download and install one of them.
+<p>
+<hr>
+<h2>SSL Support with JSSE</h3>
+<p>
+<h3>Download and Install JSSE</h3>
+
+<h3>1. Download and Install JSSE</h3>
+
+Download the <em>Java Secure Socket Extensions</em> (JSSE) package,
+version 1.0.2 or later, from
+<a href="http://java.sun.com/products/jsse/">http://java.sun.com/products/jsse/
+</a>. If you are running JDK 1.4 (currently in beta), these classes have
+been integrated directly into the JDK, so you can skip this entire step.
+<br><br>
+After expanding the package, there are two ways to make it available to
+Tomcat (choose one or the other):<br>
+<ul>
+<li>You can make JSSE an <em>installed extension</em> by copying all three JAR
+ files (<code>jcert.jar</code>, <code>jnet.jar</code>, and
+ <code>jsse.jar</code>) into your <code>$JAVA_HOME/jre/lib/ext</code>
+ directory.</li>
+<li>Alternatively, you can make these jars available via the classpath that is
+ passed to Tomcat on startup. This will need to be done in the appropriate
+ startup script for your environment (
+ <code>$TOMCAT_HOME/bin/tomcat</code> in Unix, or
+ <code>%TOMCAT_HOME%\bin\tomcat.bat</code> in Windows).</li>
+</ul>
+<b>Note:</b> The system classpath is effectively ignored by Tomcat, so
+including the JSSE jars there will <i>not</i> make them available for
+use by the Tomcat engine during runtime (although it will not conflict with
+the two methods described above if they <i>do</i> happen to be in the system
+classpath). Also, do <em>not</em> copy these jars into any of the internal
+Tomcat repositories (the <code>$TOMCAT_HOME/lib/*</code> directories,
+individual webapp directories, etc.). Doing so may cause Tomcat to fail, as
+these libraries should only be loaded by the system classloader.
+
+<h3>2. Prepare the Certificate Keystore</h3>
+<b>Note:</b> In order to execute the <code>keytool</code> command-line utility,
+the JSSE jars <em>must</em> be either in the classpath or an installed
+extension.
+<br><br>
+A "keystore" is essentially just a repository file for cryptographic objects,
+such as keys and certificates. Tomcat currently operates only on
+<code>JKS</code> format keystores. This is Java's standard "Java KeyStore"
+format, and is the format created by the <code>keytool</code> command-line
+utility. This tool is included in the JDK.
+<br><br>
+<b>To create a new keystore from scratch, containing a single self-signed
+certificate, execute the following from a terminal command line:</b>
+<br><br>
+
+<blockquote>
+<code>
+%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
+</code>
+(Windows)<br>
+<code>
+$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
+</code>
+(Unix)
+</blockquote>
+<br>
+(The RSA algorithm should be preferred as a secure algorithm, and also
+to ensure general compatibility with other servers and components such as
+Netscape and IIS.)
+<br><br>
+This command will create a new file, in the home directory of the user
+under which you run it, named "<code>.keystore</code>". To specify a
+different location or filename, add the <code>-keystore</code> parameter,
+followed by the complete pathname to your keystore file,
+to the <code>keytool</code> command shown above. For example:
+<br><br>
+
+<blockquote>
+<code>
+%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
+ -keystore /path/to/my/keystore
+</code>
+(Windows)<br>
+<code>
+$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
+ -keystore /path/to/my/keystore
+</code>
+(Unix)
+</blockquote>
+<br>
+
+After executing the <code>keytool</code> command, you will first be prompted
+for the keystore password. The default password used by Tomcat is
+"<code>changeit</code>" (all lower case), although you can specify a custom
+password if you like. Again, this will need to be reflected in the
+<code>server.xml</code> configuration file.
+<br><br>
+
+<tt><font size=-1>[root@www.vercingetorix.org /root]# $JAVA_HOME/bin/keytool -genkey -alias
+tomcat -keyalg RSA</font></tt>
+<br><tt><font size=-1>Enter keystore password: changeit</font></tt>
+<br><tt><font size=-1>What is your first and last name?</font></tt>
+<br><tt><font size=-1> [Unknown]: www.vercingetorix.org</font></tt>
+<br><tt><font size=-1>What is the name of your organizational unit?</font></tt>
+<br><tt><font size=-1> [Unknown]: Chief</font></tt>
+<br><tt><font size=-1>What is the name of your organization?</font></tt>
+<br><tt><font size=-1> [Unknown]: Gaulois</font></tt>
+<br><tt><font size=-1>What is the name of your City or Locality?</font></tt>
+<br><tt><font size=-1> [Unknown]: Alesia</font></tt>
+<br><tt><font size=-1>What is the name of your State or Province?</font></tt>
+<br><tt><font size=-1> [Unknown]: 50</font></tt>
+<br><tt><font size=-1>What is the two-letter country code for this unit?</font></tt>
+<br><tt><font size=-1> [Unknown]: FR</font></tt>
+<br><tt><font size=-1>Is <CN=www.vercingetorix.org, OU=Chief, O=Gaulois,
+L=Alesia, ST=50, C=FR> correct?</font></tt>
+<br><tt><font size=-1> [no]: yes</font></tt>
+<br><br>
+
+Finally, you will be prompted for the <em>key password</em>, which is the
+password specifically for this Certificate (as opposed to any other
+Certificates stored in the same keystore file). You <strong>MUST</strong>
+use the same password here as was used for the keystore password itself.
+(Currently, pressing the ENTER at this prompt will automatically do this.)
+<br><br>
+<b>To import an existing certificate into a JKS keystore:</b>
+<br><br>
+
+It is possible to import certificates generated with <a href="http://www.openssl.org">OpenSSL</a>.
+Here are the steps needed to generate such certs with OpenSSL :
+<ul>
+<li>
+To generate a new request and a new key</li>
+
+<pre><font face="Courier New, Courier, mono">openssl req -new -out REQ.pem -keyout KEY.pem</font></pre>
+
+<li>
+To generate a self signed x509 certificate from a certificate request using
+a supplied key, and we want to see the text form of the output certificate
+(which we will put in the file selfSign.pem)</li>
+
+<pre><font face="Courier New, Courier, mono"><font size=-1>openssl req -x509
+-in REQ.pem -key KEY.pem -out CERT.pem</font></font></pre>
+
+<li>
+Verify that the signature is correct on a certificate request.</li>
+
+<pre><font face="Courier New, Courier, mono"><font size=-1>openssl req -verify
+-in REQ.pem</font></font></pre>
+
+<li>
+Verify that the signature was made using a specified public key</li>
+
+<pre><font face="Courier New, Courier, mono"><font size=-1>openssl req -verify
+-in REQ.pem -key KEY.pem</font></font></pre>
+
+<li>
+Print the contents of a certificate request</li>
+
+<pre><font face="Courier New, Courier, mono"><font size=-1>openssl req -text
+-in REQ.pem</font></font></pre>
+
+<li>
+To import the CERT in keystore, you just do next :</li>
+
+<pre><font face="Courier New, Courier, mono"><font size=-1>keytool -import
+-v -trustcacerts -alias tomcat -file</font></font></pre>
+
+<pre><font face="Courier New, Courier, mono"><font size=-1>CERT.pem</font></font></pre>
+</ul>
+
+For more information, please read the documentation (in your JDK
+documentation package) about <code>keytool</code>.
+<br>
+<hr>
+<h2>SSL Support with PureTLS</h2>
+<h3>1. Downloading and Installing PureTLS</h3>
+The easiest way to download PureTLS is by simply downloading the
+prebuilt version from <a href="http://www.rtfm.com/puretls/prebuilt.html">
+http://www.rtfm.com/puretls/prebuilt.html</a>. This version contains
+all the jar files you will need in order to use PureTLS in one package.
+After expanding the package, there are two ways to make it available to
+Tomcat (choose one or the other):<br>
+<ul>
+ <li>You can make PureTLS an <em>installed extension</em> by copying all three JAR
+ files (<code>cryptix32.jar</code>, <code>puretls.jar</code>, and
+ <code>cryptix-asn1.jar</code>) into your <code>$JAVA_HOME/jre/lib/ext</code>
+ directory.</li>
+ <li>Alternatively, you can make these jars available via the classpath that is
+ passed to Tomcat on startup. This will need to be done in the appropriate
+ startup script for your environment (
+ <code>$TOMCAT_HOME/bin/tomcat</code> in Unix, or
+ <code>%TOMCAT_HOME%\bin\tomcat.bat</code> in Windows).</li>
+</ul>
+<b>Note:</b> The system classpath is effectively ignored by Tomcat, so
+including the PureTLS jars there will <i>not</i> make them available for
+use by the Tomcat engine during runtime (although it will not conflict with
+the two methods described above if they <i>do</i> happen to be in the system
+classpath). Also, do <em>not</em> copy these jars into any of the internal
+Tomcat repositories (the <code>$TOMCAT_HOME/lib/*</code> directories,
+individual webapp directories, etc.). Doing so may cause Tomcat to fail, as
+these libraries should only be loaded by the system classloader.
+<p>
+Alternately, you can download the PureTLS source distribution from
+<a href="http://www.rtfm.com/puretls">http://www.rtfm.com/puretls
+</a> and build it yourself. You will also need to install
+Cryptix 3.2 from <a href="http://www.cryptix.org/">http://www.cryptix.org/</a>.
+Once you've built Cryptix and PureTLS, install them as described above.
+<p>
+<h3>2. Obtaining Keys and Certificates</h3>
+<p>
+PureTLS uses OpenSSL-style keyfiles. If you have an OpenSSL key
+you can simply copy it somewhere and point Tomcat at it.
+Sometimes when people use OpenSSL they store their keys and
+certificates in separate files, such as <code>key.pem</code>
+and <code>cert.pem</code>. PureTLS expects a single file which
+you can create by just concatenating the two files. For instance:
+<code>cat key.pem cert.pem > keyfile.pem</code>.
+<p>
+PureTLS does not currently allow you to make self-signed certificates.
+However, a number of sample certificate files are included in the
+PureTLS distribution. For testing purposes you can use the file
+<code>rsa-server.pem</code> which has the password <code>password</code>.
+<p>
+Finally, PureTLS allows you to create a certificate request using
+the <code>COM.claymoresystems.ptls.cert.CertRequest</code> class.
+With PureTLS in your classpath, execute <code>COM.claymoresystems.cert.CertRequest <keyfile-name> RSA</code>. Then type your keyfile password on the
+console (currently this is echoed which is rather a bug). PureTLS will think for a while and then generate a key in <code>keyfile-name</code>. The certificate request (in Netscape format) will be printed on the screen and can be
+cut and pasted into your CA's web page. When you get your certificate
+attach it to the end of your keyfile.
+<h3>3. Trust Management for Client Authentication</h3>
+If you intend to require your clients to authenticate with certificates
+you will need to decide what CAs you trust. PureTLS gets this information
+from a <i>root file</i> which is just the concatenation of the trusted
+root CA certificates. You specify that file to Tomcat using the
+<code>rootlist</code> attribute in the configuration file.
+<hr>
+
+<h3>3. Edit the Tomcat configuration file</h3>
+
+To configure a secure (SSL) HTTP connector for Tomcat, verify that it is activated in
+the <CODE>$TOMCAT_HOME/conf/server.xml</CODE> file (the standard version of this file,
+as shipped with Tomcat, contains a simple example which is commented-out by default).
+<BLOCKQUOTE>
+<p>Syntax for Tomcat 3.2 :
+<p><tt><font size=-1><Connector className="org.apache.tomcat.service.PoolTcpConnector"></font></tt>
+<br><tt><font size=-1><Parameter name="handler" value="org.apache.tomcat.service.http.HttpConnectionHandler"/></font></tt>
+<br><tt><font size=-1><Parameter name="port" value="8443"/></font></tt>
+<br><tt><font size=-1><Parameter name="socketFactory" value="org.apache.tomcat.net.SSLSocketFactory"
+/></font></tt>
+<br><tt><font size=-1><Parameter name="keystore" value="/var/tomcat/conf/keystore"
+/></font></tt>
+<br><tt><font size=-1><Parameter name="keypass" value="mynewpass"/></font></tt>
+<br><tt><font size=-1><Parameter name="clientAuth" value="false"/></font></tt>
+<br><tt><font size=-1></Connector></font></tt><tt></tt>
+<p>Syntax for Tomcat 3.3 :
+<p><tt><font size=-1><Http10Connector</font></tt>
+<br><tt><font size=-1> port="8443"</font></tt>
+<br><tt><font size=-1> secure="true"</font></tt>
+<br><tt><font size=-1> keystore="/var/tomcat/conf/keystore"</font></tt>
+<br><tt><font size=-1> keypass="mynewpass"</font></tt>
+<br><tt><font size=-1> clientauth="false" /></font></tt><font size=-1></font>
+</BLOCKQUOTE>
+In the above examples, we indicate that the keystore is file located at
+<code>/var/tomcat/conf/keystore</code>, and the password if "mynewpass". Again,
+these attributes can be skipped if the Tomcat defaults were used. Also, we
+specified that we don't want to enforce client authentication. Also, note the
+case difference between Tomcat 3.2 and Tomcat 3.3 (i.e. "clientAuth"
+versus "clientauth").
+<P>
+For JSSE, the <i>presence</i> of the clientauth parameter will enforce
+client authentication, regardless of the parameter value. For PureTLS,
+this decision is based on the <i>value</i> of the clientauth parameter.
+<P>
+By default, Tomcat chooses whatever SSL implementation is available,
+with preference given to PureTLS over JSSE if both are available. You
+can specify the exact implementation you want using the <code>SSLImplementation</code>
+parameter, like so:
+<p><tt><font size=-1><Http10Connector</font></tt>
+<br><tt><font size=-1> port="8443"</font></tt>
+<br><tt><font size=-1> secure="true"</font></tt>
+<br><tt><font size=-1> keystore="/var/tomcat/conf/keystore"</font></tt>
+<br><tt><font size=-1> keypass="mynewpass"</font></tt>
+<br><tt><font size=-1> clientauth="false" </font></tt>
+<br><tt><font size=-1> SSLImplementation="org.apache.tomcat.util.net.PureTLSImplementation" </font></tt> /></font></tt>
+<P>
+<code>SSLImplementation</code> can be the name of any class that implements
+<code>org.apache.tomcat.util.net.SSLImplementation</code>. The values built
+into Tomcat are <code>org.apache.tomcat.util.net.PureTLSImplementation</code> for PureTLS
+and <code>org.apache.tomcat.util.net.JSSEImplementation</code> for JSSE.
+
+<hr>
+
+<h2>
+<a NAME="s9"></a>General Tips on Running SSL</h2>
+The first time a user attempts to access a secured page on your site,
+he or she is typically presented with a dialog containing the details of
+the certificate (such as the company and contact name), and asked if he or she
+wishes to accept the certificate as valid and continue with the transaction.
+Some browsers will provide an option for permanently accepting a given
+certificate as valid, in which case the user will not be bothered with a
+prompt each time they visit your site. Other browsers do not provide this
+option. Once approved by the user, a certificate will be considered valid
+for at least the entire browser session.
+<p>
+Also, while the SSL protocol was designed to be as efficient as securely
+possible, encryption/decryption is a computationally expensive process from
+a performance standpoint. It is not strictly necessary to run an entire
+web application over SSL, and indeed a developer can pick and choose which
+pages require a secure connection and which do not. For a reasonably busy
+site, it is customary to only run certain pages under SSL, namely those
+pages where sensitive information could possibly be exchanged. This would
+include things like login pages, personal information pages, and shopping
+cart checkouts, where credit card information could possibly be transmitted.
+Any page within an application can be requested over a secure socket by
+simply prefixing the address with <code>https:</code> instead of
+<code>http:</code>. Any pages which absolutely require a secure connection
+should check the protocol type associated with the page request and take the
+appropriate action if the <code>https</code> protocol is not specified.
+
+<hr>
+
+<h2>
+<a NAME="s10"></a>Troubleshooting SSL Standalone</h2>
+Here is a list of common problems that you may encounter when setting up
+Tomcat standalone for SSL, and what to do about them.</p>
+
+<ul>
+
+<li><I>I am seeing "java.security.NoSuchAlgorithmException" errors.</I>
+ <blockquote>
+ <p>The JVM cannot find the JSSE JAR files, or there was a problem in
+ loading the JSSE Provider. Please ensure that the JSSE jars have been
+ appropriately installed.</p>
+ </blockquote>
+</li>
+
+<li><I>When Tomcat starts up, I get an exception like
+ "java.io.FileNotFoundException: {some-directory}/{some-file} not found".</I>
+ <blockquote>
+ <p>A likely explanation is that Tomcat cannot find the keystore file
+ where it is looking. By default, Tomcat expects the keystore file to
+ be named <code>.keystore</code> in the user home directory under which
+ Tomcat is running (which may or may not be the same as yours :-). If
+ the keystore file is anywhere else, you will need to add the
+ <code>keystore</code> parameter/attribute to the secure connector in the
+ Tomcat configuration file (as outlined in the
+ <A HREF="#s6">Standalone SSL section</A>).</p>
+ </blockquote>
+</li>
+
+<li><I>When Tomcat starts up, I get an exception like
+ "java.io.FileNotFoundException: Keystore was tampered with, or
+ password was incorrect".</I>
+ <blockquote>
+ <p>Assuming that someone has not <em>actually</em> tampered with
+ your keystore file, the most likely cause is that Tomcat is using
+ a different password than the one you specified when creating the
+ keystore file. To fix this, you can either recreate the keystore
+ file, or you can add/update the <code>keypass</code> parameter/attribute
+ on the secure connector in the Tomcat configuration file (as outlined in
+ the <A HREF="#s6">Standalone SSL section</A>).
+
+ <P><strong>REMINDER</strong> - Passwords are case sensitive!</p>
+ </blockquote>
+</li>
+
+</ul>
+
+<p>If you are still having problems, a good source of information is the
+<strong>TOMCAT-USER</strong> mailing list. You can find pointers to archives
+of previous messages on this list, as well as subscription and unsubscription
+information, at
+<a href="http://jakarta.apache.org/site/mail.html">http://jakarta.apache.org/site/mail.html</a>.</p>
+<br>
+<hr>
+
+<h2>
+<a NAME="s7"></a>Credits</h2>
+This document was written by <a href="mailto:hgomez@slib.fr">Henri Gomez</a>, <A HREF="mailto:ccain@apache.org">Christopher Cain</A> and <A href="mailto:ekr@rtfm.com">Eric Rescorla</a>. Thanks to both Tilo
+Christ <tilo.christ@med.siemens.de> and hgopal@cmcltd.com for additional
+contributions.</P>
+<br>
+<table BORDER=0 CELLSPACING=0 CELLPADDING=10 WIDTH="100%" >
+<tr>
+<td>
+<div class="fineprint">Copyright ©1999-2001 The Apache Software Foundation</div>
+
+<p><br><a href="http://jakarta.apache.org/legal.html">Legal Stuff They
+Make Us Say</a>
+<br><a href="http://jakarta.apache.org/contact.html">Contact Information</a></td>
+</tr>
+</table>
+
+</body>
+</html>
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-ssl-howto.html
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org