FF145 Relnote: Trusted Types early beta #41518
+113
−22
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -121,3 +121,13 @@ You can find more such features on the [Experimental features](/en-US/docs/Mozil | |||||
|
|
||||||
| The CSS `text-decoration-trim` property is supported but currently disabled by default. | ||||||
| It allows you to specify {{cssxref("text-decoration")}} start and end offsets to shorten, lengthen, or shift the position of text decorations with respect to the text ([Firefox bug 1979915](https://bugzil.la/1979915)). | ||||||
|
|
||||||
| - **Trusted Types API** for scripts (Nightly/Early Beta): `dom.security.trusted_types.enabled` | ||||||
|
|
||||||
| The [Trusted Types API](/en-US/docs/Web/API/Trusted_Types_API) is now fully implemented. ([Firefox bug 1976656](https://bugzil.la/1976656)). | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| The changes include: | ||||||
| - Addition of new interfaces {{domxref("TrustedTypePolicyFactory")}}, {{domxref("TrustedTypePolicy")}}, {{domxref("TrustedHTML")}}, {{domxref("TrustedScript")}}, {{domxref("TrustedScriptURL")}}, and the `trustedTypes` property on {{domxref("Window/trustedTypes", "Window")}} and {{domxref("WorkerGlobalScope/trustedTypes", "WorkerGlobalScope")}} | ||||||
|
There was a problem hiding this comment. Same suggestions as above if you like them. |
||||||
| - Updates to [injection sink interfaces](/en-US/docs/Web/API/Trusted_Types_API##injection_sink_interfaces) APIs, such as {{domxref("Element.innerHTML")}} and {{domxref("Document.write()", "document.write()")}}, to allow the `TrustedHTML`, `TrustedScript`, `TrustedScriptURL` to be passed as well as strings. | ||||||
| - Support for the [`require-trusted-types-for`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for) and [`trusted-types`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/trusted-types) directives, and the [`'trusted-types-eval'`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#trusted-types-eval) keyword, of the {{HTTPHeader("Content-Security-Policy")}} HTTP header. | ||||||
| These can be used to enforce trusted types instead of strings, name the specific policies that are allowed, and to enable [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) and similar functions to be used when [Trusted Types](/en-US/docs/Web/API/Trusted_Types_API) are supported and enforced. | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -12,7 +12,7 @@ The **Trusted Types API** gives web developers a way to ensure that input has be | |
|
|
||
| ## Concepts and usage | ||
|
|
||
| Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as [_injection sinks_](#injection_sink_interfaces). | ||
|
|
||
| The Trusted Types API distinguishes three sorts of injection sinks: | ||
|
|
||
|
|
@@ -201,6 +201,69 @@ Either way, the injection sink gets sanitized data, and because we could enforce | |
| - {{domxref("TrustedTypePolicyFactory")}} | ||
| - : Creates policies and verifies that Trusted Type object instances were created via one of the policies. | ||
|
|
||
| ### Extensions to other interfaces | ||
|
|
||
| - {{domxref("Window.trustedTypes")}} | ||
| - : Returns the {{domxref("TrustedTypePolicyFactory")}} object associated with the global object in the main thread. | ||
| This is the entry point for using the API in the Window thread. | ||
| - {{domxref("WorkerGlobalScope.trustedTypes")}}. | ||
| - : Returns the {{domxref("TrustedTypePolicyFactory")}} object associated with the global object in a worker. | ||
|
|
||
| ### Extensions to HTTP | ||
|
|
||
| #### `Content-Security-Policy` directives | ||
|
|
||
| - {{CSP("require-trusted-types-for")}} | ||
| - : Enforces that [Trusted Types](/en-US/docs/Web/API/Trusted_Types_API) are passed to DOM XSS [injection sinks](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage). | ||
| - {{CSP("trusted-types")}} | ||
| - : Used to specify an allowlist of [Trusted Types](/en-US/docs/Web/API/Trusted_Types_API) policy names. | ||
|
|
||
| #### `Content-Security-Policy` keywords | ||
|
|
||
| - [`trusted-types-eval`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#trusted-types-eval) | ||
| - : Allows [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) and similar functions to be used but only when [Trusted Types](/en-US/docs/Web/API/Trusted_Types_API) are supported and enforced. | ||
|
|
||
| ## Injection sink interfaces | ||
|
|
||
| This section provides a (potentially) non-exhaustive list of injection sink interfaces. | ||
|
|
||
| ##### TrustedHTML | ||
hamishwillee marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| - {{domxref("Document.execCommand()")}} with a `commandName` of [`"insertHTML"`](/en-US/docs/Web/API/Document/execCommand#inserthtml) | ||
| - {{domxref("Document.parseHTMLUnsafe_static()")}} | ||
| - {{domxref("Document.write()")}} | ||
| - {{domxref("Document.writeln()")}} | ||
| - {{domxref("DOMParser.parseFromString()")}} | ||
| - {{domxref("Element.innerHTML")}} | ||
| - {{domxref("Element.insertAdjacentHTML")}} | ||
| - {{domxref("Element.outerHTML")}} | ||
| - {{domxref("Element.setHTMLUnsafe()")}} | ||
| - {{domxref("HTMLIFrameElement.srcdoc")}} | ||
| - {{domxref("Range.createContextualFragment()")}} | ||
| - {{domxref("ShadowRoot.innerHTML")}} | ||
| - {{domxref("ShadowRoot.setHTMLUnsafe()")}} | ||
|
|
||
| ##### TrustedScript | ||
|
|
||
| - [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) | ||
| - [`Element.setAttribute()`](/en-US/docs/Web/API/Element/setAttribute#value) (`value` argument) | ||
| - [`Element.setAttributeNS()`](/en-US/docs/Web/API/Element/setAttributeNS#value) (`value` argument) | ||
| - [`Function()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/Function) | ||
| - {{domxref("HTMLScriptElement.innerText")}} | ||
| - {{domxref("HTMLScriptElement.textContent")}} | ||
| - {{domxref("HTMLScriptElement.text")}} | ||
| - [`window.setTimeout()`](/en-US/docs/Web/API/Window/setTimeout#code) and [`WorkerGlobalScope.setTimeout()`](/en-US/docs/Web/API/WorkerGlobalScope/setTimeout#code) (`code` argument) | ||
| - [`window.setInterval()`](/en-US/docs/Web/API/Window/setInterval#code) and [`WorkerGlobalScope.setInterval()`](/en-US/docs/Web/API/WorkerGlobalScope/setInterval#code) (`code` argument) | ||
|
|
||
| ##### TrustedScriptURL | ||
|
|
||
| - {{domxref("HTMLScriptElement.src")}} | ||
| - {{domxref("ServiceWorkerContainer.register()")}} | ||
| - {{domxref("SvgAnimatedString.baseVal")}} | ||
| - {{domxref("WorkerGlobalScope.importScripts()")}} | ||
| - `url` argument to [`Worker()` constructor](/en-US/docs/Web/API/Worker/Worker#url) | ||
| - `url` argument to [`SharedWorker()` constructor](/en-US/docs/Web/API/SharedWorker/SharedWorker#url) | ||
|
|
||
| ## Examples | ||
|
|
||
| In the below example we create a policy that will create {{domxref("TrustedHTML")}} objects using {{domxref("TrustedTypePolicyFactory.createPolicy()")}}. We can then use {{domxref("TrustedTypePolicy.createHTML()")}} to create a sanitized HTML string to be inserted into the document. | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -329,7 +329,11 @@ Like inline JavaScript, if a CSP contains either a `default-src` or a `script-sr | |||||
| setTimeout("console.log('hello from setTimeout')", 1); | ||||||
| ``` | ||||||
|
|
||||||
| The `unsafe-eval` keyword can be used to override this behavior, and as with `unsafe-inline`, and for the same reasons: **developers should avoid `unsafe-eval`**. | ||||||
|
|
||||||
| Sometimes it can be difficult to remove usages of `eval()` and the other methods: in these situations, the [Trusted Types API](/en-US/docs/Web/API/Trusted_Types_API) can make it safer, by ensuring that the input meets a defined policy. | ||||||
| The `trusted-types-eval` keyword should be used to override the behavior in this case! | ||||||
|
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. Or we could drop this para in a note block if you think we should highlight it? |
||||||
| Unlike `unsafe-inline` it only overrides the behavior in browser when trusted types are supported and enabled; which ensures that the methods will remain blocked on browsers that don't support trusted types. | ||||||
|
|
||||||
| Unlike `unsafe-inline`, the `unsafe-eval` keyword does still work in a directive that contains nonce or hash expressions. | ||||||
|
|
||||||
|
|
||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -159,10 +159,8 @@ Reporting directives control the destination URL for CSP violation reports in `C | |
| - : Used to specify an allowlist of [Trusted Types](/en-US/docs/Web/API/Trusted_Types_API) policies. | ||
| Trusted Types allows applications to lock down DOM XSS injection sinks to only accept non-spoofable, typed values in place of strings. | ||
| - {{CSP("upgrade-insecure-requests")}} | ||
| - : Instructs user agents to treat all of a site's insecure URLs (those served over HTTP) as though they have been replaced with secure URLs (those served over HTTPS). | ||
| This directive is intended for websites with large numbers of insecure legacy URLs that need to be rewritten. | ||
|
|
||
| ### Deprecated directives | ||
|
|
||
|
|
@@ -272,14 +270,33 @@ Secure upgrades are allowed. For example: | |
| - If the document is served from `http://example.com`, then a CSP of `'self'` will also permit resources from `https://example.com`. | ||
| - If the document is served from `ws://example.org`, then a CSP of `'self'` will also permit resources from `wss://example.org`. | ||
|
|
||
| ### 'trusted-types-eval' | ||
|
|
||
| By default, if a CSP contains a `default-src` or a `script-src` directive, then JavaScript functions which evaluate their arguments as JavaScript are disabled. | ||
| This includes [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval), the [`code`](/en-US/docs/Web/API/Window/setTimeout#code) argument to {{domxref("Window.setTimeout()", "setTimeout()")}}, or the {{jsxref("Function/Function()", "Function()")}} constructor. | ||
|
|
||
| The `trusted-types-eval` keyword can be used to undo this protection, but only when [Trusted Types](/en-US/docs/Web/API/Trusted_Types_API) are enforced and passed to these functions instead of strings. | ||
| This allows dynamic evaluation of strings as JavaScript, but only after inputs have been passed through a transformation function before it is injected, which has the chance to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input to remove potentially dangerous markup. | ||
|
|
||
| The `trusted-types-eval` must be used instead of [`'unsafe-eval'`](#unsafe-eval) when using these methods with trusted types. | ||
| This ensures that access to the methods is blocked on browsers that don't support trusted types. | ||
|
|
||
| > [!NOTE] | ||
| > Developers should avoid using `trusted-types-eval` or these methods unless absolutely necessary. | ||
| > Trusted types ensure that the input passes through a transformation function — they don't ensure that the transformation makes the input safe (and this can be very hard to get right). | ||
|
|
||
| See [`eval()` and similar APIs](/en-US/docs/Web/HTTP/Guides/CSP#eval_and_similar_apis) in the CSP guide for more usage information. | ||
|
|
||
| ### 'unsafe-eval' | ||
|
|
||
| By default, if a CSP contains a `default-src` or a `script-src` directive, then JavaScript functions which evaluate their arguments as JavaScript are disabled. | ||
| This includes [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval), the [`code`](/en-US/docs/Web/API/Window/setTimeout#code) argument to {{domxref("Window.setTimeout()", "setTimeout()")}}, or the {{jsxref("Function/Function()", "Function()")}} constructor. | ||
|
|
||
| The `unsafe-eval` keyword can be used to undo this protection, allowing dynamic evaluation of strings as JavaScript. | ||
|
|
||
| > [!WARNING] | ||
| > Developers should avoid `'unsafe-eval'`, because it defeats much of the purpose of having a CSP. | ||
| > ['trusted-types-eval'](#trusted-types-eval) provides a "potentially" safer alternative if using these methods is necessary. | ||
|
|
||
| See [`eval()` and similar APIs](/en-US/docs/Web/HTTP/Guides/CSP#eval_and_similar_apis) in the CSP guide for more usage information. | ||
|
|
||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.