org.owasp.esapi
Interface Validator

All Known Implementing Classes:

DefaultValidator

public interface Validator

The Validator interface defines a set of methods for canonicalizing and validating untrusted input. Implementors should feel free to extend this interface to accommodate 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	addRule(ValidationRule rule)
void	assertValidFileUpload(java.lang.String context, java.lang.String filepath, java.lang.String filename, java.io.File parent, byte[] content, int maxBytes, java.util.List<java.lang.String> allowedExtensions, boolean allowNull) Validates the filepath, filename, and content of a file.
void	assertValidFileUpload(java.lang.String context, java.lang.String filepath, java.lang.String filename, java.io.File parent, byte[] content, int maxBytes, java.util.List<java.lang.String> allowedExtensions, boolean allowNull, ValidationErrorList errorList) Calls getValidFileUpload with the supplied errorList to capture ValidationExceptions
void	assertValidHTTPRequestParameterSet(java.lang.String context, javax.servlet.http.HttpServletRequest request, java.util.Set<java.lang.String> required, java.util.Set<java.lang.String> optional) Validates that the parameters in the current request contain all required parameters and only optional ones in addition.
void	assertValidHTTPRequestParameterSet(java.lang.String context, javax.servlet.http.HttpServletRequest request, java.util.Set<java.lang.String> required, java.util.Set<java.lang.String> optional, ValidationErrorList errorList) Calls getValidHTTPRequestParameterSet with the supplied errorList to capture ValidationExceptions
ValidationRule	getRule(java.lang.String name)
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.lang.String	getValidCreditCard(java.lang.String context, java.lang.String input, boolean allowNull, ValidationErrorList errorList) Calls getValidCreditCard with the supplied errorList to capture ValidationExceptions
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.util.Date	getValidDate(java.lang.String context, java.lang.String input, java.text.DateFormat format, boolean allowNull, ValidationErrorList errorList) Calls getValidDate with the supplied errorList to capture ValidationExceptions
java.lang.String	getValidDirectoryPath(java.lang.String context, java.lang.String input, java.io.File parent, boolean allowNull) Returns a canonicalized and validated directory path as a String, provided that the input maps to an existing directory that is an existing subdirectory (at any level) of the specified parent.
java.lang.String	getValidDirectoryPath(java.lang.String context, java.lang.String input, java.io.File parent, boolean allowNull, ValidationErrorList errorList) Calls getValidDirectoryPath with the supplied errorList to capture ValidationExceptions
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.
java.lang.Double	getValidDouble(java.lang.String context, java.lang.String input, double minValue, double maxValue, boolean allowNull, ValidationErrorList errorList) Calls getValidDouble with the supplied errorList to capture ValidationExceptions
byte[]	getValidFileContent(java.lang.String context, byte[] input, int maxBytes, boolean allowNull) Returns validated file content as a byte array.
byte[]	getValidFileContent(java.lang.String context, byte[] input, int maxBytes, boolean allowNull, ValidationErrorList errorList) Calls getValidFileContent with the supplied errorList to capture ValidationExceptions
java.lang.String	getValidFileName(java.lang.String context, java.lang.String input, java.util.List<java.lang.String> allowedExtensions, boolean allowNull) Returns a canonicalized and validated file name as a String.
java.lang.String	getValidFileName(java.lang.String context, java.lang.String input, java.util.List<java.lang.String> allowedExtensions, boolean allowNull, ValidationErrorList errorList) Calls getValidFileName with the supplied errorList to capture ValidationExceptions
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.String	getValidInput(java.lang.String context, java.lang.String input, java.lang.String type, int maxLength, boolean allowNull, boolean canonicalize) Returns validated input as a String with optional canonicalization.
java.lang.String	getValidInput(java.lang.String context, java.lang.String input, java.lang.String type, int maxLength, boolean allowNull, boolean canonicalize, ValidationErrorList errorList) Calls getValidInput with the supplied errorList to capture ValidationExceptions
java.lang.String	getValidInput(java.lang.String context, java.lang.String input, java.lang.String type, int maxLength, boolean allowNull, ValidationErrorList errorList) Calls getValidInput with the supplied errorList to capture ValidationExceptions
java.lang.Integer	getValidInteger(java.lang.String context, java.lang.String input, int minValue, int maxValue, boolean allowNull) Returns a validated integer.
java.lang.Integer	getValidInteger(java.lang.String context, java.lang.String input, int minValue, int maxValue, boolean allowNull, ValidationErrorList errorList) Calls getValidInteger with the supplied errorList to capture ValidationExceptions
java.lang.String	getValidListItem(java.lang.String context, java.lang.String input, java.util.List<java.lang.String> list) Returns the list item that exactly matches the canonicalized input.
java.lang.String	getValidListItem(java.lang.String context, java.lang.String input, java.util.List<java.lang.String> list, ValidationErrorList errorList) Calls getValidListItem with the supplied errorList to capture ValidationExceptions
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 within the range of minValue to maxValue.
java.lang.Double	getValidNumber(java.lang.String context, java.lang.String input, long minValue, long maxValue, boolean allowNull, ValidationErrorList errorList) Calls getValidSafeHTML with the supplied errorList to capture ValidationExceptions
char[]	getValidPrintable(java.lang.String context, char[] input, int maxLength, boolean allowNull) Returns canonicalized and validated printable characters as a byte array.
char[]	getValidPrintable(java.lang.String context, char[] input, int maxLength, boolean allowNull, ValidationErrorList errorList) Calls getValidPrintable with the supplied errorList to capture ValidationExceptions
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	getValidPrintable(java.lang.String context, java.lang.String input, int maxLength, boolean allowNull, ValidationErrorList errorList) Calls getValidPrintable with the supplied errorList to capture ValidationExceptions
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	getValidRedirectLocation(java.lang.String context, java.lang.String input, boolean allowNull, ValidationErrorList errorList) Calls getValidRedirectLocation with the supplied errorList to capture ValidationExceptions
java.lang.String	getValidSafeHTML(java.lang.String context, java.lang.String input, int maxLength, boolean allowNull) Returns canonicalized and validated "safe" HTML that does not contain unwanted scripts in the body, attributes, CSS, URLs, or anywhere else.
java.lang.String	getValidSafeHTML(java.lang.String context, java.lang.String input, int maxLength, boolean allowNull, ValidationErrorList errorList) Calls getValidSafeHTML with the supplied errorList to capture ValidationExceptions
boolean	isValidCreditCard(java.lang.String context, java.lang.String input, boolean allowNull) Calls getValidCreditCard and returns true if no exceptions are thrown.
boolean	isValidCreditCard(java.lang.String context, java.lang.String input, boolean allowNull, ValidationErrorList errorList) Calls getValidCreditCard and returns true if no exceptions are thrown.
boolean	isValidDate(java.lang.String context, java.lang.String input, java.text.DateFormat format, boolean allowNull) Calls isValidDate and returns true if no exceptions are thrown.
boolean	isValidDate(java.lang.String context, java.lang.String input, java.text.DateFormat format, boolean allowNull, ValidationErrorList errorList) Calls isValidDate and returns true if no exceptions are thrown.
boolean	isValidDirectoryPath(java.lang.String context, java.lang.String input, java.io.File parent, boolean allowNull) Calls getValidDirectoryPath and returns true if no exceptions are thrown.
boolean	isValidDirectoryPath(java.lang.String context, java.lang.String input, java.io.File parent, boolean allowNull, ValidationErrorList errorList) Calls getValidDirectoryPath and returns true if no exceptions are thrown.
boolean	isValidDouble(java.lang.String context, java.lang.String input, double minValue, double maxValue, boolean allowNull) Calls getValidDouble and returns true if no exceptions are thrown.
boolean	isValidDouble(java.lang.String context, java.lang.String input, double minValue, double maxValue, boolean allowNull, ValidationErrorList errorList) Calls getValidDouble and returns true if no exceptions are thrown.
boolean	isValidFileContent(java.lang.String context, byte[] input, int maxBytes, boolean allowNull) Calls getValidFileContent and returns true if no exceptions are thrown.
boolean	isValidFileContent(java.lang.String context, byte[] input, int maxBytes, boolean allowNull, ValidationErrorList errorList) Calls getValidFileContent and returns true if no exceptions are thrown.
boolean	isValidFileName(java.lang.String context, java.lang.String input, boolean allowNull) Calls getValidFileName with the default list of allowedExtensions
boolean	isValidFileName(java.lang.String context, java.lang.String input, boolean allowNull, ValidationErrorList errorList) Calls getValidFileName with the default list of allowedExtensions
boolean	isValidFileName(java.lang.String context, java.lang.String input, java.util.List<java.lang.String> allowedExtensions, boolean allowNull) Calls getValidFileName and returns true if no exceptions are thrown.
boolean	isValidFileName(java.lang.String context, java.lang.String input, java.util.List<java.lang.String> allowedExtensions, boolean allowNull, ValidationErrorList errorList) Calls getValidFileName and returns true if no exceptions are thrown.
boolean	isValidFileUpload(java.lang.String context, java.lang.String filepath, java.lang.String filename, java.io.File parent, byte[] content, int maxBytes, boolean allowNull) Calls getValidFileUpload and returns true if no exceptions are thrown.
boolean	isValidFileUpload(java.lang.String context, java.lang.String filepath, java.lang.String filename, java.io.File parent, byte[] content, int maxBytes, boolean allowNull, ValidationErrorList errorList) Calls getValidFileUpload and returns true if no exceptions are thrown.
boolean	isValidHTTPRequestParameterSet(java.lang.String context, javax.servlet.http.HttpServletRequest request, java.util.Set<java.lang.String> required, java.util.Set<java.lang.String> optional) Calls assertValidHTTPRequestParameterSet and returns true if no exceptions are thrown.
boolean	isValidHTTPRequestParameterSet(java.lang.String context, javax.servlet.http.HttpServletRequest request, java.util.Set<java.lang.String> required, java.util.Set<java.lang.String> optional, ValidationErrorList errorList) Calls assertValidHTTPRequestParameterSet and returns true if no exceptions are thrown.
boolean	isValidInput(java.lang.String context, java.lang.String input, java.lang.String type, int maxLength, boolean allowNull) Calls isValidInput and returns true if no exceptions are thrown.
boolean	isValidInput(java.lang.String context, java.lang.String input, java.lang.String type, int maxLength, boolean allowNull, boolean canonicalize) Calls isValidInput and returns true if no exceptions are thrown.
boolean	isValidInput(java.lang.String context, java.lang.String input, java.lang.String type, int maxLength, boolean allowNull, boolean canonicalize, ValidationErrorList errorList) Calls isValidInput and returns true if no exceptions are thrown.
boolean	isValidInput(java.lang.String context, java.lang.String input, java.lang.String type, int maxLength, boolean allowNull, ValidationErrorList errorList) Calls isValidInput and returns true if no exceptions are thrown.
boolean	isValidInteger(java.lang.String context, java.lang.String input, int minValue, int maxValue, boolean allowNull) Calls getValidInteger and returns true if no exceptions are thrown.
boolean	isValidInteger(java.lang.String context, java.lang.String input, int minValue, int maxValue, boolean allowNull, ValidationErrorList errorList) Calls getValidInteger and returns true if no exceptions are thrown.
boolean	isValidListItem(java.lang.String context, java.lang.String input, java.util.List<java.lang.String> list) Calls getValidListItem and returns true if no exceptions are thrown.
boolean	isValidListItem(java.lang.String context, java.lang.String input, java.util.List<java.lang.String> list, ValidationErrorList errorList) Calls getValidListItem and returns true if no exceptions are thrown.
boolean	isValidNumber(java.lang.String context, java.lang.String input, long minValue, long maxValue, boolean allowNull) Calls getValidNumber and returns true if no exceptions are thrown.
boolean	isValidNumber(java.lang.String context, java.lang.String input, long minValue, long maxValue, boolean allowNull, ValidationErrorList errorList) Calls getValidNumber and returns true if no exceptions are thrown.
boolean	isValidPrintable(java.lang.String context, char[] input, int maxLength, boolean allowNull) Calls getValidPrintable and returns true if no exceptions are thrown.
boolean	isValidPrintable(java.lang.String context, char[] input, int maxLength, boolean allowNull, ValidationErrorList errorList) Calls getValidPrintable and returns true if no exceptions are thrown.
boolean	isValidPrintable(java.lang.String context, java.lang.String input, int maxLength, boolean allowNull) Calls getValidPrintable and returns true if no exceptions are thrown.
boolean	isValidPrintable(java.lang.String context, java.lang.String input, int maxLength, boolean allowNull, ValidationErrorList errorList) Calls getValidPrintable and returns true if no exceptions are thrown.
boolean	isValidRedirectLocation(java.lang.String context, java.lang.String input, boolean allowNull) Calls getValidRedirectLocation and returns true if no exceptions are thrown.
boolean	isValidRedirectLocation(java.lang.String context, java.lang.String input, boolean allowNull, ValidationErrorList errorList) Calls getValidRedirectLocation and returns true if no exceptions are thrown.
boolean	isValidSafeHTML(java.lang.String context, java.lang.String input, int maxLength, boolean allowNull) Calls getValidSafeHTML and returns true if no exceptions are thrown.
boolean	isValidSafeHTML(java.lang.String context, java.lang.String input, int maxLength, boolean allowNull, ValidationErrorList errorList) Calls getValidSafeHTML and returns true if no exceptions are thrown.
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

