org.owasp.esapi.interfaces
Interface IHTTPUtilities

All Known Implementing Classes:

HTTPUtilities

public interface IHTTPUtilities

The IHTTPUtilities interface is a collection of methods that provide additional security related to HTTP requests, responses, sessions, cookies, headers, and logging.

Since:

June 1, 2007

Author:

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

Method Summary

java.lang.String	addCSRFToken(java.lang.String href) Adds the current user's CSRF token (see User.getCSRFToken()) to the URL for purposes of preventing CSRF attacks.
javax.servlet.http.HttpSession	changeSessionIdentifier() Invalidate the old session after copying all of its contents to a newly created session with a new session id.
java.lang.String	decryptHiddenField(java.lang.String encrypted) Decrypts an encrypted hidden field value and returns the cleartest.
java.util.Map	decryptQueryString(java.lang.String encrypted) Takes an encrypted querystring and returns a Map containing the original parameters.
java.util.Map	decryptStateFromCookie() Retrieves a map of data from the encrypted cookie.
void	enableRememberToken(int maxAge, java.lang.String domain, java.lang.String path) Set a cookie containing the current User's remember token for automatic authentication.
java.lang.String	encryptHiddenField(java.lang.String value) Encrypts a hidden field value for use in HTML.
java.lang.String	encryptQueryString(java.lang.String query) Takes a querystring (i.e.
void	encryptStateInCookie(java.util.Map cleartext) Stores a Map of data in an encrypted cookie.
java.lang.String	getCookie(java.lang.String name) Returns the first cookie matching the given name.
javax.servlet.http.HttpServletRequest	getCurrentRequest() Retrieves the current HttpServletRequest
javax.servlet.http.HttpServletResponse	getCurrentResponse() Retrieves the current HttpServletResponse
java.util.List	getSafeFileUploads(java.io.File tempDir, java.io.File finalDir) Extract uploaded files from a multipart HTTP requests.
boolean	isSecureChannel() Returns true if the request and response are using an SSL-enabled connection.
void	killAllCookies() Kill all cookies received in the last request from the browser.
void	killCookie(java.lang.String name) Kills the specified cookie by setting a new cookie that expires immediately.
void	logHTTPRequest(ILogger logger) Format the Source IP address, URL, URL parameters, and all form parameters into a string suitable for the log file.
void	logHTTPRequest(ILogger logger, java.util.List parameterNamesToObfuscate) Format the Source IP address, URL, URL parameters, and all form parameters into a string suitable for the log file.
void	safeAddCookie(java.lang.String name, java.lang.String value, int maxAge, java.lang.String domain, java.lang.String path) Adds a cookie to the specified HttpServletResponse and adds the Http-Only flag.
void	safeAddHeader(java.lang.String name, java.lang.String value) Adds a header to an HttpServletResponse after checking for special characters (such as CRLF injection) that could enable attacks like response splitting and other header-based attacks that nobody has thought of yet.
void	safeSendForward(java.lang.String context, java.lang.String location) This method perform a forward to any resource located inside the WEB-INF directory.
void	safeSendRedirect(java.lang.String context, java.lang.String location) This method generates a redirect response that can only be used to redirect the browser to safe locations.
void	safeSetContentType() Sets the content type on each HTTP response, to help protect against cross-site scripting attacks and other types of injection into HTML documents.
void	safeSetHeader(java.lang.String name, java.lang.String value) Sets a header in an HttpServletResponse after checking for special characters (such as CRLF injection) that could enable attacks like response splitting and other header-based attacks that nobody has thought of yet.
void	setCurrentHTTP(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Stores the current HttpRequest and HttpResponse so that they may be readily accessed throughout ESAPI (and elsewhere)
void	setNoCacheHeaders() Set headers to protect sensitive information against being cached in the browser.
void	verifyCSRFToken() Checks the CSRF token in the URL (see User.getCSRFToken()) against the user's CSRF token and throws an IntrusionException if it is missing.

Method Detail

addCSRFToken

public java.lang.String addCSRFToken(java.lang.String href)

Adds the current user's CSRF token (see User.getCSRFToken()) to the URL for purposes of preventing CSRF attacks. This method should be used on all URLs to be put into all links and forms the application generates.

Returns:

the updated href with the CSRF token parameter

safeAddCookie

public void safeAddCookie(java.lang.String name,
                          java.lang.String value,
                          int maxAge,
                          java.lang.String domain,
                          java.lang.String path)

Adds a cookie to the specified HttpServletResponse and adds the Http-Only flag.

Parameters:

name - the name

value - the value

domain - the domain

path - the path

maxAge - the max age

safeAddHeader

public void safeAddHeader(java.lang.String name,
                          java.lang.String value)
                   throws ValidationException

Adds a header to an HttpServletResponse after checking for special characters (such as CRLF injection) that could enable attacks like response splitting and other header-based attacks that nobody has thought of yet.

Parameters:

name - the name

value - the value

Throws:

ValidationException

safeSetHeader

public void safeSetHeader(java.lang.String name,
                          java.lang.String value)
                   throws ValidationException

Sets a header in an HttpServletResponse after checking for special characters (such as CRLF injection) that could enable attacks like response splitting and other header-based attacks that nobody has thought of yet.

Parameters:

name - the name

value - the value

Throws:

ValidationException

changeSessionIdentifier

public javax.servlet.http.HttpSession changeSessionIdentifier()
                                                       throws AuthenticationException

Invalidate the old session after copying all of its contents to a newly created session with a new session id. Note that this is different from logging out and creating a new session identifier that does not contain the existing session contents. Care should be taken to use this only when the existing session does not contain hazardous contents.

Returns:

the http session

Throws:

EnterpriseSecurityException - the enterprise security exception

AuthenticationException

verifyCSRFToken

public void verifyCSRFToken()
                     throws IntrusionException

Checks the CSRF token in the URL (see User.getCSRFToken()) against the user's CSRF token and throws an IntrusionException if it is missing.

Throws:

IntrusionException

decryptHiddenField

public java.lang.String decryptHiddenField(java.lang.String encrypted)

Decrypts an encrypted hidden field value and returns the cleartest. If the field does not decrypt properly, an IntrusionException is thrown to indicate tampering.

Parameters:

encrypted -

Returns:

enableRememberToken

public void enableRememberToken(int maxAge,
                                java.lang.String domain,
                                java.lang.String path)

Set a cookie containing the current User's remember token for automatic authentication. The use of remember tokens is not recommended, but this method will help do it as safely as possible. The user interface should strongly warn the user that this should only be enabled on computers where no other users will have access.

Parameters:

maxAge -

domain -

path -

encryptHiddenField

public java.lang.String encryptHiddenField(java.lang.String value)
                                    throws EncryptionException

Encrypts a hidden field value for use in HTML.

Parameters:

value -

Returns:

Throws:

EncryptionException

encryptQueryString

public java.lang.String encryptQueryString(java.lang.String query)
                                    throws EncryptionException

Takes a querystring (i.e. everything after the ? in the URL) and returns an encrypted string containing the parameters.

Returns:

Throws:

EncryptionException

decryptQueryString

public java.util.Map decryptQueryString(java.lang.String encrypted)
                                 throws EncryptionException

Takes an encrypted querystring and returns a Map containing the original parameters.

Parameters:

encrypted -

Returns:

Throws:

EncryptionException

getCookie

public java.lang.String getCookie(java.lang.String name)

Returns the first cookie matching the given name.

getSafeFileUploads

public java.util.List getSafeFileUploads(java.io.File tempDir,
                                         java.io.File finalDir)
                                  throws ValidationException

Extract uploaded files from a multipart HTTP requests. Implementations must check the content to ensure that it is safe before making a permanent copy on the local filesystem. Checks should include length and content checks, possibly virus checking, and path and name checks. Refer to the file checking methods in IValidator for more information.

Parameters:

tempDir - the temp dir

finalDir - the final dir

Returns:

List of new File objects from upload

Throws:

ValidationException - the validation exception

decryptStateFromCookie

public java.util.Map decryptStateFromCookie()
                                     throws EncryptionException

Retrieves a map of data from the encrypted cookie.

Throws:

EncryptionException

isSecureChannel

public boolean isSecureChannel()

Returns true if the request and response are using an SSL-enabled connection. This check should be made on every request from the login page through the logout confirmation page. Essentially, any page that uses the Authenticator.login() call should call this. Implementers should consider calling this method directly in their Authenticator.login() method. If this method returns true for a page that requires SSL, there must be a misconfiguration, an AuthenticationException is warranted.

Returns:

killAllCookies

public void killAllCookies()

Kill all cookies received in the last request from the browser. Note that new cookies set by the application in this response may not be killed by this method.

killCookie

public void killCookie(java.lang.String name)

Kills the specified cookie by setting a new cookie that expires immediately.

Parameters:

name - the cookie name

encryptStateInCookie

public void encryptStateInCookie(java.util.Map cleartext)
                          throws EncryptionException

Stores a Map of data in an encrypted cookie.

Throws:

EncryptionException

safeSendRedirect

public void safeSendRedirect(java.lang.String context,
                             java.lang.String location)
                      throws java.io.IOException

This method generates a redirect response that can only be used to redirect the browser to safe locations. Importantly, redirect requests can be modified by attackers, so do not rely information contained within redirect requests, and do not include sensitive information in a redirect.

Parameters:

location - the URL to redirect to

Throws:

java.io.IOException - Signals that an I/O exception has occurred.

safeSendForward

public void safeSendForward(java.lang.String context,
                            java.lang.String location)
                     throws AccessControlException,
                            javax.servlet.ServletException,
                            java.io.IOException

This method perform a forward to any resource located inside the WEB-INF directory. Forwarding to publically accessible resources can be dangerous, as the request will have already passed the URL based access control check. This method ensures that you can only forward to non-publically accessible resources.

Parameters:

context -

location -

Throws:

AccessControlException

javax.servlet.ServletException

java.io.IOException

safeSetContentType

public void safeSetContentType()

Sets the content type on each HTTP response, to help protect against cross-site scripting attacks and other types of injection into HTML documents.

setNoCacheHeaders

public void setNoCacheHeaders()

Set headers to protect sensitive information against being cached in the browser. Developers should make this call for any HTTP responses that contain any sensitive data that should not be cached within the browser or any intermediate proxies or caches. Implementations should set headers for the expected browsers. The safest approach is to set all relevant headers to their most restrictive setting. These include:

 
 Cache-Control: no-store

 Cache-Control: no-cache

 Cache-Control: must-revalidate

 Expires: -1

 
 

Note that the header "pragma: no-cache" is only useful in HTTP requests, not HTTP responses. So even though there are many articles recommending the use of this header, it is not helpful for preventing browser caching. For more information, please refer to the relevant standards:

• HTTP/1.1 Cache-Control "no-cache"
• HTTP/1.1 Cache-Control "no-store"
• HTTP/1.0 Pragma "no-cache"
• HTTP/1.0 Expires
• IE6 Caching Issues
• Firefox browser.cache.disk_cache_ssl
• Mozilla

setCurrentHTTP

public void setCurrentHTTP(javax.servlet.http.HttpServletRequest request,
                           javax.servlet.http.HttpServletResponse response)

Stores the current HttpRequest and HttpResponse so that they may be readily accessed throughout ESAPI (and elsewhere)

Parameters:

request - the current request

response - the current response

getCurrentRequest

public javax.servlet.http.HttpServletRequest getCurrentRequest()

Retrieves the current HttpServletRequest

Returns:

the current request

getCurrentResponse

public javax.servlet.http.HttpServletResponse getCurrentResponse()

Retrieves the current HttpServletResponse

Returns:

the current response

logHTTPRequest

public void logHTTPRequest(ILogger logger)

Format the Source IP address, URL, URL parameters, and all form parameters into a string suitable for the log file. Be careful not to log sensitive information, and consider masking with the logHTTPRequest( List parameterNamesToObfuscate ) method.

logHTTPRequest

public void logHTTPRequest(ILogger logger,
                           java.util.List parameterNamesToObfuscate)

Format the Source IP address, URL, URL parameters, and all form parameters into a string suitable for the log file. The list of parameters to obfuscate should be specified in order to prevent sensitive information from being logged. If a null list is provided, then all parameters will be logged.

Parameters:

parameterNamesToObfuscate - the sensitive params