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 ausführt. 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 könnten JavaScript ausführen, 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 enthält, die Eingaben transformieren, die an einen Injection Sink übergeben werden, um sie sicher zu machen. Die Richtlinie kann unterschiedliche Methoden für die verschiedenen Arten von Sinks definieren:

• Für HTML Sinks bereinigt die Transformationsfunktion typischerweise die Eingaben, zum Beispiel durch die Verwendung einer Bibliothek wie DOMPurify.
• Für JavaScript- und JavaScript-URL-Sinks kann die Richtlinie die Sinks vollständig 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 heißt, die API ermöglicht 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 ermöglicht 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, verfügbar 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 repräsentieren Daten, die durch die Richtlinie gegangen sind und können 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 ausführen 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 können 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 Nächstes können 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 vertrauenswürdiger Typen

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

Um sicherzustellen, dass immer ein vertrauenswürdiger Typ übergeben werden muss, schließen Sie die require-trusted-types-for Direktive in Ihre CSP ein. Mit dieser Direktive werden bei Übergabe von Strings in Sinks TypeError Ausnahmen ausgelöst:

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

element.innerHTML = userInput; // Throws a TypeError

Zusätzlich 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 für die Richtlinie an. Die trusted-types CSP-Direktive listet zulässige Richtliniennamen auf, sodass createPolicy() eine Ausnahme auslöst, wenn es einen Namen erhält, 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 können 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 können, um anstelle dessen vertrauenswürdige Typen zu erstellen und zu übergeben.

Wenn Sie eine Richtlinie namens "default" erstellen und Ihre CSP die Verwendung vertrauenswürdiger 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 zurückgibt, wird der Browser einen TypeError auslösen, 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 vertrauenswürdige Typen prüfen, wenn sie ausgewertet werden. Sie können vertrauenswürdige Typen (TrustedHTML, TrustedScript oder TrustedScriptURL) sowie Strings übergeben und müssen vertrauenswürdige Typen übergeben, wenn die Durchsetzung vertrauenswürdiger 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 unzuverlässige Strings über einen Zwischenmechanismus, der keine vertrauenswürdigen Typen akzeptiert oder erzwingt, in das DOM injiziert werden. Diese unterscheiden sich von den "direkten" Injection Sink Interfaces, die im vorherigen Abschnitt aufgeführt sind und bei ihrem Aufruf vertrauenswürdige Typprüfungen durchführen.

Zum Beispiel erstellt der folgende Code indirekt eine Script-Element-Quelle. Zuerst wird ein Textknoten mit einem vom Benutzer bereitgestellten String erstellt und anschließend ein <script> Element konstruiert und der Textknoten als Kindelement angehängt. Danach wird das Script-Element dem Dokument als Kind des <body> Elements hinzugefügt — an diesem Punkt können die im ursprünglichen String definierten Skripte ausgeführt 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 für den Browser anzunehmen, er solle als vertrauenswürdige Typquelle verwendet werden, daher werden vertrauenswürdige Typen in Zeichenfolgen serialisiert und sind nicht erzwungen.

Stattdessen führen Browser die Prüfungen durch, wenn das Script-Element ausführbar wird — d.h. in diesem Beispiel, wenn document.body.appendChild(script) aufgerufen wird, um das Script-Element zum Dokument hinzuzufügen.

Der Browser prüft zuerst, ob der String, der als Skriptinhalt verwendet wird, vertrauenswürdig ist. Jede Operation, die es ermöglicht, die Textquelle eines <script> zu ändern, ohne explizit ein TrustedScript festzulegen, macht sie unzuverlässig. 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 aufgeführt).

Wenn der String nicht vertrauenswürdig ist und vertrauenswürdige 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 zurückgibt wird, wird die Operation eine Ausnahme auslösen.

Trusted Types Tinyfill

Der Trusted Types Tinyfill unterstützt Sie bei der Arbeit mit Browsern, die die Trusted Types API selbst nicht unterstützen.

Das Tinyfill ist einfach folgendes:

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

Das heißt, es bietet eine Implementierung von trustedTypes.createPolicy(), die einfach das policyOptions Objekt zurückgibt, das übergeben wurde. Das policyOptions Objekt definiert Datenbereinigungsfunktionen, und diese Funktionen sollen Strings zurückgeben.

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 vertrauenswürdige Typen unterstützen, wird dies eine TrustedTypePolicy zurückgeben, die ein TrustedHTML Objekt erstellen wird, wenn wir policy.createHTML() aufrufen. Das TrustedHTML Objekt kann dann an einen Injection Sink übergeben werden und wir können erzwingen, dass der Sink einen vertrauenswürdigen Typ und keinen String erhält.

In Browsern, die vertrauenswürdige Typen nicht unterstützen, gibt dieser Code ein Objekt mit einer createHTML() Funktion zurück, die ihre Eingaben bereinigt und als String zurückgibt. 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 erhält der Injection Sink bereinigte Daten, und da wir die Verwendung der Richtlinie im unterstützenden Browser erzwingen konnten, wissen wir, dass dieser Codepfad auch im nicht unterstützenden Browser durch die Bereinigungsfunktion geht.

Das bedeutet, dass solange Sie Ihren Code in einem unterstützenden 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 unterstützen.

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 ausführen, läuft er dennoch durch die gleichen Codepfade und bietet denselben Schutz.

Schnittstellen

TrustedHTML

Repräsentiert einen String, der in einen Injection Sink eingefügt werden soll, der ihn als HTML rendern wird.

TrustedScript

Repräsentiert einen String, der in einen Injection Sink eingefügt werden soll, der zur Ausführung des Skripts führen könnte.

TrustedScriptURL

Repräsentiert einen String, der in einen Injection Sink eingefügt 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 überprüft, ob Trusted Type Objektinstanzen über eine der Richtlinien erstellt wurden.

Erweiterungen anderer Schnittstellen

Window.trustedTypes

Gibt das TrustedTypePolicyFactory Objekt zurück, das mit dem globalen Objekt im Hauptthread assoziiert ist. Dies ist der Einstiegspunkt für die Nutzung der API im Window-Thread.

WorkerGlobalScope.trustedTypes.

Gibt das TrustedTypePolicyFactory Objekt zurück, 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 Schlüsselwörter

trusted-types-eval

Ermöglicht die Verwendung von eval() und ähnlichen Funktionen, jedoch nur, wenn Trusted Types unterstützt und erzwungen werden.

Beispiele

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

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

<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 Möglichkeiten zur Bereinigung von Eingaben in dem Artikel Vermeiden Sie DOM-basierte Cross-Site-Scripting-Schwachstellen mit Trusted Types.

Spezifikationen

Browser-Kompatibilität

Siehe auch

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