Make Encoding.decodeHtml publicly available.

Fixes OWASP#91

Author: mikesamuel

RELEASE-checklist.sh

@@ -10,6 +10,7 @@ set -e
 # Make sure the build is ok via
 mvn -Dguava.version=27.0-jre -f aggregate clean verify javadoc:jar source:jar
 mvn -f aggregate clean verify jacoco:report site javadoc:jar source:jar
+mvn install
 mvn org.sonatype.ossindex.maven:ossindex-maven-plugin:audit -f aggregate
 
 echo

change_log.md

@@ -1,6 +1,9 @@
 # OWASP Java HTML Sanitizer Change Log
 
 Most recent at top.
+ * Unreleased
+ * Make Encoding class public so that clients can use HTML text decoder.
+ * Fix bug in srcset handling.
  * Release 20190325.1
  * Properly parse `srcset` attribute values to apply URL policy to
  each URL in turn.

src/main/java/org/owasp/html/Encoding.java

@@ -33,11 +33,14 @@
 import javax.annotation.Nullable;
 
 /** Encoders and decoders for HTML. */
-final class Encoding {
+public final class Encoding {
 
  /**
  * Decodes HTML entities to produce a string containing only valid
  * Unicode scalar values.
+ *
+ * @param s text/html
+ * @return text/plain
  */
  public static String decodeHtml(String s) {
  int firstAmp = s.indexOf('&');
@@ -151,11 +154,40 @@ private static int longestPrefixOfGoodCodeunits(String s) {
  return -1;
  }
 
+ /**
+ * Appends an encoded form of plainText to output where the encoding is
+ * sufficient to prevent an HTML parser from interpreting any characters in
+ * the appended chunk as part of an attribute or tag boundary.
+ *
+ * @param plainText text/plain
+ * @param output a buffer of text/html that has a well-formed HTML prefix that
+ * ends after the open-quote of an attribute value and does not yet contain
+ * a corresponding close quote.
+ * Modified in place.
+ */
  static void encodeHtmlAttribOnto(String plainText, Appendable output)
  throws IOException {
  encodeHtmlOnto(plainText, output, "{\u200B");
  }
 
+ /**
+ * Appends an encoded form of plainText to putput where the encoding is
+ * sufficient to prevent an HTML parser from transitioning out of the
+ * <a href="https://html.spec.whatwg.org/multipage/parsing.html#data-state">
+ * Data state</a>.
+ *
+ * This is suitable for encoding a text node inside any element that does not
+ * require special handling as a context element (see "context element" in
+ * <a href="https://html.spec.whatwg.org/multipage/parsing.html#parsing-html-fragments">
+ * step 4</a>.)
+ *
+ * @param plainText text/plain
+ * @param output a buffer of text/html that has a well-formed HTML prefix that
+ * would leave an HTML parser in the Data state if it were to encounter a space
+ * character as the next character. In practice this means that the buffer
+ * does not contain partial tags or comments, and does not have an unclosed
+ * element with a special content model.
+ */
  static void encodePcdataOnto(String plainText, Appendable output)
  throws IOException {
  // Avoid problems with client-side template languages like
@@ -166,7 +198,23 @@ static void encodePcdataOnto(String plainText, Appendable output)
  encodeHtmlOnto(plainText, output, "{<!-- -->");
  }
 
- static void encodeRcdataOnto(String plainText, Appendable output)
+ /**
+ * Appends an encoded form of plainText to putput where the encoding is
+ * sufficient to prevent an HTML parser from transitioning out of the
+ * <a href="https://html.spec.whatwg.org/multipage/parsing.html#rcdata-state">
+ * RCDATA state</a>.
+ *
+ * This is suitable for encoding a text node inside a {@code <textarea>} or
+ * {@code <title>} element outside foreign content.
+ *
+ * @param plainText text/plain
+ * @param output a buffer of text/html that has a well-formed HTML prefix that
+ * would leave an HTML parser in the Data state if it were to encounter a space
+ * character as the next character. In practice this means that the buffer
+ * does not contain partial tags or comments, and the most recently opened
+ * element is `<textarea>` or `<title>` and that element is still open.
+ */
+ public static void encodeRcdataOnto(String plainText, Appendable output)
  throws IOException {
  // Avoid problems with client-side template languages like
  // Angular & Polymer which attach special significance to text like
@@ -316,7 +364,7 @@ static void appendNumericEntity(int codepoint, Appendable output)
  };
 
  /** Maps ASCII chars that need to be encoded to an equivalent HTML entity. */
- static final String[] REPLACEMENTS = new String[0x80];
+ private static final String[] REPLACEMENTS = new String[0x80];
  static {
  for (int i = 0; i < ' '; ++i) {
  // We elide control characters so that we can ensure that our output is
@@ -342,8 +390,8 @@ static void appendNumericEntity(int codepoint, Appendable output)
  }
 
  /**
- * {@code DECODES_TO_SELF[c]} is true iff the codepoint c decodes to itself in
- * an HTML5 text node or properly quoted attribute value.
+ * IS_BANNED_ASCII[i] where is an ASCII control character codepoint (&lt; 0x20)
+ * is true for control characters that are not allowed in an XML source text.
  */
  private static boolean[] IS_BANNED_ASCII = new boolean[0x20];
  static {

src/main/java/org/owasp/html/HtmlEntities.java

@@ -33,7 +33,7 @@
 /**
  * Utilities for decoding HTML entities, e.g., {@code &}.
  */
-class HtmlEntities {
+final class HtmlEntities {
 
  /**
  * Decodes any HTML entity at the given location. This handles both named and