Fix issue 453

api/src/main/java/jakarta/servlet/ServletContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2021 Oracle and/or its affiliates and others.
+ * Copyright (c) 1997, 2022 Oracle and/or its affiliates and others.
  * All rights reserved.
  * Copyright 2004 The Apache Software Foundation
  *
@@ -207,6 +207,16 @@ public interface ServletContext {
      * <tt>getResourcePaths("/catalog/")</tt> would return <tt>{"/catalog/index.html", "/catalog/products.html",
      * "/catalog/offers/", "/catalog/moreOffers/"}</tt>.
      *
+     * <p>
+     * This method bypasses both implicit (no direct access to WEB-INF or META-INF) and explicit (defined by the web
+     * application) security constraints. Care should be taken both when constructing the path (e.g. avoid unsanitized user
+     * provided data) and when using the result not to create a security vulnerability in the application.
+     * 
+     * <p>
+     * The provided {@code path} parameter is canonicalized as per <a href=
+     * "https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html#uri-path-canonicalization">Servlet 6.0,
+     * 3.5.2</a> before being used to match resources.
+     * 
      * @param path the partial path used to match the resources, which must start with a <tt>/</tt>
      * @return a Set containing the directory listing, or null if there are no resources in the web application whose path
      * begins with the supplied path.
@@ -252,6 +262,11 @@ public interface ServletContext {
      * application) security constraints. Care should be taken both when constructing the path (e.g. avoid unsanitized user
      * provided data) and when using the result not to create a security vulnerability in the application.
      *
+     * <p>
+     * The provided {@code path} parameter is canonicalized as per <a href=
+     * "https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html#uri-path-canonicalization">Servlet 6.0,
+     * 3.5.2</a> before being used to match resources.
+     * 
      * @param path a <code>String</code> specifying the path to the resource
      *
      * @return the resource located at the named path, or <code>null</code> if there is no resource at that path
@@ -286,7 +301,11 @@ public interface ServletContext {
      * application) security constraints. Care should be taken both when constructing the path (e.g. avoid unsanitized user
      * provided data) and when using the result not to create a security vulnerability in the application.
      *
-     *
+     * <p>
+     * The provided {@code path} parameter is canonicalized as per <a href=
+     * "https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html#uri-path-canonicalization">Servlet 6.0,
+     * 3.5.2</a> before being used to match resources.
+     * 
      * @param path a <code>String</code> specifying the path to the resource
      *
      * @return the <code>InputStream</code> returned to the servlet, or <code>null</code> if no resource exists at the
@@ -308,6 +327,16 @@ public interface ServletContext {
      * This method returns <code>null</code> if the <code>ServletContext</code> cannot return a
      * <code>RequestDispatcher</code>.
      *
+     * <p>
+     * This method bypasses both implicit (no direct access to WEB-INF or META-INF) and explicit (defined by the web
+     * application) security constraints. Care should be taken both when constructing the path (e.g. avoid unsanitized user
+     * provided data) and when using the result not to create a security vulnerability in the application.
+     * 
+     * <p>
+     * The provided {@code path} parameter is canonicalized as per <a href=
+     * "https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html#uri-path-canonicalization">Servlet 6.0,
+     * 3.5.2</a> before being used to match resources.
+     * 
      * @param path a <code>String</code> specifying the pathname to the resource
      *
      * @return a <code>RequestDispatcher</code> object that acts as a wrapper for the resource at the specified path, or
@@ -386,6 +415,16 @@ public interface ServletContext {
      * This method returns <code>null</code> if the servlet container is unable to translate the given <i>virtual</i> path
      * to a <i>real</i> path.
      *
+     * <p>
+     * This method bypasses both implicit (no direct access to WEB-INF or META-INF) and explicit (defined by the web
+     * application) security constraints. Care should be taken both when constructing the path (e.g. avoid unsanitized user
+     * provided data) and when using the result not to create a security vulnerability in the application.
+     * 
+     * <p>
+     * The provided {@code path} parameter is canonicalized as per <a href=
+     * "https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html#uri-path-canonicalization">Servlet 6.0,
+     * 3.5.2</a> before being used to match resources.
+     * 
      * @param path the <i>virtual</i> path to be translated to a <i>real</i> path
      *
      * @return the <i>real</i> path, or <tt>null</tt> if the translation cannot be performed

api/src/main/java/jakarta/servlet/http/HttpServletRequest.java

@@ -194,7 +194,7 @@ public interface HttpServletRequest extends ServletRequest {
      * </ul>
      * </p>
      * <p>
-     * The returned object is immutable. Servlet 4.0 compliant implementations must override this method.
+     * The returned object is immutable. Servlet 4.0 onwards compliant implementations must override this method.
      * </p>
      * 
      * @implSpec The default implementation returns a {@code
@@ -253,12 +253,15 @@ public String toString() {
      *
      * @return a <code>String</code> specifying extra path information that comes after the servlet path but before the
      * query string in the request URL; or <code>null</code> if the URL does not have any extra path information. The path
-     * will be canonicalized as per section 3.5 of the specification. This method will not return any encoded characters
-     * unless the container is configured specifically to allow them.
+     * will be canonicalized as per <a href=
+     * "https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html#request-uri-path-processing">Servlet
+     * 6.0, 3.5</a>. This method will not return any encoded characters unless the container is configured specifically to
+     * allow them.
      * @throws IllegalArgumentException In standard configuration, this method will never throw. However, a container may be
-     * configured to not reject some suspicious sequences identified by 3.5.2, furthermore the container may be configured
-     * to allow such paths to only be accessed via safer methods like {@link #getRequestURI()} and to throw
-     * IllegalArgumentException if this method is called for such suspicious paths.
+     * configured to not reject some suspicious sequences identified by <a href=
+     * "https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html#uri-path-canonicalization">Servlet 6.0,
+     * 3.5.2<a/>, furthermore the container may be configured to allow such paths to only be accessed via safer methods like
+     * {@link #getRequestURI()} and to throw IllegalArgumentException if this method is called for such suspicious paths.
      */
     public String getPathInfo();
 
@@ -307,12 +310,15 @@ default public PushBuilder newPushBuilder() {
      * of the application.
      *
      * @return a <code>String</code> specifying the portion of the request URI that indicates the context of the request.
-     * The path will be canonicalized as per section 3.5 of the specification. This method will not return any encoded
-     * characters unless the container is configured specifically to allow them.
+     * The path will be canonicalized as per <a href=
+     * "https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html#request-uri-path-processing">Servlet
+     * 6.0, 3.5</a>. This method will not return any encoded characters unless the container is configured specifically to
+     * allow them.
      * @throws IllegalArgumentException In standard configuration, this method will never throw. However, a container may be
-     * configured to not reject some suspicious sequences identified by 3.5.2, furthermore the container may be configured
-     * to allow such paths to only be accessed via safer methods like {@link #getRequestURI()} and to throw
-     * IllegalArgumentException if this method is called for such suspicious paths.
+     * configured to not reject some suspicious sequences identified by <a href=
+     * "https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html#uri-path-canonicalization">Servlet 6.0,
+     * 3.5.2<a/>, furthermore the container may be configured to allow such paths to only be accessed via safer methods like
+     * {@link #getRequestURI()} and to throw IllegalArgumentException if this method is called for such suspicious paths.
      * @see jakarta.servlet.ServletContext#getContextPath()
      */
     public String getContextPath();
@@ -432,12 +438,15 @@ default public PushBuilder newPushBuilder() {
      *
      * @return a <code>String</code> containing the path of the servlet being called, as specified in the request URL, or an
      * empty string if the servlet used to process the request is matched using the "/*" pattern. The path will be
-     * canonicalized as per section 3.5 of the specification. This method will not return any encoded characters unless the
-     * container is configured specifically to allow them.
+     * canonicalized as per <a href=
+     * "https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html#request-uri-path-processing">Servlet
+     * 6.0, 3.5</a>. This method will not return any encoded characters unless the container is configured specifically to
+     * allow them.
      * @throws IllegalArgumentException In standard configuration, this method will never throw. However, a container may be
-     * configured to not reject some suspicious sequences identified by 3.5.2, furthermore the container may be configured
-     * to allow such paths to only be accessed via safer methods like {@link #getRequestURI()} and to throw
-     * IllegalArgumentException if this method is called for such suspicious paths.
+     * configured to not reject some suspicious sequences identified by <a href=
+     * "https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html#uri-path-canonicalization">Servlet 6.0,
+     * 3.5.2<a/>, furthermore the container may be configured to allow such paths to only be accessed via safer methods like
+     * {@link #getRequestURI()} and to throw IllegalArgumentException if this method is called for such suspicious paths.
      */
     public String getServletPath();
 

spec/src/main/asciidoc/servlet-spec-body.adoc

@@ -8569,6 +8569,10 @@ Clarify the behaviour of `getDateHeader()` and `getIntHeader()` when multiple
 headers with the same name are present in the `HttpServletRequest`. The expected
 behaviour is aligned with `getHeader()`. 
 
+link:https://github.com/eclipse-ee4j/servlet-api/issues/453[Issue 453]::
+Add a security warning and a clarification of canonicalization requirements to
+all `ServletContext` methods that accept a path parameter.
+
 link:https://github.com/eclipse-ee4j/servlet-api/issues/463[Issue 463]::
 Clarify Javadoc for `MultipartConfigElement` and `MultipartConfig` that sizes
 are in bytes.