Package de.uplanet.lucy.server.scripting.velocity.callables

Klasse OwaspEncoder

java.lang.Object
de.uplanet.lucy.server.scripting.velocity.callables.OwaspEncoder
@VelocityVariable("Encoder") @VelocityCallable("singleton") public final class OwaspEncoder extends Object
A wrapper for methods from the OWASP Encoder

  • Felddetails

  • Methodendetails

    • forHtml

      public String forHtml(Object p_input)

      Encodes for (X)HTML text content and text attributes. Since this method encodes for both contexts, it may be slightly less efficient to use this method over the methods targeted towards the specific contexts (forHtmlAttribute(Object) and forHtmlContent(Object)). In general this method should be preferred unless you are really concerned with saving a few bytes or are writing a framework that utilizes this package.

      Example Velocity Usage 
               <div>$Encoder.forHtml($unsafeData)</div>

         <input value="$Encoder.forHtml($unsafeData)" />
      Encoding Table
      Input Result
      & &amp;
      < &lt;
      > &gt;
      " &#34;
      ' &#39;

      Additional Notes

      • The encoding of the greater-than sign (>) is not strictly required, but is included for maximum compatibility.
      • Numeric encoding is used for double-quote character ( ") as it shorter than the also valid &quot;.
      • Carriage return (U+0D), line-feed (U+0A), horizontal tab (U+09) and space (U+20) are valid in quoted attributes and in block in an unescaped form.
      • Surrogate pairs are passed through only if valid.
      • Characters that are not valid according to the XML specification are replaced by a space character as they could lead to parsing errors. In particular only #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF] are considered valid.
      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Gibt zurück:
      The data encoded for html, or null if the given input was null.

    • forHtml

      public void forHtml(Writer p_writer, Object p_input) throws IOException
      See forHtml(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.

    • forHtmlContent

      public String forHtmlContent(Object p_input)

      This method encodes for HTML text content. It does not escape quotation characters and is thus unsafe for use with HTML attributes. Use either forHtml(Object) or forHtmlAttribute(Object) for those methods.

      Example Velocity Usage 

               <div>$Encoder.forHtmlContent($unsafeData)</div>

      Encoding Table
      Input Result
      & &amp;
      < &lt;
      > &gt;

      Additional Notes

      • Single-quote character (') and double-quote character (") do not require encoding in HTML blocks, unlike other HTML contexts.
      • The encoding of the greater-than sign (>) is not strictly required, but is included for maximum compatibility.
      • Carriage return (U+0D), line-feed (U+0A), horizontal tab (U+09) and space (U+20) are valid in quoted attributes and in block in an unescaped form.
      • Surrogate pairs are passed through only if valid.
      • Characters that are not valid according to the XML specification are replaced by a space character as they could lead to parsing errors. In particular only #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF] are considered valid.
      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Gibt zurück:
      The encoded result, or null if the given input was null.

    • forHtmlContent

      public void forHtmlContent(Writer p_writer, Object p_input) throws IOException
      See forHtmlContent(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.

    • forHtmlAttribute

      public String forHtmlAttribute(Object p_input)

      This method encodes for HTML text attributes. Do not use for JavaScript event attributes or for attributes that are interpreted as a URL. Instead use forJavaScript(Object) and forUriComponent(Object) respectively for those.

      Example Velocity Usage 

               <input value="$Encoder.forHtmlAttribute($unsafeData)" title="$Encoder.forHtmlAttribute($moreUnsafeData)" />

      Encoding Table
      Input Result
      & &amp;
      < &lt;
      " &#34;
      ' &#39;

      Additional Notes

      • When using this method, the caller must provide quotes around the attribute value.
      • Both the single-quote character (') and the double-quote character (") are encoded so this is safe for HTML attributes with either enclosing character.
      • The encoding of the greater-than sign (>) is not required for attributes.
      • Numeric encoding is used for double-quote character ( ") as it shorter than the also valid &quot;.
      • Carriage return (U+0D), line-feed (U+0A), horizontal tab (U+09) and space (U+20) are valid in quoted attributes and in block in an unescaped form.
      • Surrogate pairs are passed through only if valid.
      • Characters that are not valid according to the XML specification are replaced by a space character as they could lead to parsing errors. In particular only #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF] are considered valid.
      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Gibt zurück:
      The encoded result, or null if the given input was null.

    • forHtmlAttribute

      public void forHtmlAttribute(Writer p_writer, Object p_input) throws IOException
      See forHtmlAttribute(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.

    • forHtmlUnquotedAttribute

      public String forHtmlUnquotedAttribute(Object p_input)

      Encodes for unquoted HTML attribute values. forHtml(Object) or forHtmlAttribute(Object) should usually be preferred over this method as quoted attributes are XHTML compliant.

      When using this method, the caller is not required to provide quotes around the attribute (since it is encoded for such context). The caller should make sure that the attribute value does not abut unsafe characters--and thus should usually err on the side of including a space character after the value.

      Use of this method is discouraged as quoted attributes are generally more compatible and safer. Also note, that no attempt has been made to optimize this encoding, though it is still probably faster than other encoding libraries.

      Example Velocity Usage 
               <input value=$Encoder.forHtmlUnquotedAttribute($unsafeData) >
      Encoding Table
      Input Result
      U+0009 (horizontal tab) &#9;
      U+000A (line feed) &#10;
      U+000C (form feed) &#12;
      U+000D (carriage return) &#13;
      U+0020 (space) &#32;
      & &amp;
      < &lt;
      > &gt;
      " &#34;
      ' &#39;
      / &#47;
      = &#61;
      ` &#96;
      U+0085 (next line) &#133;
      U+2028 (line separator) &#8232;
      U+2029 (paragraph separator) &#8233;

      Additional Notes

      • The following characters are not encoded: 0-9, a-z, A-Z, !, #, $, %, (, ), *, +, ,, -, ., [, \, ], ^, _, }.
      • Surrogate pairs are passed through only if valid. Invalid surrogate pairs are replaced by a hyphen (-).
      • Characters in the C0 and C1 control blocks and not otherwise listed above are considered invalid and replaced by a hyphen (-) character.
      • Unicode "non-characters" are replaced by hyphens (-).
      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Gibt zurück:
      The attribute value encoded for unquoted attribute context, or null if the given input was null.

    • forHtmlUnquotedAttribute

      public void forHtmlUnquotedAttribute(Writer p_writer, Object p_input) throws IOException
      See forHtmlUnquotedAttribute(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.

    • forCssString

      public String forCssString(Object p_input)
      Encodes for CSS strings. The context must be surrounded by quotation characters. It is safe for use in both style blocks and attributes in HTML.

      Example Velocity Usage 

               <div style='background: url("$Encoder.forCssString(...)");'>

         <style type="text/css">
                 background: url("$Encoder.forCssString(...)");
         </style>

      Encoding Notes

      • The following characters are encoded using hexadecimal encodings: U+0000 - U+001f, ", ', \, <, &, /, >, U+007f, line separator (U+2028), paragraph separator (U+2029).
      • Any character requiring encoding is encoded as \xxx where xxx is the shortest hexadecimal representation of its Unicode code point (after decoding surrogate pairs if necessary). This encoding is never zero padded. Thus, for example, the tab character is encoded as \9, not \0009.
      • The encoder looks ahead 1 character in the input and appends a space to an encoding to avoid the next character becoming part of the hexadecimal encoded sequence. Thus “'1” is encoded as “\27 1”, and not as “\271”. If a space is not necessary, it is not included, thus “ 'x” is encoded as “\27x”, and not as “\27 x”.
      • Surrogate pairs are passed through only if valid. Invalid surrogate pairs are replaced by an underscore (_).
      • Unicode "non-characters" are replaced by underscores (_).

      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Gibt zurück:
      The encoded result, or null if the given input was null.

    • forCssString

      public void forCssString(Writer p_writer, Object p_input) throws IOException
      See forCssString(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.

    • forCssUrl

      public String forCssUrl(Object p_input)
      Encodes for CSS URL contexts. The context must be surrounded by "url(" and ")". It is safe for use in both style blocks and attributes in HTML. Note: this does not do any checking on the quality or safety of the URL itself. The caller should insure that the URL is safe for embedding (e.g. input validation) by other means.

      Example Velocity Usage 

               <div style='background:url("$Encode.forCssUrl(...)");'>

         <style type="text/css">
                 background: url("$Encoder.forCssUrl(...)");
         </style>

      Encoding Notes

      • The following characters are encoded using hexadecimal encodings: U+0000 - U+001f, ", ', \, <, &, /, >, U+007f, line separator (U+2028), paragraph separator (U+2029).
      • Any character requiring encoding is encoded as \xxx where xxx is the shortest hexadecimal representation of its Unicode code point (after decoding surrogate pairs if necessary). This encoding is never zero padded. Thus, for example, the tab character is encoded as \9, not \0009.
      • The encoder looks ahead 1 character in the input and appends a space to an encoding to avoid the next character becoming part of the hexadecimal encoded sequence. Thus “'1” is encoded as “\27 1”, and not as “\271”. If a space is not necessary, it is not included, thus “ 'x” is encoded as “\27x”, and not as “\27 x”.
      • Surrogate pairs are passed through only if valid. Invalid surrogate pairs are replaced by an underscore (_).
      • Unicode "non-characters" are replaced by underscores (_).

      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Gibt zurück:
      The encoded result, or null if the given input was null.

    • forCssUrl

      public void forCssUrl(Writer p_writer, Object p_input) throws IOException
      See forCssUrl(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.

    • forUriComponent

      public String forUriComponent(Object p_input)
      Performs percent-encoding for a component of a URI, such as a query parameter name or value, path or query-string. In particular this method insures that special characters in the component do not get interpreted as part of another component. 
               <a href="http://www.owasp.org/$Encoder.forUriComponent(...)?query#fragment">

         <a href="/search?value=$Encoder.forUriComponent(...)&order=1#top">
      Encoding Table

      The following characters are not encoded: 

       U+20:                                             - .   0 1 2 3 4 5 6 7 8 9
 U+40:   A B C D E F G H I J K L M N O P Q R S T U V W X Y Z             _
 U+60:   a b c d e f g h i j k l m n o p q r s t u v w x y z       ~
      Encoding Notes
      • This method is safe to be used in most containing contexts, including: HTML/XML, CSS, and JavaScript contexts.
      • URL encoding is an encoding for bytes, not unicode. The input string is thus first encoded as a sequence of UTF-8 byte. The bytes are then encoded as %xx where xx is the two-digit hexadecimal representation of the byte. (The implementation does this as one step for performance.)
      • Surrogate pairs are first decoded to a Unicode code point before encoding as UTF-8.
      • Invalid characters (e.g. partial or invalid surrogate pairs), are replaced with a hyphen (-) character.
      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Gibt zurück:
      The encoded result, or null if the given input was null.

    • forUriComponent

      public void forUriComponent(Writer p_writer, Object p_input) throws IOException
      See forUriComponent(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.

    • forXml

      public String forXml(Object p_input)
      Encoder for XML and XHTML. See forHtml(Object) for a description of the encoding and context.
      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Gibt zurück:
      The encoded result, or null if the given input was null.
      Siehe auch:

    • forXml

      public void forXml(Writer p_writer, Object p_input) throws IOException
      See forXml(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.

    • forXmlContent

      public String forXmlContent(Object p_input)
      Encoder for XML and XHTML text content. See forHtmlContent(Object) for description of encoding and context.
      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Gibt zurück:
      The encoded result, or null if the given input was null.
      Siehe auch:

    • forXmlContent

      public void forXmlContent(Writer p_writer, Object p_input) throws IOException
      See forXmlContent(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.

    • forXmlAttribute

      public String forXmlAttribute(Object p_input)
      Encoder for XML and XHTML attribute content. See forHtmlAttribute(Object) for description of encoding and context.
      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Gibt zurück:
      The encoded result, or null if the given input was null.
      Siehe auch:

    • forXmlAttribute

      public void forXmlAttribute(Writer p_writer, Object p_input) throws IOException
      See forXmlAttribute(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.

    • forXmlComment

      public String forXmlComment(Object p_input)
      Encoder for XML comments. NOT FOR USE WITH (X)HTML CONTEXTS. (X)HTML comments may be interpreted by browsers as something other than a comment, typically in vendor specific extensions (e.g. <--if[IE]-->). For (X)HTML it is recommend that unsafe content never be included in a comment.

      The caller must provide the comment start and end sequences.

      This method replaces all invalid XML characters with spaces, and replaces the "--" sequence (which is invalid in XML comments) with "-~" (hyphen-tilde). This encoding behavior may change in future releases. If the comments need to be decoded, the caller will need to come up with their own encode/decode system. 

       out.println("<?xml version='1.0'?>");
 out.println("<data>");
 out.println("<!-- " + Encode.forXmlComment(comment) + " -->");
 out.println("</data>");
      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Gibt zurück:
      The encoded result, or null if the given input was null.

    • forXmlComment

      public void forXmlComment(Writer p_writer, Object p_input) throws IOException
      See forXmlComment(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.

    • forCDATA

      public String forCDATA(Object p_input)
      Encodes data for an XML CDATA section. On the chance that the input contains a terminating "]]>", it will be replaced by "]]>]]<![CDATA[>". As with all XML contexts, characters that are invalid according to the XML specification will be replaced by a space character. Caller must provide the CDATA section boundaries. 
               <xml-data><![CDATA[$Encoder.forCDATA(...)]]></xml-data>
      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Gibt zurück:
      The encoded result, or null if the given input was null.

    • forCDATA

      public void forCDATA(Writer p_writer, Object p_input) throws IOException
      See forCDATA(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.

    • forJavaScript

      public String forJavaScript(Object p_input)

      Encodes for a JavaScript string. It is safe for use in HTML script attributes (such as onclick), script blocks, JSON files, and JavaScript source. The caller MUST provide the surrounding quotation characters for the string. Since this performs additional encoding so it can work in all of the JavaScript contexts listed, it may be slightly less efficient than using one of the methods targeted to a specific JavaScript context (forJavaScriptAttribute(Object), forJavaScriptBlock(java.lang.Object), forJavaScriptSource(java.lang.Object)). Unless you are interested in saving a few bytes of output or are writing a framework on top of this library, it is recommend that you use this method over the others.

      Example Velocity Usage: 
              <button onclick="alert($ESC.getAPOS()$Encoder.forJavaScript($unsafeData)$ESC.getAPOS());">
        <script type="text/javascript">
                var data = "$Encoder.forJavaScript($unsafeData)";
        </script>
      Encoding Description
      Input Character Encoded Result Notes
      U+0008 BS \b Backspace character
      U+0009 HT \t Horizontal tab character
      U+000A LF \n Line feed character
      U+000C FF \f Form feed character
      U+000D CR \r Carriage return character
      U+0022 " \x22 The encoding \" is not used here because it is not safe for use in HTML attributes. (In HTML attributes, it would also be correct to use "\&quot;".)
      U+0026 & \x26 Ampersand character
      U+0027 ' \x27 The encoding \' is not used here because it is not safe for use in HTML attributes. (In HTML attributes, it would also be correct to use "\&#39;".)
      U+002F / \/ This encoding is used to avoid an input sequence "</" from prematurely terminating a </script> block.
      U+005C \ \\
      U+0000 to U+001F \x## Hexadecimal encoding is used for characters in this range that were not already mentioned in above.
      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Gibt zurück:
      The input encoded for JavaScript, or null if the given input was null.
      Siehe auch:

    • forJavaScript

      public void forJavaScript(Writer p_writer, Object p_input) throws IOException
      See forJavaScript(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.

    • forJavaScriptAttribute

      public String forJavaScriptAttribute(Object p_input)

      This method encodes for JavaScript strings contained within HTML script attributes (such as onclick). It is NOT safe for use in script blocks. The caller MUST provide the surrounding quotation characters. This method performs the same encode as forJavaScript(Object) with the exception that / is not escaped.

      Unless you are interested in saving a few bytes of output or are writing a framework on top of this library, it is recommend that you use forJavaScript(Object) over this method.

      Example Velocity Usage: 
              <button onclick="alert($ESC.getAPOS()$Encoder.forJavaScript($unsafeData)$ESC.getAPOS());">
      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Gibt zurück:
      The input encoded for JavaScript, or null if the given input was null.
      Siehe auch:

    • forJavaScriptAttribute

      public void forJavaScriptAttribute(Writer p_writer, Object p_input) throws IOException
      See forJavaScriptAttribute(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.

    • forJavaScriptBlock

      public String forJavaScriptBlock(Object p_input)

      This method encodes for JavaScript strings contained within HTML script blocks. It is NOT safe for use in script attributes (such as onclick). The caller must provide the surrounding quotation characters. This method performs the same encode as forJavaScript(Object) with the exception that " and ' are encoded as \" and \' respectively.

      Unless you are interested in saving a few bytes of output or are writing a framework on top of this library, it is recommend that you use forJavaScript(Object) over this method.

      Example Velocity Usage: 

              <script type="text/javascript">
                var data = "$Encoder.forJavaScriptBlock($unsafeData)";
        </script>

      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Gibt zurück:
      The input encoded for JavaScript, or null if the given input was null.
      Siehe auch:

    • forJavaScriptBlock

      public void forJavaScriptBlock(Writer p_writer, Object p_input) throws IOException
      See forJavaScriptBlock(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.

    • forJavaScriptSource

      public String forJavaScriptSource(Object p_input)

      This method encodes for JavaScript strings contained within a JavaScript or JSON file. This method is NOT safe for use in ANY context embedded in HTML. The caller must provide the surrounding quotation characters. This method performs the same encode as forJavaScript(Object) with the exception that / and & are not escaped and " and ' are encoded as \" and \' respectively.

      Unless you are interested in saving a few bytes of output or are writing a framework on top of this library, it is recommend that you use forJavaScript(Object) over this method.

      Example Velocity Usage: This example is serving up JavaScript source directly: 
              var data = "$Encoder.forJavaScriptSource($unsafeData)";
      This example is serving up JSON data (users of this use-case are encouraged to read up on "JSON Hijacking"): 
              {"data":"$Encoder.forJavaScriptSource(data)"}
      Parameter:
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode.
      Siehe auch:

    • forJavaScriptSource

      public void forJavaScriptSource(Writer p_writer, Object p_input) throws IOException
      See forJavaScriptSource(Object) for description of encoding. This version writes directly to a Writer without an intervening string.
      Parameter:
      p_writer - where to write encoded output
      p_input - The input object of type string, primitive, IValueHolder or IIxValue to encode. If the input is null then nothing will be written.
      Löst aus:
      IOException - If thrown by writer.