public interface HTTPUtilities
Note: This most of the methods in this interface NOT compatible with the Jakarta Servlet API Spec 5.0 or later, which uses the jakarta.servlet package namespace rather than the javax.servlet package namespace. For further details, please see the GitHub Discussion issue Add support for Jakarta Servlet API Specification #768.
Modifier and Type | Field and Description |
---|---|
static int |
COOKIE |
static String |
CSRF_TOKEN_NAME |
static String |
ESAPI_STATE |
static int |
HEADER |
static int |
MAX_COOKIE_LEN |
static int |
MAX_COOKIE_PAIRS |
static int |
PARAMETER |
static String |
REMEMBER_TOKEN_COOKIE_NAME |
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 |
getFileUploads()
Calls
getFileUploads with the current request, default upload directory, and default allowed file extensions |
List |
getFileUploads(javax.servlet.http.HttpServletRequest request)
Call
getFileUploads with the specified request, default upload directory, and default allowed file extensions |
List |
getFileUploads(javax.servlet.http.HttpServletRequest request,
File finalDir)
Call
getFileUploads with the specified request, specified upload directory, and default allowed file extensions |
List |
getFileUploads(javax.servlet.http.HttpServletRequest request,
File destinationDir,
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.
|
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)
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,
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)
Deprecated.
|
String |
setRememberToken(String password,
int maxAge,
String domain,
String path)
Deprecated.
|
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.
|
static final String REMEMBER_TOKEN_COOKIE_NAME
static final int MAX_COOKIE_LEN
static final int MAX_COOKIE_PAIRS
static final String CSRF_TOKEN_NAME
static final String ESAPI_STATE
static final int PARAMETER
static final int HEADER
static final int COOKIE
void addCookie(javax.servlet.http.Cookie cookie)
cookie
- The cookie to addsetCurrentHTTP(HttpServletRequest, HttpServletResponse)
void addCookie(javax.servlet.http.HttpServletResponse response, javax.servlet.http.Cookie cookie)
response
- The HTTP response to add the cookie tocookie
- The cookie to addString addCSRFToken(String href)
href
- the URL to which the CSRF token will be appendedvoid addHeader(javax.servlet.http.HttpServletResponse response, String name, String value)
name
- value
- void assertSecureRequest() throws AccessControlException
void assertSecureChannel() throws AccessControlException
void assertSecureRequest(javax.servlet.http.HttpServletRequest request) throws AccessControlException
request
- AccessControlException
- if security constraints are not metvoid assertSecureChannel(javax.servlet.http.HttpServletRequest request) throws AccessControlException
request
- AccessControlException
- if security constraints are not metjavax.servlet.http.HttpSession changeSessionIdentifier() throws AuthenticationException
javax.servlet.http.HttpSession changeSessionIdentifier(javax.servlet.http.HttpServletRequest request) throws AuthenticationException
request
- AuthenticationException
- the exceptionvoid clearCurrent()
ESAPI.clearCurrent()
String decryptHiddenField(String encrypted)
encrypted
- hidden field value to decryptMap<String,String> decryptQueryString(String encrypted) throws EncryptionException
encrypted
- the encrypted querystring to decryptEncryptionException
Map<String,String> decryptStateFromCookie() throws EncryptionException
EncryptionException
setCurrentHTTP(HttpServletRequest, HttpServletResponse)
Map<String,String> decryptStateFromCookie(javax.servlet.http.HttpServletRequest request) throws EncryptionException
request
- EncryptionException
String encryptHiddenField(String value) throws EncryptionException
value
- the cleartext value of the hidden fieldEncryptionException
String encryptQueryString(String query) throws EncryptionException
query
- the querystring to encryptEncryptionException
void encryptStateInCookie(Map<String,String> cleartext) throws EncryptionException
EncryptionException
setCurrentHTTP(HttpServletRequest, HttpServletResponse)
void encryptStateInCookie(javax.servlet.http.HttpServletResponse response, Map<String,String> cleartext) throws EncryptionException
response
- cleartext
- EncryptionException
String getCookie(String name) throws ValidationException
name
- The cookie to getValidationException
setCurrentHTTP(HttpServletRequest, HttpServletResponse)
String getCookie(javax.servlet.http.HttpServletRequest request, String name) throws ValidationException
request
- name
- The cookie to getValidationException
String getCSRFToken()
javax.servlet.http.HttpServletRequest getCurrentRequest()
javax.servlet.http.HttpServletResponse getCurrentResponse()
List getFileUploads() throws ValidationException
getFileUploads
with the current request, default upload directory, and default allowed file extensionsValidationException
- if the file fails validationsetCurrentHTTP(HttpServletRequest, HttpServletResponse)
List getFileUploads(javax.servlet.http.HttpServletRequest request) throws ValidationException
getFileUploads
with the specified request, default upload directory, and default allowed file extensionsrequest
- The applicable HTTP requestValidationException
- if the file fails validationList getFileUploads(javax.servlet.http.HttpServletRequest request, File finalDir) throws ValidationException
getFileUploads
with the specified request, specified upload directory, and default allowed file extensionsrequest
- The applicable HTTP requestfinalDir
- The destination directory to leave the uploaded file(s) in.ValidationException
- if the file fails validationList getFileUploads(javax.servlet.http.HttpServletRequest request, File destinationDir, List allowedExtensions) throws ValidationException
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 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
reasource that you may find usefule are:
request
- The applicable HTTP requestdestinationDir
- 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.)File
objects from uploadValidationException
- if the file fails validationAccessControlException
- If anonymous users are not allowed and the user is
not authenticated as per the ESAPI Authenticator
.String getHeader(String name) throws ValidationException
ValidationException
setCurrentHTTP(HttpServletRequest, HttpServletResponse)
String getHeader(javax.servlet.http.HttpServletRequest request, String name) throws ValidationException
request
- name
- ValidationException
String getParameter(String name) throws ValidationException
ValidationException
setCurrentHTTP(HttpServletRequest, HttpServletResponse)
String getParameter(javax.servlet.http.HttpServletRequest request, String name) throws ValidationException
request
- name
- ValidationException
void killAllCookies()
void killAllCookies(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
request
- response
- void killCookie(String name)
void killCookie(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, String name)
request
- name
- response
- void logHTTPRequest()
void logHTTPRequest(javax.servlet.http.HttpServletRequest request, Logger logger)
request
- logger
- the logger to write the request tovoid logHTTPRequest(javax.servlet.http.HttpServletRequest request, Logger logger, List parameterNamesToObfuscate)
request
- The HTTP request to loglogger
- the logger to write the request toparameterNamesToObfuscate
- the sensitive parametersvoid sendForward(String location) throws AccessControlException, javax.servlet.ServletException, IOException
AccessControlException
javax.servlet.ServletException
IOException
setCurrentHTTP(HttpServletRequest, HttpServletResponse)
void sendForward(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, String location) throws AccessControlException, javax.servlet.ServletException, IOException
request
- response
- location
- the URL to forward to, including parametersAccessControlException
javax.servlet.ServletException
IOException
void sendRedirect(String location) throws AccessControlException, IOException
void sendRedirect(javax.servlet.http.HttpServletResponse response, String location) throws AccessControlException, IOException
response
- location
- the URL to forward to, including parametersAccessControlException
IOException
void setContentType()
void setContentType(javax.servlet.http.HttpServletResponse response)
response
- The servlet response to set the content type for.void setCurrentHTTP(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
request
- the current requestresponse
- the current responsevoid setHeader(javax.servlet.http.HttpServletResponse response, String name, String value)
name
- value
- void setNoCacheHeaders()
void setNoCacheHeaders(javax.servlet.http.HttpServletResponse response)
Cache-Control: no-storeNote 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:
Cache-Control: no-cache
Cache-Control: must-revalidate
Expires: -1
response
- @Deprecated String setRememberToken(String password, int maxAge, String domain, String path)
String setRememberToken(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, int maxAge, String domain, String path)
@Deprecated String setRememberToken(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, String password, int maxAge, String domain, String path)
request
- password
- the user's passwordresponse
- maxAge
- the length of time that the token should be valid for in relative secondsdomain
- the domain to restrict the token to or nullpath
- the path to restrict the token to or nullvoid verifyCSRFToken()
void verifyCSRFToken(javax.servlet.http.HttpServletRequest request) throws IntrusionException
request
- IntrusionException
- if CSRF token is missing or incorrect<T> T getSessionAttribute(String key)
key
- The key that references the session attributegetSessionAttribute(javax.servlet.http.HttpSession, String)
<T> T getSessionAttribute(javax.servlet.http.HttpSession session, String key)
HttpSession
associated with the current
thread.session
- The session to retrieve the attribute fromkey
- The key that references the requested object<T> T getRequestAttribute(String key)
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.key
- The key that references the request attribute.<T> T getRequestAttribute(javax.servlet.http.HttpServletRequest request, String key)
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.request
- The request to retrieve the attribute fromkey
- The key that references the request attribute.Copyright © 2023 The Open Worldwide Application Security Project (OWASP). All rights reserved.