hirondelle.web4j.security
Class SafeText

Object
  hirondelle.web4j.security.SafeText

All Implemented Interfaces:

Serializable, Comparable<SafeText>

public final class SafeText
extends Object
implements Serializable, Comparable<SafeText>

Models free-form text entered by the user, and protects your application from Cross Site Scripting (XSS).

Free-form text refers to text entered by the end user. It differs from other data in that its content is not tightly constrained. Examples of free-form text might include a user name, a description of something, a comment, and so on. If you model free-form text as a simple String, then when presenting that text in a web page, you must take special precautions against Cross Site Scripting attacks, by escaping special characters. When modeling such data as SafeText, however, such special steps are not needed, since the escaping is built directly into its toString() method.

It is worth noting that there are two defects with JSTL' s handling of this problem :

• the <c:out> tag escapes only 5 of the 12 special characters identified by the Open Web App Security Project as being a concern.
• used in a JSP, the Expression Language allows pleasingly concise presentation, but does not escape special characters in any way. Even when one is aware of this, it is easy to forget to take precautions against Cross Site Scripting attacks.

Using SafeText will protect you from both of these defects. Since the correct escaping is built into toString(), you may freely use JSP Expression Language, without needing to do any escaping in the view. Note that if you use <c:out> with SafeText (not recommeded), then you must use escapeXml='false' to avoid double-escaping of special characters.

There are various ways of presenting text :

• as HTML (most common) - use toString() to escape a large number of special characters.
• as XML - use getXmlSafe() to escape 5 special characters.
• as JavaScript Object Notation (JSON) - use getJsonSafe() to escape a number of special characters
• as plain text - use getRawString() to do no escaping at all.

Checking For Vulnerabilities Upon Startup

WEB4J will perform checks for Cross-Site Scripting vulnerabilities upon startup, by scanning your application's classes for public Model Objects having public getXXX methods that return a String. It will log such occurrences to encourage you to investigate them further.

Design Notes :
This class is final, immutable, Serializable, and Comparable, in imitation of the other building block classes such as String, Integer, and so on.

The reason why protection against Cross-Site Scripting is not implemented as a Servlet Filter is because a filter would have no means of distinguishing between safe and unsafe markup.

One might object to escaping special characters in the Model, instead of in the View. However, from a practical point of view, it seems more likely that the programmer will remember to use SafeText once in the Model, than remember to do the escaping repeatedly in the View.

See Also:

Serialized Form

Constructor Summary

SafeText(String aText)
Constructor.

Method Summary

int	compareTo(SafeText aThat)
boolean	equals(Object aThat)
static SafeText	from(String aText) Factory method.
String	getJsonSafe() Return the text in a form safe for JSON (JavaScript Object Notation) data.
String	getRawString() Return the (trimmed) text passed to the constructor.
String	getXmlSafe() Return the text in a form safe for an XML element.
int	hashCode()
static boolean	isEscaped(int aCodePoint) Returns true only if the given character is always escaped by toString().
String	toString() Return the text in a form safe for an HTML document.

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SafeText

public SafeText(String aText)

Constructor.

Parameters:

aText - free-form text input by the end user, which may contain Cross Site Scripting attacks. Non-null. The text is trimmed by this constructor.

Method Detail

isEscaped

public static boolean isEscaped(int aCodePoint)

Returns true only if the given character is always escaped by toString(). For the list of characters, see EscapeChars.forHTML(String).

Recommended that your implementation of PermittedCharacters use this method. This will allow you to accept many special characters in your list of permissible characters.

from

public static SafeText from(String aText)

Factory method. Simply a slightly more compact way of building an object, as opposed to 'new'.

toString

public String toString()

Return the text in a form safe for an HTML document. Passes the raw text through EscapeChars.forHTML(String).

Overrides:

toString in class Object

getRawString

public String getRawString()

Return the (trimmed) text passed to the constructor.

getXmlSafe

public String getXmlSafe()

Return the text in a form safe for an XML element.

Arbitrary text can be rendered safely in an XML document in two ways :

• using a CDATA block
• escaping special characters &, <, >, ", '.

This method will escape the above five special characters, and replace them with character entities, using EscapeChars.forXML(String)

getJsonSafe

public String getJsonSafe()

Return the text in a form safe for JSON (JavaScript Object Notation) data.

This method is intended for the data elements of JSON. It is intended for values of things, not for their names. Typically, only the values will come from end user input, while the names will be hard-coded.

equals

public boolean equals(Object aThat)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

compareTo

public int compareTo(SafeText aThat)

Specified by:

compareTo in interface Comparable<SafeText>