addRule

void addRule(ValidationRule rule)

getRule

ValidationRule getRule(java.lang.String name)

isValidInput

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

Calls isValidInput and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidInput

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

Calls isValidInput and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidInput

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

Calls isValidInput and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidInput

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

Calls isValidInput and returns true if no exceptions are thrown.

Throws:

IntrusionException

getValidInput

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 of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

input - The actual user input data to validate.

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

maxLength - The maximum post-canonicalized String length allowed.

allowNull - If allowNull is true then an 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

getValidInput

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

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

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

input - The actual user input data to validate.

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

maxLength - The maximum post-canonicalized String length allowed.

allowNull - If allowNull is true then an 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.

canonicalize - If canonicalize is true then input will be canonicalized before validation

Returns:

The canonicalized user input.

Throws:

ValidationException

IntrusionException

getValidInput

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

Calls getValidInput with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

getValidInput

java.lang.String getValidInput(java.lang.String context,
                               java.lang.String input,
                               java.lang.String type,
                               int maxLength,
                               boolean allowNull,
                               boolean canonicalize,
                               ValidationErrorList errorList)
                               throws IntrusionException

Calls getValidInput with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

isValidDate

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

Calls isValidDate and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidDate

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

Calls isValidDate and returns true if no exceptions are thrown.

