Trusted Types API

Konzepte und Verwendung

Clientseitige oder DOM-basierte XSS-Angriffe treten auf, wenn von einem Angreifer erstellte Daten an eine Browser-API bergeben werden, die diese Daten als Code ausfhrt. Diese APIs sind bekannt als Injection Sinks.

Die Trusted Types API unterscheidet drei Arten von Injection Sinks:

• HTML Sinks: APIs, die ihre Eingaben als HTML interpretieren, wie Element.innerHTML oder document.write(). Diese APIs knnten JavaScript ausfhren, wenn es im HTML eingebettet ist, zum Beispiel in <script>-Tags oder Attributen von Ereignis-Handlern.
• JavaScript Sinks: APIs, die ihre Eingaben als JavaScript interpretieren, wie zum Beispiel eval() oder HTMLScriptElement.text.
• JavaScript URL Sinks: APIs, die ihre Eingaben als die URL eines Skripts interpretieren, wie zum Beispiel HTMLScriptElement.src.

Eine der Hauptverteidigungen gegen DOM-basierte XSS-Angriffe besteht darin sicherzustellen, dass Eingaben sicher gemacht werden, bevor sie an einen Injection Sink bergeben werden.

In der Trusted Types API definiert ein Entwickler ein Policy Object, das Methoden enthlt, die Eingaben transformieren, die an einen Injection Sink bergeben werden, um sie sicher zu machen. Die Richtlinie kann unterschiedliche Methoden fr die verschiedenen Arten von Sinks definieren:

• Fr HTML Sinks bereinigt die Transformationsfunktion typischerweise die Eingaben, zum Beispiel durch die Verwendung einer Bibliothek wie DOMPurify.
• Fr JavaScript- und JavaScript-URL-Sinks kann die Richtlinie die Sinks vollstndig deaktivieren oder bestimmte vordefinierte Eingaben zulassen (zum Beispiel bestimmte URLs).

Die Trusted Types API stellt dann sicher, dass Eingaben durch die entsprechende Transformationsfunktion geleitet werden, bevor sie in den Sink bergeben werden.

Das heit, die API ermglicht es Ihnen, Ihre Richtlinie an einer Stelle zu definieren, und dann sicher zu sein, dass alle Daten, die an einen Injection Sink bergeben werden, durch die Richtlinie gegangen sind.

Die API hat zwei Hauptkomponenten:

• Eine JavaScript-API ermglicht es einem Entwickler, Daten zu bereinigen, bevor sie an einen Injection Sink bergeben werden.
• Zwei CSP-Direktiven erzwingen und kontrollieren die Nutzung der JavaScript-API.

Die Trusted Types JavaScript API

In der Trusted Types API:

• Die globale Eigenschaft trustedTypes, verfgbar sowohl im Window als auch im Worker Kontext, wird zur Erstellung von TrustedTypePolicy Objekten verwendet.
• Ein TrustedTypePolicy Objekt wird verwendet, um Trusted Type Objekte zu erstellen: Es tut dies, indem es die Daten durch eine Transformationsfunktion leitet.
• Trusted Type Objekte reprsentieren Daten, die durch die Richtlinie gegangen sind und knnen daher sicher an einen Injection Sink bergeben werden. Es gibt drei Arten von Trusted Types, die den verschiedenen Arten von Injection Sinks entsprechen:
  • TrustedHTML ist zur bergabe an einen Sink, der die Daten als HTML rendern wird.
  • TrustedScript ist zur bergabe an einen Sink, der die Daten als JavaScript ausfhren wird.
  • TrustedScriptURL ist zur bergabe an einen Sink, der die Daten als URL zu einem Skript analysieren wird.

Mit dieser API anstatt einen String an einen Injection Sink wie innerHTML zu bergeben, verwenden Sie eine TrustedTypePolicy, um ein TrustedHTML Objekt aus dem String zu erstellen, bergeben dann dieses an den Sink, und knnen sicher sein, dass der String durch eine Transformationsfunktion gegangen ist.

Zum Beispiel erzeugt dieser Code eine TrustedTypePolicy, die TrustedHTML Objekte durch Bereinigung der Eingabe-Strings mit der DOMPurify Bibliothek erstellen kann:

const policy = trustedTypes.createPolicy("my-policy", {
  createHTML: (input) => DOMPurify.sanitize(input),
});

Als Nchstes knnen Sie dieses policy Objekt verwenden, um ein TrustedHTML Objekt zu erstellen und dieses in den Injection Sink zu bergeben:

const userInput = "<p>I might be XSS</p>";
const element = document.querySelector("#container");

const trustedHTML = policy.createHTML(userInput);
element.innerHTML = trustedHTML;

