diff options
Diffstat (limited to 'docs/content/en/functions/safe')
| -rw-r--r-- | docs/content/en/functions/safe/CSS.md | 62 | ||||
| -rw-r--r-- | docs/content/en/functions/safe/HTML.md | 54 | ||||
| -rw-r--r-- | docs/content/en/functions/safe/HTMLAttr.md | 60 | ||||
| -rw-r--r-- | docs/content/en/functions/safe/JS.md | 60 | ||||
| -rw-r--r-- | docs/content/en/functions/safe/JSStr.md | 62 | ||||
| -rw-r--r-- | docs/content/en/functions/safe/URL.md | 61 | ||||
| -rw-r--r-- | docs/content/en/functions/safe/_index.md | 7 |
7 files changed, 366 insertions, 0 deletions
diff --git a/docs/content/en/functions/safe/CSS.md b/docs/content/en/functions/safe/CSS.md new file mode 100644 index 000000000..12ebbf8aa --- /dev/null +++ b/docs/content/en/functions/safe/CSS.md @@ -0,0 +1,62 @@ +--- +title: safe.CSS +description: Declares the given string as a safe CSS string. +categories: [] +keywords: [] +params: + functions_and_methods: + aliases: [safeCSS] + returnType: template.CSS + signatures: [safe.CSS INPUT] +aliases: [/functions/safecss] +--- + +## Introduction + +{{% include "/_common/functions/go-html-template-package.md" %}} + +## Usage + +Use the `safe.CSS` function to encapsulate known safe content that matches any of: + +1. The CSS3 stylesheet production, such as `p { color: purple }`. +1. The CSS3 rule production, such as `a[href=~"https:"].foo#bar`. +1. CSS3 declaration productions, such as `color: red; margin: 2px`. +1. The CSS3 value production, such as `rgba(0, 0, 255, 127)`. + +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. + +See the [Go documentation] for details. + +## Example + +Without a safe declaration: + +```go-html-template +{{ $style := "color: red;" }} +<p style="{{ $style }}">foo</p> +``` + +Hugo renders the above to: + +```html +<p style="ZgotmplZ">foo</p> +``` + +> [!note] +> `ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime. + +To declare the string as safe: + +```go-html-template +{{ $style := "color: red;" }} +<p style="{{ $style | safeCSS }}">foo</p> +``` + +Hugo renders the above to: + +```html +<p style="color: red;">foo</p> +``` + +[Go documentation]: https://pkg.go.dev/html/template#CSS diff --git a/docs/content/en/functions/safe/HTML.md b/docs/content/en/functions/safe/HTML.md new file mode 100644 index 000000000..25ffb3318 --- /dev/null +++ b/docs/content/en/functions/safe/HTML.md @@ -0,0 +1,54 @@ +--- +title: safe.HTML +description: Declares the given string as a safeHTML string. +categories: [] +keywords: [] +params: + functions_and_methods: + aliases: [safeHTML] + returnType: template.HTML + signatures: [safe.HTML INPUT] +aliases: [/functions/safehtml] +--- + +## Introduction + +{{% include "/_common/functions/go-html-template-package.md" %}} + +## Usage + +Use the `safe.HTML` function to encapsulate a known safe HTML document fragment. It should not be used for HTML from a third-party, or HTML with unclosed tags or comments. + +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. + +See the [Go documentation] for details. + +[Go documentation]: https://pkg.go.dev/html/template#HTML + +## Example + +Without a safe declaration: + +```go-html-template +{{ $html := "<em>emphasized</em>" }} +{{ $html }} +``` + +Hugo renders the above to: + +```html +<em>emphasized</em> +``` + +To declare the string as safe: + +```go-html-template +{{ $html := "<em>emphasized</em>" }} +{{ $html | safeHTML }} +``` + +Hugo renders the above to: + +```html +<em>emphasized</em> +``` diff --git a/docs/content/en/functions/safe/HTMLAttr.md b/docs/content/en/functions/safe/HTMLAttr.md new file mode 100644 index 000000000..7cfefdfb2 --- /dev/null +++ b/docs/content/en/functions/safe/HTMLAttr.md @@ -0,0 +1,60 @@ +--- +title: safe.HTMLAttr +description: Declares the given key-value pair as a safe HTML attribute. +categories: [] +keywords: [] +params: + functions_and_methods: + aliases: [safeHTMLAttr] + returnType: template.HTMLAttr + signatures: [safe.HTMLAttr INPUT] +aliases: [/functions/safehtmlattr] +--- + +## Introduction + +{{% include "/_common/functions/go-html-template-package.md" %}} + +## Usage + +Use the `safe.HTMLAttr` function to encapsulate an HTML attribute from a trusted source. + +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. + +See the [Go documentation] for details. + +[Go documentation]: https://pkg.go.dev/html/template#HTMLAttr + +## Example + +Without a safe declaration: + +```go-html-template +{{ with .Date }} + {{ $humanDate := time.Format "2 Jan 2006" . }} + {{ $machineDate := time.Format "2006-01-02T15:04:05-07:00" . }} + <time datetime="{{ $machineDate }}">{{ $humanDate }}</time> +{{ end }} +``` + +Hugo renders the above to: + +```html +<time datetime="2024-05-26T07:19:55+02:00">26 May 2024</time> +``` + +To declare the key-value pair as safe: + +```go-html-template +{{ with .Date }} + {{ $humanDate := time.Format "2 Jan 2006" . }} + {{ $machineDate := time.Format "2006-01-02T15:04:05-07:00" . }} + <time {{ printf "datetime=%q" $machineDate | safeHTMLAttr }}>{{ $humanDate }}</time> +{{ end }} +``` + +Hugo renders the above to: + +```html +<time datetime="2024-05-26T07:19:55+02:00">26 May 2024</time> +``` diff --git a/docs/content/en/functions/safe/JS.md b/docs/content/en/functions/safe/JS.md new file mode 100644 index 000000000..0c4d9009d --- /dev/null +++ b/docs/content/en/functions/safe/JS.md @@ -0,0 +1,60 @@ +--- +title: safe.JS +description: Declares the given string as a safe JavaScript expression. +categories: [] +keywords: [] +params: + functions_and_methods: + aliases: [safeJS] + returnType: template.JS + signatures: [safe.JS INPUT] +aliases: [/functions/safejs] +--- + +## Introduction + +{{% include "/_common/functions/go-html-template-package.md" %}} + +## Usage + +Use the `safe.JS` function to encapsulate a known safe EcmaScript5 Expression. + +Template authors are responsible for ensuring that typed expressions do not break the intended precedence and that there is no 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 the `safe.JS` function to include valid but untrusted JSON is not safe. A safe alternative is to parse the JSON with the [`transform.Unmarshal`] function and then pass the resultant object into the template, where it will be converted to sanitized JSON when presented in a JavaScript context. + +[`transform.Unmarshal`]: /functions/transform/unmarshal/ + +See the [Go documentation] for details. + +[Go documentation]: https://pkg.go.dev/html/template#JS + +## Example + +Without a safe declaration: + +```go-html-template +{{ $js := "x + y" }} +<script>const a = {{ $js }}</script> +``` + +Hugo renders the above to: + +```html +<script>const a = "x + y"</script> +``` + +To declare the string as safe: + +```go-html-template +{{ $js := "x + y" }} +<script>const a = {{ $js | safeJS }}</script> +``` + +Hugo renders the above to: + +```html +<script>const a = x + y</script> +``` diff --git a/docs/content/en/functions/safe/JSStr.md b/docs/content/en/functions/safe/JSStr.md new file mode 100644 index 000000000..81946a14c --- /dev/null +++ b/docs/content/en/functions/safe/JSStr.md @@ -0,0 +1,62 @@ +--- +title: safe.JSStr +description: Declares the given string as a safe JavaScript string. +categories: [] +keywords: [] +params: + functions_and_methods: + aliases: [safeJSStr] + returnType: template.JSStr + signatures: [safe.JSStr INPUT] +aliases: [/functions/safejsstr] +--- + +## Introduction + +{{% include "/_common/functions/go-html-template-package.md" %}} + +## Usage + +Use the `safe.JSStr` function to encapsulate a sequence of characters meant to be embedded between quotes in a JavaScript expression. + +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. + +See the [Go documentation] for details. + +[Go documentation]: https://pkg.go.dev/html/template#JSStr + +## Example + +Without a safe declaration: + +```go-html-template +{{ $title := "Lilo & Stitch" }} +<script> + const a = "Title: " + {{ $title }}; +</script> +``` + +Hugo renders the above to: + +```html +<script> + const a = "Title: " + "Lilo \u0026 Stitch"; +</script> +``` + +To declare the string as safe: + +```go-html-template +{{ $title := "Lilo & Stitch" }} +<script> + const a = "Title: " + {{ $title | safeJSStr }}; +</script> +``` + +Hugo renders the above to: + +```html +<script> + const a = "Title: " + "Lilo & Stitch"; +</script> +``` diff --git a/docs/content/en/functions/safe/URL.md b/docs/content/en/functions/safe/URL.md new file mode 100644 index 000000000..44bed8064 --- /dev/null +++ b/docs/content/en/functions/safe/URL.md @@ -0,0 +1,61 @@ +--- +title: safe.URL +description: Declares the given string as a safe URL or URL substring. +categories: [] +keywords: [] +params: + functions_and_methods: + aliases: [safeURL] + returnType: template.URL + signatures: [safe.URL INPUT] +aliases: [/functions/safeurl] +--- + +## Introduction + +{{% include "/_common/functions/go-html-template-package.md" %}} + +## Usage + +Use the `safe.URL` function to encapsulate a known safe URL or URL substring. Schemes other than the following are considered unsafe: + +- `http:` +- `https:` +- `mailto:` + +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. + +See the [Go documentation] for details. + +## Example + +Without a safe declaration: + +```go-html-template +{{ $href := "irc://irc.freenode.net/#golang" }} +<a href="{{ $href }}">IRC</a> +``` + +Hugo renders the above to: + +```html +<a href="#ZgotmplZ">IRC</a> +``` + +> [!note] +> `ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime. + +To declare the string as safe: + +```go-html-template +{{ $href := "irc://irc.freenode.net/#golang" }} +<a href="{{ $href | safeURL }}">IRC</a> +``` + +Hugo renders the above to: + +```html +<a href="irc://irc.freenode.net/#golang">IRC</a> +``` + +[Go documentation]: https://pkg.go.dev/html/template#URL diff --git a/docs/content/en/functions/safe/_index.md b/docs/content/en/functions/safe/_index.md new file mode 100644 index 000000000..8d5697b8d --- /dev/null +++ b/docs/content/en/functions/safe/_index.md @@ -0,0 +1,7 @@ +--- +title: Safe functions +linkTitle: safe +description: Use these functions to declare a value as safe in the context of Go's html/template package. +categories: [] +keywords: [] +--- |