com.coverity.security

Class Escape

java.lang.Object

com.coverity.security.Escape

public class Escape
extends Object

Escape is a small set of methods for escaping tainted data. These escaping methods are useful in transforming user-controlled ("tainted") data into forms that are safe from being interpreted as something other than data, such as JavaScript.

At this time most of these escaping routines focus on cross-site scripting mitigations. Each method is good for a different HTML context. For a primer on HTML contexts, see OWASP's XSS Prevention Cheat Sheet (note however that the escaping routines are not implemented exactly according to OWASP's recommendations) or the Coverity Security Advisor documentation. Also see the Coverity Security Research Laboratory blog on how to properly use each function.

While Coverity's static analysis product references these escaping routines as exemplars and understands their behavior, there is no dependency on Coverity products and these routines are completely standalone. Feel free to use them! Just make sure you use them correctly.

Author:

Romain Gaucher, Andy Chou, Jon Passki

Constructor Summary

Constructors

Constructor and Description
Escape()

Method Summary

Methods

Modifier and Type	Method and Description
static String	cssString(String input) CSS String escaper.
static String	html(String input) HTML entity escaping for text content and attributes.
static String	htmlText(String input) Faster HTML entity escaping for tag content or quoted attributes values only.
static String	jsRegex(String input) JavaScript regex content escaper.
static String	jsString(String input) JavaScript String Unicode escaper.
static String	sqlLikeClause(String input) SQL LIKE clause escaper.
static String	sqlLikeClause(String input, char escape) SQL LIKE clause escaper.
static String	uri(String input) Same as uriParam(String) for now.
static String	uriParam(String input) URI encoder.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Escape

public Escape()

Method Detail

html

public static String html(String input)

HTML entity escaping for text content and attributes.

HTML entity escaping that is appropriate for the most common HTML contexts: PCDATA and "normal" attributes (non-URI, non-event, and non-CSS attributes).
Note that we do not recommend using non-quoted HTML attributes since the security obligations vary more between web browser. We recommend to always quote (single or double quotes) HTML attributes.
This method is generic to HTML entity escaping, and therefore escapes more characters than usually necessary -- mostly to handle non-quoted attribute values. If this method is somehow too slow, such as you output megabytes of text with spaces, please use the htmlText(String) method which only escape HTML text specific characters.

The following characters are escaped:

• HTML characters: ' (U+0022), " (U+0027), \ (U+005C), / (U+002F), < (U+003C), > (U+003E), & (U+0026)
• Control characters: \t (U+0009), \n (U+000A), \f (U+000C), \r (U+000D), SPACE (U+0020)
• Unicode newlines: LS (U+2028), PS (U+2029)

Parameters:

input - the string to be escaped

Returns:

the HTML escaped string or null if input is null

Since:

1.0

htmlText

public static String htmlText(String input)

Faster HTML entity escaping for tag content or quoted attributes values only.

HTML entity escaping that is specific to text elements such as the content of a typical HTML tag (div, p, etc.).
This method is not appropriate in all cases, and especially when appending data in a non-quoted context (e.g., an HTML attribute value that is not surrounded by single or double quotes). Note that we however, highly discourage the use of non-quoted attributes.

The following characters are escaped:

• HTML characters: ' (U+0022), " (U+0027), < (U+003C), > (U+003E), & (U+0026)

Parameters:

input - the string to be escaped

Returns:

the HTML escaped string or null if input is null

Since:

1.0

uriParam

public static String uriParam(String input)

URI encoder.

URI encoding for query string values of the URI: /example/?name=URI_ENCODED_VALUE_HERE
Note that this method is not sufficient to protect for cross-site scripting in a generic URI context, but only for query string values. If you need to escape a URI in an href attribute (for example), ensure that:

• The scheme is allowed (restrict to http, https, or mailto)
• Use the HTML escaper html(String) on the entire URI

This URI encoder processes the following characters:

• URI characters: ' (U+0022), " (U+0027), \ (U+005C), / (U+002F), < (U+003C), > (U+003E), & (U+0026), < (U+003C), > (U+003E), ! (U+0021), # (U+0023), $ (U+0024), % (U+0025), ( (U+0028), ) (U+0029), * (U+002A), + (U+002B), , (U+002C), . (U+002E), : (U+003A), ; (U+003B), = (U+003D), ? (U+003F), @ (U+0040), [ (U+005B), ] (U+005D)
• Control characters: \t (U+0009), \n (U+000A), \f (U+000C), \r (U+000D), SPACE (U+0020)

Parameters:

input - the string to be escaped

Returns:

the URI encoded string or null if input is null

Since:

1.0

uri

public static String uri(String input)