Verwendung einer CSP zur Erzwingung vertrauenswrdiger Typen

Die oben beschriebene API ermglicht es Ihnen, Daten zu bereinigen, aber sie stellt nicht sicher, dass Ihr Code niemals Eingaben direkt an einen Injection Sink bergibt: Das heit, sie hindert Sie nicht daran, einen String in innerHTML zu bergeben.

Um sicherzustellen, dass immer ein vertrauenswrdiger Typ bergeben werden muss, schlieen Sie die require-trusted-types-for Direktive in Ihre CSP ein. Mit dieser Direktive werden bei bergabe von Strings in Sinks TypeError Ausnahmen ausgelst:

const userInput = "<p>I might be XSS</p>";
const element = document.querySelector("#container");

element.innerHTML = userInput; // Throws a TypeError

Zustzlich kann die trusted-types CSP-Direktive verwendet werden, um zu kontrollieren, welche Richtlinien Ihr Code erstellen darf. Wenn Sie eine Richtlinie mit trustedTypes.createPolicy() erstellen, geben Sie einen Namen fr die Richtlinie an. Die trusted-types CSP-Direktive listet zulssige Richtliniennamen auf, sodass createPolicy() eine Ausnahme auslst, wenn es einen Namen erhlt, der nicht in trusted-types aufgelistet wurde. Dies verhindert, dass ein Code in Ihrer Webanwendung eine Richtlinie erstellt, die Sie nicht erwartet haben.

Die Standardrichtlinie

In der Trusted Types API knnen Sie eine Standardrichtlinie definieren. Dies hilft Ihnen, alle Stellen in Ihrem Code zu finden, an denen Sie noch Strings in Injection Sinks bergeben, sodass Sie den Code umschreiben knnen, um anstelle dessen vertrauenswrdige Typen zu erstellen und zu bergeben.

Wenn Sie eine Richtlinie namens "default" erstellen und Ihre CSP die Verwendung vertrauenswrdiger Typen erzwingt, wird jeder String-Argument, der in Injection Sinks bergeben wird, automatisch an diese Richtlinie weitergeleitet. Zum Beispiel, nehmen wir an, wir erstellen eine Richtlinie wie diese:

trustedTypes.createPolicy("default", {
  createHTML(value) {
    console.log("Please refactor this code");
    return sanitize(value);
  },
});

Mit dieser Richtlinie wird, wenn Ihr Code einen String einem innerHTML zuweist, der Browser die createHTML() Methode der Richtlinie aufrufen und ihr Ergebnis dem Sink zuweisen:

const userInput = "<p>I might be XSS</p>";
const element = document.querySelector("#container");

element.innerHTML = userInput;
// Logs "Please refactor this code"
// Assigns the result of sanitize(userInput)

Wenn die Standardrichtlinie null oder undefined zurckgibt, wird der Browser einen TypeError auslsen, wenn das Ergebnis dem Sink zugewiesen wird:

trustedTypes.createPolicy("default", {
  createHTML(value) {
    console.log("Please refactor this code");
    return null;
  },
});

const userInput = "<p>I might be XSS</p>";
const element = document.querySelector("#container");

element.innerHTML = userInput;
// Logs "Please refactor this code"
// Throws a TypeError

Injection Sink Interfaces

Dieser Abschnitt bietet eine Liste von "direkten" Injection Sink Interfaces.

Dies sind die API-Eigenschaften und -Methoden, die vertrauenswrdige Typen prfen, wenn sie ausgewertet werden. Sie knnen vertrauenswrdige Typen (TrustedHTML, TrustedScript oder TrustedScriptURL) sowie Strings bergeben und mssen vertrauenswrdige Typen bergeben, wenn die Durchsetzung vertrauenswrdiger Typen aktiviert ist und keine Standardrichtlinie definiert ist.

TrustedHTML

• Document.execCommand() mit einem commandName von "insertHTML"
• Document.parseHTMLUnsafe()
• Document.write()
• Document.writeln()
• DOMParser.parseFromString()
• Element.innerHTML
• Element.insertAdjacentHTML
• Element.outerHTML
• Element.setHTMLUnsafe()
• HTMLIFrameElement.srcdoc
• Range.createContextualFragment()
• ShadowRoot.innerHTML
• ShadowRoot.setHTMLUnsafe()

TrustedScript

• AsyncFunction() Konstruktor
• AsyncGeneratorFunction() Konstruktor
• eval()
• Element.setAttribute() (value Argument)
• Element.setAttributeNS() (value Argument)
• Function() Konstruktor
• GeneratorFunction() Konstruktor
• HTMLScriptElement.innerText
• HTMLScriptElement.textContent
• HTMLScriptElement.text
• window.setTimeout() und WorkerGlobalScope.setTimeout() (code Argument)
• window.setInterval() und WorkerGlobalScope.setInterval() (code Argument)

