safeurl.js
No description.

File Location

/goog/html/safeurl.js

Classes

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.

Public Protected Private

Global Functions

goog.html.SafeUrl.createSafeUrlSecurityPrivateDoNotAccessOrElse_(url) !goog.html.SafeUrl
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:
url : string
The string to initialize the SafeUrl object with.
Returns: !goog.html.SafeUrl  The initialized SafeUrl object.
code »
goog.html.SafeUrl.fromConstant(url) !goog.html.SafeUrl
Creates a SafeUrl object from a compile-time constant string. Compile-time constant strings are inherently program-controlled and hence trusted.
Arguments:
url : !goog.string.Const
A compile-time-constant string from which to create a SafeUrl.
Returns: !goog.html.SafeUrl  A SafeUrl object initialized to url.
code »
goog.html.SafeUrl.normalize_(url) string
Normalizes url the UTF-8 encoding of url, using a whitelist of characters. Whitelisted characters are not percent-encoded.
Arguments:
url : string
The URL to normalize.
Returns: string  The normalized URL.
code »
goog.html.SafeUrl.sanitize(url) !goog.html.SafeUrl
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:
url : string | !goog.string.TypedString
The URL to validate.
Returns: !goog.html.SafeUrl  The validated URL, wrapped as a SafeUrl.
code »
goog.html.SafeUrl.unwrap(safeUrl) string
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:
safeUrl : !goog.html.SafeUrl
The object to extract from.
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 »

Directory html

File Reference