OWASP Java Encoder | OWASP Foundation
OWASP Java Encoder
About
The OWASP Java Encoder is a Java 1.8+ simple-to-use drop-in high-performance encoder class with no dependencies and little baggage. This project will help Java web developers defend against Cross Site Scripting!
Cross-Site Scripting (XSS) attacks are a type of injection, in which malicious scripts (primarily JavaScript) are injected into otherwise trusted web sites. One of the primary defenses to stop Cross Site Scripting is a technique called Contextual Output Encoding. WARNING: Please note that XSS prevention requires other defensive strategies besides encoding! For more information, please read the
Cross Site Scripting prevention cheatsheet
We actively track project issues and seek to remediate any issues that arise. The project owners feel this project is stable and ready for production use and are seeking project status promotion.
Happy Encoding!
Getting Started
The OWASP Java Encoder library is intended for quick contextual encoding with very little overhead, either in performance or usage. To get started, simply add the encoder-1.3.0.jar, import org.owasp.encoder.Encode and start encoding.
Please look at the javadoc for
Encode
, to see the variety of contexts for which you can encode. Tag libraries and JSP EL functions can be found in the encoder-jsp-1.3.0.jar.
Licensing
The OWASP Java Encoder is free to use under the New BSD License.
GitHub
Extensive documentation on how to use this project can be found in our
GitHub repository
Example
Put whatever you like here: news, screenshots, features, supporters, or remove this file and don’t use tabs at all.
How to Use the OWASP Java Encoder
The general API pattern is to utilize the Java Encoder Project in your
user interface code and wrap all variables added dynamically to HTML
with a proper encoding function. The encoding pattern is
“Encode.forContextName(untrustedData)”
, where “ContextName” is
the name of the target context and “untrustedData” is untrusted output.
Basic HTML Context
body
><%=
Encode
forHtml
UNTRUSTED
%>body
HTML Content Context
textarea
name
"text"
><%=
Encode
forHtmlContent
UNTRUSTED
%>textarea
HTML Attribute context
input
type
"text"
name
"address"
value
"<%= Encode.forHtmlAttribute(UNTRUSTED) %>"
/>
Generally
Encode.forHtml(UNTRUSTED)
is also safe but slightly
less efficient for the above two contexts (for textarea content and
input value text) since it encodes more characters than necessary but
might be easier for developers to use.
Encode URL parameter values
href
"/search?value=<%= Encode.forUriComponent(UNTRUSTED) %>&order=1#top"
Encode REST URL parameters
href
"/page/<%= Encode.forUriComponent(UNTRUSTED) %>"
Handling a Full Untrusted URL
When handling a full URL with the OWASP Java encoder, first validate to ensure the URL is in the format of a legal URL.
String
url
validateURL
untrustedInput
);
Then encode the URL as an HTML attribute when outputting to the page.
Note the linkable text needs to be encoded in a different context.
href
"<%= Encode.forHtmlAttribute(untrustedUrl) %>"
<%=
Encode
forHtmlContent
untrustedLinkName
%>
Javascript Block context
script
type
text/javascript
var
msg
<%= Encode.forJavaScriptBlock(UNTRUSTED) %>
alert
msg
);
/script
Javascript Variable context
button
onclick
"alert('<%= Encode.forJavaScriptAttribute(UNTRUSTED) %>');"
click
me
button
JavaScript Content Notes:
Encode.forJavaScript(UNTRUSTED)
is safe for the above two contexts, but encodes more characters and is less efficient.
CSS contexts
div
style
"width:<= Encode.forCssString(UNTRUSTED) %>"
div
style
"background:<= Encode.forCssUrl(UNTRUSTED) %>"
To use in a JSP with EL
Jakarta Servlet Spec
If using Jakarta Servlet Spec 5+ use the following dependency and taglib:
org.owasp.encoder
encoder-jakarta-jsp
1.3.0
<%@page
contentType=
"text/html;charset=UTF-8"
language=
"java"
%>
<%@taglib
prefix=
"c"
uri=
"jakarta.tags.core"
%>
<%@taglib
prefix=
"e"
uri=
"owasp.encoder.jakarta"
%>
${e:forHtml(param.data)}
Legacy Servlet Spec
If using legacy JSP (javax.servlet.jsp) use the following dependency and taglib:
org.owasp.encoder
encoder-jsp
1.3.0
<%@page
contentType="text/html" pageEncoding="UTF-8"
%>
DOCTYPE
HTML
PUBLIC
//
W3C
//
DTD
HTML
4.01
Transitional
//
EN
http:
//
www.w3.org
TR
html4
loose.dtd
<%@taglib
prefix="e" uri="https://www.owasp.org/index.php/OWASP_Java_Encoder_Project"
%>
${e:forHtml(param.data)}
How to Handle Numbers
Numbers don’t need encoding since they cannot cause XSS. There are no numbers that will break out of a javascript context.
If (and only if) ‘javaNumber’ is a numeric type (primitive or box wrapper), just use:
var
javaScriptNumber
<%=
javaNumber
%>
This is true even for the special cases of java.lang.Double.POSITIVE_INFINITY, NEGATIVE_INFINITY, NaN, and java.lang.Float equivalents.
On the other hand, if ‘javaNumber’ is some user provided data that is NOT a numeric type, then you should either (see option 1) convert it to a number on the java side, or (option 2) encode it to a string and handle it on the javascript side. E.g.
Option 1
<%
String
javaNumber
untrusted
data
);
Double
actualNumber
Double
parseDouble
javaNumber
);
//remember to catch NumberFormatException
%>
script
var
jsNumber
<%=
actualNumber
%>
/script
Option 2
<%
String
javaNumber
untrusted
data
);
%>
script
var
jsNumber
parseInt
<%=Encode.forJavaScript(javaNumber)%>
);
/script
Grave Accent Issue
The following describes the Grave Accent XSS issue with unpatched versions of Internet Explorer. Thank you to
Rafay Baloch
for bringing this to our attention and to
Jeff Ichnowski
for the workaround.
Introduction
The grave accent (`), ASCII 96, hex 60 (
wikipedia
) is subject to a critical flaw in unpatched Internet Explorer. There is no possible encoding of the character that can avoid the issue. For a more in depth presentation on the issue discussed herein, please see
Mario Heidrech’s presentation
Background
In Internet Explorer, the grave accent is usable as an HTML attribute quotation character, equivalent to single and double quotes.
Specifically, IE treats the following as equivalent:
"this is the value"
`this is the value`
It is an IE extension, is not in HTML specifications
HTML4
HTML5
), and is probably not well supported in other browsers.
The Issue
The following HTML snippet, demonstrates the cross-site scripting vulnerability related to grave accents on unpatched Internet Explorer:
"``onmouseover=alert(1)"