Throws:

IntrusionException

getValidDate

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.

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

input - The actual user input data to validate.

format - Required formatting of date inputted.

allowNull - If allowNull is true then an 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:

A valid date as a Date

Throws:

ValidationException

IntrusionException

getValidDate

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

Calls getValidDate with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

isValidSafeHTML

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

Calls getValidSafeHTML and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidSafeHTML

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

Calls getValidSafeHTML and returns true if no exceptions are thrown.

Throws:

IntrusionException

getValidSafeHTML

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

Returns canonicalized and validated "safe" HTML that does not contain unwanted scripts in the body, attributes, CSS, URLs, or anywhere else. 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.

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

input - The actual user input data to validate.

maxLength - The maximum String length allowed.

allowNull - If allowNull is true then an 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:

Valid safe HTML

Throws:

ValidationException

IntrusionException

getValidSafeHTML

java.lang.String getValidSafeHTML(java.lang.String context,
                                  java.lang.String input,
                                  int maxLength,
                                  boolean allowNull,
                                  ValidationErrorList errorList)
                                  throws IntrusionException

Calls getValidSafeHTML with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

isValidCreditCard

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

Calls getValidCreditCard and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidCreditCard

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

Calls getValidCreditCard and returns true if no exceptions are thrown.

Throws:

