mirrors/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-04-29 15:10:35 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Merge commit '8b9803425e'

Browse source
This commit is contained in:
Bjørn Erik Pedersen 2024-06-21 09:41:24 +02:00
commit af0cb57aaf
No known key found for this signature in database
475 changed files with 7408 additions and 4720 deletions
Download patch file Download diff file Expand all files Collapse all files

48
docs/content/en/functions/safe/CSS.md
View file

@ -1,6 +1,6 @@
---
title: safe.CSS
description: Declares the given string as safe CSS string.
description: Declares the given string as a safe CSS string.
categories: []
keywords: []
action:
@ -13,21 +13,57 @@ action:
- functions/safe/URL
returnType: template.CSS
signatures: [safe.CSS INPUT]
toc: true
aliases: [/functions/safecss]
---
In this context, *safe* means CSS content that matches any of the following:
## Introduction
{{% include "functions/_common/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 }`.
2. The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
3. CSS3 declaration productions, such as `color: red; margin: 2px`.
4. The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
Example: Given `style = "color: red;"` defined in the front matter of your `.md` file:
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.
* `<p style="{{ .Params.style | safeCSS }}">…</p>` &rarr; `<p style="color: red;">…</p>`
* `<p style="{{ .Params.style }}">…</p>` &rarr; `<p style="ZgotmplZ">…</p>`
See the [Go documentation] for details.
[Go documentation]: https://pkg.go.dev/html/template#CSS
## 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.
`ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime.
{{% /note %}}
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>
```

43
docs/content/en/functions/safe/HTML.md
View file

@ -13,27 +13,48 @@ action:
- functions/safe/URL
returnType: template.HTML
signatures: [safe.HTML INPUT]
toc: true
aliases: [/functions/safehtml]
---
It should not be used for HTML from a third-party, or HTML with unclosed tags or comments.
## Introduction
Given a site-wide [`hugo.toml`][config] with the following `copyright` value:
{{% include "functions/_common/go-html-template-package.md" %}}
{{< code-toggle file=hugo >}}
copyright = "© 2015 Jane Doe. <a href=\"https://creativecommons.org/licenses/by/4.0/\">Some rights reserved</a>."
{{< /code-toggle >}}
## Usage
`{{ .Site.Copyright | safeHTML }}` in a template would then output:
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.
```html
© 2015 Jane Doe. <a href="https://creativecommons.org/licenses/by/4.0/">Some rights reserved</a>.
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 }}
```
However, without the `safeHTML` function, html/template assumes `.Site.Copyright` to be unsafe and therefore escapes all HTML tags and renders the whole string as plain text:
Hugo renders the above to:
```html
<p>© 2015 Jane Doe. &lt;a href=&#34;https://creativecommons.org/licenses by/4.0/&#34;&gt;Some rights reserved&lt;/a&gt;.</p>
&lt;em&gt;emphasized&lt;/em&gt;
```
[config]: /getting-started/configuration/
To declare the string as safe:
```go-html-template
{{ $html := "<em>emphasized</em>" }}
{{ $html | safeHTML }}
```
Hugo renders the above to:
```html
<em>emphasized</em>
```

53
docs/content/en/functions/safe/HTMLAttr.md
View file

@ -1,6 +1,6 @@
---
title: safe.HTMLAttr
description: Declares the given key/value pair as a safe HTML attribute.
description: Declares the given key-value pair as a safe HTML attribute.
categories: []
keywords: []
action:
@ -13,43 +13,54 @@ action:
- functions/safe/URL
returnType: template.HTMLAttr
signatures: [safe.HTMLAttr INPUT]
toc: true
aliases: [/functions/safehtmlattr]
---
Given a site configuration that contains this menu entry:
## Introduction
{{< code-toggle file=hugo >}}
[[menus.main]]
name = "IRC"
url = "irc://irc.freenode.net/#golang"
{{< /code-toggle >}}
{{% include "functions/_common/go-html-template-package.md" %}}
Attempting to use the `url` value directly in an attribute:
## 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
{{ range site.Menus.main }}
<a href="{{ .URL }}">{{ .Name }}</a>
{{ with .Date }}
{{ $humanDate := time.Format "2 Jan 2006" . }}
{{ $machineDate := time.Format "2006-01-02T15:04:05-07:00" . }}
<time datetime="{{ $machineDate }}">{{ $humanDate }}</time>
{{ end }}
```
Will produce:
Hugo renders the above to:
```html
<a href="#ZgotmplZ">IRC</a>
<time datetime="2024-05-26T07:19:55&#43;02:00">26 May 2024</time>
```
`ZgotmplZ` is a special value, inserted by Go's [template/html] package, that indicates that unsafe content reached a CSS or URL context.
To indicate that the HTML attribute is safe:
To declare the key-value pair as safe:
```go-html-template
{{ range site.Menus.main }}
<a {{ printf "href=%q" .URL | safeHTMLAttr }}>{{ .Name }}</a>
{{ 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 }}
```
{{% note %}}
As demonstrated above, you must pass the HTML attribute name _and_ value through the function. Applying `safeHTMLAttr` to the attribute value has no effect.
{{% /note %}}
Hugo renders the above to:
[template/html]: https://pkg.go.dev/html/template
```html
<time datetime="2024-05-26T07:19:55+02:00">26 May 2024</time>
```

50
docs/content/en/functions/safe/JS.md
View file

@ -13,14 +13,54 @@ action:
- functions/safe/URL
returnType: template.JS
signatures: [safe.JS INPUT]
toc: true
aliases: [/functions/safejs]
---
In this context, *safe* means the string encapsulates a known safe EcmaScript5 Expression (e.g., `(x + y * z())`).
## Introduction
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.
{{% include "functions/_common/go-html-template-package.md" %}}
Example: Given `hash = "619c16f"` defined in the front matter of your `.md` file:
## Usage
* `<script>var form_{{ .Params.hash | safeJS }};…</script>` &rarr; `<script>var form_619c16f;…</script>`
* `<script>var form_{{ .Params.hash }};…</script>` &rarr; `<script>var form_"619c16f";…</script>`
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>
```

29
docs/content/en/functions/safe/JSStr.md
View file

@ -13,12 +13,27 @@ action:
- functions/safe/URL
returnType: template.JSStr
signatures: [safe.JSStr INPUT]
toc: true
aliases: [/functions/safejsstr]
---
Encapsulates 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.
Without declaring a variable to be a safe JavaScript string:
## Introduction
{{% include "functions/_common/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" }}
@ -27,7 +42,7 @@ Without declaring a variable to be a safe JavaScript string:
</script>
```
Rendered:
Hugo renders the above to:
```html
<script>
@ -35,7 +50,7 @@ Rendered:
</script>
```
To avoid escaping by Go's [html/template] package:
To declare the string as safe:
```go-html-template
{{ $title := "Lilo & Stitch" }}
@ -44,12 +59,10 @@ To avoid escaping by Go's [html/template] package:
</script>
```
Rendered:
Hugo renders the above to:
```html
<script>
const a = "Title: " + "Lilo & Stitch";
</script>
```
[html/template]: https://pkg.go.dev/html/template

76
docs/content/en/functions/safe/URL.md
View file

@ -13,58 +13,56 @@ action:
- functions/safe/JSStr
returnType: template.URL
signatures: [safe.URL INPUT]
toc: true
aliases: [/functions/safeurl]
---
`safeURL` declares the provided string as a "safe" URL or URL substring (see [RFC 3986]). A URL like `javascript:checkThatFormNotEditedBeforeLeavingPage()` from a trusted source should go in the page, but by default dynamic `javascript:` URLs are filtered out since they are a frequently exploited injection vector.
## Introduction
Without `safeURL`, only the URI schemes `http:`, `https:` and `mailto:` are considered safe by Go templates. If any other URI schemes (e.g., `irc:` and `javascript:`) are detected, the whole URL will be replaced with `#ZgotmplZ`. This is to "defang" any potential attack in the URL by rendering it useless.
{{% include "functions/_common/go-html-template-package.md" %}}
The following examples use a [site `hugo.toml`][configuration] with the following [menu entry][menus]:
## Usage
{{< code-toggle file=hugo >}}
[[menus.main]]
name = "IRC: #golang at freenode"
url = "irc://irc.freenode.net/#golang"
{{< /code-toggle >}}
Use the `safe.URL` function to encapsulate a known safe URL or URL substring. Schemes other than the following are considered unsafe:
The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example:
- `http:`
- `https:`
- `mailto:`
{{< code file=layouts/partials/bad-url-sidebar-menu.html >}}
<!-- This unordered list may be part of a sidebar menu -->
<ul>
{{ range .Site.Menus.main }}
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
{{ end }}
</ul>
{{< /code >}}
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.
This partial would produce the following HTML output:
See the [Go documentation] for details.
```html
<!-- This unordered list may be part of a sidebar menu -->
<ul>
<li><a href="#ZgotmplZ">IRC: #golang at freenode</a></li>
</ul>
[Go documentation]: https://pkg.go.dev/html/template#URL
## Example
Without a safe declaration:
```go-html-template
{{ $href := "irc://irc.freenode.net/#golang" }}
<a href="{{ $href }}">IRC</a>
```
The odd output can be remedied by adding ` | safeURL` to our `.URL` page variable:
{{< code file=layouts/partials/correct-url-sidebar-menu.html >}}
<!-- This unordered list may be part of a sidebar menu -->
<ul>
<li><a href="{{ .URL | safeURL }}">{{ .Name }}</a></li>
</ul>
{{< /code >}}
With the `.URL` page variable piped through `safeURL`, we get the desired output:
Hugo renders the above to:
```html
<ul class="sidebar-menu">
<li><a href="irc://irc.freenode.net/#golang">IRC: #golang at freenode</a></li>
</ul>
<a href="#ZgotmplZ">IRC</a>
```
[configuration]: /getting-started/configuration/
[menus]: /content-management/menus/
[RFC 3986]: https://tools.ietf.org/html/rfc3986
{{% note %}}
`ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime.
{{% /note %}}
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>
```