org.owasp.esapi.interfaces
Interface IValidator

All Known Implementing Classes:

Validator

public interface IValidator

The IValidator interface defines a set of methods for canonicalizing and validating untrusted input. Implementors should feel free to extend this interface to accomodate their own data formats. Rather than throw exceptions, this interface returns boolean results because not all validation problems are security issues. Boolean returns allow developers to handle both valid and invalid results more cleanly than exceptions.

Implementations must adopt a "whitelist" approach to validation where a specific pattern or character set is matched. "Blacklist" approaches that attempt to identify the invalid or disallowed characters are much more likely to allow a bypass with encoding or other tricks.

Since:

June 1, 2007

Author:

Jeff Williams (jeff.williams .at. aspectsecurity.com) Aspect Security

Method Summary

void	assertIsValidHTTPRequest() Validates the current HTTP request by comparing parameters, headers, and cookies to a predefined whitelist of allowed characters.
void	assertIsValidHTTPRequestParameterSet(java.lang.String context, java.util.Set required, java.util.Set optional) Validates that the parameters in the current request contain all required parameters and only optional ones in addition.
void	assertValidFileUpload(java.lang.String context, java.lang.String filepath, java.lang.String filename, byte[] content, int maxBytes, boolean allowNull) Validates the filepath, filename, and content of a file.
java.lang.String	getValidCreditCard(java.lang.String context, java.lang.String input, boolean allowNull) Returns a canonicalized and validated credit card number as a String.
java.util.Date	getValidDate(java.lang.String context, java.lang.String input, java.text.DateFormat format, boolean allowNull) Returns a valid date as a Date.
java.lang.String	getValidDirectoryPath(java.lang.String context, java.lang.String input, boolean allowNull) Returns a canonicalized and validated directory path as a String.
java.lang.Double	getValidDouble(java.lang.String context, java.lang.String input, double minValue, double maxValue, boolean allowNull) Returns a validated real number as a double.
byte[]	getValidFileContent(java.lang.String context, byte[] input, int maxBytes, boolean allowNull) Returns validated file content as a byte array.
java.lang.String	getValidFileName(java.lang.String context, java.lang.String input, boolean allowNull) Returns a canonicalized and validated file name as a String.
java.lang.String	getValidInput(java.lang.String context, java.lang.String input, java.lang.String type, int maxLength, boolean allowNull) Returns canonicalized and validated input as a String.
java.lang.Integer	getValidInteger(java.lang.String context, java.lang.String input, int minValue, int maxValue, boolean allowNull) Returns a validated integer as an int.
java.lang.String	getValidListItem(java.lang.String context, java.lang.String input, java.util.List list) Returns the list item that exactly matches the canonicalized input.
java.lang.Double	getValidNumber(java.lang.String context, java.lang.String input, long minValue, long maxValue, boolean allowNull) Returns a validated number as a double.
byte[]	getValidPrintable(java.lang.String context, byte[] input, int maxLength, boolean allowNull) Returns canonicalized and validated printable characters as a byte array.
java.lang.String	getValidPrintable(java.lang.String context, java.lang.String input, int maxLength, boolean allowNull) Returns canonicalized and validated printable characters as a String.
java.lang.String	getValidRedirectLocation(java.lang.String context, java.lang.String input, boolean allowNull) Returns a canonicalized and validated redirect location as a String.
java.lang.String	getValidSafeHTML(java.lang.String context, java.lang.String input, int maxLength, boolean allowNull) Returns canonicalized and validated "safe" HTML.
boolean	isValidCreditCard(java.lang.String context, java.lang.String input, boolean allowNull) Returns true if input is a valid credit card.
boolean	isValidDate(java.lang.String context, java.lang.String input, java.text.DateFormat format, boolean allowNull) Returns true if input is a valid date according to the specified date format.
boolean	isValidDirectoryPath(java.lang.String context, java.lang.String input, boolean allowNull) Returns true if input is a valid directory path.
boolean	isValidDouble(java.lang.String context, java.lang.String input, double minValue, double maxValue, boolean allowNull) Returns true if input is a valid double.
boolean	isValidFileContent(java.lang.String context, byte[] input, int maxBytes, boolean allowNull) Returns true if input is valid file content.
boolean	isValidFileName(java.lang.String context, java.lang.String input, boolean allowNull) Returns true if input is a valid file name.
boolean	isValidFileUpload(java.lang.String context, java.lang.String filepath, java.lang.String filename, byte[] content, int maxBytes, boolean allowNull) Returns true if a file upload has a valid name, path, and content.
boolean	isValidHTTPRequest() Validate the current HTTP request by comparing parameters, headers, and cookies to a predefined whitelist of allowed characters.
boolean	isValidHTTPRequestParameterSet(java.lang.String context, java.util.Set required, java.util.Set optional) Returns true if the parameters in the current request contain all required parameters and only optional ones in addition.
boolean	isValidInput(java.lang.String context, java.lang.String input, java.lang.String type, int maxLength, boolean allowNull) Returns true if input is valid according to the specified type.
boolean	isValidInteger(java.lang.String context, java.lang.String input, int minValue, int maxValue, boolean allowNull) Returns true if input is a valid integer.
boolean	isValidListItem(java.lang.String context, java.lang.String input, java.util.List list) Returns true if input is a valid list item.
boolean	isValidNumber(java.lang.String context, java.lang.String input, long minValue, long maxValue, boolean allowNull) Returns true if input is a valid number.
boolean	isValidPrintable(java.lang.String context, byte[] input, int maxLength, boolean allowNull) Returns true if input is valid printable ASCII characters.
boolean	isValidPrintable(java.lang.String context, java.lang.String input, int maxLength, boolean allowNull) Returns true if input is valid printable ASCII characters (32-126).
boolean	isValidRedirectLocation(java.lang.String context, java.lang.String input, boolean allowNull) Returns true if input is a valid redirect location.
boolean	isValidSafeHTML(java.lang.String context, java.lang.String input, int maxLength, boolean allowNull) Returns true if input is "safe" HTML.
java.lang.String	safeReadLine(java.io.InputStream inputStream, int maxLength) Reads from an input stream until end-of-line or a maximum number of characters.