IntrusionException

getValidCreditCard

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.

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

input - The actual user input data to validate.

allowNull - If allowNull is true then an 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:

A valid credit card number

Throws:

ValidationException

IntrusionException

getValidCreditCard

java.lang.String getValidCreditCard(java.lang.String context,
                                    java.lang.String input,
                                    boolean allowNull,
                                    ValidationErrorList errorList)
                                    throws IntrusionException

Calls getValidCreditCard with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

isValidDirectoryPath

boolean isValidDirectoryPath(java.lang.String context,
                             java.lang.String input,
                             java.io.File parent,
                             boolean allowNull)
                             throws IntrusionException

Calls getValidDirectoryPath and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidDirectoryPath

boolean isValidDirectoryPath(java.lang.String context,
                             java.lang.String input,
                             java.io.File parent,
                             boolean allowNull,
                             ValidationErrorList errorList)
                             throws IntrusionException

Calls getValidDirectoryPath and returns true if no exceptions are thrown.

Throws:

IntrusionException

getValidDirectoryPath

java.lang.String getValidDirectoryPath(java.lang.String context,
                                       java.lang.String input,
                                       java.io.File parent,
                                       boolean allowNull)
                                       throws ValidationException,
                                              IntrusionException

Returns a canonicalized and validated directory path as a String, provided that the input maps to an existing directory that is an existing subdirectory (at any level) of the specified parent. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException. Instead of throwing a ValidationException on error, this variant will store the exception inside of the ValidationErrorList.

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

