1 // Copyright 2011 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
6 Package template (html/template) is a specialization of package text/template
7 that automates the construction of HTML output that is safe against code
13 This package wraps package template so you can use the standard template API
14 to parse and execute templates.
16 set, err := new(template.Set).Parse(...)
17 // Error checking elided
18 err = set.Execute(out, "Foo", data)
20 If successful, set will now be injection-safe. Otherwise, err is an error
21 defined in the docs for ErrorCode.
23 HTML templates treat data values as plain text which should be encoded so they
24 can be safely embedded in an HTML document. The escaping is contextual, so
25 actions can appear within JavaScript, CSS, and URI contexts.
27 The security model used by this package assumes that template authors are
28 trusted, while Execute's data parameter is not. More details are provided below.
34 t, err := (&template.Set{}).Parse(`{{define "T"}}Hello, {{.}}!{{end}}`)
35 err = t.Execute(out, "T", "<script>alert('you have been pwned')</script>")
39 Hello, <script>alert('you have been pwned')</script>!
41 but with contextual autoescaping,
43 import "html/template"
45 t, err := (&template.Set{}).Parse(`{{define "T"}}Hello, {{.}}!{{end}}`)
46 err = t.Execute(out, "T", "<script>alert('you have been pwned')</script>")
48 produces safe, escaped HTML output
50 Hello, <script>alert('you have been pwned')</script>!
55 This package understands HTML, CSS, JavaScript, and URIs. It adds sanitizing
56 functions to each simple action pipeline, so given the excerpt
58 <a href="/search?q={{.}}">{{.}}</a>
60 At parse time each {{.}} is overwritten to add escaping functions as necessary,
63 <a href="/search?q={{. | urlquery}}">{{. | html}}</a>
68 See the documentation of ErrorCode for details.
73 The rest of this package comment may be skipped on first reading; it includes
74 details necessary to understand escaping contexts and error messages. Most users
75 will not need to understand these details.
80 Assuming {{.}} is `O'Reilly: How are <i>you</i>?`, the table below shows
81 how {{.}} appears when used in the context to the left.
84 {{.}} O'Reilly: How are <i>you</i>?
85 <a title='{{.}}'> O'Reilly: How are you?
86 <a href="/{{.}}"> O'Reilly: How are %3ci%3eyou%3c/i%3e?
87 <a href="?q={{.}}"> O'Reilly%3a%20How%20are%3ci%3e...%3f
88 <a onx='f("{{.}}")'> O\x27Reilly: How are \x3ci\x3eyou...?
89 <a onx='f({{.}})'> "O\x27Reilly: How are \x3ci\x3eyou...?"
90 <a onx='pattern = /{{.}}/;'> O\x27Reilly: How are \x3ci\x3eyou...\x3f
92 If used in an unsafe context, then the value might be filtered out:
95 <a href="{{.}}"> #ZgotmplZ
97 since "O'Reilly:" is not an allowed protocol like "http:".
100 If {{.}} is the innocuous word, `left`, then it can appear more widely,
104 <a title='{{.}}'> left
105 <a href='{{.}}'> left
106 <a href='/{{.}}'> left
107 <a href='?dir={{.}}'> left
108 <a style="border-{{.}}: 4px"> left
109 <a style="align: {{.}}"> left
110 <a style="background: '{{.}}'> left
111 <a style="background: url('{{.}}')> left
112 <style>p.{{.}} {color:red}</style> left
114 Non-string values can be used in JavaScript contexts.
117 []struct{A,B string}{ "foo", "bar" }
119 in the escaped template
121 <script>var pair = {{.}};</script>
123 then the template output is
125 <script>var pair = {"A": "foo", "B": "bar"};</script>
127 See package json to understand how non-string content is marshalled for
128 embedding in JavaScript contexts.
133 By default, this package assumes that all pipelines produce a plain text string.
134 It adds escaping pipeline stages necessary to correctly and safely embed that
135 plain text string in the appropriate context.
137 When a data value is not plain text, you can make sure it is not over-escaped
138 by marking it with its type.
140 Types HTML, JS, URL, and others from content.go can carry safe content that is
141 exempted from escaping.
149 tmpl.Execute(out, HTML(`<b>World</b>`))
157 Hello, <b>World<b>!
159 that would have been produced if {{.}} was a regular string.
164 http://js-quasis-libraries-and-repl.googlecode.com/svn/trunk/safetemplate.html#problem_definition defines "safe" as used by this package.
166 This package assumes that template authors are trusted, that Execute's data
167 parameter is not, and seeks to preserve the properties below in the face
170 Structure Preservation Property
171 "... when a template author writes an HTML tag in a safe templating language,
172 the browser will interpret the corresponding portion of the output as a tag
173 regardless of the values of untrusted data, and similarly for other structures
174 such as attribute boundaries and JS and CSS string boundaries."
177 "... only code specified by the template author should run as a result of
178 injecting the template output into a page and all code specified by the
179 template author should run as a result of the same."
181 Least Surprise Property
182 "A developer (or code reviewer) familiar with HTML, CSS, and JavaScript, who
183 knows that contextual autoescaping happens should be able to look at a {{.}}
184 and correctly infer what sanitization happens."