Method Detail

isValidInput

public boolean isValidInput(java.lang.String context,
                            java.lang.String input,
                            java.lang.String type,
                            int maxLength,
                            boolean allowNull)
                     throws IntrusionException

Returns true if input is valid according to the specified type. The type parameter must be the name of a defined type in the ESAPI configuration or a valid regular expression. Implementers should take care to make the type storage simple to understand and configure.

Parameters:

context - A descriptive name for the field to validate. This is used for error facing validation messages and element identification.

input - The actual user input data to validate.

type - The regular expression name while maps to the actual regular expression from "ESAPI.properties".

maxLength - The maximum post-canonicalized String length allowed.

allowNull - If allowNull is true then a input that is NULL or an empty string will be legal. If allowNull is false then NULL or an empty String will throw a ValidationException.

Returns:

The canonicalized user input.

Throws:

IntrusionException

getValidInput

public java.lang.String getValidInput(java.lang.String context,
                                      java.lang.String input,
                                      java.lang.String type,
                                      int maxLength,
                                      boolean allowNull)
                               throws ValidationException,
                                      IntrusionException

Returns canonicalized and validated input as a String. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Parameters:

context - A descriptive name for the field to validate. This is used for error facing validation messages and element identification.

input - The actual user input data to validate.

type - The regular expression name while maps to the actual regular expression from "ESAPI.properties".

maxLength - The maximum post-canonicalized String length allowed.

allowNull - If allowNull is true then a input that is NULL or an empty string will be legal. If allowNull is false then NULL or an empty String will throw a ValidationException.

Returns:

The canonicalized user input.

Throws:

ValidationException

IntrusionException

isValidDate

public boolean isValidDate(java.lang.String context,
                           java.lang.String input,
                           java.text.DateFormat format,
                           boolean allowNull)
                    throws IntrusionException

Returns true if input is a valid date according to the specified date format.

Throws:

IntrusionException

getValidDate

public java.util.Date getValidDate(java.lang.String context,
                                   java.lang.String input,
                                   java.text.DateFormat format,
                                   boolean allowNull)
                            throws ValidationException,
                                   IntrusionException

Returns a valid date as a Date. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Throws:

ValidationException

IntrusionException

isValidSafeHTML

public boolean isValidSafeHTML(java.lang.String context,
                               java.lang.String input,
                               int maxLength,
                               boolean allowNull)
                        throws IntrusionException

Returns true if input is "safe" HTML. Implementors should reference the OWASP AntiSamy project for ideas on how to do HTML validation in a whitelist way, as this is an extremely difficult problem.

Throws:

IntrusionException

