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.SafeUrl |
![]()
Returns this URLs directionality, which is always
LTR .
|
code » | |
![]()
Returns this SafeUrl's value a string.
IMPORTANT: In code where it is security relevant that an object's type is
indeed
SafeUrl , use goog.html.SafeUrl.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 that
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.IMPORTANT: The guarantees of the SafeUrl type contract only extend to the behavior of browsers when interpreting URLs. Values of SafeUrl objects MUST be appropriately escaped before embedding in a HTML document. Note that the required escaping is context-sensitive (e.g. a different escaping is required for embedding a URL in a style property within a style attribute, as opposed to embedding in a href attribute). |
code » | |
![]()
Returns a debug string-representation of this value.
To obtain the actual string value wrapped in a SafeUrl, use
goog.html.SafeUrl.unwrap .
|
code » |
![]()
A type marker used to implement additional run-time type checking.
|
Code » | |
![]()
No description.
|
Code » | |
![]()
No description.
|
Code » | |
![]()
The contained value of this SafeUrl. The field has a purposely ugly
name to make (non-compiled) code that attempts to directly access this
field stand out.
|
Code » |
Utility method to create SafeUrl 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.SafeUrl
The initialized SafeUrl object.
|
code » | ||
Creates a SafeUrl object from a compile-time constant string.
Compile-time constant strings are inherently program-controlled and hence
trusted.
Arguments:
|
code » | ||
Normalizes
url the UTF-8 encoding of url, using a whitelist of
characters. Whitelisted characters are not percent-encoded.
|
code » | ||
Creates a SafeUrl object from
url . If url is a
goog.html.SafeUrl then it is simply returned. Otherwise the input string is
validated to match a pattern of commonly used safe URLs. The string is
converted to UTF-8 and non-whitelisted characters are percent-encoded. The
string wrapped by the created SafeUrl will thus contain only ASCII printable
characters.
url may be a URL with the http, https, or mailto scheme,
or a relative URL (i.e., a URL without a scheme; specifically, a
scheme-relative, absolute-path-relative, or path-relative URL).
url is converted to UTF-8 and non-whitelisted characters are
percent-encoded. Whitelisted characters are '%' and, from RFC 3986,
unreserved characters and reserved characters, with the exception of '\'',
'(' and ')'. This ensures the the SafeUrl contains only ASCII-printable
characters and reduces the chance of security bugs were it to be
interpolated into a specific context without the necessary escaping.
If url fails validation or does not UTF-16 decode correctly
(JavaScript strings are UTF-16 encoded), this function returns a SafeUrl
object containing an innocuous string, goog.html.SafeUrl.INNOCUOUS_STRING.
Arguments:
Returns: !goog.html.SafeUrl
The validated URL, wrapped as a SafeUrl.
|
code » | ||
Performs a runtime check that the provided object is indeed a SafeUrl
object, and returns its value.
IMPORTANT: The guarantees of the SafeUrl type contract only extend to the
behavior of browsers when interpreting URLs. Values of SafeUrl objects MUST
be appropriately escaped before embedding in a HTML document. Note that the
required escaping is context-sensitive (e.g. a different escaping is
required for embedding a URL in a style property within a style
attribute, as opposed to embedding in a href attribute).
Note that the returned value does not necessarily correspond to the string
with which the SafeUrl was constructed, since goog.html.SafeUrl.sanitize
will percent-encode many characters.
Arguments:
Returns: string
The SafeUrl 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 » |
![]()
The innocuous string generated by goog.html.SafeUrl.sanitize when passed
an unsafe URL.
about:invalid is registered in
http://www.w3.org/TR/css3-values/#about-invalid.
http://tools.ietf.org/html/rfc6694#section-2.2.1 permits about URLs to
contain a fragment, which is not to be considered when determining if an
about URL is well-known.
Using about:invalid seems preferable to using a fixed data URL, since
browsers might choose to not report CSP violations on it, as legitimate
CSS function calls to attr() can result in this URL being produced. It is
also a standard URL which matches exactly the semantics we need:
"The about:invalid URI references a non-existent document with a generic
error condition. It can be used when a URI is necessary, but the default
value shouldn't be resolveable as any type of document".
|
Code » | |
![]()
Matches characters and strings which need to be replaced in the string
generated by encodeURI. Specifically:
- '\'', '(' and ')' are not encoded. They are part of the reserved
characters group in RFC 3986 but only appear in the obsolete mark
production in Appendix D.2 of RFC 3986, so they can be encoded without
changing semantics.
- '[' and ']' are encoded by encodeURI, despite being reserved characters
which can be used to represent IPv6 addresses. So they need to be decoded.
- '%' is encoded by encodeURI. However, encoding '%' characters that are
already part of a valid percent-encoded sequence changes the semantics of a
URL, and hence we need to preserve them. Note that this may allow
non-encoded '%' characters to remain in the URL (i.e., occurrences of '%'
that are not part of a valid percent-encoded sequence, for example,
'ab%xy').
|
Code » | |
![]()
Map of replacements to be done in string generated by encodeURI.
|
Code » | |
![]()
Type marker for the SafeUrl type, used to implement additional run-time
type checking.
|
Code » |