From cee2ea9c609fd3b0b95d1c242c9d1843f71d7677 Mon Sep 17 00:00:00 2001
From: Rob Winch <rwinch@users.noreply.github.com>
Date: Thu, 15 Feb 2018 17:12:55 -0600
Subject: [PATCH] Polish StrictHttpFirewall Javadoc

Also cleanup DefaultHttpFirewall Javadoc

Issue: gh-5009
---
 .../security/web/firewall/DefaultHttpFirewall.java        | 8 ++++++--
 .../security/web/firewall/StrictHttpFirewall.java         | 5 +++--
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/web/src/main/java/org/springframework/security/web/firewall/DefaultHttpFirewall.java b/web/src/main/java/org/springframework/security/web/firewall/DefaultHttpFirewall.java
index 304fcff212..6f69ec428e 100644
--- a/web/src/main/java/org/springframework/security/web/firewall/DefaultHttpFirewall.java
+++ b/web/src/main/java/org/springframework/security/web/firewall/DefaultHttpFirewall.java
@@ -19,6 +19,11 @@ import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
 /**
+ * <p>
+ * User's should consider using {@link StrictHttpFirewall} because rather than trying to
+ * sanitize a malicious URL it rejects the malicious URL providing better security
+ * guarantees.
+ * <p>
  * Default implementation which wraps requests in order to provide consistent
  * values of the {@code servletPath} and {@code pathInfo}, which do not contain
  * path parameters (as defined in
@@ -37,10 +42,9 @@ import javax.servlet.http.HttpServletResponse;
  * containers normalize the paths before performing the servlet-mapping, but
  * again this is not guaranteed by the servlet spec.
  *
- * @deprecated Use {@link StrictHttpFirewall} instead
  * @author Luke Taylor
+ * @see StrictHttpFirewall
  */
-@Deprecated
 public class DefaultHttpFirewall implements HttpFirewall {
 	private boolean allowUrlEncodedSlash;
 
diff --git a/web/src/main/java/org/springframework/security/web/firewall/StrictHttpFirewall.java b/web/src/main/java/org/springframework/security/web/firewall/StrictHttpFirewall.java
index 7dd508aa2f..d3049cfbc7 100644
--- a/web/src/main/java/org/springframework/security/web/firewall/StrictHttpFirewall.java
+++ b/web/src/main/java/org/springframework/security/web/firewall/StrictHttpFirewall.java
@@ -95,8 +95,9 @@ public class StrictHttpFirewall implements HttpFirewall {
 	/**
 	 * <p>
 	 * Determines if semicolon is allowed in the URL (i.e. matrix variables). The default
-	 * is to disable this behavior because it is a common way of attempting to bypass URL
-	 * based security.
+	 * is to disable this behavior because it is a common way of attempting to perform
+	 * <a href="https://www.owasp.org/index.php/Reflected_File_Download">Reflected File Download Attacks</a>.
+	 * It is also the source of many exploits which bypass URL based security.
 	 * </p>
 	 * <p>For example, the following CVEs are a subset of the issues related
 	 * to ambiguities in the Servlet Specification on how to treat semicolons that