Dokument: Statische Methode parseHTMLUnsafe()

Syntax

Document.parseHTMLUnsafe(input)
Document.parseHTMLUnsafe(input, options)

Parameter

input

Eine TrustedHTML-Instanz oder eine Zeichenfolge, die das zu parsende HTML enthält.

options Optional

Ein Optionsobjekt mit den folgenden optionalen Parametern:

sanitizer Optional

Ein Sanitizer- oder SanitizerConfig-Objekt, das festlegt, welche Elemente der Eingabe zugelassen oder entfernt werden. Dies kann auch die Zeichenfolge "default" sein. Damit wird ein Sanitizer mit der (XSS-sicheren) Standardkonfiguration für den Sanitizer angewendet. Wird dieser Parameter nicht angegeben, wird kein Sanitizer verwendet.

Wenn Sie dieselbe Konfiguration mehrfach verwenden, ist es voraussichtlich effizienter, einen Sanitizer zu verwenden und ihn bei Bedarf anzupassen.

Rückgabewert

Ein Document.

Ausnahmen

TypeError

Wird ausgelöst, wenn:

• für html eine Zeichenfolge übergeben wird, während Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.
• für options.sanitizer Folgendes übergeben wird:
  • eine SanitizerConfig, die nicht gültig ist. Beispielsweise eine Konfiguration, die sowohl Einstellungen für zugelassene als auch für entfernte Elemente enthält.
  • eine Zeichenfolge mit einem anderen Wert als "default".
  • ein Wert, der weder ein Sanitizer- noch ein SanitizerConfig-Objekt oder eine Zeichenfolge ist.

Beschreibung

Mit der statischen Methode parseHTMLUnsafe() können Sie eine neue Document-Instanz erstellen und dabei optional unerwünschte Elemente und Attribute herausfiltern. Das resultierende Document hat den Inhaltstyp „text/html“, den Zeichensatz UTF-8 und die URL „about:blank“.

Das eingegebene HTML kann deklarative Shadow Roots enthalten. Definiert die HTML-Zeichenfolge mehr als einen deklarativen Shadow Root für einen bestimmten Shadow Host, wird nur der erste ShadowRoot erstellt. Weitere Deklarationen werden als <template>-Elemente innerhalb dieses Shadow Roots geparst.

parseHTMLUnsafe() führt standardmäßig keine Bereinigung durch. Wird kein Sanitizer als Parameter übergeben, werden alle HTML-Entitäten aus der Eingabe eingefügt.

Sicherheitsaspekte

Das Suffix „Unsafe“ im Methodennamen weist darauf hin, dass die Methode – anders als Document.parseHTML() – nicht sicherstellt, dass alle XSS-unsicheren HTML-Entitäten entfernt werden. Mit einem geeigneten Sanitizer ist dies zwar möglich, die Methode muss aber keinen wirksamen Sanitizer verwenden – und auch überhaupt keinen! Sie ist daher ein möglicher Angriffsvektor für Cross-Site-Scripting (XSS), wenn potenziell unsichere, von Benutzern bereitgestellte Zeichenfolgen ohne vorherige Bereinigung in das DOM eingefügt werden.

Sie sollten dieses Risiko verringern, indem Sie stets TrustedHTML-Objekte statt Zeichenfolgen übergeben und Trusted Types mithilfe der CSP-Direktive require-trusted-types-for erzwingen. Dadurch wird sichergestellt, dass die Eingabe eine Transformationsfunktion durchläuft, die sie vor dem Einfügen bereinigen und potenziell gefährliches Markup wie <script>-Elemente und Event-Handler-Attribute entfernen kann.

Durch die Verwendung von TrustedHTML können Sie den Bereinigungscode an wenigen Stellen prüfen und seine Wirksamkeit kontrollieren, statt dies für alle Injection Sinks einzeln tun zu müssen. Wenn Sie TrustedHTML verwenden, sollten Sie der Methode keinen Sanitizer übergeben müssen.

Falls Sie TrustedHTML aus irgendeinem Grund nicht verwenden können (oder, noch besser, setHTML()), ist die nächstsicherste Option setHTMLUnsafe() mit der XSS-sicheren Standardkonfiguration für den Sanitizer.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Document.parseHTML()
• Element.setHTML() und Element.setHTMLUnsafe()
• ShadowRoot.setHTML() und ShadowRoot.setHTMLUnsafe()
• DOMParser.parseFromString() zum Parsen von HTML oder XML in einen DOM-Baum
• HTML Sanitizer API