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:
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
SafeStyle.fromConstant().
The following example values comply with this type's contract:
width: 1em;
height:1em;
width: 1em;height: 1em;
background:url('http://url');
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.SafeStyle |
![]()
Returns this SafeStyle's value as a string.
IMPORTANT: In code where it is security relevant that an object's type is
indeed
SafeStyle , use goog.html.SafeStyle.unwrap instead of
this method. If in doubt, assume that it's security relevant. In particular,
note that goog.html functions which return a goog.html type do not guarantee
the returned instance is of the right type. For example:
var fakeSafeHtml = new String('fake'); fakeSafeHtml.__proto__ = goog.html.SafeHtml.prototype; var newSafeHtml = goog.html.SafeHtml.htmlEscape(fakeSafeHtml); // newSafeHtml is just an alias for fakeSafeHtml, it's passed through by // goog.html.SafeHtml.htmlEscape() as fakeSafeHtml // instanceof goog.html.SafeHtml. |
code » | |
![]()
Returns a debug string-representation of this value.
To obtain the actual string value wrapped in a SafeStyle, use
goog.html.SafeStyle.unwrap .
|
code » |
![]()
A type marker used to implement additional run-time type checking.
|
Code » | |
![]()
No description.
|
Code » | |
![]()
The contained value of this SafeStyle. The field has a purposely
ugly name to make (non-compiled) code that attempts to directly access this
field stand out.
|
Code » |
![]()
Checks if the style definition is valid.
Arguments:
|
code » | ||
Creates a new SafeStyle object by concatenating the values.
Arguments:
|
code » | ||
Creates a new SafeStyle object from the properties specified in the map.
Arguments:
|
code » | ||
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:
Returns: !goog.html.SafeStyle
The initialized SafeStyle object.
|
code » | ||
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:
|
code » | ||
Performs a runtime check that the provided object is indeed a
SafeStyle object, and returns its value.
Arguments:
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 » |
A SafeStyle instance corresponding to the empty string.
|
Code » | |
![]()
The innocuous string generated by goog.html.SafeUrl.create when passed
an unsafe value.
|
Code » | |
![]()
Mapping of property names to their values.
|
Code » | |
![]()
Type marker for the SafeStyle type, used to implement additional
run-time type checking.
|
Code » | |
![]()
Regular expression for safe values.
|
Code » |