Use HttpFirewall Bean

Fixes: gh-5022

config/src/main/java/org/springframework/security/config/annotation/web/builders/WebSecurity.java

@@ -25,6 +25,7 @@ import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 
 import org.springframework.beans.BeansException;
+import org.springframework.beans.factory.NoSuchBeanDefinitionException;
 import org.springframework.context.ApplicationContext;
 import org.springframework.context.ApplicationContextAware;
 import org.springframework.http.HttpMethod;
@@ -382,5 +383,8 @@ public final class WebSecurity extends
 		this.defaultWebSecurityExpressionHandler
 				.setApplicationContext(applicationContext);
 		this.ignoredRequestRegistry = new IgnoredRequestConfigurer(applicationContext);
+		try {
+			this.httpFirewall = applicationContext.getBean(HttpFirewall.class);
+		} catch(NoSuchBeanDefinitionException e) {}
 	}
 }

config/src/test/groovy/org/springframework/security/config/annotation/web/configurers/NamespaceHttpFirewallTests.groovy

@@ -13,7 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.springframework.security.config.annotation.web.configurers;
+package org.springframework.security.config.annotation.web.configurers
+
+import org.springframework.context.annotation.Bean;
 
 import javax.servlet.http.HttpServletRequest
 import javax.servlet.http.HttpServletResponse
@@ -89,6 +91,28 @@ public class NamespaceHttpFirewallTests extends BaseSpringSpec {
 		}
 	}
 
+	def "http-firewall bean"() {
+		setup:
+		loadConfig(CustomHttpFirewallBeanConfig)
+		springSecurityFilterChain = context.getBean(FilterChainProxy)
+		request.setParameter("deny", "true")
+		when:
+		springSecurityFilterChain.doFilter(request,response,chain)
+		then: "the custom firewall is used"
+		thrown(RequestRejectedException)
+	}
+
+	@Configuration
+	static class CustomHttpFirewallBeanConfig extends BaseWebConfig {
+		@Override
+		protected void configure(HttpSecurity http) { }
+
+		@Bean
+		CustomHttpFirewall firewall() {
+			return new CustomHttpFirewall();
+		}
+	}
+
 	static class CustomHttpFirewall extends DefaultHttpFirewall {
 
 		@Override

docs/manual/src/docs/asciidoc/index.adoc

@@ -3416,6 +3416,32 @@ Security defined at the service layer is much more robust and harder to bypass,
 
 The `HttpFirewall` also prevents https://www.owasp.org/index.php/HTTP_Response_Splitting[HTTP Response Splitting] by rejecting new line characters in the HTTP Response headers.
 
+By default the `StrictHttpFirewall` is used.
+This implementation rejects requests that appear to be malicious.
+If it is too strict for your needs, then you can customize what types of requests are rejected.
+However, it is important that you do so knowing that this can open your application up to attacks.
+For example, if you wish to leverage Spring MVC's Matrix Variables, the following configuration could be used in XML:
+
+[source,xml]
+----
+<b:bean id="httpFirewall"
+      class="org.springframework.security.web.firewall.StrictHttpFirewall"
+      p:allowSemicolon="true"/>
+
+<http-firewall ref="httpFirewall"/>
+----
+
+The same thing can be achieved with Java Configuration by exposing a `StrictHttpFirewall` bean.
+
+[source,java]
+----
+@Bean
+public StrictHttpFirewall httpFirewall() {
+    StrictHttpFirewall firewall = new StrictHttpFirewall();
+    firewall.setAllowSemicolon(true);
+    return firewall;
+}
+----
 
 === Use with other Filter-Based Frameworks
 If you're using some other framework that is also filter-based, then you need to make sure that the Spring Security filters come first. This enables the `SecurityContextHolder` to be populated in time for use by the other filters. Examples are the use of SiteMesh to decorate your web pages or a web framework like Wicket which uses a filter to handle its requests.