ScanCode.io: ttomcat-d57d818b-1778514372955

security-howto.xml | 34.8 KB |

<?xml version="1.0" encoding="UTF-8"?>  <!DOCTYPE document [ <!ENTITY project SYSTEM "project.xml"> ]> <document url="security-howto.html"> &project; <properties> <title>Security Considerations</title> </properties> <body> <section name="Table of Contents"> <toc/> </section> <section name="Introduction"> Tomcat is configured to be reasonably secure for most use cases by default. Some environments may require more, or less, secure configurations. This page is to provide a single point of reference for configuration options that may impact security and to offer some commentary on the expected impact of changing those options. The intention is to provide a list of configuration options that should be considered when assessing the security of a Tomcat installation. Note: Reading this page is not a substitute for reading and understanding the detailed configuration documentation. Fuller descriptions of these attributes may be found in the relevant documentation pages. </section> <section name="Non-Tomcat settings"> Tomcat configuration should not be the only line of defense. The other components in the system (operating system, network, database, etc.) should also be secured. Tomcat should not be run under the root user. Create a dedicated user for the Tomcat process and provide that user with the minimum necessary permissions for the operating system. For example, it should not be possible to log on remotely using the Tomcat user. File permissions should also be suitably restricted. In the <code>.tar.gz</code> distribution, files and directories are not world readable and the group does not have write access. On Unix like operating systems, Tomcat runs with a default umask of <code>0027</code> to maintain these permissions for files created while Tomcat is running (e.g. log files, expanded WARs, etc.). Taking the Tomcat instances at the ASF as an example (where auto-deployment is disabled and web applications are deployed as exploded directories), the standard configuration is to have all Tomcat files owned by root with group Tomcat and whilst owner has read/write privileges, group only has read and world has no permissions. The exceptions are the logs, temp and work directory that are owned by the Tomcat user rather than root. This means that even if an attacker compromises the Tomcat process, they can't change the Tomcat configuration, deploy new web applications or modify existing web applications. The Tomcat process runs with a umask of 007 to maintain these permissions. At the network level, consider using a firewall to limit both incoming and outgoing connections to only those connections you expect to be present. <subsection name="JMX"> The security of the JMX connection is dependent on the implementation provided by the JRE and therefore falls outside the control of Tomcat. Typically, access control is very limited (either read-only to everything or read-write to everything). Tomcat exposes a large amount of internal information and control via JMX to aid debugging, monitoring and management. Given the limited access control available, JMX access should be treated as equivalent to local root/admin access and restricted accordingly. The JMX access control provided by most (all?) JRE vendors does not log failed authentication attempts, nor does it provide an account lock-out feature after repeated failed authentications. This makes a brute force attack easy to mount and difficult to detect. Given all of the above, care should be taken to ensure that, if used, the JMX interface is appropriately secured. Options you may wish to consider to secure the JMX interface include: <ul> <li>configuring a strong password for all JMX users;</li> <li>binding the JMX listener only to an internal network;</li> <li>limiting network access to the JMX port to trusted clients; and</li> <li>providing an application specific health page for use by external monitoring systems.</li> </ul> </subsection> </section> <section name="Default web applications"> <subsection name="General"> Tomcat ships with a number of web applications that are enabled by default. Vulnerabilities have been discovered in these applications in the past. Applications that are not required should be removed so the system will not be at risk if another vulnerability is discovered. </subsection> <subsection name="ROOT"> The ROOT web application presents a very low security risk but it does include the version of Tomcat that is being used. The ROOT web application should normally be removed from a publicly accessible Tomcat instance, not for security reasons, but so that a more appropriate default page is shown to users. </subsection> <subsection name="Documentation"> The documentation web application presents a very low security risk but it does identify the version of Tomcat that is being used. It should normally be removed from a publicly accessible Tomcat instance. </subsection> <subsection name="Examples"> The examples web application should always be removed from any security sensitive installation. While the examples web application does not contain any known vulnerabilities, it is known to contain features (particularly the cookie examples that display the contents of all cookies received and allow new cookies to be set) that may be used by an attacker in conjunction with a vulnerability in another application deployed on the Tomcat instance to obtain additional information that would otherwise be unavailable. </subsection> <subsection name="Manager"> The Manager application allows the remote deployment of web applications and is frequently targeted by attackers due to the widespread use of weak passwords and publicly accessible Tomcat instances with the Manager application enabled. The Manager application is not accessible by default as no users are configured with the necessary access. If the Manager application is enabled then guidance in the section Securing Management Applications section should be followed. </subsection> <subsection name="Host Manager"> The Host Manager application allows the creation and management of virtual hosts - including the enabling of the Manager application for a virtual host. The Host Manager application is not accessible by default as no users are configured with the necessary access. If the Host Manager application is enabled then guidance in the section Securing Management Applications section should be followed. </subsection> <subsection name="Securing Management Applications"> When deploying a web application that provides management functions for the Tomcat instance, the following guidelines should be followed: <ul> <li>Ensure that any users permitted to access the management application have strong passwords.</li> <li>Do not remove the use of the <a href="config/realm.html#LockOut_Realm_-_org.apache.catalina.realm.LockOutRealm">LockOutRealm</a> which prevents brute force attacks against user passwords.</li> <li>Configure the <a href="config/valve.html#Remote_CIDR_Valve">RemoteCIDRValve</a> in the <a href="config/context.html">context.xml</a> file for the management application which limits access to localhost by default. If remote access is required, limit it to specific IP addresses using this valve.</li> </ul> </subsection> </section> <section name="User web applications"> Web applications are assumed to be trusted. It is not safe to deploy web applications from untrusted sources. Any application functionality that permits the modification of a web application (WebDAV, HTTP PUT requests etc.) may impact the security of either the web application or the Tomcat instance on which it is running. Such functionality should either be restricted to trusted users or limited in scope (e.g. via security constraints) such that users with access to the functionality are unable to imapct the security of either the web application or the Tomcat instance on which it is running. Consider using the <a href="config/filter.html#CORS_Filter">CORS filter</a> and/or the <a href="config/filter.html#CSRF_Prevention_Filter">CSRF prevention filter</a> with deployed web applications. </section> <section name="Security manager"> Support for running under a security manager has been removed for Tomcat 11 onwards. Similar (arguably better) functionality maybe obtained by running a single web application on a dedicated Tomcat instance in a dedicated environment such as a container or VM. </section> <section name="server.xml"> <subsection name="General"> The default server.xml contains a large number of comments, including some example component definitions that are commented out. Removing these comments makes it considerably easier to read and comprehend server.xml. If a component type is not listed, then there are no settings for that type that directly impact security. </subsection> <subsection name="Server"> Setting the port attribute to <code>-1</code> disables the shutdown port. If the shutdown port is not disabled, a strong password should be configured for shutdown. </subsection> <subsection name="Listeners"> The APR Lifecycle Listener is not stable if compiled on Solaris using gcc. If using the APR/native connector on Solaris, compile it with the Sun Studio compiler. The JNI Library Loading Listener may be used to load native code. It should only be used to load trusted libraries. The Security Lifecycle Listener should be enabled and configured as appropriate. </subsection> <subsection name="Connectors"> By default, a non-TLS, HTTP/1.1 connector is configured on port 8080. Connectors that will not be used should be removed from server.xml. AJP is a clear text protocol. AJP Connectors should normally only be used on trusted networks. If used on an untrusted network, use of the <code>secret</code> attribute will limit access to authorised clients but the <code>secret</code> attribute will be visible to anyone who can observe network traffic. AJP Connectors block forwarded requests with unknown request attributes. Known safe and/or expected attributes may be allowed by configuration an appropriate regular expression for the <code>allowedRequestAttributesPattern</code> attribute. The address attribute may be used to control which IP address a connector listens on for connections. By default, a connector listens on all configured IP addresses. The allowBackslash attribute allows non-standard parsing of the request URI. Setting this attribute to a non-default value when behind a reverse proxy may enable an attacker to bypass any security constraints enforced by the proxy. The allowTrace attribute may be used to enable TRACE requests which can be useful for debugging. Due to the way some browsers handle the response from a TRACE request (which exposes the browser to an XSS attack), support for TRACE requests is disabled by default. The discardFacades attribute set to <code>true</code> will cause a new facade object to be created for each request. This is the default value, and this reduces the chances of a bug in an application exposing data from one request to another. The encodedSolidusHandling attribute allows non-standard parsing of the request URI. Setting this attribute to a non-default value when behind a reverse proxy may enable an attacker to bypass any security constraints enforced by the proxy. The enforceEncodingInGetWriter attribute has security implications if set to <code>false</code>. Many user agents, in breach of RFC 7230, try to guess the character encoding of text media types when the specification-mandated default of ISO-8859-1 should be used. Some browsers will interpret as UTF-7 a response containing characters that are safe for ISO-8859-1 but trigger an XSS vulnerability if interpreted as UTF-7. The maxParameterCount attribute controls the maximum total number of request parameters (including uploaded files) obtained from the query string and, for POST requests, the request body if the content type is <code>application/x-www-form-urlencoded</code> or <code>multipart/form-data</code>. Requests with excessive parameters are rejected. The maxPartCount attribute controls the maximum number of parts supported for a multipart request. This is limited to 50 by default to reduce exposure to a DoS attack. The documentation for maxPartCount provides more details on the memory requirements for processing multipart requests. Requests with excessive parts are rejected. The maxPostSize attribute controls the maximum size of data from a POST request that will be parsed for request parameters. The parameters are cached for the duration of the request so this is limited to 2 MiB by default to reduce exposure to a DoS attack. The maxSavePostSize attribute controls the saving of the request body during FORM and CLIENT-CERT authentication and HTTP/1.1 upgrade. For FORM authentication, the request body is cached in the HTTP session for the duration of the authentication so the cached request body is limited to 4 KiB by default to reduce exposure to a DOS attack. To further reduce exposure to a DoS attack by limiting the permitted duration of the FORM authentication, a reduced session timeout is used if the session is created by the FORM authentication. This reduced timeout is controlled by the <code>authenticationSessionTimeout</code> attribute of the <a href="config/valve.html#Form_Authenticator_Valve">FORM authenticator</a>. The rejectSuspiciousURIs attribute can be used to reject valid URIs that contain patterns that are often used by malicious clients to mount attacks using techniques such as directory traversal. Note that this attribute is <code>false</code> by default as there is some overlap betweeen suspicious URIs and legitimate usage. The requiredSecret attribute in AJP connectors configures shared secret between Tomcat and reverse proxy in front of Tomcat. It is used to prevent unauthorized connections over AJP protocol. The server attribute controls the value of the Server HTTP header. The default value of this header for Tomcat 4.1.x to 8.0.x is Apache-Coyote/1.1. From 8.5.x onwards this header is not set by default. This header can provide limited information to both legitimate clients and attackers. The SSLEnabled, scheme and secure attributes may all be independently set. These are normally used when Tomcat is located behind a reverse proxy and the proxy is connecting to Tomcat via HTTP or HTTPS. They allow Tomcat to see the SSL attributes of the connections between the client and the proxy rather than the proxy and Tomcat. For example, the client may connect to the proxy over HTTPS but the proxy connects to Tomcat using HTTP. If it is necessary for Tomcat to be able to distinguish between secure and non-secure connections received by a proxy, the proxy must use separate connectors to pass secure and non-secure requests to Tomcat. If the proxy uses AJP then the SSL attributes of the client connection are passed via the AJP protocol and separate connectors are not needed. The tomcatAuthentication and tomcatAuthorization attributes are used with the AJP connectors to determine if Tomcat should handle all authentication and authorisation or if authentication should be delegated to the reverse proxy (the authenticated user name is passed to Tomcat as part of the AJP protocol) with the option for Tomcat to still perform authorization. The xpoweredBy attribute controls whether or not the X-Powered-By HTTP header is sent with each request. If sent, the value of the header contains the Servlet and JSP specification versions, the full Tomcat version (e.g. Apache Tomcat/<version-major-minor/>), the name of the JVM vendor and the version of the JVM. This header is disabled by default. This header can provide useful information to both legitimate clients and attackers. </subsection> <subsection name="Host"> The host element controls deployment. Automatic deployment allows for simpler management but also makes it easier for an attacker to deploy a malicious application. Automatic deployment is controlled by the autoDeploy and deployOnStartup attributes. If both are <code>false</code>, only Contexts defined in server.xml will be deployed and any changes will require a Tomcat restart. In a hosted environment where web applications may not be trusted, set the deployXML attribute to <code>false</code> to ignore any context.xml packaged with the web application that may try to assign increased privileges to the web application. Note that if the security manager is enabled that the deployXML attribute will default to <code>false</code>. </subsection> <subsection name="Context"> This applies to <a href="config/context.html">Context</a> elements in all places where they can be defined: <code>server.xml</code> file, default <code>context.xml</code> file, per-host <code>context.xml.default</code> file, web application context file in per-host configuration directory or inside the web application. The crossContext attribute controls if a context is allowed to access the resources of another context. It is <code>false</code> by default and should only be changed for trusted web applications. The privileged attribute controls if a context is allowed to use container provided servlets like the Manager servlet. It is <code>false</code> by default and should only be changed for trusted web applications. The allowLinking attribute of a nested <a href="config/resources.html">Resources</a> element controls if a context is allowed to use linked files. If enabled and the context is undeployed, the links will be followed when deleting the context resources. Changing this setting from the default of <code>false</code> on case insensitive operating systems (this includes Windows) will disable a number of security measures and allow, among other things, direct access to the WEB-INF directory. The sessionCookiePathUsesTrailingSlash can be used to work around a bug in a number of browsers (Internet Explorer, Safari and Edge) to prevent session cookies being exposed across applications when applications share a common path prefix. However, enabling this option can create problems for applications with Servlets mapped to <code>/*</code>. It should also be noted the RFC6265 section 8.5 makes it clear that different paths should not be considered sufficient to isolate cookies from other applications. When antiResourceLocking is enabled, Tomcat will copy the unpacked web application to the directory defined by the <code>java.io.tmpdir</code> system property (<code>$CATALINA_BASE/temp</code> by default). This location should be secured with appropriate file permissions - typically read/write for the Tomcat user and no access for other users. When mapperContextRootRedirectEnabled and/or mapperDirectoryRedirectEnabled are enabled, request processing will be more efficient but there are security side effects. First, the existence of a web application or a directory may be confirmed even though the user does not have access to that directory. Secondly, any Valves and/or Filters - including those providing security functionality - will not have an opportunity to process the request. </subsection> <subsection name="Valves"> It is strongly recommended that an AccessLogValve is configured. The default Tomcat configuration includes an AccessLogValve. These are normally configured per host but may also be configured per engine or per context as required. Any administrative application should be protected by a RemoteCIDRValve (this Valve is also available as a Filter). The allow attribute should be used to limit access to a set of known trusted hosts. The default ErrorReportValve includes the Tomcat version number in the response sent to clients. To avoid this, custom error handling can be configured within each web application. Alternatively, you can explicitly configure an <a href="config/valve.html">ErrorReportValve</a> and set its showServerInfo attribute to <code>false</code>. Alternatively, the version number can be changed by creating the file CATALINA_BASE/lib/org/apache/catalina/util/ServerInfo.properties with content as follows: <source>server.info=Apache Tomcat/<version-major-minor/>.x</source> Modify the values as required. Note that this will also change the version number reported in some of the management tools and may make it harder to determine the real version installed. The CATALINA_HOME/bin/version.bat|sh script will still report the correct version number. The default ErrorReportValve can display stack traces and/or JSP source code to clients when an error occurs. To avoid this, custom error handling can be configured within each web application. Alternatively, you can explicitly configure an <a href="config/valve.html">ErrorReportValve</a> and set its showReport attribute to <code>false</code>. The RewriteValve uses regular expressions and poorly formed regex patterns may be vulnerable to "catastrophic backtracking" or "ReDoS". See <a href="rewrite.html">Rewrite docs</a> for more details. </subsection> <subsection name="Realms"> The MemoryRealm is not intended for production use as any changes to tomcat-users.xml require a restart of Tomcat to take effect. The UserDatabaseRealm is not intended for large-scale installations. It is intended for small-scale, relatively static environments. The JAASRealm is not widely used and therefore the code is not as mature as the other realms. Additional testing is recommended before using this realm. By default, the realms do not implement any form of account lock-out. This means that brute force attacks can be successful. To prevent a brute force attack, the chosen realm should be wrapped in a LockOutRealm. </subsection> <subsection name="Manager"> The manager component is used to generate session IDs. The class used to generate random session IDs may be changed with the randomClass attribute. The length of the session ID may be changed with the sessionIdLength attribute. The persistAuthentication controls whether the authenticated Principal associated with the session (if any) is included when the session is persisted during a restart or to a Store. When using the JDBCStore, the session store should be secured (dedicated credentials, appropriate permissions) such that only the JDBCStore is able to access the persisted session data. In particular, the JDBCStore should not be accessible via any credentials available to a web application. Manager implementations that persist sessions to storage or replicate sessions in a cluster typically use Java serialization. While the session data is considered trusted (since the application is trusted), system administrators may wish to consider placing restrictions on the Java serialization. This can be done using the sessionAttributeValueClassNameFilter attribute. A safe starting value for this attribute is <code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)|org\\.apache\\.catalina\\.realm\\.GenericPrincipal\\$SerializablePrincipal|\\[Ljava.lang.String;</code> which can then be adjusted to meet the needs of the application. If setting a value for sessionAttributeValueClassNameFilter it is recommended that warnOnSessionAttributeFilterFailure is set to <code>true</code>. </subsection> <subsection name="Cluster"> The cluster implementation is written on the basis that a secure, trusted network is used for all of the cluster related network traffic. It is not safe to run a cluster on a insecure, untrusted network. If you require confidentiality and/or integrity protection then you can use the <a href="config/cluster-interceptor.html#org.apache.catalina.tribes.group.interceptors.EncryptInterceptor_Attributes">EncryptInterceptor</a> to encrypt traffic between nodes. This interceptor does not protect against all the risks of running on an untrusted network, particularly DoS attacks. </subsection> </section> <section name="web.xml"> This applies to the default <code>conf/web.xml</code> file, the <code>/WEB-INF/tomcat-web.xml</code> and the <code>/WEB-INF/web.xml</code> files in web applications if they define the components mentioned here. The <a href="default-servlet.html">DefaultServlet</a> is configured with readonly set to <code>true</code>. Changing this to <code>false</code> allows clients to delete or modify static resources on the server and to upload new resources. This should not normally be changed without requiring authentication. The DefaultServlet is configured with listings set to <code>false</code>. This isn't because allowing directory listings is considered unsafe but because generating listings of directories with thousands of files can consume significant CPU leading to a DOS attack. The DefaultServlet is configured with showServerInfo set to <code>true</code>. When the directory listings is enabled the Tomcat version number is included in the response sent to clients. To avoid this, you can explicitly configure a DefaultServlet and set its showServerInfo attribute to false. Alternatively, the version number can be changed by creating the file CATALINA_BASE/lib/org/apache/catalina/util/ServerInfo.properties with content as follows: <source>server.info=Apache Tomcat/<version-major-minor/>.x</source> Modify the values as required. Note that this will also change the version number reported in some of the management tools and may make it harder to determine the real version installed. The CATALINA_HOME/bin/version.bat|sh script will still report the correct version number. The CGI Servlet is disabled by default. If enabled, the debug initialisation parameter should not be set to <code>10</code> or higher on a production system because the debug page is not secure. When using the CGI Servlet on Windows with <code>enableCmdLineArguments</code> enabled, review the setting of <code>cmdLineArgumentsDecoded</code> carefully and ensure that it is appropriate for your environment. The default value is secure. Insecure configurations may expose the server to remote code execution. Further information on the potential risks and mitigations may be found by following the links in the <a href="cgi-howto.html">CGI How To</a>. <a href="config/filter.html">HttpHeaderSecurityFilter</a> can be used to add headers to responses to improve security. If clients access Tomcat directly, then you probably want to enable this filter and all the headers it sets unless your application is already setting them. If Tomcat is accessed via a reverse proxy, then the configuration of this filter needs to be co-ordinated with any headers that the reverse proxy sets. The WebDAV servlet enables edit functionality for web application content. If the WebDAV servlet is enabled, the WebDAV functionality should be appropriately secured. This should include CORS protection if it is expected that any legitimate users will access the web application via a browser. When configuring security constraints, care should be taken if the URL pattern for one or more constraints covers any segment of the URL that becomes part of the pathInfo for a servlet and the servlet uses the pathInfo to identify some other resource (like the default servlet does). In those circumstances, correct application of the security constraint depends on the implementation of the Servlet. All servlets included with Tomcat will behave correctly in this scenario. </section> <section name="Embedded Tomcat"> When using embedded Tomcat, the typical defaults provided by the scripts, server.xml and other configuration are not set. Users of embedded Tomcat may wish to consider the following: <ul> <li>The listeners normally configured in server.xml, including <code>org.apache.catalina.security.SecurityListener</code>, will not be configured by default. They must be explicitly enabled if required.</li> <li>The <code>java.io.tmpdir</code> will not be set (it is normally set to <code>$CATALINA_BASE/temp</code>). This directory is used for various temporary files that may be security sensitive including file uploads and a copy of the web application if anti-resource locking is enabled. Consider setting the <code>java.io.tmpdir</code> system property to an appropriately secured directory.</li> </ul> </section> <section name="Reverse Proxies"> All clients, including reverse proxies, are responsible for the consequences of the data they present to Tomcat. The servlet specification removes path parameters when normalizing requests. HTTP servers do not normally do this. This creates the possibility of a client using a <code>/..;a=b/</code> type sequence in a URI to bypass a security constraint implemented in the reverse proxy. This possibility can be avoided with appropriate configuration such as using the setting <code>mapping=servlet</code> with httpd's mod_proxy. If Tomcat is deployed behind a reverse proxy and that reverse proxy implements one or more security constraints, it is recommended a defense in depth approach is taken and Tomcat is secured as if the reverse proxy was not in use. </section> <section name="General"> BASIC and FORM authentication pass user names and passwords in clear text. Web applications using these authentication mechanisms with clients connecting over untrusted networks should use SSL. The session cookie for a session with an authenticated user is nearly as useful as the user's password to an attacker and should be afforded the same level of protection as the password itself. This usually means authenticating over SSL and continuing to use SSL until the session ends. Tomcat's implementation of the Servlet API's file upload support may use the directory defined by the <code>java.io.tmpdir</code> system property (<code>$CATALINA_BASE/temp</code> by default) to store temporary files. This location should be secured with appropriate file permissions - typically read/write for the Tomcat user and no access for other users. </section> </body> </document>

ttomcat-1778514358873.zip-extract/apache-tomcat-11.0.18-src/webapps/docs/security-howto.xml

ttomcat-1778514358873.zip -extract/apache-tomcat-11.0.18-src/webapps/docs/security-howto.xml