getValidSafeHTML

public java.lang.String getValidSafeHTML(java.lang.String context,
                                         java.lang.String input,
                                         int maxLength,
                                         boolean allowNull)
                                  throws ValidationException

Returns canonicalized and validated "safe" HTML. Implementors should reference the OWASP AntiSamy project for ideas on how to do HTML validation in a whitelist way, as this is an extremely difficult problem.

Throws:

ValidationException

isValidCreditCard

public boolean isValidCreditCard(java.lang.String context,
                                 java.lang.String input,
                                 boolean allowNull)
                          throws IntrusionException

Returns true if input is a valid credit card. Maxlength is mandated by valid credit card type.

Throws:

IntrusionException

getValidCreditCard

public java.lang.String getValidCreditCard(java.lang.String context,
                                           java.lang.String input,
                                           boolean allowNull)
                                    throws ValidationException,
                                           IntrusionException

Returns a canonicalized and validated credit card number as a String. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Throws:

ValidationException

IntrusionException

isValidDirectoryPath

public boolean isValidDirectoryPath(java.lang.String context,
                                    java.lang.String input,
                                    boolean allowNull)
                             throws IntrusionException

Returns true if input is a valid directory path.

Throws:

IntrusionException

getValidDirectoryPath

public java.lang.String getValidDirectoryPath(java.lang.String context,
                                              java.lang.String input,
                                              boolean allowNull)
                                       throws ValidationException,
                                              IntrusionException

Returns a canonicalized and validated directory path as a String. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Throws:

ValidationException

IntrusionException

isValidFileName

public boolean isValidFileName(java.lang.String context,
                               java.lang.String input,
                               boolean allowNull)
                        throws IntrusionException

Returns true if input is a valid file name.

Throws:

IntrusionException

getValidFileName

public java.lang.String getValidFileName(java.lang.String context,
                                         java.lang.String input,
                                         boolean allowNull)
                                  throws ValidationException,
                                         IntrusionException

Returns a canonicalized and validated file name as a String. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Throws:

ValidationException

IntrusionException

isValidNumber

public boolean isValidNumber(java.lang.String context,
                             java.lang.String input,
                             long minValue,
                             long maxValue,
                             boolean allowNull)
                      throws IntrusionException

Returns true if input is a valid number.

Throws:

IntrusionException

getValidNumber

public java.lang.Double getValidNumber(java.lang.String context,
                                       java.lang.String input,
                                       long minValue,
                                       long maxValue,
                                       boolean allowNull)
                                throws ValidationException,
                                       IntrusionException

Returns a validated number as a double. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Throws:

ValidationException

IntrusionException

isValidInteger

public boolean isValidInteger(java.lang.String context,
                              java.lang.String input,
                              int minValue,
                              int maxValue,
                              boolean allowNull)
                       throws IntrusionException

Returns true if input is a valid integer.

Throws:

IntrusionException

getValidInteger

public java.lang.Integer getValidInteger(java.lang.String context,
                                         java.lang.String input,
                                         int minValue,
                                         int maxValue,
                                         boolean allowNull)
                                  throws ValidationException,
                                         IntrusionException

Returns a validated integer as an int. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Throws:

ValidationException

IntrusionException

isValidDouble

public boolean isValidDouble(java.lang.String context,
                             java.lang.String input,
                             double minValue,
                             double maxValue,
                             boolean allowNull)
                      throws IntrusionException

Returns true if input is a valid double.

Throws:

IntrusionException

getValidDouble

public java.lang.Double getValidDouble(java.lang.String context,
                                       java.lang.String input,
                                       double minValue,
                                       double maxValue,
                                       boolean allowNull)
                                throws ValidationException,
                                       IntrusionException

Returns a validated real number as a double. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Throws:

ValidationException

IntrusionException

isValidFileContent

public boolean isValidFileContent(java.lang.String context,
                                  byte[] input,
                                  int maxBytes,
                                  boolean allowNull)
                           throws IntrusionException

Returns true if input is valid file content.

Throws:

IntrusionException

getValidFileContent

public byte[] getValidFileContent(java.lang.String context,
                                  byte[] input,
                                  int maxBytes,
                                  boolean allowNull)
                           throws ValidationException,
                                  IntrusionException

Returns validated file content as a byte array. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Throws:

ValidationException

IntrusionException

isValidFileUpload

