diff --git a/files/en-us/mozilla/firefox/experimental_features/index.md b/files/en-us/mozilla/firefox/experimental_features/index.md index 874df29ace2307a..171b65536c3e8f1 100644 --- a/files/en-us/mozilla/firefox/experimental_features/index.md +++ b/files/en-us/mozilla/firefox/experimental_features/index.md @@ -408,26 +408,20 @@ The {{domxref("CloseWatcher")}} interface allows developers to implement UI comp ### Trusted Types API The [Trusted Types API](/en-US/docs/Web/API/Trusted_Types_API) provides mechanisms to ensure that functions that can potentially be used as vectors for XSS attacks are only able to be called with data that has been validated or sanitized. +The API is enabled in early beta releases ([Firefox bug 1992941](https://bugzil.la/1992941)). -> [!NOTE] -> At the time of writing not enough of the API has been implemented for it to be effectively testable. -> This note will be removed once it is ready. +This includes (non-exhaustively): -This subset of the API has been implemented: - -- {{domxref("TrustedTypePolicyFactory")}}: - - {{domxref("TrustedTypePolicyFactory/getAttributeType", "getAttributeType()")}} and {{domxref("TrustedTypePolicyFactory/getPropertyType", "getPropertyType()")}} ([Firefox bug 1917783](https://bugzil.la/1917783), [Firefox bug 1917784](https://bugzil.la/1917784)). -- The {{domxref("Document.write()", "write()")}} and {{domxref("Document.writeln()","writeln()")}} methods of the {{domxref("Document")}} interface now accept {{domxref("TrustedHTML")}} objects as parameters, in addition to strings. ([Firefox bug 1906301](https://bugzil.la/1906301)). -- The {{domxref("HTMLScriptElement.text","text")}}, {{domxref("HTMLElement.innerText","innerText")}}, and {{domxref("Node.textContent","textContent")}} properties of the {{domxref("HTMLScriptElement")}} interface now accept {{domxref("TrustedScript")}} objects a value, while {{domxref("HTMLScriptElement.src", "src")}} accepts {{domxref("TrustedScriptURL")}} values. ([Firefox bug 1905706](https://bugzil.la/1905706)). -- The {{domxref("Window.setInterval()")}} and {{domxref("Window.setTimeout()")}} methods can be called with a {{domxref("TrustedScript")}}. ([Firefox bug 1931290](https://bugzil.la/1931290)). -- The global [`trustedTypes`](/en-US/docs/Web/API/Window/trustedTypes) property is available for accessing the Trusted Types API. -- The properties {{domxref("Element.innerHTML")}} and {{domxref("ShadowRoot.innerHTML")}} can be called with [trusted types](/en-US/docs/Web/API/Trusted_Types_API). +- Addition of the {{domxref("TrustedTypePolicyFactory")}}, {{domxref("TrustedTypePolicy")}}, {{domxref("TrustedHTML")}}, {{domxref("TrustedScript")}}, {{domxref("TrustedScriptURL")}} interfaces, and the `trustedTypes` property on {{domxref("Window/trustedTypes", "Window")}} and {{domxref("WorkerGlobalScope/trustedTypes", "WorkerGlobalScope")}}. +- Updates to [injection sink interfaces](/en-US/docs/Web/API/Trusted_Types_API#injection_sink_interfaces), 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. | Release channel | Version added | Enabled by default? | | ----------------- | ------------- | ------------------- | -| Nightly | 133 | No | -| Developer Edition | 133 | No | -| Beta | 133 | No | +| Nightly | 145 | Yes | +| Developer Edition | 145 | Yes | +| Beta | 145 | Yes | | Release | 133 | No | - `dom.security.trusted_types.enabled` diff --git a/files/en-us/mozilla/firefox/releases/145/index.md b/files/en-us/mozilla/firefox/releases/145/index.md index a395dcfae112634..970669612365f55 100644 --- a/files/en-us/mozilla/firefox/releases/145/index.md +++ b/files/en-us/mozilla/firefox/releases/145/index.md @@ -121,3 +121,14 @@ 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 enabled in early beta releases. ([Firefox bug 1976656](https://bugzil.la/1976656)). + + The changes include: + +- Addition of the {{domxref("TrustedTypePolicyFactory")}}, {{domxref("TrustedTypePolicy")}}, {{domxref("TrustedHTML")}}, {{domxref("TrustedScript")}}, {{domxref("TrustedScriptURL")}} interfaces, and the `trustedTypes` property on {{domxref("Window/trustedTypes", "Window")}} and {{domxref("WorkerGlobalScope/trustedTypes", "WorkerGlobalScope")}}. + - 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. diff --git a/files/en-us/web/api/trusted_types_api/index.md b/files/en-us/web/api/trusted_types_api/index.md index 3e1d59146291f9b..a019bfeacb60cf0 100644 --- a/files/en-us/web/api/trusted_types_api/index.md +++ b/files/en-us/web/api/trusted_types_api/index.md @@ -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_. +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: @@ -134,6 +134,50 @@ element.innerHTML = userInput; > [!NOTE] > It's recommended that you use the default policy only while you are transitioning from legacy code that passes input directly to injection sinks, to code that uses trusted types explicitly. +### Injection sink interfaces + +This section provides an list of "direct" injection sink interfaces. + +Note that there are cases where untrusted strings may be "indirectly injected", such as when an untrusted string is added as the child node of a script element, and then the element is added to the document. +These cases are evaluated the untrusted script is added to the document. + +#### TrustedHTML + +- {{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) + ### Cross-browser support for trusted types The Trusted Types API is not yet available in all modern browsers, but it is usable everywhere today thanks to [compatibility aids created by the W3C](https://github.com/w3c/trusted-types/tree/main?tab=readme-ov-file#polyfill). @@ -201,6 +245,28 @@ 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. + ## 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. diff --git a/files/en-us/web/http/guides/csp/index.md b/files/en-us/web/http/guides/csp/index.md index 6d242d928845cbf..3cc707774a1aa57 100644 --- a/files/en-us/web/http/guides/csp/index.md +++ b/files/en-us/web/http/guides/csp/index.md @@ -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()`: 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 `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. +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. diff --git a/files/en-us/web/http/reference/headers/content-security-policy/index.md b/files/en-us/web/http/reference/headers/content-security-policy/index.md index 0188146485e73de..9f60d6e334ec677 100644 --- a/files/en-us/web/http/reference/headers/content-security-policy/index.md +++ b/files/en-us/web/http/reference/headers/content-security-policy/index.md @@ -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. + - : 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. +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.