TrustedScriptURL

• HTMLScriptElement.src
• ServiceWorkerContainer.register()
• SvgAnimatedString.baseVal
• WorkerGlobalScope.importScripts()
• url Argument an Worker() Konstruktor
• url Argument an SharedWorker() Konstruktor

Indirekte Injection Sinks

Indirekte Injection Sinks sind Sinks, bei denen unzuverlssige Strings ber einen Zwischenmechanismus, der keine vertrauenswrdigen Typen akzeptiert oder erzwingt, in das DOM injiziert werden. Diese unterscheiden sich von den "direkten" Injection Sink Interfaces, die im vorherigen Abschnitt aufgefhrt sind und bei ihrem Aufruf vertrauenswrdige Typprfungen durchfhren.

Zum Beispiel erstellt der folgende Code indirekt eine Script-Element-Quelle. Zuerst wird ein Textknoten mit einem vom Benutzer bereitgestellten String erstellt und anschlieend ein <script> Element konstruiert und der Textknoten als Kindelement angehngt. Danach wird das Script-Element dem Dokument als Kind des <body> Elements hinzugefgt an diesem Punkt knnen die im ursprnglichen String definierten Skripte ausgefhrt werden.

// Create a text node
const untrustedString =
  "console.log('A potentially malicious script from an untrusted source!');";
const textNode = document.createTextNode(untrustedString);

// Create a script element and append the text node
const script = document.createElement("script");
script.appendChild(textNode);

// Add the script into the document, where it can run
document.body.appendChild(script);

Wenn der Textknoten erstellt wird, gibt es keinen Grund fr den Browser anzunehmen, er solle als vertrauenswrdige Typquelle verwendet werden, daher werden vertrauenswrdige Typen in Zeichenfolgen serialisiert und sind nicht erzwungen.

Stattdessen fhren Browser die Prfungen durch, wenn das Script-Element ausfhrbar wird d.h. in diesem Beispiel, wenn document.body.appendChild(script) aufgerufen wird, um das Script-Element zum Dokument hinzuzufgen.

