Source file src/html/template/doc.go
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. 4 5 /* 6 Package template (html/template) implements data-driven templates for 7 generating HTML output safe against code injection. It provides the 8 same interface as [text/template] and should be used instead of 9 [text/template] whenever the output is HTML. 10 11 The documentation here focuses on the security features of the package. 12 For information about how to program the templates themselves, see the 13 documentation for [text/template]. 14 15 # Introduction 16 17 This package wraps [text/template] so you can share its template API 18 to parse and execute HTML templates safely. 19 20 tmpl, err := template.New("name").Parse(...) 21 // Error checking elided 22 err = tmpl.Execute(out, data) 23 24 If successful, tmpl will now be injection-safe. Otherwise, err is an error 25 defined in the docs for ErrorCode. 26 27 HTML templates treat data values as plain text which should be encoded so they 28 can be safely embedded in an HTML document. The escaping is contextual, so 29 actions can appear within JavaScript, CSS, and URI contexts. 30 31 Comments are stripped from output, except for those passed in via the 32 [HTML], [CSS], and [JS] types for their respective contexts. 33 34 The security model used by this package assumes that template authors are 35 trusted, while Execute's data parameter is not. More details are 36 provided below. 37 38 Example 39 40 import "text/template" 41 ... 42 t, err := template.New("foo").Parse(`{{define "T"}}Hello, {{.}}!{{end}}`) 43 err = t.ExecuteTemplate(out, "T", "<script>alert('you have been pwned')</script>") 44 45 produces 46 47 Hello, <script>alert('you have been pwned')</script>! 48 49 but the contextual autoescaping in html/template 50 51 import "html/template" 52 ... 53 t, err := template.New("foo").Parse(`{{define "T"}}Hello, {{.}}!{{end}}`) 54 err = t.ExecuteTemplate(out, "T", "<script>alert('you have been pwned')</script>") 55 56 produces safe, escaped HTML output 57 58 Hello, <script>alert('you have been pwned')</script>! 59 60 # Contexts 61 62 This package understands HTML, CSS, JavaScript, and URIs. It adds sanitizing 63 functions to each simple action pipeline, so given the excerpt 64 65 <a href="/search?q={{.}}">{{.}}</a> 66 67 At parse time each {{.}} is overwritten to add escaping functions as necessary. 68 In this case it becomes 69 70 <a href="/search?q={{. | urlescaper | attrescaper}}">{{. | htmlescaper}}</a> 71 72 where urlescaper, attrescaper, and htmlescaper are aliases for internal escaping 73 functions. 74 75 For these internal escaping functions, if an action pipeline evaluates to 76 a nil interface value, it is treated as though it were an empty string. 77 78 # Namespaced and data- attributes 79 80 Attributes with a namespace are treated as if they had no namespace. 81 Given the excerpt 82 83 <a my:href="{{.}}"></a> 84 85 At parse time the attribute will be treated as if it were just "href". 86 So at parse time the template becomes: 87 88 <a my:href="{{. | urlescaper | attrescaper}}"></a> 89 90 Similarly to attributes with namespaces, attributes with a "data-" prefix are 91 treated as if they had no "data-" prefix. So given 92 93 <a data-href="{{.}}"></a> 94 95 At parse time this becomes 96 97 <a data-href="{{. | urlescaper | attrescaper}}"></a> 98 99 If an attribute has both a namespace and a "data-" prefix, only the namespace 100 will be removed when determining the context. For example 101 102 <a my:data-href="{{.}}"></a> 103 104 This is handled as if "my:data-href" was just "data-href" and not "href" as 105 it would be if the "data-" prefix were to be ignored too. Thus at parse 106 time this becomes just 107 108 <a my:data-href="{{. | attrescaper}}"></a> 109 110 As a special case, attributes with the namespace "xmlns" are always treated 111 as containing URLs. Given the excerpts 112 113 <a xmlns:title="{{.}}"></a> 114 <a xmlns:href="{{.}}"></a> 115 <a xmlns:onclick="{{.}}"></a> 116 117 At parse time they become: 118 119 <a xmlns:title="{{. | urlescaper | attrescaper}}"></a> 120 <a xmlns:href="{{. | urlescaper | attrescaper}}"></a> 121 <a xmlns:onclick="{{. | urlescaper | attrescaper}}"></a> 122 123 # Errors 124 125 See the documentation of ErrorCode for details. 126 127 # A fuller picture 128 129 The rest of this package comment may be skipped on first reading; it includes 130 details necessary to understand escaping contexts and error messages. Most users 131 will not need to understand these details. 132 133 # Contexts 134 135 Assuming {{.}} is `O'Reilly: How are <i>you</i>?`, the table below shows 136 how {{.}} appears when used in the context to the left. 137 138 Context {{.}} After 139 {{.}} O'Reilly: How are <i>you</i>? 140 <a title='{{.}}'> O'Reilly: How are you? 141 <a href="/{{.}}"> O'Reilly: How are %3ci%3eyou%3c/i%3e? 142 <a href="?q={{.}}"> O'Reilly%3a%20How%20are%3ci%3e...%3f 143 <a onx='f("{{.}}")'> O\x27Reilly: How are \x3ci\x3eyou...? 144 <a onx='f({{.}})'> "O\x27Reilly: How are \x3ci\x3eyou...?" 145 146 If used in an unsafe context, then the value might be filtered out: 147 148 Context {{.}} After 149 <a href="{{.}}"> #ZgotmplZ 150 151 since "O'Reilly:" is not an allowed protocol like "http:". 152 153 If {{.}} is the innocuous word, `left`, then it can appear more widely, 154 155 Context {{.}} After 156 {{.}} left 157 <a title='{{.}}'> left 158 <a href='{{.}}'> left 159 <a href='/{{.}}'> left 160 <a href='?dir={{.}}'> left 161 <a style="border-{{.}}: 4px"> left 162 <a style="align: {{.}}"> left 163 <a style="background: '{{.}}'> left 164 <a style="background: url('{{.}}')> left 165 <style>p.{{.}} {color:red}</style> left 166 167 Non-string values can be used in JavaScript contexts. 168 If {{.}} is 169 170 struct{A,B string}{ "foo", "bar" } 171 172 in the escaped template 173 174 <script>var pair = {{.}};</script> 175 176 then the template output is 177 178 <script>var pair = {"A": "foo", "B": "bar"};</script> 179 180 See package json to understand how non-string content is marshaled for 181 embedding in JavaScript contexts. 182 183 # Typed Strings 184 185 By default, this package assumes that all pipelines produce a plain text string. 186 It adds escaping pipeline stages necessary to correctly and safely embed that 187 plain text string in the appropriate context. 188 189 When a data value is not plain text, you can make sure it is not over-escaped 190 by marking it with its type. 191 192 Types HTML, JS, URL, and others from content.go can carry safe content that is 193 exempted from escaping. 194 195 The template 196 197 Hello, {{.}}! 198 199 can be invoked with 200 201 tmpl.Execute(out, template.HTML(`<b>World</b>`)) 202 203 to produce 204 205 Hello, <b>World</b>! 206 207 instead of the 208 209 Hello, <b>World<b>! 210 211 that would have been produced if {{.}} was a regular string. 212 213 # JavaScript 214 215 This package escapes template actions in JavaScript contexts depending 216 on where the action appears. For example, in the template 217 218 <script> 219 let x = {{.}}; 220 let y = "{{.}}, world."; 221 let z = `{{.}}, world.`; 222 </script> 223 224 if {{.}} is "hello" then the template output is 225 226 <script> 227 let x = "hello"; 228 let y = "hello, world."; 229 let z = `hello, world.`; 230 </script> 231 232 with double quotes added to the first substitution but not the second or third. 233 234 Template actions in JavaScript may appear in a <script> element 235 (either with no type attribute, or one of the types shown below) 236 or an HTML on* handler. Actions appearing in any other location may 237 not be detected. 238 239 <script>let x = {{.}};</script> // script 240 <script type="module">let x = {{.}};</script> // script 241 <script type="text/javascript">let x = {{.}};</script> // script 242 <script type="application/javascript">let x = {{.}};</script> // script 243 <script type="application/json">{{.}}</script> // JSON 244 <script type="application/ld+json">{{.}}</script> // JSON 245 <button onclick="f({{.}})"> // event handler 246 247 This package interprets a subset of JavaScript syntax. 248 Template actions in JavaScript are safe when all of the following hold: 249 250 - The script the action appears in consists of only 251 declarations, assignments, literals, and calls. 252 253 - The action is a standalone value, or is inside a quoted string 254 or template literal (without ${...}). 255 256 - The interpolated value is used as data, not as an object property key, 257 and is not passed to APIs that interpret strings as code, HTML, or URLs. 258 This package does not sanitize HTML or URLs inside JavaScript. 259 260 The following are safe uses of actions in JavaScript: 261 262 let a = {{.}}; // entire initializer 263 window.b = {{.}}; // entire right-hand side 264 const c = [{{.X}}, {{.Y}}]; // entire array element 265 const d = {key: {{.}}}; // entire property value 266 f({{.}}); // entire call argument 267 let e = "Hello, {{.}}."; // double-quoted string 268 let g = 'Hello, {{.}}.'; // single-quoted string 269 let h = `Hello, {{.}}.`; // template literal, no ${...} 270 271 Outside of the cases described above, escaping is best-effort 272 and safety cannot be assured. 273 274 The following is a non-exhaustive list of unsafe uses of actions in JavaScript: 275 276 let a = x + {{.}}; // UNSAFE: operator 277 let b = /{{.}}/; // UNSAFE: regular expression 278 let c = `${x}{{.}}`; // UNSAFE: template literal with ${...} 279 let d = { {{.}}: 1 }; // UNSAFE: property key 280 let e = obj[{{.}}]; // UNSAFE: property lookup 281 if ({{.}}) { ... } // UNSAFE: control flow 282 el.innerHTML = {{.}}; // UNSAFE: value interpreted as HTML 283 284 To pass template data to a complex JavaScript program, 285 use a dedicated <script> element to initialize variables 286 and keep complex program logic in separate elements 287 or external files. 288 289 # Security Model 290 291 https://web.archive.org/web/20160501113828/http://js-quasis-libraries-and-repl.googlecode.com/svn/trunk/safetemplate.html#problem_definition defines "safe" as used by this package. 292 293 This package assumes that template authors are trusted, that Execute's data 294 parameter is not, and seeks to preserve the properties below in the face 295 of untrusted data: 296 297 Structure Preservation Property: 298 "... when a template author writes an HTML tag in a safe templating language, 299 the browser will interpret the corresponding portion of the output as a tag 300 regardless of the values of untrusted data, and similarly for other structures 301 such as attribute boundaries and JS and CSS string boundaries." 302 303 Code Effect Property: 304 "... only code specified by the template author should run as a result of 305 injecting the template output into a page and all code specified by the 306 template author should run as a result of the same." 307 308 Least Surprise Property: 309 "A developer (or code reviewer) familiar with HTML, CSS, and JavaScript, who 310 knows that contextual autoescaping happens should be able to look at a {{.}} 311 and correctly infer what sanitization happens." 312 313 Interpolation of template actions into JavaScript contexts outside of the 314 safe subset documented in the JavaScript section above is outside the scope 315 of this package's security model. Incorrect escaping outside of the safe subset 316 may be a bug but is not considered a security issue. 317 */ 318 package template 319