hirondelle.web4j.security
Interface ApplicationFirewall

All Known Implementing Classes:

ApplicationFirewallImpl

public interface ApplicationFirewall

Perform hard validation on each incoming request.

See BuildImpl for important information on how this item is configured. BuildImpl.forApplicationFirewall() returns the configured implementation of this interface.

The main intent of an application firewall is to defend against malicious attacks. As a side effect, an application firewall will often detect obvious bugs during unit testing - usually unexpected request parameters.

The Open Web Application Security Project is a superb resource for learning about web application security. Implementors of this interface are highly recommended to read and use its guidelines.

WEB4J divides validation tasks into hard validation and soft validation. They are distinguished by :

• when they are applied
• their behavior when they fail

"Hard" Validation
Hard validation is applied earlier in processing. A failed hard validation represents either a bug, or a malicious request (a "hack"). When a hard validation fails, a curt and unpolished response can be sent. Hard validations are performed by an ApplicationFirewall, ultimately called by the Controller, as the first step in processing a request, before any Action is executed. Items for hard validation might include :

• overall request size
• parameter names
• parameter values (not business validations, however - see below)
• HTTP headers
• cookies

For request parameters, hard validation must include only those checks whose failure would constitute a bug or a malicious request.

"Soft" Validation
Soft validation is applied later in processing. If a soft validation fails, resulting response pages use a polished presentation. They are applied to items that are input directly by the user, for example the content of a text input control. Invalid values are handled as part of the normal operation of the program. Soft validations are "problem domain" validations, and are usually implemented in a Model Object constructor.

To clarify, here are two examples, using the default implementation of ApplicationFirewallImpl.

Example 1
A select control named Spin submits two fixed values, UP and DOWN. Under normal operation of the program, no other values are expected. In this case, the submitted request parameter should undergo these checks :

Hard validation - must be one of the two values UP or DOWN. This is implemented by simply defining, in the Action that handles this parameter, a single field :

public static final RequestParameter SPIN = RequestParameter.withRegexCheck("Spin", "(UP|DOWN)");

ApplicationFirewallImpl uses such fields to determine, for each Action, how to do hard validation for request parameters. It checks permitted parameter names, and permitted parameter values versus a regular expression.

Soft validation - none. In this case, the hard validation checks the parameter value completely, so there is no further validation to be performed.

Example 2
A text input control named Age accepts any text as input. That text should correspond to an integer in the range 0..130. In this case, the validation is shared between hard validation and soft validation :

Hard validation - can only make a basic sanity check. For instance, a check that the parameter value is not an unreasonable size - under 5K, for instance. This is meant only to detect obvious hacks. It has nothing to do with business logic. That is, this size check does not correspond to the maximum number of characters expected (3), since failure of a hard validation produces a response which should not be seen by the typical user during normal operation of the program. In this case, the field declared in the Action is :

public static final RequestParameter AGE = RequestParameter.withLengthCheck("Age");

(The actual maximum length is set in web.xml.)

Soft validation #1 - first, make sure the user input can be translated into an Integer. This is a very common task, and is implemented by RequestParser, using its various toXXX methods (and, at a higher lever, by ModelFromRequest). When user input cannot be parsed into an Integer, then an error message is displayed to the user. See ConvertParamError.

Soft validation #2 - make sure the Integer returned by the previous validation is in the range 0..150. This is an example of a typical business validation. These are usually implemented in the constructor of a Model Object. Again, if a problem is detected, then an error message is displayed to to the user.

Check and Validator are provided to help you implement soft validations.

Method Summary

void	doHardValidation(Action aAction, RequestParser aRequestParser) Perform hard validation on each HTTP request.

Method Detail

doHardValidation

void doHardValidation(Action aAction,
                      RequestParser aRequestParser)
                      throws BadRequestException

Perform hard validation on each HTTP request.

If a problem is detected, then a BadRequestException is thrown, indicating the standard HTTP status code, as defined in HttpServletRequest. (An error message may also be included, if desired.) The response will then be sent immediately, without further processing, using HttpServletResponse.sendError(int), or HttpServletResponse.sendError(int, java.lang.String) if BadRequestException.getErrorMessage() has content.

Parameters:

aAction - corresponding to this request. If the underlying request is unknown to RequestParser.getWebAction(), then that method will throw a BadRequestException, and this method will not be called.

aRequestParser - provides the raw underlying request, through RequestParser.getRequest();

Throws:

BadRequestException