uncheckedconversions

Documentation

Overview

Package uncheckedconversions provides functions to create values of package safehtml types from plain strings. Use of these functions could potentially result in instances of safe HTML types that violate their type contracts, and hence result in security vulnerabilties.

Avoid use of the functions in this file whenever possible; instead prefer to create instances of package safehtml types using inherently safe builders or template systems.

Example appropriate uses include:

• Wrapping the result of general-purpose or application-specific content sanitizer libraries.
• Wrapping the result of rendering strictly contextually autoescaping templates (assuming the template's autoescaping implementation is indeed strict enough to support the type contract).

Index

• func HTMLFromStringKnownToSatisfyTypeContract(s string) safehtml.HTML
• func IdentifierFromStringKnownToSatisfyTypeContract(s string) safehtml.Identifier
• func ScriptFromStringKnownToSatisfyTypeContract(s string) safehtml.Script
• func StyleFromStringKnownToSatisfyTypeContract(s string) safehtml.Style
• func StyleSheetFromStringKnownToSatisfyTypeContract(s string) safehtml.StyleSheet
• func TrustedResourceURLFromStringKnownToSatisfyTypeContract(s string) safehtml.TrustedResourceURL
• func URLFromStringKnownToSatisfyTypeContract(s string) safehtml.URL

Functions

func HTMLFromStringKnownToSatisfyTypeContract

func HTMLFromStringKnownToSatisfyTypeContract(s string) safehtml.HTML

HTMLFromStringKnownToSatisfyTypeContract converts a string into a HTML.

func IdentifierFromStringKnownToSatisfyTypeContract

func IdentifierFromStringKnownToSatisfyTypeContract(s string) safehtml.Identifier

IdentifierFromStringKnownToSatisfyTypeContract converts a string into a Identifier.

func ScriptFromStringKnownToSatisfyTypeContract

func ScriptFromStringKnownToSatisfyTypeContract(s string) safehtml.Script

ScriptFromStringKnownToSatisfyTypeContract converts a string into a Script.

Users of this function must ensure themselves that the string does not contain unsafe script. Note in particular that '<' is dangerous, even when inside JavaScript strings, and so should always be forbidden or JavaScript escaped in user controlled input. For example, if "</script><script>evil</script>" were interpolated inside a JavaScript string,it would break out of the context of the original script element and "evil" would execute. Also note that within an HTML script (raw text) element, HTML character references, such as "&lt;" are not allowed. See http://www.w3.org/TR/html5/scripting-1.html#restrictions-for-contents-of-script-elements.

func StyleFromStringKnownToSatisfyTypeContract

func StyleFromStringKnownToSatisfyTypeContract(s string) safehtml.Style

StyleFromStringKnownToSatisfyTypeContract converts a string into a Style.

Users of thie function must ensure themselves that the string:

• Does not contain unsafe CSS.
• Does not contain literal angle brackets. Otherwise, it could be unsafe to place a Style into the contents of a <style> element where it can't be HTML escaped (see http://www.w3.org/International/questions/qa-escapes). For example, if the Style containing "font: 'foo <style/><script>evil</script>'" was interpolated within a <style> tag, it would then break out of the style context into HTML.
• Does not end in a property value or property name context. For example, a value of "background:url(\"" or "font-" does not satisfy the Style type contract. This rule is enforced to ensure composability: concatenating two incomplete strings that themselves do 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.

The string may, however, contain literal single or double quotes (for example, in the "content" property). Therefore, the entire style string must be escaped when used in a style attribute.

The following example values comply with Style's type contract:

width: 1em;
height:1em;
width: 1em;height: 1em;
background:url('http://url');

In addition, the empty string is safe for use in a style 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/.

func StyleSheetFromStringKnownToSatisfyTypeContract

func StyleSheetFromStringKnownToSatisfyTypeContract(s string) safehtml.StyleSheet

StyleSheetFromStringKnownToSatisfyTypeContract converts a string into a StyleSheet.

Users of this function must ensure themselves that the string does not contain unsafe script. Note in particular that '<' is dangerous, even when inside CSS strings, and so should always be forbidden or CSS-escaped in user controlled input. For example, if "</style><script>evil</script>" were interpolated inside a CSS string, it would break out of the context of the original style element and "evil" would execute. Also note that within an HTML style (raw text) element, HTML character references, such as "&lt;", are not allowed.See http://www.w3.org/TR/html5/scripting-1.html#restrictions-for-contents-of-script-elements (Similar considerations apply to the style element.)

func TrustedResourceURLFromStringKnownToSatisfyTypeContract

func TrustedResourceURLFromStringKnownToSatisfyTypeContract(s string) safehtml.TrustedResourceURL

TrustedResourceURLFromStringKnownToSatisfyTypeContract converts a string into a TrustedResourceURL.

func URLFromStringKnownToSatisfyTypeContract

func URLFromStringKnownToSatisfyTypeContract(s string) safehtml.URL

URLFromStringKnownToSatisfyTypeContract converts a string into a URL.