org.owasp.fileio

Class FileValidator

java.lang.Object

org.owasp.fileio.FileValidator

public class FileValidator
extends Object

Reference implementation of the FileValidator. This implementation provides basic validation functions. This library has a heavy emphasis on whitelist validation and canonicalization.

Author:

August Detlefsen CodeMagi

Field Summary

Fields

Modifier and Type	Field and Description
static String	DIRECTORY_NAME_REGEX
static String	FILE_NAME_REGEX

Constructor Summary

Constructors

Constructor and Description
FileValidator() Initialize file validator with an appropriate set of codecs
FileValidator(Encoder encoder) Initialize file validator with an appropriate set of codecs

Method Summary

Modifier and Type	Method and Description
void	assertValidFileUpload(String context, String directorypath, String filename, File parent, byte[] content, int maxBytes, List<String> allowedExtensions, boolean allowNull) Validates the filepath, filename, and content of a file.
void	assertValidFileUpload(String context, String directorypath, String filename, File parent, byte[] content, int maxBytes, List<String> allowedExtensions, boolean allowNull, List<ValidationException> errors) Calls getValidFileUpload with the supplied List to capture ValidationExceptions
List<String>	getAllowedExtensions()
Encoder	getFileEncoder()
Integer	getMaxFilePathSize()
Long	getMaxFileUploadSize()
String	getValidDirectoryPath(String context, String input, 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.
String	getValidDirectoryPath(String context, String input, File parent, boolean allowNull, List<ValidationException> errors) Calls getValidDirectoryPath with the supplied error List to capture ValidationExceptions
byte[]	getValidFileContent(String context, byte[] input, boolean allowNull) Returns validated file content as a byte array.
byte[]	getValidFileContent(String context, byte[] input, int maxBytes, boolean allowNull, List<ValidationException> errors) Calls getValidFileContent with the supplied List to capture ValidationExceptions
byte[]	getValidFileContent(String context, byte[] input, long maxBytes, boolean allowNull) Returns validated file content as a byte array.
String	getValidFileName(String context, String input, List<String> allowedExtensions, boolean allowNull) Returns a canonicalized and validated file name as a String.
String	getValidFileName(String context, String input, List<String> allowedExtensions, boolean allowNull, List<ValidationException> errors) Calls getValidFileName with the supplied List to capture ValidationExceptions
String	getValidInput(String context, String input, String type, int maxLength, boolean allowNull) Validates data received from the browser and returns a safe version.
String	getValidInput(String context, String input, String type, int maxLength, boolean allowNull, boolean canonicalize) Validates data received from the browser and returns a safe version.
boolean	isValidDirectoryPath(String context, String input, File parent, boolean allowNull) Calls getValidDirectoryPath and returns true if no exceptions are thrown.
boolean	isValidDirectoryPath(String context, String input, File parent, boolean allowNull, List<ValidationException> errors) Calls getValidDirectoryPath and returns true if no exceptions are thrown.
boolean	isValidFileContent(String context, byte[] input, int maxBytes, boolean allowNull) Calls getValidFileContent and returns true if no exceptions are thrown.
boolean	isValidFileContent(String context, byte[] input, int maxBytes, boolean allowNull, List<ValidationException> errors) Calls getValidFileContent and returns true if no exceptions are thrown.
boolean	isValidFileName(String context, String input, boolean allowNull) Calls getValidFileName with the default list of allowedExtensions
boolean	isValidFileName(String context, String input, boolean allowNull, List<ValidationException> errors) Calls getValidFileName with the default list of allowedExtensions
boolean	isValidFileName(String context, String input, List<String> allowedExtensions, boolean allowNull) Calls getValidFileName with the default list of allowedExtensions
boolean	isValidFileName(String context, String input, List<String> allowedExtensions, boolean allowNull, List<ValidationException> errors) Calls getValidFileName with the default list of allowedExtensions
boolean	isValidFileUpload(String context, String directorypath, String filename, File parent, byte[] content, int maxBytes, boolean allowNull) Calls getValidFileUpload and returns true if no exceptions are thrown.
boolean	isValidFileUpload(String context, String directorypath, String filename, File parent, byte[] content, int maxBytes, boolean allowNull, List<ValidationException> errors) Calls getValidFileUpload and returns true if no exceptions are thrown.
void	setAllowedExtensions(List<String> allowedExtensions)
void	setFileEncoder(Encoder fileEncoder)
void	setMaxFilePathSize(Integer maxFilePathSize)
void	setMaxFileUploadSize(Long maxFileUploadSize)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FILE_NAME_REGEX

public static final String FILE_NAME_REGEX

See Also:

Constant Field Values

DIRECTORY_NAME_REGEX

public static final String DIRECTORY_NAME_REGEX

See Also:

Constant Field Values

Constructor Detail

FileValidator

public FileValidator()

Initialize file validator with an appropriate set of codecs

FileValidator

public FileValidator(Encoder encoder)

Initialize file validator with an appropriate set of codecs

Parameters:

encoder - The encoder instance to use

Method Detail

getMaxFileUploadSize

public Long getMaxFileUploadSize()

setMaxFileUploadSize

public void setMaxFileUploadSize(Long maxFileUploadSize)

getAllowedExtensions

public List<String> getAllowedExtensions()

setAllowedExtensions

public void setAllowedExtensions(List<String> allowedExtensions)

getMaxFilePathSize

public Integer getMaxFilePathSize()

setMaxFilePathSize

public void setMaxFilePathSize(Integer maxFilePathSize)

getFileEncoder

public Encoder getFileEncoder()

setFileEncoder

public void setFileEncoder(Encoder fileEncoder)

isValidDirectoryPath

public boolean isValidDirectoryPath(String context,
                                    String input,
                                    File parent,
                                    boolean allowNull)

Calls getValidDirectoryPath and returns true if no exceptions are thrown.

Note: On platforms that support symlinks, this function will fail canonicalization if directorypath is a symlink. For example, on MacOS X, /etc is actually /private/etc. If you mean to use /etc, use its real path (/private/etc), not the symlink (/etc).

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.

parent - A File indicating the parent directory into which the input File will be placed.

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:

true if no validation exceptions are thrown

isValidDirectoryPath

public boolean isValidDirectoryPath(String context,
                                    String input,
                                    File parent,
                                    boolean allowNull,
                                    List<ValidationException> errors)

Calls getValidDirectoryPath and returns true if no exceptions are thrown.

Note: On platforms that support symlinks, this function will fail canonicalization if directorypath is a symlink. For example, on MacOS X, /etc is actually /private/etc. If you mean to use /etc, use its real path (/private/etc), not the symlink (/etc).

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.

parent - A File indicating the parent directory into which the input File will be placed.

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.

errors - A List to contain any validation errors.

Returns:

true if no validation exceptions are thrown

getValidDirectoryPath

public String getValidDirectoryPath(String context,
                                    String input,
                                    File parent,
                                    boolean allowNull)
                             throws ValidationException

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.

parent - A File indicating the parent directory into which the input File will be placed.

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 - if validation errors occur

getValidDirectoryPath

public String getValidDirectoryPath(String context,
                                    String input,
                                    File parent,
                                    boolean allowNull,
                                    List<ValidationException> errors)

Calls getValidDirectoryPath with the supplied error List to capture ValidationExceptions

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.

parent - A File indicating the parent directory into which the input File will be placed.

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.

errors - A List to contain any validation errors.

Returns:

A valid directory path

isValidFileName

public boolean isValidFileName(String context,
                               String input,
                               boolean allowNull)

Calls getValidFileName with the default list of allowedExtensions

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:

true if no validation exceptions occur

isValidFileName

public boolean isValidFileName(String context,
                               String input,
                               boolean allowNull,
                               List<ValidationException> errors)

Calls getValidFileName with the default list of allowedExtensions

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.

errors - A List to contain any validation errors.

Returns:

true if no validation exceptions occur

isValidFileName

public boolean isValidFileName(String context,
                               String input,
                               List<String> allowedExtensions,
                               boolean allowNull)

Calls getValidFileName with the default list of allowedExtensions

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.

allowedExtensions - A List of allowed file extensions to validate against

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:

true if no validation exceptions occur

isValidFileName

public boolean isValidFileName(String context,
                               String input,
                               List<String> allowedExtensions,
                               boolean allowNull,
                               List<ValidationException> errors)

Calls getValidFileName with the default list of allowedExtensions

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.

allowedExtensions - A List of allowed file extensions to validate against

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.

errors - A List to contain any validation errors.

Returns:

true if no validation exceptions occur

getValidFileName

public String getValidFileName(String context,
                               String input,
                               List<String> allowedExtensions,
                               boolean allowNull)
                        throws ValidationException

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. Note: If you do not explicitly specify a white list of allowed extensions, all extensions will be allowed by default.

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.

allowedExtensions - A List of allowed file extensions to validate against

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 - if validation errors occur

getValidFileName

public String getValidFileName(String context,
                               String input,
                               List<String> allowedExtensions,
                               boolean allowNull,
                               List<ValidationException> errors)

Calls getValidFileName with the supplied List to capture ValidationExceptions

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.

allowedExtensions - A List of allowed file extensions to validate against

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.

errors - A List to contain any validation errors.

Returns:

A valid file name

isValidFileUpload

public boolean isValidFileUpload(String context,
                                 String directorypath,
                                 String filename,
                                 File parent,
                                 byte[] content,
                                 int maxBytes,
                                 boolean allowNull)
                          throws ValidationException

Calls getValidFileUpload and returns true if no exceptions are thrown.

Note: On platforms that support symlinks, this function will fail canonicalization if directorypath is a symlink. For example, on MacOS X, /etc is actually /private/etc. If you mean to use /etc, use its real path (/private/etc), not the symlink (/etc).

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.

directorypath - The file path of the uploaded file.

filename - The filename of the uploaded file

parent - A File indicating the parent directory into which the input File will be placed.

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.

Returns:

true if no validation exceptions are thrown

Throws:

ValidationException - if validation errors occur

isValidFileUpload

public boolean isValidFileUpload(String context,
                                 String directorypath,
                                 String filename,
                                 File parent,
                                 byte[] content,
                                 int maxBytes,
                                 boolean allowNull,
                                 List<ValidationException> errors)

Calls getValidFileUpload and returns true if no exceptions are thrown.

Note: On platforms that support symlinks, this function will fail canonicalization if directorypath is a symlink. For example, on MacOS X, /etc is actually /private/etc. If you mean to use /etc, use its real path (/private/etc), not the symlink (/etc).

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.

directorypath - The file path of the uploaded file.

filename - The filename of the uploaded file

parent - A File indicating the parent directory into which the input File will be placed.

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.

errors - A List to contain any validation errors.

Returns:

true if no validation exceptions are thrown

assertValidFileUpload

public void assertValidFileUpload(String context,
                                  String directorypath,
                                  String filename,
                                  File parent,
                                  byte[] content,
                                  int maxBytes,
                                  List<String> allowedExtensions,
                                  boolean allowNull)
                           throws ValidationException

Validates the filepath, filename, and content of a file. Invalid input will generate a descriptive ValidationException.

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.

directorypath - The file path of the uploaded file.

filename - The filename of the uploaded file

parent - A File indicating the parent directory into which the input File will be placed.

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

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

allowedExtensions - A List of allowed file extensions to validate against

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 - if validation errors occur

assertValidFileUpload

public void assertValidFileUpload(String context,
                                  String directorypath,
                                  String filename,
                                  File parent,
                                  byte[] content,
                                  int maxBytes,
                                  List<String> allowedExtensions,
                                  boolean allowNull,
                                  List<ValidationException> errors)

Calls getValidFileUpload with the supplied List to capture ValidationExceptions

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.

directorypath - The file path of the uploaded file.

filename - The filename of the uploaded file

parent - A File indicating the parent directory into which the input File will be placed.

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

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

allowedExtensions - A List of allowed file extensions to validate against

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.

errors - A List to contain any validation errors.

isValidFileContent

public boolean isValidFileContent(String context,
                                  byte[] input,
                                  int maxBytes,
                                  boolean allowNull)

Calls getValidFileContent and returns true if no exceptions are thrown.

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 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.

Returns:

true if no validation exceptions occur

isValidFileContent

public boolean isValidFileContent(String context,
                                  byte[] input,
                                  int maxBytes,
                                  boolean allowNull,
                                  List<ValidationException> errors)

Calls getValidFileContent and returns true if no exceptions are thrown.

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 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.

errors - A List to contain any validation errors.

Returns:

true if no validation exceptions occur

getValidFileContent

public byte[] getValidFileContent(String context,
                                  byte[] input,
                                  boolean allowNull)
                           throws ValidationException

Returns validated file content as a byte array. This method checks for max file size (according to the value configured in the maxFileUploadSize class variable) and null input ONLY. It can be extended to check for allowed character sets, and do virus scans. Invalid input will generate a descriptive ValidationException.

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 byte array containing valid file content.

Throws:

ValidationException - if validation errors occur

getValidFileContent

public byte[] getValidFileContent(String context,
                                  byte[] input,
                                  long maxBytes,
                                  boolean allowNull)
                           throws ValidationException

Returns validated file content as a byte array. This method checks for max file size and null input ONLY. It can be extended to check for allowed character sets, and do virus scans. Invalid input will generate a descriptive ValidationException.

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 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.

Returns:

A byte array containing valid file content.

Throws:

ValidationException - if validation errors occur

getValidFileContent

public byte[] getValidFileContent(String context,
                                  byte[] input,
                                  int maxBytes,
                                  boolean allowNull,
                                  List<ValidationException> errors)
                           throws ValidationException

Calls getValidFileContent with the supplied List to capture ValidationExceptions

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 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.

errors - A List to contain any validation errors.

Returns:

A byte array containing valid file content.

Throws:

ValidationException - if validation errors occur

getValidInput

public String getValidInput(String context,
                            String input,
                            String type,
                            int maxLength,
                            boolean allowNull)
                     throws ValidationException

Validates data received from the browser and returns a safe version. Double encoding is treated as an attack. The default encoder supports html encoding, URL encoding, and javascript escaping. Input is canonicalized by default before validation.

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 which 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 - if validation errors occur

getValidInput

public String getValidInput(String context,
                            String input,
                            String type,
                            int maxLength,
                            boolean allowNull,
                            boolean canonicalize)
                     throws ValidationException

Validates data received from the browser and returns a safe version. Only URL encoding is supported. Double encoding is treated as an attack.

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 which maps to the actual regular expression in the ESAPI validation configuration file

maxLength - The maximum String length allowed. If input is canonicalized per the canonicalize argument, then maxLength must be verified after canonicalization

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.

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

Returns:

The user input, may be canonicalized if canonicalize argument is true

Throws:

ValidationException - if validation errors occur