Escape (coverity-escapers 1.0 API)

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()

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)
    - 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

Class Escape

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Escape

Method Detail

html

htmlText

uriParam

uri

jsString

jsRegex

cssString

sqlLikeClause

sqlLikeClause