html

Classes

goog.html.SafeHtml
A string that is safe to use in HTML context in DOM APIs and HTML documents. A SafeHtml is a string-like object that carries the security type contract that its value as a string will not cause untrusted script execution when evaluated as HTML in a browser. Values of this type are guaranteed to be safe to use in HTML contexts, such as, assignment to the innerHTML DOM property, or interpolation into a HTML template in HTML PC_DATA context, in the sense that the use will not result in a Cross-Site-Scripting vulnerability. Instances of this type must be created via the factory methods ( goog.html.SafeHtml.create, goog.html.SafeHtml.htmlEscape), etc and not by invoking its constructor. The constructor intentionally takes no parameters and the type is immutable; hence only a default instance corresponding to the empty string can be obtained via constructor invocation.
goog.html.SafeStyle
A string-like object which represents a sequence of CSS declarations ( propertyName1: propertyvalue1; propertyName2: propertyValue2; ...) and that carries the security type contract that its value, as a string, will not cause untrusted script execution (XSS) when evaluated as CSS in a browser. Instances of this type must be created via the factory methods ( goog.html.SafeStyle.create or goog.html.SafeStyle.fromConstant) and not by invoking its constructor. The constructor intentionally takes no parameters and the type is immutable; hence only a default instance corresponding to the empty string can be obtained via constructor invocation. A SafeStyle's string representation ( #getSafeStyleString()) can safely:
  • Be interpolated as the entire content of a *quoted* HTML style attribute, or before already existing properties. The SafeStyle string *must be HTML-attribute-escaped* (where " and ' are escaped) before interpolation.
  • Be interpolated as the entire content of a {}-wrapped block within a stylesheet, or before already existing properties. The SafeStyle string should not be escaped before interpolation. SafeStyle's contract also guarantees that the string will not be able to introduce new properties or elide existing ones.
  • Be assigned to the style property of a DOM node. The SafeStyle string should not be escaped before being assigned to the property.
A SafeStyle may never contain literal angle brackets. Otherwise, it could be unsafe to place a SafeStyle into a <style> tag (where it can't be HTML escaped). For example, if the SafeStyle containing " font: 'foo &lt;style/&gt;&lt;script&gt;evil&lt;/script&gt;'" were interpolated within a <style> tag, this would then break out of the style context into HTML. A SafeStyle may contain literal single or double quotes, and as such the entire style string must be escaped when used in a style attribute (if this were not the case, the string could contain a matching quote that would escape from the style attribute). Values of this type must be composable, i.e. for any two values style1 and style2 of this type, style1.getSafeStyleString() + style2.getSafeStyleString() must itself be a value that satisfies the SafeStyle type constraint. This requirement implies that for any value style of this type, style.getSafeStyleString() must not end in a "property value" or "property name" context. For example, a value of background:url(" or font- would not satisfy the SafeStyle contract. This is because concatenating such strings with a second value that itself does not contain unsafe CSS can result in an overall string that does. For example, if javascript:evil())" is appended to background:url(", the resulting string may result in the execution of a malicious script. TODO(user): Consider whether we should implement UTF-8 interchange validity checks and blacklisting of newlines (including Unicode ones) and other whitespace characters (\t, \f). Document here if so and also update SafeStyle.fromConstant(). The following example values comply with this type's contract:
  • width: 1em;
  • height:1em;
  • width: 1em;height: 1em;
  • background:url('http://url');
In addition, the empty string is safe for use in a CSS attribute. The following example values do NOT comply with this type's contract:
  • background: red
    (missing a trailing semi-colon)
  • background:
    (missing a value and a trailing semi-colon)
  • 1em
    (missing an attribute name, which provides context for the value)
goog.html.SafeUrl
A string that is safe to use in URL context in DOM APIs and HTML documents. A SafeUrl is a string-like object that carries the security type contract that its value as a string will not cause untrusted script execution when evaluated as a hyperlink URL in a browser. Values of this type are guaranteed to be safe to use in URL/hyperlink contexts, such as, assignment to URL-valued DOM properties, or interpolation into a HTML template in URL context (e.g., inside a href attribute), in the sense that the use will not result in a Cross-Site-Scripting vulnerability. Note that, as documented in goog.html.SafeUrl.unwrap, this type's contract does not guarantee that instances are safe to interpolate into HTML without appropriate escaping. Note also that this type's contract does not imply any guarantees regarding the resource the URL refers to. In particular, SafeUrls are not safe to use in a context where the referred-to resource is interpreted as trusted code, e.g., as the src of a script tag. Instances of this type must be created via the factory methods ( goog.html.SafeUrl.from, goog.html.SafeUrl.sanitize), etc and not by invoking its constructor. The constructor intentionally takes no parameters and the type is immutable; hence only a default instance corresponding to the empty string can be obtained via constructor invocation.
goog.html.TrustedResourceUrl
A URL which is under application control and from which script, CSS, and other resources that represent executable code, can be fetched. Given that the URL can only be constructed from strings under application control and is used to load resources, bugs resulting in a malformed URL should not have a security impact and are likely to be easily detectable during testing. Given the wide number of non-RFC compliant URLs in use, stricter validation could prevent some applications from being able to use this type. Instances of this type must be created via the factory method, ( goog.html.TrustedResourceUrl.fromConstant), and not by invoking its constructor. The constructor intentionally takes no parameters and the type is immutable; hence only a default instance corresponding to the empty string can be obtained via constructor invocation.

Public Protected Private

Global Properties

goog.html.SAFE_URL_PATTERN_ :
A pattern that recognizes a commonly useful subset of URLs that satisfy the SafeUrl contract. This regular expression matches a subset of URLs that will not cause script execution if used in URL context within a HTML document. Specifically, this regular expression matches if (comment from here on and regex copied from Soy's EscapingConventions): (1) Either a protocol in a whitelist (http, https, mailto). (2) or no protocol. A protocol must be followed by a colon. The below allows that by allowing colons only after one of the characters [/?#]. A colon after a hash (#) must be in the fragment. Otherwise, a colon after a (?) must be in a query. Otherwise, a colon after a single solidus (/) must be in a path. Otherwise, a colon after a double solidus (//) must be in the authority (before port). The pattern disallows &, used in HTML entity declarations before one of the characters in [/?#]. This disallows HTML entities used in the protocol name, which should never happen, e.g. "http" for "http". It also disallows HTML entities in the first path part of a relative path, e.g. "foo<bar/baz". Our existing escaping functions should not produce that. More importantly, it disallows masking of a colon, e.g. "javascript:...".
Code »
goog.html.ScrubberTest :
No description.
Code »
goog.html.UtilsTest :
No description.
Code »
goog.html.legacyconversions :
No description.
Code »
goog.html.legacyconversionsTest :
No description.
Code »
goog.html.safeHtmlTest :
No description.
Code »
goog.html.safeStyleTest :
No description.
Code »
goog.html.safeUrlTest :
No description.
Code »
goog.html.testing :
No description.
Code »
goog.html.trustedResourceUrlTest :
No description.
Code »
goog.html.uncheckedconversions :
No description.
Code »
goog.html.uncheckedconversionsTest :
No description.
Code »
goog.html.utils :
No description.
Code »

Package html

Package Reference