input - The actual input data to validate.

allowNull - If allowNull is true then an 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:

A valid directory path

Throws:

ValidationException

IntrusionException

getValidDirectoryPath

java.lang.String getValidDirectoryPath(java.lang.String context,
                                       java.lang.String input,
                                       java.io.File parent,
                                       boolean allowNull,
                                       ValidationErrorList errorList)
                                       throws IntrusionException

Calls getValidDirectoryPath with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

isValidFileName

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

Calls getValidFileName with the default list of allowedExtensions

Throws:

IntrusionException

isValidFileName

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

Calls getValidFileName with the default list of allowedExtensions

Throws:

IntrusionException

isValidFileName

boolean isValidFileName(java.lang.String context,
                        java.lang.String input,
                        java.util.List<java.lang.String> allowedExtensions,
                        boolean allowNull)
                        throws IntrusionException

Calls getValidFileName and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidFileName

boolean isValidFileName(java.lang.String context,
                        java.lang.String input,
                        java.util.List<java.lang.String> allowedExtensions,
                        boolean allowNull,
                        ValidationErrorList errorList)
                        throws IntrusionException

Calls getValidFileName and returns true if no exceptions are thrown.

Throws:

IntrusionException

getValidFileName

java.lang.String getValidFileName(java.lang.String context,
                                  java.lang.String input,
                                  java.util.List<java.lang.String> allowedExtensions,
                                  boolean allowNull)
                                  throws ValidationException,
                                         IntrusionException

Returns a canonicalized and validated file name as a String. Implementors should check for allowed file extensions here, as well as allowed file name characters, as declared in "ESAPI.properties". Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

input - The actual input data to validate.

allowNull - If allowNull is true then an 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:

A valid file name

Throws:

ValidationException

IntrusionException

getValidFileName

java.lang.String getValidFileName(java.lang.String context,
                                  java.lang.String input,
                                  java.util.List<java.lang.String> allowedExtensions,
                                  boolean allowNull,
                                  ValidationErrorList errorList)
                                  throws IntrusionException

Calls getValidFileName with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

isValidNumber

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

Calls getValidNumber and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidNumber

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

Calls getValidNumber and returns true if no exceptions are thrown.

Throws:

IntrusionException

getValidNumber

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 within the range of minValue to maxValue. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

input - The actual input data to validate.

allowNull - If allowNull is true then an 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.

minValue - Lowest legal value for input.

maxValue - Highest legal value for input.

Returns:

A validated number as a double.

Throws:

ValidationException

IntrusionException

getValidNumber

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

Calls getValidSafeHTML with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

isValidInteger

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

Calls getValidInteger and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidInteger

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

Calls getValidInteger and returns true if no exceptions are thrown.

Throws:

IntrusionException

getValidInteger

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. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

input - The actual input data to validate.

allowNull - If allowNull is true then an 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.

minValue - Lowest legal value for input.

maxValue - Highest legal value for input.

Returns:

A validated number as an integer.

Throws:

ValidationException

IntrusionException

getValidInteger

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

Calls getValidInteger with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

isValidDouble

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

Calls getValidDouble and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidDouble

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

Calls getValidDouble and returns true if no exceptions are thrown.

Throws:

IntrusionException

getValidDouble

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.

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

input - The actual input data to validate.

allowNull - If allowNull is true then an 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.

minValue - Lowest legal value for input.

maxValue - Highest legal value for input.

Returns:

A validated real number as a double.

Throws:

ValidationException

IntrusionException

getValidDouble

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

Calls getValidDouble with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

isValidFileContent

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

Calls getValidFileContent and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidFileContent

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

Calls getValidFileContent and returns true if no exceptions are thrown.

Throws:

IntrusionException

getValidFileContent

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

Returns validated file content as a byte array. This is a good place to check for max file size, allowed character sets, and do virus scans. Invalid input will generate a descriptive ValidationException, and input that is clearly an attack will generate a descriptive IntrusionException.

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

input - The actual input data to validate.

maxBytes - The maximum number of bytes allowed in a legal file.

allowNull - If allowNull is true then an 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:

A byte array containing valid file content.

Throws:

ValidationException

IntrusionException

getValidFileContent

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

Calls getValidFileContent with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

isValidFileUpload

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

Calls getValidFileUpload and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidFileUpload

boolean isValidFileUpload(java.lang.String context,
                          java.lang.String filepath,
                          java.lang.String filename,
                          java.io.File parent,
                          byte[] content,
                          int maxBytes,
                          boolean allowNull,
                          ValidationErrorList errorList)
                          throws IntrusionException

Calls getValidFileUpload and returns true if no exceptions are thrown.

Throws:

IntrusionException

assertValidFileUpload

