DOMParser: Methode parseFromString()

Syntax

parseFromString(input, mimeType)

Parameter

input

Eine TrustedHTML-Instanz oder ein String, der das zu parsende HTML definiert. Das Markup muss ein HTML-, XML-, XHTML- oder SVG-Dokument enthalten.

mimeType

Ein String, der angibt, ob der XML-Parser oder der HTML-Parser zum Parsen des Strings verwendet wird.

Zulässige Werte sind:

• text/html
• text/xml
• application/xml
• application/xhtml+xml
• image/svg+xml

Rückgabewert

Ein Document, dessen contentType dem angegebenen mimeType entspricht.

Ausnahmen

TypeError

Wird in folgenden Fällen ausgelöst:

• Für mimeType wird ein Wert übergeben, der nicht zu den zulässigen Werten gehört.
• Für input wird ein String übergeben, während Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.

Beschreibung

Die Methode parseFromString() parst eine Eingabe, die entweder HTML oder XML enthält, und gibt ein Document zurück, dessen contentType dem mimeType entspricht. Dieses Document enthält ein vollständiges DOM im Arbeitsspeicher, das vom Hauptdokument der zugehörigen Seite getrennt ist.

Wenn mimeType den Wert text/html hat, wird die Eingabe als HTML geparst. <script>-Elemente werden als nicht ausführbar markiert, Events werden nicht ausgelöst und Event-Handler werden nicht aufgerufen, um Inline-Skripte auszuführen. Das Dokument kann zwar Ressourcen herunterladen, die in <iframe>- und <img>-Elementen angegeben sind, ist aber im Wesentlichen inaktiv. Das ist nützlich, weil Sie HTML-Eingaben mit deklarativen Shadow Roots parsen und Operationen am Dokument ausführen können, ohne die sichtbare Seite zu beeinflussen. Sie können beispielsweise den Eingabebaum bereinigen und bei Bedarf Teile der Eingabe in das sichtbare DOM einfügen.

Bei den anderen zulässigen Werten (text/xml, application/xml, application/xhtml+xml und image/svg+xml) wird die Eingabe als XML geparst. Das ist nützlich, wenn Sie XML-Dateien importieren, ihre Struktur validieren und Daten daraus extrahieren möchten. Wenn die Eingabe kein wohlgeformtes XML darstellt, enthält das zurückgegebene Dokument einen <parsererror>-Knoten, der den Parse-Fehler beschreibt.

Unzulässige mimeType-Werte führen dazu, dass ein TypeError ausgelöst wird.

Sicherheitsaspekte

Diese Methode parst ihre Eingabe in ein separates DOM im Arbeitsspeicher. Dabei deaktiviert sie alle <script>-Elemente und verhindert die Ausführung von Event-Handlern. Obwohl das zurückgegebene Dokument praktisch inaktiv ist, können Event-Handler und Skripte in seinem DOM ausgeführt werden, wenn sie in das sichtbare DOM eingefügt werden. Die Methode kann daher für Cross-Site-Scripting-Angriffe (XSS) ausgenutzt werden: Potenziell unsichere Eingaben werden zunächst ohne Bereinigung in ein Document geparst und anschließend in das sichtbare, aktive DOM eingefügt, wo Code ausgeführt werden kann.

Sie sollten dieses Risiko verringern, indem Sie statt Strings stets TrustedHTML-Objekte übergeben und Trusted Types mit 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 ihn über alle Ihre Injection Sinks verteilt vorzufinden. Wenn Sie TrustedHTML verwenden, sollten Sie der Methode keinen Sanitizer übergeben müssen.

Beachten Sie, dass Sie beim Umgang mit Benutzereingaben weiterhin vorsichtig sein müssen, selbst wenn Sie Elemente und Attribute entfernen, die Code ausführen können. Beispielsweise könnte Ihre Seite Daten aus einem XML-Dokument verwenden, um Dateien abzurufen, die sie anschließend ausführt.

Beispiele

Eine Eingabe mit Trusted Types parsen

