DefaultHTTPUtilities (ESAPI 2.6.0.0 API)

java.lang.Object
- org.owasp.esapi.reference.DefaultHTTPUtilities

All Implemented Interfaces:

HTTPUtilities
```
public class DefaultHTTPUtilities
extends Object
implements HTTPUtilities
```
Reference implementation of the HTTPUtilities interface. This implementation uses the Apache Commons FileUploader library, which in turn uses the Apache Commons IO library.
To simplify the interface, some methods use the current request and response that are tracked by ThreadLocal variables in the Authenticator. This means that you must have called ESAPI.authenticator().setCurrentHTTP(request, response) before calling these methods.
Typically, this is done by calling the Authenticator.login() method, which calls setCurrentHTTP() automatically. However if you want to use these methods in another application, you should explicitly call setCurrentHTTP() in your own code. In either case, you *must* call ESAPI.clearCurrent() to clear threadlocal variables before the thread is reused. The advantages of having identity everywhere outweigh the disadvantages of this approach.

Since:

June 1, 2007

Author:

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

See Also:

HTTPUtilities

Field Summary
- Fields inherited from interface org.owasp.esapi.HTTPUtilities
  COOKIE, CSRF_TOKEN_NAME, ESAPI_STATE, HEADER, MAX_COOKIE_LEN, MAX_COOKIE_PAIRS, PARAMETER, REMEMBER_TOKEN_COOKIE_NAME

Constructor Summary

Constructors
Constructor and Description

DefaultHTTPUtilities()
No arg constructor.

