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>

Protects your application from Cross Site Scripting (XSS); models free-form text entered by the user.

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 in to 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, then you must use escapeXml='false' to avoid double-escaping of special characters.

There are typically three ways of presenting text :

• as HTML (most common) - use toString() to escape 12 special characters.
• as XML - use getXmlSafe() to escape 5 special characters.
• as plain text - use getRawString() to do no escaping at all.

Search Forms

Search forms represent an interesting exception. If the search criteria are presented only in the search form itself, then a package-private Model Object can be used to represent user input. Since it is package-private, it is simply not possible to render such objects in a JSP (since JSPs can only use public Model Objects). Hence, it is perfectly safe for such a Model Object to use a String, and not SafeText, if desired, since it will never be rendered in a JSP.

Checking For Vulnerabilities Upon Startup

The full version of 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 in the Model, than remember to do the escaping (using some other tool) in the View.

See Also:

Serialized Form

Constructor Summary

SafeText(String aText)
Constructor.

Method Summary

int	compareTo(SafeText aThat)
boolean	equals(Object aThat)
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()
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

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)

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>