public boolean isValidFileUpload(java.lang.String context,
                                 java.lang.String filepath,
                                 java.lang.String filename,
                                 byte[] content,
                                 int maxBytes,
                                 boolean allowNull)
                          throws IntrusionException

Returns true if a file upload has a valid name, path, and content.

Throws:

IntrusionException

assertValidFileUpload

public void assertValidFileUpload(java.lang.String context,
                                  java.lang.String filepath,
                                  java.lang.String filename,
                                  byte[] content,
                                  int maxBytes,
                                  boolean allowNull)
                           throws ValidationException,
                                  IntrusionException

Validates the filepath, filename, and content of a file. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Throws:

ValidationException

IntrusionException

isValidHTTPRequest

public boolean isValidHTTPRequest()
                           throws IntrusionException

Validate the current HTTP request by comparing parameters, headers, and cookies to a predefined whitelist of allowed characters. See the SecurityConfiguration class for the methods to retrieve the whitelists.

Throws:

IntrusionException

assertIsValidHTTPRequest

public void assertIsValidHTTPRequest()
                              throws ValidationException,
                                     IntrusionException

Validates the current HTTP request by comparing parameters, headers, and cookies to a predefined whitelist of allowed characters. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Throws:

ValidationException

IntrusionException

isValidListItem

public boolean isValidListItem(java.lang.String context,
                               java.lang.String input,
                               java.util.List list)
                        throws IntrusionException

Returns true if input is a valid list item.

Throws:

IntrusionException

getValidListItem

public java.lang.String getValidListItem(java.lang.String context,
                                         java.lang.String input,
                                         java.util.List list)
                                  throws ValidationException,
                                         IntrusionException

Returns the list item that exactly matches the canonicalized input. Invalid or non-matching input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Throws:

ValidationException

IntrusionException

isValidHTTPRequestParameterSet

public boolean isValidHTTPRequestParameterSet(java.lang.String context,
                                              java.util.Set required,
                                              java.util.Set optional)
                                       throws IntrusionException

Returns true if the parameters in the current request contain all required parameters and only optional ones in addition.

Throws:

IntrusionException

assertIsValidHTTPRequestParameterSet

public void assertIsValidHTTPRequestParameterSet(java.lang.String context,
                                                 java.util.Set required,
                                                 java.util.Set optional)
                                          throws ValidationException,
                                                 IntrusionException

Validates that the parameters in the current request contain all required parameters and only optional ones in addition. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Throws:

ValidationException

IntrusionException

isValidPrintable

public boolean isValidPrintable(java.lang.String context,
                                byte[] input,
                                int maxLength,
                                boolean allowNull)
                         throws IntrusionException

Returns true if input is valid printable ASCII characters.

Throws:

IntrusionException

getValidPrintable

public byte[] getValidPrintable(java.lang.String context,
                                byte[] input,
                                int maxLength,
                                boolean allowNull)
                         throws ValidationException

Returns canonicalized and validated printable characters as a byte array. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Throws:

ValidationException

isValidPrintable

public boolean isValidPrintable(java.lang.String context,
                                java.lang.String input,
                                int maxLength,
                                boolean allowNull)
                         throws IntrusionException

Returns true if input is valid printable ASCII characters (32-126).

Throws:

IntrusionException

getValidPrintable

public java.lang.String getValidPrintable(java.lang.String context,
                                          java.lang.String input,
                                          int maxLength,
                                          boolean allowNull)
                                   throws ValidationException

Returns canonicalized and validated printable characters as a String. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Throws:

ValidationException

isValidRedirectLocation

public boolean isValidRedirectLocation(java.lang.String context,
                                       java.lang.String input,
                                       boolean allowNull)
                                throws IntrusionException

Returns true if input is a valid redirect location.

Throws:

IntrusionException

getValidRedirectLocation

public java.lang.String getValidRedirectLocation(java.lang.String context,
                                                 java.lang.String input,
                                                 boolean allowNull)
                                          throws ValidationException

Returns a canonicalized and validated redirect location as a String. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Throws:

ValidationException

safeReadLine

public java.lang.String safeReadLine(java.io.InputStream inputStream,
                                     int maxLength)
                              throws ValidationException

Reads from an input stream until end-of-line or a maximum number of characters. This method protects against the inherent denial of service attack in reading until the end of a line. If an attacker doesn't ever send a newline character, then a normal input stream reader will read until all memory is exhausted and the platform throws an OutOfMemoryError and probably terminates.

Throws:

ValidationException