Same as uriParam(String) for now.

Eventually, this method will evolve into filtering the URI so that it is safely considered as a URL by a web browser, and does not contain malicious payloads (data:text/html..., javascript:, etc.).

jsString

public static String jsString(String input)

JavaScript String Unicode escaper.

JavaScript String Unicode escaping (\UXXXX) to be used in single or double quoted JavaScript strings:

 <script type="text/javascript">
   window.myString = 'JS_STRING_ESCAPE_HERE';
   window.yourString = "JS_STRING_ESCAPE_HERE";
 </script>
 

This JavaScript string escaper processes the following characters:

• JS String characters: ' (U+0022), " (U+0027), \ (U+005C)
• URI encoding characters: % (U+0025)
• HTML characters: / (U+002F), < (U+003C), > (U+003E), & (U+0026)
• Control characters: \b (U+0008), \t (U+0009), \n (U+000A), 0x0b (U+000B), \f (U+000C), \r (U+000D)
• Unicode newlines: LS (U+2028), PS (U+2029)

Parameters:

input - the string to be escaped

Returns:

the JavaScript string Unicode escaped string or null if input is null

Since:

1.0

jsRegex

public static String jsRegex(String input)

JavaScript regex content escaper.

Escape for a JavaScript regular expression:

 <script type="text/javascript">
   var b = /^JS_REGEX_ESCAPE_HERE/.test(document.location);
 </script>
 

Note that when using a regular expression inside a JavaScript string such as:

<script type="text/javascript">
   var b = (new RegExp('^CONTENT_HERE')).test(document.location);
 </script>

You should first escape using the jsRegex(String) escaper, and make sure that the JavaScript string itself is properly rendered using the jsString(String) escaper. This is a nested context scenario in which we have a JavaScript regex inside a JavaScript string, for which we need to first escape the inner most context and walking back the stack of context to the outer most one.

This JavaScript regex escaper processes the following characters:

• Regex characters: \ (U+005C), / (U+002F), ( (U+0028), [ (U+005B), { (U+007B), ] (U+005D), } (U+007D), ) (U+0029), * (U+002A), + (U+002B), - (U+002D), . (U+002E), ? (U+003F), ! (U+0021), ^ (U+005E), $ (U+0024), | (U+007C)
• Control characters: \t (U+0009), \n (U+000A), \v (U+000B), \f (U+000C), \r (U+000D)

Parameters:

input - the string to be escaped

Returns:

the escaped JavaScript regex or null if input is null

Since:

1.0

cssString

public static String cssString(String input)

CSS String escaper.

CSS escaper for strings such as CSS selector or quoted URI:

 <style">
  a[href *= "DATA_HERE"] {...}
  li { background: url('DATA_HERE'); }
 </style>
 

This CSS string escaper processes the following characters:

• CSS string characters: ' (U+0022), " (U+0027), \ (U+005C)
• HTML characters: / (U+002F), < (U+003C), > (U+003E), & (U+0026)
• Control characters: \b (U+0008), \t (U+0009), \n (U+000A), \f (U+000C), \r (U+000D)
• Unicode newlines: LS (U+2028), PS (U+2029)

Parameters:

input - the string to be escaped

Returns:

the CSS string escaped or null if input is null

Since:

1.0

sqlLikeClause

public static String sqlLikeClause(String input)

SQL LIKE clause escaper.

This SQL LIKE clause escaper does not protect against SQL injection, but ensure that the string to be consumed in SQL LIKE clause does not alter the current LIKE query by inserting % or _:

 entityManager.createQuery("FROM MyEntity e WHERE e.content LIKE :like_query ESCAPE '@'")
              .setParameter("like_query", "%" + Escape.sqlLikeClause(USER_DATA_HERE))
              .getResultList();
 

This escaper has to be used with a safe SQL query construct such as the JPQL named parameterized query in the previous example.

This escaper uses by default the @ as escape character. The other method sqlLikeClause(String,char) allows for using a different escape character such as \.

This SQL LIKE escaper processes the following characters:

• SQL LIKE characters: _ (U+005F), % (U+0025), @ (U+0040)

Parameters:

input - the string to be escaped

Returns:

the SQL LIKE escaped string or null if input is null

Since:

1.0

sqlLikeClause

public static String sqlLikeClause(String input,
                   char escape)

SQL LIKE clause escaper.

Similar to sqlLikeClause(String), but allows to specify the escape character to be used. When a character different than @ is used, @ will not be escaped by the escaper, and the specified escape character will be.

Parameters:

input - the string to be escaped

escape - the escape character to be used

Returns:

the SQL LIKE escaped string or null if input is null

Since:

1.0