Der Browser prft zuerst, ob der String, der als Skriptinhalt verwendet wird, vertrauenswrdig ist. Jede Operation, die es ermglicht, die Textquelle eines <script> zu ndern, ohne explizit ein TrustedScript festzulegen, macht sie unzuverlssig. Die oben verwendete Methode Node.appendChild() ist nur ein Beispiel (weitere sind in den WPT Live Tests unter https://wpt.live/trusted-types/script-enforcement-001.html aufgefhrt).

Wenn der String nicht vertrauenswrdig ist und vertrauenswrdige Typen erzwungen werden, wird der Browser versuchen, ein TrustedScript aus einer Standardrichtlinie zu erhalten, um es stattdessen als Quelle zu verwenden. Wenn eine Standardrichtlinie nicht definiert ist oder kein TrustedScript zurckgibt wird, wird die Operation eine Ausnahme auslsen.

Trusted Types Tinyfill

Der Trusted Types Tinyfill untersttzt Sie bei der Arbeit mit Browsern, die die Trusted Types API selbst nicht untersttzen.

Das Tinyfill ist einfach folgendes:

if (typeof trustedTypes === "undefined")
  trustedTypes = { createPolicy: (n, rules) => rules };

Das heit, es bietet eine Implementierung von trustedTypes.createPolicy(), die einfach das policyOptions Objekt zurckgibt, das bergeben wurde. Das policyOptions Objekt definiert Datenbereinigungsfunktionen, und diese Funktionen sollen Strings zurckgeben.

Mit diesem Tinyfill an Ort und Stelle, stellen wir uns vor, wir erstellen eine Richtlinie:

const policy = trustedTypes.createPolicy("my-policy", {
  createHTML: (input) => DOMPurify.sanitize(input),
});

In Browsern, die vertrauenswrdige Typen untersttzen, wird dies eine TrustedTypePolicy zurckgeben, die ein TrustedHTML Objekt erstellen wird, wenn wir policy.createHTML() aufrufen. Das TrustedHTML Objekt kann dann an einen Injection Sink bergeben werden und wir knnen erzwingen, dass der Sink einen vertrauenswrdigen Typ und keinen String erhlt.

In Browsern, die vertrauenswrdige Typen nicht untersttzen, gibt dieser Code ein Objekt mit einer createHTML() Funktion zurck, die ihre Eingaben bereinigt und als String zurckgibt. Der bereinigte String kann dann an einen Injection Sink bergeben werden.

const userInput = "I might be XSS";
const element = document.querySelector("#container");

const trustedHTML = policy.createHTML(userInput);
// In supporting browsers, trustedHTML is a TrustedHTML object.
// In non-supporting browsers, trustedHTML is a string.

element.innerHTML = trustedHTML;
// In supporting browsers, this will throw if trustedHTML
// is not a TrustedHTML object.

So oder so erhlt der Injection Sink bereinigte Daten, und da wir die Verwendung der Richtlinie im untersttzenden Browser erzwingen konnten, wissen wir, dass dieser Codepfad auch im nicht untersttzenden Browser durch die Bereinigungsfunktion geht.

Das bedeutet, dass solange Sie Ihren Code in einem untersttzenden Browser mit der require-trusted-types-for CSP-Direktive getestet haben, das Tinyfill ausreicht, um den gleichen Schutz zu bieten, selbst in Browsern, die die Trusted Types API nicht untersttzen.

Dies liegt daran, dass die Durchsetzung Sie dazu zwingt, Ihren Code so umzugestalten, dass alle Daten durch die Trusted Types API (und daher durch eine Bereinigungsfunktion) gehen, bevor sie an einen Injection Sink bergeben werden. Wenn Sie den umgestalteten Code dann in einem anderen Browser ohne Durchsetzung ausfhren, luft er dennoch durch die gleichen Codepfade und bietet denselben Schutz.

Schnittstellen

TrustedHTML

Reprsentiert einen String, der in einen Injection Sink eingefgt werden soll, der ihn als HTML rendern wird.

TrustedScript

Reprsentiert einen String, der in einen Injection Sink eingefgt werden soll, der zur Ausfhrung des Skripts fhren knnte.

TrustedScriptURL

Reprsentiert einen String, der in einen Injection Sink eingefgt werden soll, der ihn als URL einer externen Skriptressource analysieren wird.

TrustedTypePolicy

Definiert die Funktionen, die zur Erstellung der oben genannten Trusted Type Objekte verwendet werden.

TrustedTypePolicyFactory

Erstellt Richtlinien und berprft, ob Trusted Type Objektinstanzen ber eine der Richtlinien erstellt wurden.

Erweiterungen anderer Schnittstellen

Window.trustedTypes

Gibt das TrustedTypePolicyFactory Objekt zurck, das mit dem globalen Objekt im Hauptthread assoziiert ist. Dies ist der Einstiegspunkt fr die Nutzung der API im Window-Thread.

WorkerGlobalScope.trustedTypes.

Gibt das TrustedTypePolicyFactory Objekt zurck, das mit dem globalen Objekt in einem Worker assoziiert ist.

Erweiterungen zu HTTP

Content-Security-Policy Direktiven

require-trusted-types-for

Erzwingt, dass Trusted Types an DOM-XSS Injection Sinks bergeben werden.

trusted-types

Wird verwendet, um eine Whitelist von Trusted Types Richtliniennamen anzugeben.

Content-Security-Policy Schlsselwrter

trusted-types-eval

Ermglicht die Verwendung von eval() und hnlichen Funktionen, jedoch nur, wenn Trusted Types untersttzt und erzwungen werden.

Beispiele

Im folgenden Beispiel erstellen wir eine Richtlinie, die TrustedHTML Objekte mit TrustedTypePolicyFactory.createPolicy() erstellen wird. Wir knnen dann TrustedTypePolicy.createHTML() verwenden, um einen bereinigten HTML-String zu erstellen, der in das Dokument eingefgt werden soll.

Der bereinigte Wert kann dann mit Element.innerHTML verwendet werden, um sicherzustellen, dass keine neuen HTML-Elemente injiziert werden knnen.

<div id="myDiv"></div>

const escapeHTMLPolicy = trustedTypes.createPolicy("myEscapePolicy", {
  createHTML: (string) =>
    string
      .replace(/&/g, "&")
      .replace(/</g, "&lt;")
      .replace(/"/g, "&quot;")
      .replace(/'/g, "&apos;"),
});

let el = document.getElementById("myDiv");
const escaped = escapeHTMLPolicy.createHTML("<img src=x onerror=alert(1)>");
console.log(escaped instanceof TrustedHTML); // true
el.innerHTML = escaped;

Lesen Sie mehr ber dieses Beispiel und entdecken Sie andere Mglichkeiten zur Bereinigung von Eingaben in dem Artikel Vermeiden Sie DOM-basierte Cross-Site-Scripting-Schwachstellen mit Trusted Types.

Spezifikationen

Browser-Kompatibilitt

Siehe auch

• Vermeiden Sie DOM-basierte Cross-Site-Scripting-Schwachstellen mit Trusted Types