void assertValidFileUpload(java.lang.String context,
                           java.lang.String filepath,
                           java.lang.String filename,
                           java.io.File parent,
                           byte[] content,
                           int maxBytes,
                           java.util.List<java.lang.String> allowedExtensions,
                           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.

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

filepath - The file path of the uploaded file.

filename - The filename of the uploaded file

content - A byte array containing the content of the uploaded file.

maxBytes - The max number of bytes allowed for a legal file upload.

allowNull - If allowNull is true then an 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.

Throws:

ValidationException

IntrusionException

assertValidFileUpload

void assertValidFileUpload(java.lang.String context,
                           java.lang.String filepath,
                           java.lang.String filename,
                           java.io.File parent,
                           byte[] content,
                           int maxBytes,
                           java.util.List<java.lang.String> allowedExtensions,
                           boolean allowNull,
                           ValidationErrorList errorList)
                           throws IntrusionException

Calls getValidFileUpload with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

isValidListItem

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

Calls getValidListItem and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidListItem

boolean isValidListItem(java.lang.String context,
                        java.lang.String input,
                        java.util.List<java.lang.String> list,
                        ValidationErrorList errorList)
                        throws IntrusionException

Calls getValidListItem and returns true if no exceptions are thrown.

Throws:

IntrusionException

getValidListItem

java.lang.String getValidListItem(java.lang.String context,
                                  java.lang.String input,
                                  java.util.List<java.lang.String> 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.

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

input - The value to search 'list' for.

list - The list to search for 'input'.

Returns:

The list item that exactly matches the canonicalized input.

Throws:

ValidationException

IntrusionException

getValidListItem

java.lang.String getValidListItem(java.lang.String context,
                                  java.lang.String input,
                                  java.util.List<java.lang.String> list,
                                  ValidationErrorList errorList)
                                  throws IntrusionException

Calls getValidListItem with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

isValidHTTPRequestParameterSet

boolean isValidHTTPRequestParameterSet(java.lang.String context,
                                       javax.servlet.http.HttpServletRequest request,
                                       java.util.Set<java.lang.String> required,
                                       java.util.Set<java.lang.String> optional)
                                       throws IntrusionException

Calls assertValidHTTPRequestParameterSet and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidHTTPRequestParameterSet

boolean isValidHTTPRequestParameterSet(java.lang.String context,
                                       javax.servlet.http.HttpServletRequest request,
                                       java.util.Set<java.lang.String> required,
                                       java.util.Set<java.lang.String> optional,
                                       ValidationErrorList errorList)
                                       throws IntrusionException

Calls assertValidHTTPRequestParameterSet and returns true if no exceptions are thrown.

Throws:

IntrusionException

assertValidHTTPRequestParameterSet

void assertValidHTTPRequestParameterSet(java.lang.String context,
                                        javax.servlet.http.HttpServletRequest request,
                                        java.util.Set<java.lang.String> required,
                                        java.util.Set<java.lang.String> 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.

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

required - parameters that are required to be in HTTP request

optional - additional parameters that may be in HTTP request

Throws:

ValidationException

IntrusionException

assertValidHTTPRequestParameterSet

void assertValidHTTPRequestParameterSet(java.lang.String context,
                                        javax.servlet.http.HttpServletRequest request,
                                        java.util.Set<java.lang.String> required,
                                        java.util.Set<java.lang.String> optional,
                                        ValidationErrorList errorList)
                                        throws IntrusionException

Calls getValidHTTPRequestParameterSet with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

isValidPrintable

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

Calls getValidPrintable and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidPrintable

boolean isValidPrintable(java.lang.String context,
                         char[] input,
                         int maxLength,
                         boolean allowNull,
                         ValidationErrorList errorList)
                         throws IntrusionException

Calls getValidPrintable and returns true if no exceptions are thrown.

Throws:

IntrusionException

getValidPrintable

char[] getValidPrintable(java.lang.String context,
                         char[] 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.

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

input - data to be returned as valid and printable

maxLength - Maximum number of bytes stored in 'input'

allowNull - If allowNull is true then an 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:

a byte array containing only printable characters, made up of data from 'input'

Throws:

ValidationException

getValidPrintable

char[] getValidPrintable(java.lang.String context,
                         char[] input,
                         int maxLength,
                         boolean allowNull,
                         ValidationErrorList errorList)
                         throws IntrusionException

Calls getValidPrintable with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

isValidPrintable

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

Calls getValidPrintable and returns true if no exceptions are thrown.

Throws:

IntrusionException

isValidPrintable

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

Calls getValidPrintable and returns true if no exceptions are thrown.

Throws:

IntrusionException

getValidPrintable

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.

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

input - data to be returned as valid and printable

maxLength - Maximum number of bytes stored in 'input' after canonicalization

allowNull - If allowNull is true then an 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:

a String containing only printable characters, made up of data from 'input'

Throws:

ValidationException

getValidPrintable

java.lang.String getValidPrintable(java.lang.String context,
                                   java.lang.String input,
                                   int maxLength,
                                   boolean allowNull,
                                   ValidationErrorList errorList)
                                   throws IntrusionException

Calls getValidPrintable with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

isValidRedirectLocation

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

Calls getValidRedirectLocation and returns true if no exceptions are thrown.

isValidRedirectLocation

boolean isValidRedirectLocation(java.lang.String context,
                                java.lang.String input,
                                boolean allowNull,
                                ValidationErrorList errorList)

Calls getValidRedirectLocation and returns true if no exceptions are thrown.

getValidRedirectLocation

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

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.

Parameters:

context - A descriptive name of the parameter that you are validating (e.g., LoginPage_UsernameField). This value is used by any logging or error handling that is done with respect to the value passed in.

input - redirect location to be returned as valid, according to encoding rules set in "ESAPI.properties"

allowNull - If allowNull is true then an 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:

A canonicalized and validated redirect location, as defined in "ESAPI.properties"

Throws:

ValidationException

IntrusionException

getValidRedirectLocation

java.lang.String getValidRedirectLocation(java.lang.String context,
                                          java.lang.String input,
                                          boolean allowNull,
                                          ValidationErrorList errorList)
                                          throws IntrusionException

Calls getValidRedirectLocation with the supplied errorList to capture ValidationExceptions

Throws:

IntrusionException

safeReadLine

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.

Parameters:

inputStream - The InputStream from which to read data

maxLength - Maximum characters allowed to be read in per line

Returns:

a String containing the current line of inputStream

Throws:

ValidationException