iframe
elementsrc
srcdoc
name
sandbox
seamless
width
height
interface HTMLIFrameElement : HTMLElement {
attribute DOMString src;
attribute DOMString srcdoc;
attribute DOMString name;
[PutForwards=value] readonly attribute DOMSettableTokenList sandbox;
attribute boolean seamless;
attribute DOMString width;
attribute DOMString height;
readonly attribute Document? contentDocument;
readonly attribute WindowProxy? contentWindow;
};
The iframe
element represents a
nested browsing context.
The src
attribute
gives the address of a page that the nested browsing
context is to contain. The attribute, if present, must be a
valid non-empty URL potentially surrounded by
spaces.
The srcdoc
attribute gives the content of the page that the nested
browsing context is to contain. The value of the attribute is
the source of an iframe
srcdoc
document.
For iframe
elements in HTML documents,
the attribute, if present, must have a value using the HTML
syntax that consists of the following syntactic components,
in the given order:
html
element.For iframe
elements in XML documents,
the attribute, if present, must have a value that matches the
production labeled document
in the XML
specification. [XML]
If the src
attribute and the
srcdoc
attribute are both
specified together, the srcdoc
attribute takes priority. This allows authors to provide a fallback
URL for legacy user agents that do not support the
srcdoc
attribute.
If, when the element is created, the srcdoc
attribute is not set, and
the src
attribute is either
also not set or set but its value cannot be resolved, the browsing context will remain at the
initial about:blank
page.
If the user navigates
away from this page, the iframe
's corresponding
WindowProxy
object will proxy new Window
objects for new Document
objects, but the src
attribute will not change.
Here a blog uses the srcdoc
attribute in conjunction
with the sandbox
and seamless
attributes described
below to provide users of user agents that support this feature
with an extra layer of protection from script injection in the blog
post comments:
<article> <h1>I got my own magazine!</h1> <p>After much effort, I've finally found a publisher, and so now I have my own magazine! Isn't that awesome?! The first issue will come out in September, and we have articles about getting food, and about getting in boxes, it's going to be great!</p> <footer> <p>Written by <a href="/users/cap">cap</a>, 1 hour ago. </footer> <article> <footer> Thirteen minutes ago, <a href="/users/ch">ch</a> wrote: </footer> <iframe seamless sandbox srcdoc="<p>did you get a cover picture yet?"></iframe> </article> <article> <footer> Nine minutes ago, <a href="/users/cap">cap</a> wrote: </footer> <iframe seamless sandbox srcdoc="<p>Yeah, you can see it <a href="/gallery?mode=cover&amp;page=1">in my gallery</a>."></iframe> </article> <article> <footer> Five minutes ago, <a href="/users/ch">ch</a> wrote: </footer> <iframe seamless sandbox srcdoc="<p>hey that's earl's table. <p>you should get earl&amp;me on the next cover."></iframe> </article>
Notice the way that quotes have to be escaped (otherwise the
srcdoc
attribute would end
prematurely), and the way raw ampersands (e.g. in URLs or in prose)
mentioned in the sandboxed content have to be doubly
escaped — once so that the ampersand is preserved when
originally parsing the srcdoc
attribute, and once more
to prevent the ampersand from being misinterpreted when parsing the
sandboxed content.
In the HTML syntax, authors need only
remember to use """ (U+0022) characters to wrap the
attribute contents and then to escape all """ (U+0022)
and U+0026 AMPERSAND (&) characters, and to specify the sandbox
attribute, to ensure safe
embedding of content.
Due to restrictions of the XHTML syntax, in XML the U+003C LESS-THAN SIGN character (<) needs to be escaped as well. In order to prevent attribute-value normalization, some of XML's whitespace characters — specifically "tab" (U+0009), "LF" (U+000A), and "CR" (U+000D) — also need to be escaped. [XML]
The name
attribute, if present, must be a valid browsing context
name. The given value is used to name the nested
browsing context.
The sandbox
attribute, when specified, enables a set of extra restrictions on
any content hosted by the iframe
. Its value must be an
unordered set of unique space-separated tokens that are
ASCII case-insensitive. The allowed values are
allow-forms
,
allow-same-origin
,
allow-scripts
, and
allow-top-navigation
.
When the attribute is set, the content is treated as being from a
unique origin, forms and scripts are disabled, links
are prevented from targeting other browsing contexts, and plugins are secured. The
allow-same-origin
keyword allows the content to be treated as being from the same
origin instead of forcing it into a unique origin, the allow-top-navigation
keyword allows the content to navigate its
top-level browsing context, and the allow-forms
and allow-scripts
keywords re-enable forms and scripts respectively (though scripts
are still prevented from creating popups).
Setting both the
allow-scripts
and
allow-same-origin
keywords together when the embedded page has the same
origin as the page containing the iframe
allows
the embedded page to simply remove the sandbox
attribute.
Sandboxing hostile content is of minimal help if
an attacker can convince the user to just visit the hostile content
directly, rather than in the iframe
. To limit the
damage that can be caused by hostile HTML content, it should be
served from a separate dedicated domain.
In this example, some completely-unknown, potentially hostile, user-provided HTML content is embedded in a page. Because it is served from a separate domain, it is affected by all the normal cross-site restrictions. In addition, the embedded page has scripting disabled, plugins disabled, forms disabled, and it cannot navigate any frames or windows other than itself (or any frames or windows it itself embeds).
<p>We're not scared of you! Here is your content, unedited:</p> <iframe sandbox src="http://usercontent.example.net/getusercontent.cgi?id=12193"></iframe>
It is important to use a separate domain so that if the attacker convinces the user to visit that page directly, the page doesn't run in the context of the site's origin, which would make the user vulnerable to any attack found in the page.
In this example, a gadget from another site is embedded. The gadget has scripting and forms enabled, and the origin sandbox restrictions are lifted, allowing the gadget to communicate with its originating server. The sandbox is still useful, however, as it disables plugins and popups, thus reducing the risk of the user being exposed to malware and other annoyances.
<iframe sandbox="allow-same-origin allow-forms allow-scripts" src="http://maps.example.com/embedded.html"></iframe>
Suppose a file A contained the following fragment:
<iframe sandbox="allow-same-origin allow-forms" src=B></iframe>
Suppose that file B contained an iframe also:
<iframe sandbox="allow-scripts" src=C></iframe>
Further, suppose that file C contained a link:
<a href=D>Link</a>
For this example, suppose all the files were served as
text/html
.
Page C in this scenario has all the sandboxing flags
set. Scripts are disabled, because the iframe
in A has
scripts disabled, and this overrides the allow-scripts
keyword set on the iframe
in B. Forms are also
disabled, because the inner iframe
(in B) does not
have the allow-forms
keyword
set.
Suppose now that a script in A removes all the sandbox
attributes in A
and B. This would change nothing
immediately. If the user clicked the link in C, loading page D into
the iframe
in B, page D would now act as if the
iframe
in B had the allow-same-origin
and allow-forms
keywords
set, because that was the state of the nested browsing
context in the iframe
in A when page B was
loaded.
Generally speaking, dynamically removing or changing the sandbox
attribute is
ill-advised, because it can make it quite hard to reason about what
will be allowed and what will not.
Potentially hostile files should not be served from
the same server as the file containing the iframe
element. Using a different domain ensures that scripts in the files
are unable to attack the site, even if the user is tricked into
visiting those pages directly, without the protection of the sandbox
attribute.
If the allow-scripts
keyword is set along with allow-same-origin
keyword, and the file is from the same origin as the
iframe
's Document
, then a script in the
"sandboxed" iframe could just reach out, remove the sandbox
attribute, and then
reload itself, effectively breaking out of the sandbox
altogether.
The seamless
attribute is a boolean attribute. When specified, it
indicates that the iframe
element's browsing
context is to be rendered in a manner that makes it appear to
be part of the containing document (seamlessly included in the
parent document).
The attribute can be set or removed dynamically, with the rendering updating in tandem.
In this example, the site's navigation is embedded using a
client-side include using an iframe
. Any links in the
iframe
will, in new user agents, be automatically
opened in the iframe
's parent browsing context; for
legacy user agents, the site could also include a base
element with a target
attribute with the value _parent
. Similarly,
in new user agents the styles of the parent page will be
automatically applied to the contents of the frame, but to support
legacy user agents authors might wish to include the styles
explicitly.
<nav><iframe seamless src="nav.include.html"></iframe></nav>
The iframe
element supports dimension
attributes for cases where the embedded content has specific
dimensions (e.g. ad units have well-defined dimensions).
An iframe
element never has fallback
content, as it will always create a nested browsing
context, regardless of whether the specified initial contents
are successfully used.
Descendants of iframe
elements represent
nothing. (In legacy user agents that do not support
iframe
elements, the contents would be parsed as markup
that could act as fallback content.)
When used in HTML
documents, the allowed content model of iframe
elements is text, except that invoking the HTML fragment
parsing algorithm with the iframe
element as the
context element and
the text contents as the input must result in a
list of nodes that are all phrasing content, with no
parse errors having occurred, with
no script
elements being anywhere in the list or as
descendants of elements in the list, and with all the elements in
the list (including their descendants) being themselves
conforming.
The iframe
element must be empty in XML
documents.
The HTML parser treats markup inside
iframe
elements as text.
The IDL attributes src
, srcdoc
, name
, sandbox
, and seamless
must
reflect the respective content attributes of the same
name.
The contentDocument
IDL attribute must return the Document
object of the
active document of the iframe
element's
nested browsing context, if any, or null otherwise.
The contentWindow
IDL attribute must return the WindowProxy
object of the
iframe
element's nested browsing
context, if any, or null otherwise.
Here is an example of a page using an iframe
to
include advertising from an advertising broker:
<iframe src="http://ads.example.com/?customerid=923513721&format=banner" width="468" height="60"></iframe>