This is revision 1.5612.
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.
When an iframe
element is first inserted into a document, the
user agent must create a nested browsing context, and
then process the iframe
attributes for the
first time.
Whenever an iframe
element with a nested
browsing context has its srcdoc
attribute set, changed, or
removed, the user agent must process the iframe
attributes.
Similarly, whenever an iframe
element with a
nested browsing context but with no srcdoc
attribute specified has its
src
attribute set, changed, or
removed, the user agent must process the iframe
attributes.
When the user agent is to process the iframe
attributes, it must run the first appropriate steps from the
following list:
srcdoc
attribute
is specifiedNavigate the element's
browsing context to a resource whose
Content-Type is text/html
, whose
URL is about:srcdoc
, and whose data
consists of the value of the attribute. The resulting
Document
must be considered an
iframe
srcdoc
document.
src
attribute is specified but the srcdoc
attribute is notIf the value of the src
attribute is the empty string,
jump to the empty step below.
Resolve the value of
the src
attribute, relative
to the iframe
element.
If that is not successful, then jump to the empty step below.
If the resulting absolute URL is an
ASCII case-insensitive match for the string
"about:blank
", and the user agent is processing this
iframe
's attributes for the first time, then jump to
the empty step below. (In cases other than the
first time, about:blank
is loaded
normally.)
Navigate the element's browsing context to the resulting absolute URL.
Empty: When the steps above require the user agent to
jump to the empty step, if the user agent is
processing this iframe
's attributes for the first
time, then the user agent must queue a task to
fire a simple event named load
at the iframe
element.
(After jumping to this step, the above steps are not resumed.)
No load
event
is fired at the about:blank
document
itself.
Queue a task to fire a simple event
named load
at the
iframe
element.
Any navigation required of the user
agent in the process the iframe
attributes
algorithm must be completed with the iframe
element's
document's browsing context as the source
browsing context.
Furthermore, if the browsing context's session
history contained only one Document
when the
process the iframe
attributes algorithm
was invoked, and that was the about:blank
Document
created when the browsing context
was created, then any navigation
required of the user agent in that algorithm must be completed with
replacement enabled.
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.
Removing
an iframe
from a Document
does not cause
its browsing context to be discarded. Indeed, an
iframe
's browsing context can survive its
original parent Document
if its iframe
is
moved to another Document
.
On the other hand, if an iframe
is removed from a
Document
and is then subsequently garbage collected,
this will likely mean (in the absence of other references) that the
child browsing context's WindowProxy
object will become eligble for garbage collection, which will then
lead to that browsing context being discarded, which will then
lead to its Document
being discarded also. This happens without notice to any
scripts running in that Document
; for example, no
unload
events are fired (the
"unload a document" steps are not run).
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. When the browsing
context is created, if the attribute is present, the browsing
context name must be set to the value of this attribute;
otherwise, the browsing context name must be set to the
empty string.
Whenever the name
attribute
is set, the nested browsing context's name must be changed to the new
value. If the attribute is removed, the browsing context
name must be set to the empty string.
When content loads in an iframe
, after any load
events are fired within the content
itself, the user agent must queue a task to fire
a simple event named load
at
the iframe
element. When content whose URL
has the same origin as the iframe
element's Document
fails to load (e.g. due to a DNS
error, network error, or if the server returned a 4xx or 5xx status
code or
equivalent), then the user agent must queue a
task to fire a simple event named error
at the element instead. (This event
does not fire for parse errors,
script errors, or any errors for cross-origin resources.)
The task source for these tasks is the DOM manipulation task source.
A load
event is also
fired at the iframe
element when it is created if no
other data is loaded in it.
When there is an active parser in the
iframe
, and when anything in the iframe
is
delaying the load event of
the iframe
's browsing context's
active document, the iframe
must
delay the load event of its document.
If, during the handling of the load
event, the browsing
context in the iframe
is again navigated, that will further delay the
load event.
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.
While the sandbox
attribute is specified, the iframe
element's
nested browsing context must have the flags given in
the following list set. In addition, any browsing contexts nested within an
iframe
, either directly or indirectly, must have all
the flags set on them as were set on the iframe
's
Document
's browsing context when the
iframe
's Document
was created.
This flag prevents content from navigating browsing contexts other than the sandboxed browsing context itself (or browsing contexts further nested inside it), and the top-level browsing context (which is protected by the sandboxed top-level navigation browsing context flag defined next).
This flag also prevents content
from creating new auxiliary browsing contexts, e.g. using the
target
attribute, the
window.open()
method, or the showModalDialog()
method.
sandbox
attribute's value, when
split on spaces, is
found to have the allow-top-navigation
keyword setThis flag prevents content from navigating their top-level browsing context.
When the allow-top-navigation
is set, content can navigate its top-level browsing
context, but other browsing
contexts are still protected by the sandboxed
navigation browsing context flag defined above.
This flag prevents content from instantiating plugins, whether using the embed
element, the object
element,
the applet
element, or through navigation of a nested
browsing context, unless those plugins can be secured.
This flag prevents content from using the seamless
attribute on
descendant iframe
elements.
This prevents a page inserted using the allow-same-origin
keyword from using a CSS-selector-based method of probing the DOM
of other pages on the same site (in particular, pages that contain
user-sensitive information).
sandbox
attribute's
value, when split on
spaces, is found to have the allow-same-origin
keyword setThis flag forces content into a unique origin, thus preventing it from accessing other content from the same origin.
This flag also prevents script from
reading from or writing to the document.cookie
IDL
attribute, and blocks access to localStorage
.
[WEBSTORAGE]
The allow-same-origin
attribute is intended for two cases.
First, it can be used to allow content from the same site to be sandboxed to disable scripting, while still allowing access to the DOM of the sandboxed content.
Second, it can be used to embed content from a third-party site, sandboxed to prevent that site from opening popup windows, etc, without preventing the embedded page from communicating back to its originating site, using the database APIs to store data, etc.
sandbox
attribute's
value, when split on
spaces, is found to have the allow-forms
keyword setThis flag blocks form submission.
sandbox
attribute's
value, when split on
spaces, is found to have the allow-scripts
keyword setThis flag blocks script execution.
sandbox
attribute's value, when
split on spaces, is
found to have the allow-scripts
keyword (defined above) setThis flag blocks features that trigger automatically, such as automatically playing a video or automatically focusing a form control. It is relaxed by the same flag as scripts, because when scripts are enabled these features are trivially possible anyway, and it would be unfortunate to force authors to use script to do them when sandboxed rather than allowing them to use the declarative features.
These flags must not be set unless the conditions listed above define them as being set.
These flags only take effect when the
nested browsing context of the iframe
is
navigated. Removing them, or removing
the entire sandbox
attribute, has no effect on an already-loaded page.
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). Specifically, when the
attribute is set on an iframe
element whose owner
Document
's browsing context did not have
the sandboxed seamless iframes flag set when that
Document
was created, and while either the
browsing context's active document has the
same origin as the iframe
element's
document, or the browsing context's active
document's address has the same origin as the
iframe
element's document, or the browsing
context's active document is an
iframe
srcdoc
document, the following requirements apply:
The user agent must set the seamless browsing context
flag to true for that browsing context. This
will cause links to open in the parent
browsing context unless an explicit self-navigation
override is used (target="_self"
).
In a CSS-supporting user agent: the user agent must add all
the style sheets that apply to the iframe
element to
the cascade of the active document of the
iframe
element's nested browsing context,
at the appropriate cascade levels, before any style sheets
specified by the document itself.
In a CSS-supporting user agent: the user agent must, for the
purpose of CSS property inheritance only, treat the root element of
the active document of the iframe
element's nested browsing context as being a child of
the iframe
element. (Thus inherited properties on the
root element of the document in the iframe
will
inherit the computed values of those properties on the
iframe
element instead of taking their initial
values.)
In visual media, in a CSS-supporting user agent: the user agent
should set the intrinsic width of the iframe
to the
width that the element would have if it was a non-replaced
block-level element with 'width: auto'.
In visual media, in a CSS-supporting user agent: the user
agent should set the intrinsic height of the iframe
to
the height of the bounding box around the content rendered in the
iframe
at its current width (as given in the previous
bullet point), as it would be if the scrolling position was such
that the top of the viewport for the content rendered in the
iframe
was aligned with the origin of that content's
canvas.
In visual media, in a CSS-supporting user agent: the user agent
must force the height of the initial containing block of the
active document of the nested browsing
context of the iframe
to zero.
This is intended to get around the otherwise circular dependency of percentage dimensions that depend on the height of the containing block, thus affecting the height of the document's bounding box, thus affecting the height of the viewport, thus affecting the size of the initial containing block.
In speech media, the user agent should render the nested browsing context without announcing that it is a separate document.
User agents should, in general, act as if the active
document of the iframe
's nested browsing
context was part of the document that the
iframe
is in, if any.
For example if the user agent supports listing all the links in a document, links in "seamlessly" nested documents would be included in that list without being significantly distinguished from links in the document itself.
If the attribute is not specified, or if the origin conditions listed above are not met, then the user agent should render the nested browsing context in a manner that is clearly distinguishable as a separate browsing context, and the seamless browsing context flag must be set to false for that browsing context.
It is important that user agents recheck the
above conditions whenever the active document of the
nested browsing context of the iframe
changes, such that the seamless browsing context flag
gets unset if the nested browsing context is navigated to another origin.
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>