$Id$ Release Notes for: ==================== TOMCAT Version 3.1.1 ==================== 0. TABLE OF CONTENTS: 1. Introduction 2. Installing and Running Tomcat 3. Application Development Using Tomcat 4. New Features In This Release 5. Known Bugs and Issues 6. Security Vulnerabilities Fixed in 3.1.1 ============================================================================= 1. INTRODUCTION Tomcat is a servlet container and JavaServer Pages(tm) implementation. It may be used stand alone, or in conjunction with several popular web servers: - Apache, version 1.3 or later - Microsoft Internet Information Server, version 4.0 or later - Microsoft Personal Web Server, version 4.0 or later - Netscape Enterprise Server, version 3.0 or later You should read the License Agreement (in the LICENSE file of the top level directory), which applies to all software included in this release. Tomcat Version 3.1.1 is a security related update only! See Section 6, below, for details on the changes that have been made. All other existing issues with Tomcat 3.1 will remain in 3.1.1 -- users are *strongly* urged to upgrade to Tomcat 3.2, which includes fixes for these issues. No changes to the native code components of Tomcat 3.1 have been made. Therefore, you should *not* need to recompile components such as mod_jserv in order to take advantage of this release. You only need to replace the Java based modules in the "jakarta-tomcat.*" distribution. ============================================================================= 2. INSTALLING AND RUNNING TOMCAT Tomcat requires a Java Runtime Environment conformant to JRE 1.1 or later, including any Java2 platform system. If you wish to develop applications, you will need a Java compiler, such as the one included in a Java Development Kit 1.1 or later environment, including JDKs conformant with Java2. For detailed information about installing and running Tomcat, point your browser at file "doc/uguide/tomcat_ug.html" under the directory into which you unpacked the Tomcat distribution. ============================================================================= 3. APPLICATION DEVELOPMENT USING TOMCAT Preliminary information on using Tomcat for developing Servlet/JSP based applications is provided in the included Application Developer's Guide. Point your browser at file "doc/appdev/index.html" under the directory into which you unpacked the Tomcat distribution. ============================================================================= 4. NEW FEATURES IN THIS RELEASE Many new features have been added to Tomcat since the 3.0 release. Among the most important are: - Connectors for using Tomcat to run servlets with Microsoft's IIS and Netscape's NES web server, as well as Apache and stand-alone. - Automatic generation of configuration files for Apache integration. - Automatic deployment of applications delivered as Web ARchive (WAR) files. To deploy an application, copy the WAR file to the $TOMCAT_HOME/webapps directory and restart Tomcat, after which the WAR file will be automatically expanded. To remove an application, remove the expanded directory (and the WAR file) for that application. - Automatic servlet reloading when servlet classes are changed in WEB-INF/classes or WEB-INF/lib/*.jar. This support can be configured on a per-web-application basis. - Enhanced support for logging on a per-Tomcat-component basis. - Minimal administration tool, allowing new web applications to be deployed into a running Tomcat environment, as well as removing existing applications. - Command line tool (jspc) to compile the JSP pages that comprise your application ahead of time. - Substantially improved installation and development documentation. ============================================================================= 5. KNOWN BUGS AND ISSUES 5.1 Using An Absolute Path as Document Root Under Windows In the TOMCAT_HOME/conf/server.xml file, you can declare a relative or absolute directory pathname for the docRoot attribute. If you wish to use an absolute pathname on a Windows system, you MUST include the drive letter in order to conform to Java's definition of an absolute path on this platform: GOOD: c:\mydirectory\mydocroot GOOD: c:/mydirectory/mydocroot BAD: \mydirectory\mydocroot BAD: /mydirectory/mydocroot Under Unix, absolute pathnames must begin with a slash ('/') character. 5.2 Container Managed Security Tomcat 3.1 has an experimental implementation of container managed security, as described in the Servlet API Specification, version 2.2, section 11. Please note the following information about this implementation: - BASIC authentication appears to work correctly, but has not been extensively tested. Please report any bugs you encounter here at . The example application has a protected area defined at the following URL: http://localhost:8080/examples/jsp/security/protected which can be accessed by any user defined in the configuration file $TOMCAT_HOME/conf/tomcat-users.xml that has been granted the appropriate roles. WARNING: Basic authentication is not suitable for general security use across the Internet, or across other insecure networks, because usernames and passwords are sent encoded, but not encrypted, with every single request. - Form based login is partially supported, but only lightly tested. To assist in debugging this feature, you can enable the partial support by using a nonstandard EXPERIMENTAL_FORM element in your application deployment descriptor (web.xml) file. It should not be enabled for any reason other than debugging Tomcat. - DIGEST authentication and HTTPS client authentication (i.e. SSL) are not supported in this release. 5.3 Using RequestDispatcher.include() on a Welcome File [Bug Report #160] Using the following technique triggers an IllegalStateException: OutputStream is already being used for this request: - You have a subdirectory under your document root (for example "subdir/"). - This subdirectory contains a welcome file that you have configured to be displayed when that subdirectory is requested on a URL (for example "index.html"). - You request a RequestDispatcher for path "/subdir" or path "/subdir/" and then call include() on it. The same problem can occur when you do a to a page "/subdir" or "/subdir/" as well. A workaround is to ask for a RequestDispatcher on the complete context- relative path of the file you wish to have displayed, such as "/subdir/index.html". 5.4 Automatic Servlet Reloading Tomcat 3.1 includes a new feature whereby you can ask it to automatically reload servlet classes (loaded from either the WEB-INF/classes directory or a JAR file in the WEB-INF/lib directory) that have been changed. This feature is experimental, and may not be completely functional. In particular, changes to classes other than the servlet you are requesting do not trigger class reloads -- you will need to restart Tomcat to reflect changes in those classes. Reloading is enabled by including a reloadable="true" attribute on the element in the "conf/server.xml" file. Note that automatic reload support is not recommended for production applications because of its experimental nature, and the extra overhead required to perform the necessary checks on every request. =============================================================================== 6. SECURITY VULNERABILITIES FIXED IN TOMCAT 3.1.1 6.1 Administrative Application Enabled By Default The administrative application (at context path "/admin") was enabled by default in Tomcat 3.1, which allowed unauthenticated remote users to add and remove appliations from a running Tomcat 3.1 installation if it was left installed. To avoid such problems, the administrative application has been removed from the binary distribution of Tomcat 3.1.1. It can be installed if desired by: - Downloading the source distribution of Tomcat 3.1.1. - Modifying the "build.xml" file to remove the commenting around the logic that creates the adminstrative application. - Running the build.sh or build.bat script. 6.2 Case Sensitive Matches on Static Resources In Tomcat 3.1, matches against the filenames of static resources was done in a case insensitive manner on case insensitive platforms (such as Microsoft Windows). This can cause sensitive information to be exposed to remote users who experiment with differently cased request URIs. To avoid such problems, Tomcat 3.1.1 performs filename comparisons for static resources in a case sensitive manner, even on Windows. This means that your hyperlinks must specify the correct case, or a 404 error will be returned. Because this can cause significant conversion problems for existing applications deployed on Tomcat 3.1, a configuration option is provided to temporarily turn off case sensitive matching. Edit the file "conf/web.xml" and modify the value for the "caseSensitive" initialization parameter to the default file-serving servlet. WARNING: CHANGING THIS SETTING WILL RE-INTRODUCE THE SECURITY VULNERABILITY PRESENT IN TOMCAT 3.1 -- IT IS *STRONGLY* RECOMMENDED THAT YOU CORRECT YOUR URLS TO MATCH CORRECTLY INSTEAD OF USING THIS OPTION. Note: All later versions of Tomcat perform filename matches in a case sensitive manner. 6.3 Snoop Servlet Mappings in Example Application In the deployment descriptor for the example application delivered with Tomcat 3.1, a "snoop" servlet was mapped to URL patterns "/snoop" and "*.snp". Theses mappings (in particular the second one) could cause exposure of sensitive information on the internal organization of your web application (for example, when a non-existent page "foo.snp" is requested). To avoid these problems, the offending mappings have been commented out. 6.4 Show Source Vulnerability The example application delivered with Tomcat 3.1 included a mechanism to display the source code for the JSP page examples. This mechanism could be used to bypass the restrictions on displaying sensitive information in the WEB-INF and META-INF directories. This vulnerability has been removed. 6.5 Requesting Unknown JSP Pages In Tomcat 3.1, the error message in response to a request for an unknown JSP page would include the absolute disk file pathname of the corresponding file which could not be found, which exposes sensitive information about how your application is deployed. The error message has been adjusted to include only the context-relative path of the JSP page which could not be found. 6.6 Session ID Vulnerability The algorithm used to calculate session identifiers for new sessions was subject to attack by attempting to guess what the next session identifier will be, and therefore hijack the session. In addition, the generated identifier exposed sensitive information (the number of sessions that have been created since this web application was started. To avoid these problems, the session identifier generation algorithm has been replaced by the algorithm used in Tomcat 3.2, which is not subject to these attacks, and does not expose session count information. 6.7 Server Shutdown Vulnerability In Tomcat 3.1, it was possible to establish a remote network connection to the AJP12 connector and cause Tomcat to shut itself down. Now, this network connection must be created from the same server that Tomcat is running on. NOTE: While this is more secure than Tomcat 3.1 (and mirrors the protection provided by Tomcat 3.2), it is still vulnerable to attack by users who can create socket connections from the server. Suitable use of firewalls and "TCP Wrappers" applications are suggested around the APJ12 port.