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:hgo...@slib.fr">hgo...@slib.fr</a>></tt></td> +</tr> +<tr> + <td>Christopher Cain </td> + <td><tt><<a href="mailto:cc...@apache.org">cc...@apache.org</a>></tt></td> +</tr> +<tr> + <td>Eric Rescorla</td> + <td><tt><<a href="mailto:e...@rtfm.com">e...@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.chr...@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>[r...@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:hgo...@slib.fr">Henri Gomez</a>, <A HREF="mailto:cc...@apache.org">Christopher Cain</A> and <A href="mailto:e...@rtfm.com">Eric Rescorla</a>. Thanks to both Tilo +Christ <tilo.chr...@med.siemens.de> and hgo...@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-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org