Source file src/pkg/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 package 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 package 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	The security model used by this package assumes that template authors are
    32	trusted, while Execute's data parameter is not. More details are
    33	provided below.
    34	
    35	Example
    36	
    37	  import "text/template"
    38	  ...
    39	  t, err := template.New("foo").Parse(`{{define "T"}}Hello, {{.}}!{{end}}`)
    40	  err = t.ExecuteTemplate(out, "T", "<script>alert('you have been pwned')</script>")
    41	
    42	produces
    43	
    44	  Hello, <script>alert('you have been pwned')</script>!
    45	
    46	but the contextual autoescaping in html/template
    47	
    48	  import "html/template"
    49	  ...
    50	  t, err := template.New("foo").Parse(`{{define "T"}}Hello, {{.}}!{{end}}`)
    51	  err = t.ExecuteTemplate(out, "T", "<script>alert('you have been pwned')</script>")
    52	
    53	produces safe, escaped HTML output
    54	
    55	  Hello, &lt;script&gt;alert(&#39;you have been pwned&#39;)&lt;/script&gt;!
    56	
    57	
    58	Contexts
    59	
    60	This package understands HTML, CSS, JavaScript, and URIs. It adds sanitizing
    61	functions to each simple action pipeline, so given the excerpt
    62	
    63	  <a href="/search?q={{.}}">{{.}}</a>
    64	
    65	At parse time each {{.}} is overwritten to add escaping functions as necessary.
    66	In this case it becomes
    67	
    68	  <a href="/search?q={{. | urlquery}}">{{. | html}}</a>
    69	
    70	
    71	Errors
    72	
    73	See the documentation of ErrorCode for details.
    74	
    75	
    76	A fuller picture
    77	
    78	The rest of this package comment may be skipped on first reading; it includes
    79	details necessary to understand escaping contexts and error messages. Most users
    80	will not need to understand these details.
    81	
    82	
    83	Contexts
    84	
    85	Assuming {{.}} is `O'Reilly: How are <i>you</i>?`, the table below shows
    86	how {{.}} appears when used in the context to the left.
    87	
    88	  Context                          {{.}} After
    89	  {{.}}                            O'Reilly: How are &lt;i&gt;you&lt;/i&gt;?
    90	  <a title='{{.}}'>                O&#39;Reilly: How are you?
    91	  <a href="/{{.}}">                O&#39;Reilly: How are %3ci%3eyou%3c/i%3e?
    92	  <a href="?q={{.}}">              O&#39;Reilly%3a%20How%20are%3ci%3e...%3f
    93	  <a onx='f("{{.}}")'>             O\x27Reilly: How are \x3ci\x3eyou...?
    94	  <a onx='f({{.}})'>               "O\x27Reilly: How are \x3ci\x3eyou...?"
    95	  <a onx='pattern = /{{.}}/;'>     O\x27Reilly: How are \x3ci\x3eyou...\x3f
    96	
    97	If used in an unsafe context, then the value might be filtered out:
    98	
    99	  Context                          {{.}} After
   100	  <a href="{{.}}">                 #ZgotmplZ
   101	
   102	since "O'Reilly:" is not an allowed protocol like "http:".
   103	
   104	
   105	If {{.}} is the innocuous word, `left`, then it can appear more widely,
   106	
   107	  Context                              {{.}} After
   108	  {{.}}                                left
   109	  <a title='{{.}}'>                    left
   110	  <a href='{{.}}'>                     left
   111	  <a href='/{{.}}'>                    left
   112	  <a href='?dir={{.}}'>                left
   113	  <a style="border-{{.}}: 4px">        left
   114	  <a style="align: {{.}}">             left
   115	  <a style="background: '{{.}}'>       left
   116	  <a style="background: url('{{.}}')>  left
   117	  <style>p.{{.}} {color:red}</style>   left
   118	
   119	Non-string values can be used in JavaScript contexts.
   120	If {{.}} is
   121	
   122	  []struct{A,B string}{ "foo", "bar" }
   123	
   124	in the escaped template
   125	
   126	  <script>var pair = {{.}};</script>
   127	
   128	then the template output is
   129	
   130	  <script>var pair = {"A": "foo", "B": "bar"};</script>
   131	
   132	See package json to understand how non-string content is marshalled for
   133	embedding in JavaScript contexts.
   134	
   135	
   136	Typed Strings
   137	
   138	By default, this package assumes that all pipelines produce a plain text string.
   139	It adds escaping pipeline stages necessary to correctly and safely embed that
   140	plain text string in the appropriate context.
   141	
   142	When a data value is not plain text, you can make sure it is not over-escaped
   143	by marking it with its type.
   144	
   145	Types HTML, JS, URL, and others from content.go can carry safe content that is
   146	exempted from escaping.
   147	
   148	The template
   149	
   150	  Hello, {{.}}!
   151	
   152	can be invoked with
   153	
   154	  tmpl.Execute(out, HTML(`<b>World</b>`))
   155	
   156	to produce
   157	
   158	  Hello, <b>World</b>!
   159	
   160	instead of the
   161	
   162	  Hello, &lt;b&gt;World&lt;b&gt;!
   163	
   164	that would have been produced if {{.}} was a regular string.
   165	
   166	
   167	Security Model
   168	
   169	http://js-quasis-libraries-and-repl.googlecode.com/svn/trunk/safetemplate.html#problem_definition defines "safe" as used by this package.
   170	
   171	This package assumes that template authors are trusted, that Execute's data
   172	parameter is not, and seeks to preserve the properties below in the face
   173	of untrusted data:
   174	
   175	Structure Preservation Property:
   176	"... when a template author writes an HTML tag in a safe templating language,
   177	the browser will interpret the corresponding portion of the output as a tag
   178	regardless of the values of untrusted data, and similarly for other structures
   179	such as attribute boundaries and JS and CSS string boundaries."
   180	
   181	Code Effect Property:
   182	"... only code specified by the template author should run as a result of
   183	injecting the template output into a page and all code specified by the
   184	template author should run as a result of the same."
   185	
   186	Least Surprise Property:
   187	"A developer (or code reviewer) familiar with HTML, CSS, and JavaScript, who
   188	knows that contextual autoescaping happens should be able to look at a {{.}}
   189	and correctly infer what sanitization happens."
   190	*/
   191	package template