Constructors
Constructor and Description
`DefaultHTTPUtilities()` No arg constructor.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addCookie(javax.servlet.http.Cookie cookie)` Calls addCookie with the current request.
`void`	`addCookie(javax.servlet.http.HttpServletResponse response, javax.servlet.http.Cookie cookie)` Add a cookie to the response after ensuring that there are no encoded or illegal characters in the name and name and value.
`String`	`addCSRFToken(String href)` Adds the current user's CSRF token (see User.getCSRFToken()) to the URL for purposes of preventing CSRF attacks.
`void`	`addHeader(javax.servlet.http.HttpServletResponse response, String name, String value)` Add a header to the response after ensuring that there are no encoded or illegal characters in the name and name and value.
`void`	`addHeader(String name, String value)` Calls addHeader with the current request.
`void`	`assertSecureChannel()` Calls assertSecureChannel with the current request.
`void`	`assertSecureChannel(javax.servlet.http.HttpServletRequest request)` Ensures the use of SSL to protect any sensitive parameters in the request and any sensitive data in the response.
`void`	`assertSecureRequest()` Calls assertSecureRequest with the current request.
`void`	`assertSecureRequest(javax.servlet.http.HttpServletRequest request)` Ensures that the request uses both SSL and POST to protect any sensitive parameters in the querystring from being sniffed, logged, bookmarked, included in referer header, etc...
`javax.servlet.http.HttpSession`	`changeSessionIdentifier()` Calls changeSessionIdentifier with the current request.
`javax.servlet.http.HttpSession`	`changeSessionIdentifier(javax.servlet.http.HttpServletRequest request)` Invalidate the existing session after copying all of its contents to a newly created session with a new session id.
`void`	`clearCurrent()` Clears the current HttpRequest and HttpResponse associated with the current thread.
`String`	`decryptHiddenField(String encrypted)` Decrypts an encrypted hidden field value and returns the cleartext.
`Map<String,String>`	`decryptQueryString(String encrypted)` Takes an encrypted querystring and returns a Map containing the original parameters.
`Map<String,String>`	`decryptStateFromCookie()` Calls decryptStateFromCookie with the current request.
`Map<String,String>`	`decryptStateFromCookie(javax.servlet.http.HttpServletRequest request)` Retrieves a map of data from a cookie encrypted with encryptStateInCookie().
`String`	`encryptHiddenField(String value)` Encrypts a hidden field value for use in HTML.
`String`	`encryptQueryString(String query)` Takes a querystring (everything after the question mark in the URL) and returns an encrypted string containing the parameters.
`void`	`encryptStateInCookie(javax.servlet.http.HttpServletResponse response, Map<String,String> cleartext)` Stores a Map of data in an encrypted cookie.
`void`	`encryptStateInCookie(Map<String,String> cleartext)` Calls encryptStateInCookie with the current response.
`String`	`getCookie(javax.servlet.http.HttpServletRequest request, String name)` A safer replacement for getCookies() in HttpServletRequest that returns the canonicalized value of the named cookie after "global" validation against the general type defined in ESAPI.properties.
`String`	`getCookie(String name)` Calls getCookie with the current response.
`String`	`getCSRFToken()` Returns the current user's CSRF token.
`javax.servlet.http.HttpServletRequest`	`getCurrentRequest()` Retrieves the current HttpServletRequest
`javax.servlet.http.HttpServletResponse`	`getCurrentResponse()` Retrieves the current HttpServletResponse
`List<File>`	`getFileUploads()` Calls `getFileUploads` with the current request, default upload directory, and default allowed file extensions
`List<File>`	`getFileUploads(javax.servlet.http.HttpServletRequest request)` Call `getFileUploads` with the specified request, default upload directory, and default allowed file extensions
`List<File>`	`getFileUploads(javax.servlet.http.HttpServletRequest request, File finalDir)` Call `getFileUploads` with the specified request, specified upload directory, and default allowed file extensions
`List<File>`	`getFileUploads(javax.servlet.http.HttpServletRequest request, File finalDir, List allowedExtensions)` Extract uploaded files from a multipart/form-data HTTP request.
`String`	`getHeader(javax.servlet.http.HttpServletRequest request, String name)` A safer replacement for getHeader() in HttpServletRequest that returns the canonicalized value of the named header after "global" validation against the general type defined in ESAPI.properties.
`String`	`getHeader(String name)` Calls getHeader with the current request.
`static HTTPUtilities`	`getInstance()`
`String`	`getParameter(javax.servlet.http.HttpServletRequest request, String name)` A safer replacement for getParameter() in HttpServletRequest that returns the canonicalized value of the named parameter after "global" validation against the general type defined in ESAPI.properties.
`String`	`getParameter(String name)` Calls getParameter with the current request.
`<T> T`	`getRequestAttribute(javax.servlet.http.HttpServletRequest request, String key)` Gets a typed attribute from the `HttpServletRequest` associated with the passed in request.
`<T> T`	`getRequestAttribute(String key)` Gets a typed attribute from the `HttpServletRequest` associated with the caller thread.
`<T> T`	`getSessionAttribute(javax.servlet.http.HttpSession session, String key)` Gets a typed attribute from the passed in session.
`<T> T`	`getSessionAttribute(String key)` Gets a typed attribute from the session associated with the calling thread.
`void`	`killAllCookies()` Calls killAllCookies with the current request and response.
`void`	`killAllCookies(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Kill all cookies received in the last request from the browser.
`void`	`killCookie(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, String name)` Kills the specified cookie by setting a new cookie that expires immediately.
`void`	`killCookie(String name)` Calls killCookie with the current request and response.
`void`	`logHTTPRequest()` Calls logHTTPRequest with the current request and logger.
`void`	`logHTTPRequest(javax.servlet.http.HttpServletRequest request, Logger logger)` Format the Source IP address, URL, URL parameters, and all form parameters into a string suitable for the log file.
`void`	`logHTTPRequest(javax.servlet.http.HttpServletRequest request, Logger logger, List parameterNamesToObfuscate)` Formats an HTTP request into a log suitable string.
`void`	`sendForward(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, String location)` This method performs a forward to any resource located inside the WEB-INF directory.
`void`	`sendForward(String location)` Calls sendForward with the current request and response.
`void`	`sendRedirect(javax.servlet.http.HttpServletResponse response, String location)` This method performs a forward to any resource located inside the WEB-INF directory.
`void`	`sendRedirect(String location)` Calls sendRedirect with the current response.
`void`	`setContentType()` Calls setContentType with the current request and response.
`void`	`setContentType(javax.servlet.http.HttpServletResponse response)` Set the content type character encoding header on every HttpServletResponse in order to limit the ways in which the input data can be represented.
`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`	`setHeader(javax.servlet.http.HttpServletResponse response, String name, String value)` Add a header to the response after ensuring that there are no encoded or illegal characters in the name and value.
`void`	`setHeader(String name, String value)` Calls setHeader with the current response.
`void`	`setNoCacheHeaders()` Calls setNoCacheHeaders with the current response.
`void`	`setNoCacheHeaders(javax.servlet.http.HttpServletResponse response)` Set headers to protect sensitive information against being cached in the browser.
`String`	`setRememberToken(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, int maxAge, String domain, String path)`
`String`	`setRememberToken(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, String password, int maxAge, String domain, String path)` Set a cookie containing the current User's remember me token for automatic authentication.
`String`	`setRememberToken(String password, int maxAge, String domain, String path)` Calls setNoCacheHeaders with the current response.
`void`	`verifyCSRFToken()` Calls verifyCSRFToken with the current request.
`void`	`verifyCSRFToken(javax.servlet.http.HttpServletRequest request)` Checks the CSRF token in the URL (see User.getCSRFToken()) against the user's CSRF token and throws an IntrusionException if it is missing.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail
- DefaultHTTPUtilities
```
public DefaultHTTPUtilities()
```
  No arg constructor.

Method Detail

getInstance

public static HTTPUtilities getInstance()

addCookie
```
public void addCookie(javax.servlet.http.Cookie cookie)
```
Calls addCookie with the *current* request. This implementation uses a custom "set-cookie" header rather than Java's cookie interface which doesn't allow the use of HttpOnly. Configure the HttpOnly and Secure settings in ESAPI.properties.

Specified by:

addCookie in interface HTTPUtilities

Parameters:

cookie - The cookie to add

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

addCookie
```
public void addCookie(javax.servlet.http.HttpServletResponse response,
                      javax.servlet.http.Cookie cookie)
```
Add a cookie to the response after ensuring that there are no encoded or illegal characters in the name and name and value. This method also sets the secure and HttpOnly flags on the cookie. This implementation uses a custom "set-cookie" header rather than Java's cookie interface which doesn't allow the use of HttpOnly. Configure the HttpOnly and Secure settings in ESAPI.properties.

Specified by:

addCookie in interface HTTPUtilities

Parameters:

response - The HTTP response to add the cookie to

cookie - The cookie to add

addCSRFToken
```
public String addCSRFToken(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.

Specified by:

addCSRFToken in interface HTTPUtilities

Parameters:

href - the URL to which the CSRF token will be appended

Returns:

the updated URL with the CSRF token parameter added

addHeader
```
public void addHeader(String name,
                      String value)
```
Calls addHeader with the *current* request.

Specified by:

addHeader in interface HTTPUtilities

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

addHeader
```
public void addHeader(javax.servlet.http.HttpServletResponse response,
                      String name,
                      String value)
```
Add a header to the response after ensuring that there are no encoded or illegal characters in the name and name and value. This implementation follows the following recommendation: "A recipient MAY replace any linear white space with a single SP before interpreting the field value or forwarding the message downstream." http://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2

Specified by:

addHeader in interface HTTPUtilities

assertSecureChannel
```
public void assertSecureChannel()
                         throws AccessControlException
```
Calls assertSecureChannel with the *current* request.

Specified by:

assertSecureChannel in interface HTTPUtilities

Throws:

AccessControlException

See Also:

HTTPUtilities.assertSecureChannel(HttpServletRequest), HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

assertSecureChannel
```
public void assertSecureChannel(javax.servlet.http.HttpServletRequest request)
                         throws AccessControlException
```
Ensures the use of SSL to protect any sensitive parameters in the request and any sensitive data in the response. This method should be called for any request that contains sensitive data from a web form or will result in sensitive data in the response page. This implementation ignores the built-in isSecure() method and uses the URL to determine if the request was transmitted over SSL. This is because SSL may have been terminated somewhere outside the container.

Specified by:

assertSecureChannel in interface HTTPUtilities

Throws:

AccessControlException - if security constraints are not met

assertSecureRequest
```
public void assertSecureRequest()
                         throws AccessControlException
```
Calls assertSecureRequest with the *current* request.

Specified by:

assertSecureRequest in interface HTTPUtilities

Throws:

AccessControlException

See Also:

HTTPUtilities.assertSecureRequest(HttpServletRequest), HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

assertSecureRequest
```
public void assertSecureRequest(javax.servlet.http.HttpServletRequest request)
                         throws AccessControlException
```
Ensures that the request uses both SSL and POST to protect any sensitive parameters in the querystring from being sniffed, logged, bookmarked, included in referer header, etc... This method should be called for any request that contains sensitive data from a web form.

Specified by:

assertSecureRequest in interface HTTPUtilities

Throws:

AccessControlException - if security constraints are not met

changeSessionIdentifier
```
public javax.servlet.http.HttpSession changeSessionIdentifier()
                                                       throws AuthenticationException
```
Calls changeSessionIdentifier with the *current* request.

Specified by:

changeSessionIdentifier in interface HTTPUtilities

Throws:

AuthenticationException

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

changeSessionIdentifier
```
public javax.servlet.http.HttpSession changeSessionIdentifier(javax.servlet.http.HttpServletRequest request)
                                                       throws AuthenticationException
```
Invalidate the existing 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.

Specified by:

changeSessionIdentifier in interface HTTPUtilities

Returns:

the new HttpSession with a changed id

Throws:

AuthenticationException - the exception

clearCurrent
```
public void clearCurrent()
```
Clears the current HttpRequest and HttpResponse associated with the current thread.

Specified by:

clearCurrent in interface HTTPUtilities

See Also:

ESAPI.clearCurrent()

decryptHiddenField
```
public String decryptHiddenField(String encrypted)
```
Decrypts an encrypted hidden field value and returns the cleartext. If the field does not decrypt properly, an IntrusionException is thrown to indicate tampering.

Specified by:

decryptHiddenField in interface HTTPUtilities

Parameters:

encrypted - hidden field value to decrypt

Returns:

decrypted hidden field value stored as a String

decryptQueryString
```
public Map<String,String> decryptQueryString(String encrypted)
                                      throws EncryptionException
```
Takes an encrypted querystring and returns a Map containing the original parameters.

Specified by:

decryptQueryString in interface HTTPUtilities

Parameters:

encrypted - the encrypted querystring to decrypt

Returns:

a Map object containing the decrypted querystring

Throws:

EncryptionException

decryptStateFromCookie
```
public Map<String,String> decryptStateFromCookie()
                                          throws EncryptionException
```
Calls decryptStateFromCookie with the *current* request.

Specified by:

decryptStateFromCookie in interface HTTPUtilities

Throws:

EncryptionException

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

decryptStateFromCookie
```
public Map<String,String> decryptStateFromCookie(javax.servlet.http.HttpServletRequest request)
                                          throws EncryptionException
```
Retrieves a map of data from a cookie encrypted with encryptStateInCookie().

Specified by:

decryptStateFromCookie in interface HTTPUtilities

Parameters:

request -

Returns:

a map containing the decrypted cookie state value

Throws:

EncryptionException

encryptHiddenField
```
public String encryptHiddenField(String value)
                          throws EncryptionException
```
Encrypts a hidden field value for use in HTML.

Specified by:

encryptHiddenField in interface HTTPUtilities

Parameters:

value - the cleartext value of the hidden field

Returns:

the encrypted value of the hidden field

Throws:

EncryptionException

encryptQueryString
```
public String encryptQueryString(String query)
                          throws EncryptionException
```
Takes a querystring (everything after the question mark in the URL) and returns an encrypted string containing the parameters.

Specified by:

encryptQueryString in interface HTTPUtilities

Parameters:

query - the querystring to encrypt

Returns:

encrypted querystring stored as a String

Throws:

EncryptionException

encryptStateInCookie
```
public void encryptStateInCookie(javax.servlet.http.HttpServletResponse response,
                                 Map<String,String> cleartext)
                          throws EncryptionException
```
Stores a Map of data in an encrypted cookie. Generally the session is a better place to store state information, as it does not expose it to the user at all. If there is a requirement not to use sessions, or the data should be stored across sessions (for a long time), the use of encrypted cookies is an effective way to prevent the exposure.

Specified by:

encryptStateInCookie in interface HTTPUtilities

Throws:

EncryptionException

encryptStateInCookie
```
public void encryptStateInCookie(Map<String,String> cleartext)
                          throws EncryptionException
```
Calls encryptStateInCookie with the *current* response.

Specified by:

encryptStateInCookie in interface HTTPUtilities

Throws:

EncryptionException

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

getCookie
```
public String getCookie(javax.servlet.http.HttpServletRequest request,
                        String name)
                 throws ValidationException
```
A safer replacement for getCookies() in HttpServletRequest that returns the canonicalized value of the named cookie after "global" validation against the general type defined in ESAPI.properties. This should not be considered a replacement for more specific validation.

Specified by:

getCookie in interface HTTPUtilities

name - The cookie to get

Returns:

the requested cookie value

Throws:

ValidationException

getCookie
```
public String getCookie(String name)
                 throws ValidationException
```
Calls getCookie with the *current* response.

Specified by:

getCookie in interface HTTPUtilities

Parameters:

name - The cookie to get

Returns:

the requested cookie value

Throws:

ValidationException

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

getCSRFToken
```
public String getCSRFToken()
```
Returns the current user's CSRF token. If there is no current user then return null.

Specified by:

getCSRFToken in interface HTTPUtilities

Returns:

the current user's CSRF token

getCurrentRequest
```
public javax.servlet.http.HttpServletRequest getCurrentRequest()
```
Retrieves the current HttpServletRequest

Specified by:

getCurrentRequest in interface HTTPUtilities

Returns:

the current request

getCurrentResponse
```
public javax.servlet.http.HttpServletResponse getCurrentResponse()
```
Retrieves the current HttpServletResponse

Specified by:

getCurrentResponse in interface HTTPUtilities

Returns:

the current response

getFileUploads
```
public List<File> getFileUploads()
                          throws ValidationException
```
Calls getFileUploads with the current request, default upload directory, and default allowed file extensions

Specified by:

getFileUploads in interface HTTPUtilities

Returns:

List of new File objects from upload

Throws:

ValidationException - if the file fails validation

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

getFileUploads
```
public List<File> getFileUploads(javax.servlet.http.HttpServletRequest request)
                          throws ValidationException
```
Call getFileUploads with the specified request, default upload directory, and default allowed file extensions

Specified by:

getFileUploads in interface HTTPUtilities

Parameters:

request - The applicable HTTP request

Returns:

List of new File objects from upload

Throws:

ValidationException - if the file fails validation

getFileUploads
```
public List<File> getFileUploads(javax.servlet.http.HttpServletRequest request,
                                 File finalDir)
                          throws ValidationException
```
Call getFileUploads with the specified request, specified upload directory, and default allowed file extensions

Specified by:

getFileUploads in interface HTTPUtilities

Parameters:

request - The applicable HTTP request

finalDir - The destination directory to leave the uploaded file(s) in.

Returns:

List of new File objects from upload

Throws:

ValidationException - if the file fails validation

getFileUploads

public List<File> getFileUploads(javax.servlet.http.HttpServletRequest request,
                                 File finalDir,
                                 List allowedExtensions)
                          throws ValidationException

Extract uploaded files from a multipart/form-data HTTP request. 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 Validator for more information. Important Note: The ESAPI reference implementation (i.e., org.owasp.esapi.referenceDefaultHTTPUtilities only does some of these things listed above and some of those are limited to which getFileUploads method is called and how you've set your relevant ESAPI properties in your ESAPI.properties file.

This method uses HTTPUtilities.getCurrentRequest() to obtain the HttpServletRequest object. If the ESAPI property HttpUtilities.FileUploadAllowAnonymousUser is set to false (the default is true), then getFileUploads will call ESAPI.authenticator().getCurrentUser() to check if the user is authenticated. If that property is set to false and a call to that function returns an anonymous (i.e., unauthenticated) user, then the file upload is blocked.

ESAPI properties relevant to this and the other getFileUploads methods referenced in this table. The last 2 properties are new since release 2.5.2.0:

ESAPI Property Name	ESAPI.properties Default	Builtin Default	Meaning
HttpUtilities.UploadDir	C:\ESAPI\testUpload	UploadDir	Final destination directory for uploaded files.
HttpUtilities.UploadTempDir	C:\temp	Value of system property java.io.tmpdir	Temporary staging directory for uploaded files.
HttpUtilities.ApprovedUploadExtensions	.pdf,.doc,.docx,.ppt,.pptx,.xls,.xlsx,.rtf,.txt,.jpg,.pn	.pdf,.txt,.jpg,.png	Comma separated allowed list of file suffixes that may be uploaded.
HttpUtilities.MaxUploadFileBytes	5000000	5000000	Total maximum upload file size for uploaded files per HTTP request.
HttpUtilities.MaxUploadFileCount	20	20	Maximum total number of uploaded files per HTTP request.
HttpUtilities.FileUploadAllowAnonymousUser	true	true	Controls whether anonymous (i.e., unauthenticated) users may upload files.

As alluded to above, it is important to note that these getFileUploads methods do not do everything to keey your application and environment secure. Some of the more obvious omissions are the absence of examining the actual file content to determine the actual file type or running some AV scan on the uploaded files. You have to add that functionality to you if you want or need that. Some resource that you may find useful are:

Specified by:: getFileUploads in interface HTTPUtilities
Parameters:: request - The applicable HTTP request; finalDir - The destination directory to leave the uploaded file in.; allowedExtensions - Permitted file suffixes. (Yes, this is a weak check. Use Apache Tika if you want something more.)
Returns:: List of new File objects from upload
Throws:: ValidationException - if the file fails validation

getHeader
```
public String getHeader(javax.servlet.http.HttpServletRequest request,
                        String name)
                 throws ValidationException
```
A safer replacement for getHeader() in HttpServletRequest that returns the canonicalized value of the named header after "global" validation against the general type defined in ESAPI.properties. This should not be considered a replacement for more specific validation.

Specified by:

getHeader in interface HTTPUtilities

Returns:

the requested header value

Throws:

ValidationException

getHeader
```
public String getHeader(String name)
                 throws ValidationException
```
Calls getHeader with the *current* request.

Specified by:

getHeader in interface HTTPUtilities

Throws:

ValidationException

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

getParameter
```
public String getParameter(javax.servlet.http.HttpServletRequest request,
                           String name)
                    throws ValidationException
```
A safer replacement for getParameter() in HttpServletRequest that returns the canonicalized value of the named parameter after "global" validation against the general type defined in ESAPI.properties. This should not be considered a replacement for more specific validation.

Specified by:

getParameter in interface HTTPUtilities

Returns:

the requested parameter value

Throws:

ValidationException

getParameter
```
public String getParameter(String name)
                    throws ValidationException
```
Calls getParameter with the *current* request.

Specified by:

getParameter in interface HTTPUtilities

Throws:

ValidationException

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

killAllCookies
```
public void killAllCookies()
```
Calls killAllCookies with the *current* request and response.

Specified by:

killAllCookies in interface HTTPUtilities

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

killAllCookies
```
public void killAllCookies(javax.servlet.http.HttpServletRequest request,
                           javax.servlet.http.HttpServletResponse response)
```
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.

Specified by:

killAllCookies in interface HTTPUtilities

Parameters:

request -

response -

killCookie
```
public void killCookie(javax.servlet.http.HttpServletRequest request,
                       javax.servlet.http.HttpServletResponse response,
                       String name)
```
Kills the specified cookie by setting a new cookie that expires immediately. Note that this method does not delete new cookies that are being set by the application for this response.

Specified by:

killCookie in interface HTTPUtilities

Parameters:

request -

response -

name -

killCookie
```
public void killCookie(String name)
```
Calls killCookie with the *current* request and response.

Specified by:

killCookie in interface HTTPUtilities

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

logHTTPRequest
```
public void logHTTPRequest()
```
Calls logHTTPRequest with the *current* request and logger.

Specified by:

logHTTPRequest in interface HTTPUtilities

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

logHTTPRequest
```
public void logHTTPRequest(javax.servlet.http.HttpServletRequest request,
                           Logger 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.

Specified by:

logHTTPRequest in interface HTTPUtilities

logger - the logger to write the request to

logHTTPRequest
```
public void logHTTPRequest(javax.servlet.http.HttpServletRequest request,
                           Logger logger,
                           List parameterNamesToObfuscate)
```
Formats an HTTP request into a log suitable string. This implementation logs the remote host IP address (or hostname if available), the request method (GET/POST), the URL, and all the querystring and form parameters. All the parameters are presented as though they were in the URL even if they were in a form. Any parameters that match items in the parameterNamesToObfuscate are shown as eight asterisks.

Specified by:

logHTTPRequest in interface HTTPUtilities

Parameters:

request -

logger - the logger to write the request to

parameterNamesToObfuscate - the sensitive parameters

sendForward
```
public void sendForward(javax.servlet.http.HttpServletRequest request,
                        javax.servlet.http.HttpServletResponse response,
                        String location)
                 throws AccessControlException,
                        javax.servlet.ServletException,
                        IOException
```
This method performs a forward to any resource located inside the WEB-INF directory. Forwarding to publicly 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-publicly accessible resources. This implementation simply checks to make sure that the forward location starts with "WEB-INF" and is intended for use in frameworks that forward to JSP files inside the WEB-INF folder.

Specified by:

sendForward in interface HTTPUtilities

location - the URL to forward to, including parameters

Throws:

AccessControlException

javax.servlet.ServletException

IOException

sendForward
```
public void sendForward(String location)
                 throws AccessControlException,
                        javax.servlet.ServletException,
                        IOException
```
Calls sendForward with the *current* request and response.

Specified by:

sendForward in interface HTTPUtilities

Throws:

AccessControlException

javax.servlet.ServletException

IOException

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

sendRedirect
```
public void sendRedirect(javax.servlet.http.HttpServletResponse response,
                         String location)
                  throws AccessControlException,
                         IOException
```
This method performs a forward to any resource located inside the WEB-INF directory. Forwarding to publicly 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-publicly accessible resources. This implementation checks against the list of safe redirect locations defined in ESAPI.properties.

Specified by:

sendRedirect in interface HTTPUtilities

location - the URL to forward to, including parameters

Throws:

AccessControlException

IOException

sendRedirect
```
public void sendRedirect(String location)
                  throws AccessControlException,
                         IOException
```
Calls sendRedirect with the *current* response.

Specified by:

sendRedirect in interface HTTPUtilities

Throws:

AccessControlException

IOException

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

setContentType
```
public void setContentType()
```
Calls setContentType with the *current* request and response.

Specified by:

setContentType in interface HTTPUtilities

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

setContentType
```
public void setContentType(javax.servlet.http.HttpServletResponse response)
```
Set the content type character encoding header on every HttpServletResponse in order to limit the ways in which the input data can be represented. This prevents malicious users from using encoding and multi-byte escape sequences to bypass input validation routines.
Implementations of this method should set the content type header to a safe value for your environment. The default is text/html; charset=UTF-8 character encoding, which is the default in early versions of HTML and HTTP. See RFC 2047 (http://ds.internic.net/rfc/rfc2045.txt) for more information about character encoding and MIME.
The DefaultHTTPUtilities reference implementation sets the content type as specified.

Specified by:

setContentType in interface HTTPUtilities

Parameters:

response - The servlet response to set the content type for.

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)

Specified by:

setCurrentHTTP in interface HTTPUtilities

Parameters:

request - the current request

response - the current response

setHeader
```
public void setHeader(javax.servlet.http.HttpServletResponse response,
                      String name,
                      String value)
```
Add a header to the response after ensuring that there are no encoded or illegal characters in the name and value. "A recipient MAY replace any linear white space with a single SP before interpreting the field value or forwarding the message downstream." http://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2

Specified by:

setHeader in interface HTTPUtilities

setHeader
```
public void setHeader(String name,
                      String value)
```
Calls setHeader with the *current* response.

Specified by:

setHeader in interface HTTPUtilities

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

setNoCacheHeaders
```
public void setNoCacheHeaders()
```
Calls setNoCacheHeaders with the *current* response.

Specified by:

setNoCacheHeaders in interface HTTPUtilities

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

setNoCacheHeaders
```
public void setNoCacheHeaders(javax.servlet.http.HttpServletResponse response)
```
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 intended only for use in HTTP requests, not HTTP responses. However, Microsoft has chosen to directly violate the standards, so we need to include that header here. For more information, please refer to the relevant standards:
Specified by:

setNoCacheHeaders in interface HTTPUtilities

Parameters:

response -

setRememberToken
```
public String setRememberToken(javax.servlet.http.HttpServletRequest request,
                               javax.servlet.http.HttpServletResponse response,
                               String password,
                               int maxAge,
                               String domain,
                               String path)
```
Set a cookie containing the current User's remember me token for automatic authentication. The use of remember me tokens is generally 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.
Implementations should save the user's remember me data in an encrypted cookie and send it to the user. Any old remember me cookie should be destroyed first. Setting this cookie should keep the user logged in until the maxAge passes, the password is changed, or the cookie is deleted. If the cookie exists for the current user, it should automatically be used by ESAPI to log the user in, if the data is valid and not expired.
The ESAPI reference implementation, DefaultHTTPUtilities.setRememberToken() implements all these suggestions.
The username can be retrieved with: User username = ESAPI.authenticator().getCurrentUser(); ~DEPRECATED~ Per Kevin Wall, storing passwords with reversible encryption is contrary to *many* company's stated security policies. Save the user's remember me data in an encrypted cookie and send it to the user. Any old remember me cookie is destroyed first. Setting this cookie will keep the user logged in until the maxAge passes, the password is changed, or the cookie is deleted. If the cookie exists for the current user, it will automatically be used by ESAPI to log the user in, if the data is valid and not expired.

Specified by:

setRememberToken in interface HTTPUtilities

Parameters:

request -

response -

password - the user's password

maxAge - the length of time that the token should be valid for in relative seconds

domain - the domain to restrict the token to or null

path - the path to restrict the token to or null

Returns:

encrypted "Remember Me" token stored as a String

setRememberToken

public String setRememberToken(javax.servlet.http.HttpServletRequest request,
                               javax.servlet.http.HttpServletResponse response,
                               int maxAge,
                               String domain,
                               String path)

Specified by:: setRememberToken in interface HTTPUtilities

setRememberToken
```
public String setRememberToken(String password,
                               int maxAge,
                               String domain,
                               String path)
```
Calls setNoCacheHeaders with the *current* response. ~DEPRECATED~ Per Kevin Wall, storing passwords with reversible encryption is contrary to *many* company's stated security policies.

Specified by:

setRememberToken in interface HTTPUtilities

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

verifyCSRFToken
```
public void verifyCSRFToken()
                     throws IntrusionException
```
Calls verifyCSRFToken with the *current* request.

Specified by:

verifyCSRFToken in interface HTTPUtilities

Throws:

IntrusionException

See Also:

HTTPUtilities.setCurrentHTTP(HttpServletRequest, HttpServletResponse)

verifyCSRFToken
```
public void verifyCSRFToken(javax.servlet.http.HttpServletRequest request)
                     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. This implementation uses the CSRF_TOKEN_NAME parameter for the token.

Specified by:

verifyCSRFToken in interface HTTPUtilities

Parameters:

request -

Throws:

IntrusionException - if CSRF token is missing or incorrect

getSessionAttribute
```
public <T> T getSessionAttribute(String key)
```
Gets a typed attribute from the session associated with the calling thread. If the object referenced by the passed in key is not of the implied type, a ClassCastException will be thrown to the calling code.

Specified by:

getSessionAttribute in interface HTTPUtilities

Parameters:

key - The key that references the session attribute

Returns:

The requested object.

See Also:

HTTPUtilities.getSessionAttribute(javax.servlet.http.HttpSession, String)

getSessionAttribute
```
public <T> T getSessionAttribute(javax.servlet.http.HttpSession session,
                                 String key)
```
Gets a typed attribute from the passed in session. This method has the same responsibility as {link #getSessionAttribute(String} however it only references the passed in session and thus performs slightly better since it does not need to return to the Thread to get the HttpSession associated with the current thread.

Specified by:

getSessionAttribute in interface HTTPUtilities

Parameters:

session - The session to retrieve the attribute from

key - The key that references the requested object

Returns:

The requested object

getRequestAttribute
```
public <T> T getRequestAttribute(String key)
```
Gets a typed attribute from the HttpServletRequest associated with the caller thread. If the attribute on the request is not of the implied type, a ClassCastException will be thrown back to the caller.

Specified by:

getRequestAttribute in interface HTTPUtilities

Parameters:

key - The key that references the request attribute.

Returns:

The requested object

getRequestAttribute
```
public <T> T getRequestAttribute(javax.servlet.http.HttpServletRequest request,
                                 String key)
```
Gets a typed attribute from the HttpServletRequest associated with the passed in request. If the attribute on the request is not of the implied type, a ClassCastException will be thrown back to the caller.

Specified by:

getRequestAttribute in interface HTTPUtilities

Parameters:

request - The request to retrieve the attribute from

key - The key that references the request attribute.

Returns:

The requested object

Class DefaultHTTPUtilities

Field Summary

Fields inherited from interface org.owasp.esapi.HTTPUtilities

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DefaultHTTPUtilities

Method Detail

getInstance

addCookie

addCookie

addCSRFToken

addHeader

addHeader

assertSecureChannel

assertSecureChannel

assertSecureRequest

assertSecureRequest

changeSessionIdentifier

changeSessionIdentifier

clearCurrent

decryptHiddenField

decryptQueryString

decryptStateFromCookie

decryptStateFromCookie

encryptHiddenField

encryptQueryString

encryptStateInCookie

encryptStateInCookie

getCookie

getCookie

getCSRFToken

getCurrentRequest

getCurrentResponse

getFileUploads

getFileUploads

getFileUploads

getFileUploads

getHeader

getHeader

getParameter

getParameter

killAllCookies

killAllCookies

killCookie

killCookie

logHTTPRequest

logHTTPRequest

logHTTPRequest

sendForward

sendForward

sendRedirect

sendRedirect

setContentType

setContentType

setCurrentHTTP

setHeader

setHeader

setNoCacheHeaders

setNoCacheHeaders

setRememberToken

setRememberToken

setRememberToken

verifyCSRFToken

verifyCSRFToken

getSessionAttribute

getSessionAttribute

getRequestAttribute

getRequestAttribute