In diesem Beispiel parsen wir eine potenziell schädliche HTML-Eingabe auf sichere Weise und fügen sie anschließend in das DOM der sichtbaren Seite ein.

Um das XSS-Risiko zu verringern, erstellen wir aus dem String mit dem HTML ein TrustedHTML-Objekt. Trusted Types werden noch nicht von allen Browsern unterstützt. Deshalb definieren wir zunächst den Trusted Types Tinyfill. Dieser dient als transparenter Ersatz für die Trusted Types JavaScript API:

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

Als Nächstes erstellen wir eine TrustedTypePolicy, die eine createHTML()-Funktion zur Umwandlung eines Eingabe-Strings in TrustedHTML-Instanzen definiert. Implementierungen von createHTML() verwenden üblicherweise eine Bibliothek wie DOMPurify, um die Eingabe zu bereinigen, wie unten gezeigt:

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

Anschließend verwenden wir dieses policy-Objekt, um aus dem potenziell unsicheren Eingabe-String ein TrustedHTML-Objekt zu erstellen und es in ein Document zu parsen. Beachten Sie, dass das resultierende Document ein vollständiges HTML-Dokument mit den Elementen <html>, <head> und <body> darstellt, obwohl die Eingabe diese Elemente nicht enthält:

// The potentially malicious string
const untrustedString = "<p>I might be XSS</p><img src='x' onerror='alert(1)'>";

// Create a TrustedHTML instance using the policy
const trustedHTML = policy.createHTML(untrustedString);

// Parse the TrustedHTML (which contains a trusted string)
const safeDocument = parser.parseFromString(trustedHTML, "text/html");

safeDocument enthält nun ein DOM, aus dem schädliche Elemente gemäß unserer Richtlinie entfernt wurden. Im Folgenden verwenden wir Element.replaceWith(), um den body des sichtbaren DOM durch den body unseres Dokuments zu ersetzen. Skripte im neuen body werden ebenso ausgeführt wie Code, wenn Event-Handler ausgelöst werden.

document.body.replaceWith(safeDocument.body);

XML, SVG und HTML parsen

Der folgende Code zeigt, wie Sie mit der Methode die einzelnen Inhaltstypen parsen. In produktivem Code sollten Sie Trusted Types verwenden; hier werden sie der Kürze halber weggelassen.

const parser = new DOMParser();

const xmlString = "<warning>Beware of the tiger</warning>";
const doc1 = parser.parseFromString(xmlString, "application/xml");
console.log(doc1.contentType); // "application/xml"

const svgString = '<circle cx="50" cy="50" r="50"/>';
const doc2 = parser.parseFromString(svgString, "image/svg+xml");
console.log(doc2.contentType); // "image/svg+xml"

const htmlString = "<strong>Beware of the leopard</strong>";
const doc3 = parser.parseFromString(htmlString, "text/html");
console.log(doc3.contentType); // "text/html"

console.log(doc1.documentElement.textContent);
// "Beware of the tiger"

console.log(doc2.firstChild.tagName);
// "circle"

console.log(doc3.body.firstChild.textContent);
// "Beware of the leopard"

Beachten Sie, dass die MIME-Typen application/xml und image/svg+xml oben funktional identisch sind – letzterer enthält keine SVG-spezifischen Parsing-Regeln.

Fehlerbehandlung

Wenn der XML-Parser mit einem String verwendet wird, der kein wohlgeformtes XML darstellt, enthält das von parseFromString zurückgegebene XMLDocument einen <parsererror>-Knoten, der den Parse-Fehler beschreibt.

const parser = new DOMParser();

const xmlString = "<warning>Beware of the missing closing tag";
const doc = parser.parseFromString(xmlString, "application/xml");
const errorNode = doc.querySelector("parsererror");
if (errorNode) {
  // parsing failed
} else {
  // parsing succeeded
}

Zusätzlich kann der Parse-Fehler in der JavaScript-Konsole des Browsers gemeldet werden.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• XMLSerializer
• JSON.parse() – das Gegenstück für JSON-Dokumente.