safestyle.js
No description.

File Location

/goog/html/safestyle.js

Classes

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)

Public Protected Private

Global Functions

goog.html.SafeStyle.concat&addArgument(argument)
No description.
Arguments:
argument : !goog.html.SafeStyle | !Array.<!goog.html.SafeStyle>
No description.
code »
goog.html.SafeStyle.checkStyle_(style)
Checks if the style definition is valid.
Arguments:
style : string
No description.
code »
goog.html.SafeStyle.concat(var_args) !goog.html.SafeStyle
Creates a new SafeStyle object by concatenating the values.
Arguments:
var_args : ...(!goog.html.SafeStyle | !Array.<!goog.html.SafeStyle>)
SafeStyles to concatenate.
Returns: !goog.html.SafeStyle  No description.
code »
goog.html.SafeStyle.create(map) !goog.html.SafeStyle
Creates a new SafeStyle object from the properties specified in the map.
Arguments:
map : goog.html.SafeStyle.PropertyMap
Mapping of property names to their values, for example {'margin': '1px'}. Names must consist of [-_a-zA-Z0-9]. Values might be strings consisting of [-.%_!# a-zA-Z0-9]. Other values must be wrapped in goog.string.Const. Null value causes skipping the property.
Returns: !goog.html.SafeStyle  No description.
code »
goog.html.SafeStyle.createSafeStyleSecurityPrivateDoNotAccessOrElse_(style) !goog.html.SafeStyle
Utility method to create SafeStyle instances. This function is considered "package private", i.e. calls (using "suppress visibility") from other files within this package are considered acceptable. DO NOT call this function from outside the goog.html package; use appropriate wrappers instead.
Arguments:
style : string
The string to initialize the SafeStyle object with.
Returns: !goog.html.SafeStyle  The initialized SafeStyle object.
code »
goog.html.SafeStyle.fromConstant(style) !goog.html.SafeStyle
Creates a SafeStyle object from a compile-time constant string. style should be in the format name: value; [name: value; ...] and must not have any < or > characters in it. This is so that SafeStyle's contract is preserved, allowing the SafeStyle to correctly be interpreted as a sequence of CSS declarations and without affecting the syntactic structure of any surrounding CSS and HTML. This method performs basic sanity checks on the format of style but does not constrain the format of name and value, except for disallowing tag characters.
Arguments:
style : !goog.string.Const
A compile-time-constant string from which to create a SafeStyle.
Returns: !goog.html.SafeStyle  A SafeStyle object initialized to style.
code »
goog.html.SafeStyle.unwrap(safeStyle) string
Performs a runtime check that the provided object is indeed a SafeStyle object, and returns its value.
Arguments:
safeStyle : !goog.html.SafeStyle
The object to extract from.
Returns: string  The safeStyle object's contained string, unless the run-time type check fails. In that case, unwrap returns an innocuous string, or, if assertions are enabled, throws goog.asserts.AssertionError.
code »

Directory html

File Reference