org.owasp.esapi
Interface HTTPUtilities

All Known Implementing Classes:

DefaultHTTPUtilities

public interface HTTPUtilities

The HTTPUtilities 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

Field Summary

static int	COOKIE
static java.lang.String	CSRF_TOKEN_NAME
static java.lang.String	ESAPI_STATE
static int	HEADER
static int	MAX_COOKIE_LEN
static int	MAX_COOKIE_PAIRS
static int	PARAMETER
static java.lang.String	REMEMBER_TOKEN_COOKIE_NAME

Method Summary

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.
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.
void	addHeader(javax.servlet.http.HttpServletResponse response, java.lang.String name, java.lang.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(java.lang.String name, java.lang.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.
java.lang.String	decryptHiddenField(java.lang.String encrypted) Decrypts an encrypted hidden field value and returns the cleartext.
java.util.Map<java.lang.String,java.lang.String>	decryptQueryString(java.lang.String encrypted) Takes an encrypted querystring and returns a Map containing the original parameters.
java.util.Map<java.lang.String,java.lang.String>	decryptStateFromCookie() Calls decryptStateFromCookie with the *current* request.
java.util.Map<java.lang.String,java.lang.String>	decryptStateFromCookie(javax.servlet.http.HttpServletRequest request) Retrieves a map of data from a cookie encrypted with encryptStateInCookie().
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 (everything after the question mark in the URL) and returns an encrypted string containing the parameters.
void	encryptStateInCookie(javax.servlet.http.HttpServletResponse response, java.util.Map<java.lang.String,java.lang.String> cleartext) Stores a Map of data in an encrypted cookie.
void	encryptStateInCookie(java.util.Map<java.lang.String,java.lang.String> cleartext) Calls encryptStateInCookie with the *current* response.
java.lang.String	getCookie(javax.servlet.http.HttpServletRequest request, java.lang.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.
java.lang.String	getCookie(java.lang.String name) Calls getCookie with the *current* response.
java.lang.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
java.util.List	getFileUploads() Calls getFileUploads with the *current* request, default upload directory, and default allowed file extensions
java.util.List	getFileUploads(javax.servlet.http.HttpServletRequest request) Call getFileUploads with the specified request, default upload directory, and default allowed file extensions
java.util.List	getFileUploads(javax.servlet.http.HttpServletRequest request, java.io.File finalDir) Call getFileUploads with the specified request, specified upload directory, and default allowed file extensions
java.util.List	getFileUploads(javax.servlet.http.HttpServletRequest request, java.io.File destinationDir, java.util.List allowedExtensions) Extract uploaded files from a multipart HTTP requests.
java.lang.String	getHeader(javax.servlet.http.HttpServletRequest request, java.lang.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.
java.lang.String	getHeader(java.lang.String name) Calls getHeader with the *current* request.
java.lang.String	getParameter(javax.servlet.http.HttpServletRequest request, java.lang.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.
java.lang.String	getParameter(java.lang.String name) Calls getParameter with the *current* request.
<T> T	getRequestAttribute(javax.servlet.http.HttpServletRequest request, java.lang.String key) Gets a typed attribute from the HttpServletRequest associated with the passed in request.
<T> T	getRequestAttribute(java.lang.String key) Gets a typed attribute from the HttpServletRequest associated with the caller thread.
<T> T	getSessionAttribute(javax.servlet.http.HttpSession session, java.lang.String key) Gets a typed attribute from the passed in session.
<T> T	getSessionAttribute(java.lang.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, java.lang.String name) Kills the specified cookie by setting a new cookie that expires immediately.
void	killCookie(java.lang.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, 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	sendForward(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.String location) This method performs a forward to any resource located inside the WEB-INF directory.
void	sendForward(java.lang.String location) Calls sendForward with the *current* request and response.
void	sendRedirect(javax.servlet.http.HttpServletResponse response, java.lang.String location) This method performs a forward to any resource located inside the WEB-INF directory.
void	sendRedirect(java.lang.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, java.lang.String name, java.lang.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(java.lang.String name, java.lang.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.
java.lang.String	setRememberToken(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.String password, int maxAge, java.lang.String domain, java.lang.String path) Set a cookie containing the current User's remember me token for automatic authentication.
java.lang.String	setRememberToken(java.lang.String password, int maxAge, java.lang.String domain, java.lang.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.

Field Detail

REMEMBER_TOKEN_COOKIE_NAME

static final java.lang.String REMEMBER_TOKEN_COOKIE_NAME

See Also:

Constant Field Values

MAX_COOKIE_LEN

static final int MAX_COOKIE_LEN

See Also:

Constant Field Values

MAX_COOKIE_PAIRS

static final int MAX_COOKIE_PAIRS

See Also:

Constant Field Values

CSRF_TOKEN_NAME

static final java.lang.String CSRF_TOKEN_NAME

See Also:

Constant Field Values

ESAPI_STATE

static final java.lang.String ESAPI_STATE

See Also:

Constant Field Values

PARAMETER

static final int PARAMETER

See Also:

Constant Field Values

HEADER

static final int HEADER

See Also:

Constant Field Values

COOKIE

static final int COOKIE

See Also:

Constant Field Values

Method Detail

addCookie

void addCookie(javax.servlet.http.Cookie cookie)

Calls addCookie with the *current* request.

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

addCookie

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.

Parameters:

cookie -

addCSRFToken

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.

Parameters:

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

Returns:

the updated URL with the CSRF token parameter added

addHeader

void addHeader(java.lang.String name,
               java.lang.String value)

Calls addHeader with the *current* request.

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

addHeader

void addHeader(javax.servlet.http.HttpServletResponse response,
               java.lang.String name,
               java.lang.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

Parameters:

name -

value -

assertSecureRequest

void assertSecureRequest()
                         throws AccessControlException

Calls assertSecureRequest with the *current* request.

Throws:

AccessControlException

See Also:

HTTPUtilities#assertSecureRequest(HttpServletRequest)}, HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

assertSecureChannel

void assertSecureChannel()
                         throws AccessControlException

Calls assertSecureChannel with the *current* request.

Throws:

AccessControlException

See Also:

HTTPUtilities#assertSecureChannel(HttpServletRequest)}, HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

assertSecureRequest

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.

Parameters:

request -

Throws:

AccessControlException - if security constraints are not met

assertSecureChannel

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.

Parameters:

request -

Throws:

AccessControlException - if security constraints are not met

changeSessionIdentifier

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

Calls changeSessionIdentifier with the *current* request.

Throws:

AuthenticationException

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

changeSessionIdentifier

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.

Parameters:

request -

Returns:

the new HttpSession with a changed id

Throws:

AuthenticationException - the exception

clearCurrent

void clearCurrent()

Clears the current HttpRequest and HttpResponse associated with the current thread.

See Also:

ESAPI.clearCurrent()

decryptHiddenField

java.lang.String decryptHiddenField(java.lang.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.

Parameters:

encrypted - hidden field value to decrypt

Returns:

decrypted hidden field value stored as a String

decryptQueryString

java.util.Map<java.lang.String,java.lang.String> decryptQueryString(java.lang.String encrypted)
                                                                    throws EncryptionException

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

Parameters:

encrypted - the encrypted querystring to decrypt

Returns:

a Map object containing the decrypted querystring

Throws:

EncryptionException

decryptStateFromCookie

java.util.Map<java.lang.String,java.lang.String> decryptStateFromCookie()
                                                                        throws EncryptionException

Calls decryptStateFromCookie with the *current* request.

Throws:

EncryptionException

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

decryptStateFromCookie

java.util.Map<java.lang.String,java.lang.String> decryptStateFromCookie(javax.servlet.http.HttpServletRequest request)
                                                                        throws EncryptionException

Retrieves a map of data from a cookie encrypted with encryptStateInCookie().

Parameters:

request -

Returns:

a map containing the decrypted cookie state value

Throws:

EncryptionException

encryptHiddenField

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

Encrypts a hidden field value for use in HTML.

Parameters:

value - the cleartext value of the hidden field

Returns:

the encrypted value of the hidden field

Throws:

EncryptionException

encryptQueryString

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

Takes a querystring (everything after the question mark in the URL) and returns an encrypted string containing the parameters.

Parameters:

query - the querystring to encrypt

Returns:

encrypted querystring stored as a String

Throws:

EncryptionException

encryptStateInCookie

void encryptStateInCookie(java.util.Map<java.lang.String,java.lang.String> cleartext)
                          throws EncryptionException

Calls encryptStateInCookie with the *current* response.

Throws:

EncryptionException

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

encryptStateInCookie

void encryptStateInCookie(javax.servlet.http.HttpServletResponse response,
                          java.util.Map<java.lang.String,java.lang.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.

Parameters:

response -

cleartext -

Throws:

EncryptionException

getCookie

java.lang.String getCookie(java.lang.String name)
                           throws ValidationException

Calls getCookie with the *current* response.

Throws:

ValidationException

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

getCookie

java.lang.String getCookie(javax.servlet.http.HttpServletRequest request,
                           java.lang.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.

Parameters:

request -

name -

Returns:

the requested cookie value

Throws:

ValidationException

getCSRFToken

java.lang.String getCSRFToken()

Returns the current user's CSRF token. If there is no current user then return null.

Returns:

the current users CSRF token

getCurrentRequest

javax.servlet.http.HttpServletRequest getCurrentRequest()

Retrieves the current HttpServletRequest

Returns:

the current request

getCurrentResponse

javax.servlet.http.HttpServletResponse getCurrentResponse()

Retrieves the current HttpServletResponse

Returns:

the current response

getFileUploads

java.util.List getFileUploads()
                              throws ValidationException

Calls getFileUploads with the *current* request, default upload directory, and default allowed file extensions

Throws:

ValidationException

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

getFileUploads

java.util.List getFileUploads(javax.servlet.http.HttpServletRequest request)
                              throws ValidationException

Call getFileUploads with the specified request, default upload directory, and default allowed file extensions

Throws:

ValidationException

getFileUploads

java.util.List getFileUploads(javax.servlet.http.HttpServletRequest request,
                              java.io.File finalDir)
                              throws ValidationException

Call getFileUploads with the specified request, specified upload directory, and default allowed file extensions

Throws:

ValidationException

getFileUploads

java.util.List getFileUploads(javax.servlet.http.HttpServletRequest request,
                              java.io.File destinationDir,
                              java.util.List allowedExtensions)
                              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 Validator for more information.

This method uses getCurrentRequest() to obtain the HttpServletRequest object

Parameters:

request -

Returns:

List of new File objects from upload

Throws:

ValidationException - if the file fails validation

getHeader

java.lang.String getHeader(java.lang.String name)
                           throws ValidationException

Calls getHeader with the *current* request.

Throws:

ValidationException

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

getHeader

java.lang.String getHeader(javax.servlet.http.HttpServletRequest request,
                           java.lang.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.

Parameters:

request -

name -

Returns:

the requested header value

Throws:

ValidationException

getParameter

java.lang.String getParameter(java.lang.String name)
                              throws ValidationException

Calls getParameter with the *current* request.

Throws:

ValidationException

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

getParameter

java.lang.String getParameter(javax.servlet.http.HttpServletRequest request,
                              java.lang.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.

Parameters:

request -

name -

Returns:

the requested parameter value

Throws:

ValidationException

killAllCookies

void killAllCookies()

Calls killAllCookies with the *current* request and response.

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

killAllCookies

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.

Parameters:

request -

response -

killCookie

void killCookie(java.lang.String name)

Calls killCookie with the *current* request and response.

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

killCookie

void killCookie(javax.servlet.http.HttpServletRequest request,
                javax.servlet.http.HttpServletResponse response,
                java.lang.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.

Parameters:

request -

name -

response -

logHTTPRequest

void logHTTPRequest()

Calls logHTTPRequest with the *current* request and logger.

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

logHTTPRequest

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.

Parameters:

request -

logger - the logger to write the request to

logHTTPRequest

void logHTTPRequest(javax.servlet.http.HttpServletRequest request,
                    Logger 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. If HTTP request logging is done in a central place, the parameterNamesToObfuscate could be made a configuration parameter. We include it here in case different parts of the application need to obfuscate different parameters.

Parameters:

request -

logger - the logger to write the request to

parameterNamesToObfuscate - the sensitive parameters

sendForward

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

Calls sendForward with the *current* request and response.

Throws:

AccessControlException

javax.servlet.ServletException

java.io.IOException

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

sendForward

void sendForward(javax.servlet.http.HttpServletRequest request,
                 javax.servlet.http.HttpServletResponse response,
                 java.lang.String location)
                 throws AccessControlException,
                        javax.servlet.ServletException,
                        java.io.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.

Parameters:

request -

response -

location - the URL to forward to, including parameters

Throws:

AccessControlException

javax.servlet.ServletException

java.io.IOException

sendRedirect

void sendRedirect(java.lang.String location)
                  throws AccessControlException,
                         java.io.IOException

Calls sendRedirect with the *current* response.

Throws:

AccessControlException

java.io.IOException

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

sendRedirect

void sendRedirect(javax.servlet.http.HttpServletResponse response,
                  java.lang.String location)
                  throws AccessControlException,
                         java.io.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.

Parameters:

response -

location - the URL to forward to, including parameters

Throws:

AccessControlException

javax.servlet.ServletException

java.io.IOException

setContentType

void setContentType()

Calls setContentType with the *current* request and response.

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

setContentType

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.

Parameters:

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

setCurrentHTTP

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

setHeader

void setHeader(java.lang.String name,
               java.lang.String value)

Calls setHeader with the *current* response.

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

setHeader

void setHeader(javax.servlet.http.HttpServletResponse response,
               java.lang.String name,
               java.lang.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

Parameters:

name -

value -

setNoCacheHeaders

void setNoCacheHeaders()

Calls setNoCacheHeaders with the *current* response.

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

setNoCacheHeaders

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:

• 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
• Microsoft directly violates specification for pragma: no-cache
• Mozilla

Parameters:

response -

setRememberToken

java.lang.String setRememberToken(java.lang.String password,
                                  int maxAge,
                                  java.lang.String domain,
                                  java.lang.String path)

Calls setNoCacheHeaders with the *current* response.

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

setRememberToken

java.lang.String setRememberToken(javax.servlet.http.HttpServletRequest request,
                                  javax.servlet.http.HttpServletResponse response,
                                  java.lang.String password,
                                  int maxAge,
                                  java.lang.String domain,
                                  java.lang.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();

Parameters:

request -

password - the user's password

response -

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

verifyCSRFToken

void verifyCSRFToken()

Calls verifyCSRFToken with the *current* request.

See Also:

HTTPUtilities#setCurrentHTTP(HttpServletRequest, HttpServletResponse)}

verifyCSRFToken

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.

Parameters:

request -

Throws:

IntrusionException - if CSRF token is missing or incorrect

getSessionAttribute

<T> T getSessionAttribute(java.lang.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.

Type Parameters:

T - The implied type of object expected.

Parameters:

key - The key that references the session attribute

Returns:

The requested object.

See Also:

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

getSessionAttribute

<T> T getSessionAttribute(javax.servlet.http.HttpSession session,
                          java.lang.String key)

Gets a typed attribute from the passed in session. This method has the same responsibility as {link #getSessionAttribute(String} however only it 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.

Type Parameters:

T - The implied type of object expected

Parameters:

session - The session to retrieve the attribute from

key - The key that references the requested object

Returns:

The requested object

getRequestAttribute

<T> T getRequestAttribute(java.lang.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.

Type Parameters:

T - The implied type of the object expected

Parameters:

key - The key that references the request attribute.

Returns:

The requested object

getRequestAttribute

<T> T getRequestAttribute(javax.servlet.http.HttpServletRequest request,
                          java.lang.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.

Type Parameters:

T - The implied type of the object expected

Parameters:

request - The request to retrieve the attribute from

key - The key that references the request attribute.

Returns:

The requested object