HTMLIFrameElement: srcdoc-Eigenschaft
Baseline
Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since Januar 2020.
Warnung: Diese Eigenschaft analysiert ihren Eingabewert als HTML und schreibt das Ergebnis in das DOM des Frames. Solche APIs sind als Injection-Sinks bekannt und können, wenn die Eingabe ursprünglich von einem Angreifer kommt, eine potenzielle Vektor für Cross-Site-Scripting (XSS) Angriffe sein.
Sie können dieses Risiko vermindern, indem Sie immer TrustedHTML-Objekte anstelle von Strings zuweisen und trusted types erzwingen.
Weitere Informationen finden Sie unter Sicherheitsüberlegungen.
Die srcdoc Eigenschaft des HTMLIFrameElement-Interfaces erhält oder setzt das inline HTML-Markup des Dokuments des Frames.
Wert
Das Abrufen der Eigenschaft gibt einen String zurück, der die HTML-Serialisierung des Dokuments des Frames enthält.
Dies ist undefined, wenn der Wert nicht gesetzt ist.
Das Setzen der Eigenschaft akzeptiert entweder ein TrustedHTML-Objekt oder einen String.
Es analysiert diese Eingabe als HTML-Dokument und ersetzt den Inhalt des Frames mit dem Ergebnis.
Ausnahmen
TypeError-
Wird ausgelöst, wenn die Eigenschaft auf einen String gesetzt wird, während Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.
Beschreibung
Die srcdoc-Eigenschaft spiegelt den Inhalt des <iframe>-Elements srcdoc-Attributs wider und kann verwendet werden, um das dem <iframe> zugehörige HTML-Dokument zu setzen oder abzurufen.
Beim Setzen der Eigenschaft sollte die Eingabe ein gültiges HTML-Dokument definieren, einschließlich der DOCTYPE-Direktive, <html>, <body> und anderen Tags.
Beachten Sie jedoch, dass Browser normalerweise tolerant gegenüber ungültigem Markup sind und die meisten versuchen sollten, Eingaben zu rendern, die nur Body-Inhalte enthalten.
Jedes vom Browser unterstützte Markup wird analysiert/serialisiert, einschließlich Shadow Roots.
Beachten Sie, dass, wenn dies gesetzt wird, es jeden im src -Eigenschaft gesetzten Wert überschreibt.
Sicherheitsüberlegungen
Die srcdoc-Eigenschaft erlaubt standardmäßig, dass beliebiges HTML-Markup in einem Frame ausgeführt wird.
Wenn der Frame nicht mit der Content Security Policy (CSP) sandbox-Direktive sandboxed ist (oder sandboxed ist, aber den Wert allow-same-origin einschließt), dann wird er dieselbe Herkunft wie das Elternteil haben.
Das bedeutet, dass der Frame vollständigen Zugriff auf das übergeordnete DOM und die Ressourcen hat und umgekehrt.
Dies ist ein bedeutender Vektor für Cross-Site-Scripting (XSS) Angriffe, wenn potenziell unsichere Strings, die von einem Benutzer bereitgestellt werden, ohne vorherige Bereinigung in einen Frame injiziert werden. Betrachten Sie den folgenden Code, bei dem ein String von HTML von einem Benutzer in einen Frame übergeben werden könnte, der dann dem Dokument hinzugefügt wird.
const untrustedStringFromUser = `<!doctype html><script src="http://evil.com/naughty.js"></script>`;
const iframe = document.createElement("iframe");
iframe.srcdoc = untrustedStringFromUser;
document.body.appendChild(iframe);
Wenn der Frame nicht erwartet wird, dass er auf Ihr übergeordnetes Dokument zugreifen muss, können Sie das Risiko mindern, indem Sie einen CSP-Sandbox ohne den Wert allow-same-origin verwenden.
Der Frame wird dann als Cross-Origin-Ressource behandelt, und Angriffe werden erheblich eingeschränkt.
Sie können auch eine allgemeinere CSP verwenden, um die Standorte einzuschränken, von denen Skripte und andere Ressourcen abgerufen werden dürfen.
Sie können das Risiko weiter reduzieren, indem Sie immer TrustedHTML-Objekte anstelle von Strings zuweisen und trusted types erzwingen mit der CSP-Direktive require-trusted-types-for.
Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Chance hat, die Eingabe zu bereinigen, um potenziell gefährliches Markup zu entfernen, bevor es eingefügt wird.
Beispiele
Das HTML aus einem Frame lesen
Das Lesen von srcdoc veranlasst den Nutzer-Agenten, das Dokument des Frames zu serialisieren.
Angenommen, Sie haben folgendes HTML:
<frame
id="example"
srcdoc="<!doctype html><body><p>Hello World!</p></body>"></frame>
Sie können das Markup abrufen und protokollieren, wie im Folgenden gezeigt:
const frame = document.querySelector("#frame");
const frameDoc = frame.srcdoc;
console.log(frameDoc); // "<!doctype html><body><p>Hello World!</p></body>"
Die Inline-Quelle des Frames ersetzen
In diesem Beispiel werden wir das Dokument eines Frames ersetzen, indem wir HTML seiner srcdoc-Eigenschaft zuweisen.
Um das Risiko von XSS zu mindern, erstellen wir zuerst ein TrustedHTML-Objekt aus dem String, der das HTML enthält und weisen dieses Objekt dann srcdoc zu.
Trusted Types werden noch nicht von allen Browsern unterstützt, daher definieren wir zuerst das trusted types tinyfill. Dies fungiert 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() definiert, um einen Eingabestring in TrustedHTML-Instanzen zu transformieren.
In der Regel verwenden Implementierungen von createHTML() eine Bibliothek wie DOMPurify, um die Eingabe zu bereinigen, wie unten gezeigt:
const policy = trustedTypes.createPolicy("my-policy", {
createHTML: (input) => DOMPurify.sanitize(input),
});
Dann verwenden wir dieses policy-Objekt, um ein TrustedHTML-Objekt aus dem potenziell unsicheren Eingabestring zu erstellen und weisen das Ergebnis dem Element zu:
// The potentially malicious string
const untrustedString =
"<!doctype html><body><p>I might be XSS</p><img src='x' onerror='alert(1)'></body>";
// Create a TrustedHTML instance using the policy
const trustedHTML = policy.createHTML(untrustedString);
// Inject the TrustedHTML (which contains a trusted string)
const frame = document.querySelector("#frame");
const frameDoc = frame.srcdoc;
Warnung:
Obwohl Sie einem srcdoc einen String direkt zuweisen können, stellt dies ein Sicherheitsrisiko dar, wenn der einzufügende String potenziell schädlichen Inhalt enthält.
Sie sollten TrustedHTML verwenden, um sicherzustellen, dass der Inhalt bereinigt wird, bevor er eingefügt wird, und Sie sollten einen CSP-Header festlegen, um trusted types zu erzwingen.
Spezifikationen
| Specification |
|---|
| HTML # dom-iframe-srcdoc |
Browser-Kompatibilität
Loading…