com.google.common.html.types

Class SafeStyle

java.lang.Object

com.google.common.html.types.SafeStyle

@Immutable
 @JsType
public final class SafeStyle
extends Object

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.

A SafeStyle's string representation (getSafeStyleString()) can safely:

• Be interpolated as the content of a quoted HTML style attribute. The SafeStyle string must be HTML-attribute-escaped (where " and ' are escaped) before interpolation.
• Be interpolated as the content of a {}-wrapped block within a stylesheet. 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.

TODO(user): Do we need to require SafeStyle to be the entire content of a style attribute or the {}-wrapped block above? It would seem that validating untrusted properties would be enough to guarantee that it also would not affect any surrounding, constant, properties. See discussion in cl/61826926.

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 <style/><script>evil</script>'" 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 SafeStyles.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)

See Also:

http://www.w3.org/TR/css3-syntax/

Field Summary

Fields

Modifier and Type	Field and Description
static SafeStyle	EMPTY The SafeStyle wrapping an empty string.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object other)
String	getSafeStyleString() Returns this value's underlying string.
int	hashCode()
String	toString() Returns a debug representation of this value's underlying string, NOT the string representation of the style declaration(s).

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY

public static final SafeStyle EMPTY

The SafeStyle wrapping an empty string.

Method Detail

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object other)

Overrides:

equals in class Object

toString

public String toString()

Returns a debug representation of this value's underlying string, NOT the string representation of the style declaration(s).

Having toString() return a debug representation is intentional. This type has a GWT-compiled JavaScript version; JavaScript has no static typing and a distinct method method name provides a modicum of type-safety.

Overrides:

toString in class Object

See Also:

getSafeStyleString()

getSafeStyleString

public String getSafeStyleString()

Returns this value's underlying string. See class documentation for what guarantees exist on the returned string.