html/template: mention risks of the CSS, HTML, JS, etc. types

Fixes #15399

Change-Id: I5b9645cb9ddede6981ce0a005e0c6fdd8a751c6f
Reviewed-on: https://go-review.googlesource.com/22824
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Minux Ma <minux@golang.org>
Reviewed-by: Russ Cox <rsc@golang.org>

diff --git a/src/html/template/content.go b/src/html/template/content.go
index 3715ed5c93805f8dbb8222be2e5142154a3872a5..2e14bd1231f7997f6839892b0a43acbbb9a346e4 100644 (file)
--- a/src/html/template/content.go
+++ b/src/html/template/content.go
@@ -18,16 +18,28 @@ type (
        //   4. The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
        // See http://www.w3.org/TR/css3-syntax/#parsing and
        // https://web.archive.org/web/20090211114933/http://w3.org/TR/css3-syntax#style
+       //
+       // Use of this type presents a security risk:
+       // the encapsulated content should come from a trusted source,
+       // as it will be included verbatim in the template output.
        CSS string
 
        // HTML encapsulates a known safe HTML document fragment.
        // It should not be used for HTML from a third-party, or HTML with
        // unclosed tags or comments. The outputs of a sound HTML sanitizer
        // and a template escaped by this package are fine for use with HTML.
+       //
+       // Use of this type presents a security risk:
+       // the encapsulated content should come from a trusted source,
+       // as it will be included verbatim in the template output.
        HTML string
 
        // HTMLAttr encapsulates an HTML attribute from a trusted source,
        // for example, ` dir="ltr"`.
+       //
+       // Use of this type presents a security risk:
+       // the encapsulated content should come from a trusted source,
+       // as it will be included verbatim in the template output.
        HTMLAttr string
 
        // JS encapsulates a known safe EcmaScript5 Expression, for example,
@@ -37,6 +49,15 @@ type (
        // statement/expression ambiguity as when passing an expression like
        // "{ foo: bar() }\n['foo']()", which is both a valid Expression and a
        // valid Program with a very different meaning.
+       //
+       // Use of this type presents a security risk:
+       // the encapsulated content should come from a trusted source,
+       // as it will be included verbatim in the template output.
+       //
+       // Using JS to include valid but untrusted JSON is not safe.
+       // A safe alternative is to parse the JSON with json.Unmarshal and then
+       // pass the resultant object into the template, where it will be
+       // converted to sanitized JSON when presented in a JavaScript context.
        JS string
 
        // JSStr encapsulates a sequence of characters meant to be embedded
@@ -46,6 +67,10 @@ type (
        //                    | EscapeSequence
        // Note that LineContinuations are not allowed.
        // JSStr("foo\\nbar") is fine, but JSStr("foo\\\nbar") is not.
+       //
+       // Use of this type presents a security risk:
+       // the encapsulated content should come from a trusted source,
+       // as it will be included verbatim in the template output.
        JSStr string
 
        // URL encapsulates a known safe URL or URL substring (see RFC 3986).
@@ -53,6 +78,10 @@ type (
        // from a trusted source should go in the page, but by default dynamic
        // `javascript:` URLs are filtered out since they are a frequently
        // exploited injection vector.
+       //
+       // Use of this type presents a security risk:
+       // the encapsulated content should come from a trusted source,
+       // as it will be included verbatim in the template output.
        URL string
 )