From 1a49bf03a81418ae14430e11d95e258defb64764 Mon Sep 17 00:00:00 2001 From: Rachel Andrew Date: Fri, 5 Mar 2021 15:54:10 +0000 Subject: [PATCH 1/5] Trusted Types API Overview --- .../web/api/trusted_types_api/index.html | 105 ++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 files/en-us/web/api/trusted_types_api/index.html diff --git a/files/en-us/web/api/trusted_types_api/index.html b/files/en-us/web/api/trusted_types_api/index.html new file mode 100644 index 000000000000000..722ab06c7900009 --- /dev/null +++ b/files/en-us/web/api/trusted_types_api/index.html @@ -0,0 +1,105 @@ +--- +title: Trusted Types API +slug: Web/API/Trusted_Types_API +tags: + - API + - Overview + - Reference + - Trusted Types +--- +
{{DefaultAPISidebar("Trusted Types API")}}
+ +

The Trusted Types API gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.

+ +

Concepts and Usage

+ +

Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as injection sinks. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.

+ +

The Trusted Types API locks down the risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a TypeError and prevent the use of the function.

+ +

Trusted Types works alongside Content-Security Policy with the trusted-types and require-trusted-types-for directives.

+ +

Injection Sinks

+ +

The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or santized input. Examples of injection sinks include:

+ + + +

Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.

+ +

Trusted Type Policies

+ +

A policy is a factory for Trusted Types. Web developers can specify a set of policies used for the creation of typed objects which form the trusted codebase for valid Trusted Type objects.

+ +

Interfaces

+ +
+
{{domxref("TrustedHTML")}}
+
Represents a string to insert into an injection sink that will render it as HTML.
+
{{domxref("TrustedScript")}}
+
Represents a string to insert into an injection sink that could lead to the script being executed.
+
{{domxref("TrustedScriptURL")}}
+
Represents a string to insert into an injection sink that will parse it as an URL of an external script resource.
+
{{domxref("TrustedTypePolicy")}}
+
Defines the functions used to create the above Trusted Type objects.
+
{{domxref("TrustedTypePolicyFactory")}}
+
Creates policies and verifies that Trusted Type object instances were created via one of the policies.
+
{{domxref("TrustedTypePolicyOptions")}}
+
A dictionary that holds author-defined functions for converting string values into trusted values.
+
+ +

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.

+ +

The sanitized value can then be used with {{domxref("Element.innerHTML")}} to ensure that no new HTML elements can be injected.

+ +
<div id="myDiv"></div>
+ +
const escapeHTMLPolicy = trustedTypes.createPolicy("myEscapePolicy", {
+  createHTML: (string) => string.replace(/\>/g, "<")
+});
+
+let el = document.getElementById("myDiv");
+const escaped = escapeHTMLPolicy.createHTML("<img src=x onerror=alert(1)>");
+console.log(escaped instanceof TrustedHTML); // true
+el.innerHTML = escaped;
+
+ +

Read more details about this example, and discover other ways to sanitize input in the article Prevent DOM-based cross-site scripting vulnerabilities with Trusted Types.

+ +

Specifications

+ + + + + + + + + + + + + + +
SpecificationStatusComment
{{SpecName('Trusted Types')}}{{Spec2('Trusted Types')}}Initial definition.
+ +

Browser compatibility

+ +

See the compatibility data for each of the Trusted Types API interfaces.

+ +

Polyfill

+ +

A polyfill is available. The polyfill is also available as an npm package trusted-types.

+ +

See also

+ + From fc72d043a984840536d93bf0f3805b6c17316480 Mon Sep 17 00:00:00 2001 From: Rachel Andrew Date: Sat, 6 Mar 2021 07:58:51 +0000 Subject: [PATCH 2/5] Update files/en-us/web/api/trusted_types_api/index.html Co-authored-by: Joe Medley --- files/en-us/web/api/trusted_types_api/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/trusted_types_api/index.html b/files/en-us/web/api/trusted_types_api/index.html index 722ab06c7900009..4a2caf69dce726d 100644 --- a/files/en-us/web/api/trusted_types_api/index.html +++ b/files/en-us/web/api/trusted_types_api/index.html @@ -15,7 +15,7 @@

Concepts and Usage

Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as injection sinks. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.

-

The Trusted Types API locks down the risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a TypeError and prevent the use of the function.

+

The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.

Trusted Types works alongside Content-Security Policy with the trusted-types and require-trusted-types-for directives.

From cb5e36b58c2bada91b9ebb0ca0d230315addc319 Mon Sep 17 00:00:00 2001 From: Rachel Andrew Date: Sat, 6 Mar 2021 07:58:59 +0000 Subject: [PATCH 3/5] Update files/en-us/web/api/trusted_types_api/index.html Co-authored-by: Joe Medley --- files/en-us/web/api/trusted_types_api/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/trusted_types_api/index.html b/files/en-us/web/api/trusted_types_api/index.html index 4a2caf69dce726d..bbd2ffc956c9770 100644 --- a/files/en-us/web/api/trusted_types_api/index.html +++ b/files/en-us/web/api/trusted_types_api/index.html @@ -25,7 +25,7 @@

Injection Sinks

  • Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write")}}.
    • -
  • Functions that create a new same-origin {{domxref("Document")}} with caller controlled markup such as {{domxref("DOMParser.parseFromString")}}.
    • +
  • Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString")}}.
  • Functions that execute code such as {{jsxref("Global_Objects/eval")}}.
  • Setters for {{domxref("Element")}} attributes that accept a URL of the code to load or code to execute.
From 07a318dc1daf097b3e1a48dedcbe551653132a26 Mon Sep 17 00:00:00 2001 From: Rachel Andrew Date: Sat, 6 Mar 2021 07:59:13 +0000 Subject: [PATCH 4/5] Update files/en-us/web/api/trusted_types_api/index.html Co-authored-by: Joe Medley --- files/en-us/web/api/trusted_types_api/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/trusted_types_api/index.html b/files/en-us/web/api/trusted_types_api/index.html index bbd2ffc956c9770..30fbe8585ff3031 100644 --- a/files/en-us/web/api/trusted_types_api/index.html +++ b/files/en-us/web/api/trusted_types_api/index.html @@ -27,7 +27,7 @@

Injection Sinks

  • Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write")}}.
  • Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString")}}.
  • Functions that execute code such as {{jsxref("Global_Objects/eval")}}.
    • -
  • Setters for {{domxref("Element")}} attributes that accept a URL of the code to load or code to execute.
    • +
  • Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.

    • Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.

    From 86b5b0561a870e107667fb880db735d0becfc883 Mon Sep 17 00:00:00 2001 From: Rachel Andrew Date: Sat, 6 Mar 2021 08:02:43 +0000 Subject: [PATCH 5/5] Update files/en-us/web/api/trusted_types_api/index.html Co-authored-by: Joe Medley --- files/en-us/web/api/trusted_types_api/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/trusted_types_api/index.html b/files/en-us/web/api/trusted_types_api/index.html index 30fbe8585ff3031..cfdb9f6c184fb52 100644 --- a/files/en-us/web/api/trusted_types_api/index.html +++ b/files/en-us/web/api/trusted_types_api/index.html @@ -71,7 +71,7 @@

    Examples

    el.innerHTML = escaped; -

    Read more details about this example, and discover other ways to sanitize input in the article Prevent DOM-based cross-site scripting vulnerabilities with Trusted Types.

    +

    Read more about this example, and discover other ways to sanitize input in the article Prevent DOM-based cross-site scripting vulnerabilities with Trusted Types.

    Specifications