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, &lt;script&gt;alert(&#39;you have been pwned&#39;)&lt;/script&gt;!
    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 &lt;i&gt;you&lt;/i&gt;?
   140  	<a title='{{.}}'>                O&#39;Reilly: How are you?
   141  	<a href="/{{.}}">                O&#39;Reilly: How are %3ci%3eyou%3c/i%3e?
   142  	<a href="?q={{.}}">              O&#39;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, &lt;b&gt;World&lt;b&gt;!
   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  

View as plain text