This specification is like no other — it has been processed with you, the humble web developer, in mind.
The focus of this specification is readability and ease of access. Unlike the full HTML Standard, this "developer's edition" removes information that only browser vendors need know. It is automatically produced from the full specification by our build tooling, and thus always in sync with the latest developments in HTML.
To read about its conception, construction, and future, read the original press release, and the blog post about its relaunch.
Finally, feel free to contribute on GitHub to make this edition better for everyone!
Origins are the fundamental currency of the Web's security model. Two actors in the Web platform that share an origin are assumed to trust each other and to have the same authority. Actors with differing origins are considered potentially hostile versus each other, and are isolated from each other to varying degrees.
For example, if Example Bank's Web site, hosted at bank.example.com
, tries to examine the DOM of Example Charity's Web site, hosted
at charity.example.org
, a "SecurityError
"
DOMException
will be raised.
An origin is one of the following:
An internal value, with no serialization it can be recreated from (it is serialized as
"null
" per serialization of an origin), for which the only
meaningful operation is testing for equality.
A tuple consists of:
Origins can be shared, e.g., among multiple
Document
objects. Furthermore, origins are generally
immutable. Only the domain of a tuple origin can be changed, and only through the document.domain
API.
The effective domain of an origin origin is computed as follows:
If origin is an opaque origin, then return null.
If origin's domain is non-null, then return origin's domain.
Return origin's host.
domain
[ = domain ]Returns the current domain used for security checks.
Can be set to a value that removes subdomains, to change the origin's domain to allow pages on other subdomains of the same
domain (if they do the same thing) to access each other. (Can't be set in sandboxed
iframe
s.)
The document.domain
attribute is used to
enable pages on different hosts of a domain to access each other's DOMs.
Do not use the document.domain
attribute when using shared hosting. If an untrusted third party is able to host an HTTP server at
the same IP address but on a different port, then the same-origin protection that normally
protects two different sites on the same host will fail, as the ports are ignored when comparing
origins after the document.domain
attribute has been
used.
A sandboxing flag set is a set of zero or more of the following flags, which are used to restrict the abilities that potentially untrusted resources have:
This flag prevents content from navigating browsing contexts other than the sandboxed browsing context itself (or browsing contexts further nested inside it), auxiliary browsing contexts (which are protected by the sandboxed auxiliary navigation browsing context flag defined next), and the top-level browsing context (which is protected by the sandboxed top-level navigation without user activation browsing context flag and sandboxed top-level navigation with user activation browsing context flag defined below).
If the sandboxed auxiliary navigation browsing context flag is not set, then in certain cases the restrictions nonetheless allow popups (new top-level browsing contexts) to be opened. These browsing contexts always have one permitted sandboxed navigator, set when the browsing context is created, which allows the browsing context that created them to actually navigate them. (Otherwise, the sandboxed navigation browsing context flag would prevent them from being navigated even if they were opened.)
This flag prevents content from creating new auxiliary browsing
contexts, e.g. using the target
attribute or
the window.open()
method.
This flag prevents content from navigating their top-level browsing context and prevents content from closing their top-level browsing context. It is consulted only from algorithms that are not triggered by user activation.
When the sandboxed top-level navigation without user activation browsing context flag is not set, content can navigate its top-level browsing context, but other browsing contexts are still protected by the sandboxed navigation browsing context flag and possibly the sandboxed auxiliary navigation browsing context flag.
This flag prevents content from navigating their top-level browsing context and prevents content from closing their top-level browsing context. It is consulted only from algorithms that are triggered by user activation.
As with the sandboxed top-level navigation without user activation browsing context flag, this flag only affects the top-level browsing context; if it is not set, other browsing contexts might still be protected by other flags.
This flag prevents content from instantiating plugins, whether
using the embed
element, the object
element, or through navigation of a nested browsing context, unless
those plugins can be secured.
This 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
.
This flag blocks form submission.
This flag disables the Pointer Lock API. [POINTERLOCK]
This flag blocks script execution.
This flag blocks features that trigger automatically, such as automatically playing a video or automatically focusing a form control.
This flag prevents URL schemes that use storage areas from being able to access the origin's data.
document.domain
browsing context flagThis flag prevents content from using the
document.domain
setter.
This flag prevents content from escaping the sandbox by ensuring that any auxiliary browsing context it creates inherits the content's active sandboxing flag set.
This flag prevents content from using any of the following features to produce modal dialogs:
This flag disables the ability to lock the screen orientation. [SCREENORIENTATION]
This flag disables the Presentation API. [PRESENTATION]
When the user agent is to parse a sandboxing directive, given a string input, a sandboxing flag set output, it must run the following steps:
Split input on ASCII whitespace, to obtain tokens.
Let output be empty.
Add the following flags to output:
The sandboxed auxiliary navigation browsing context flag, unless tokens contains the allow-popups
keyword.
The sandboxed top-level navigation without user activation browsing context flag, unless
tokens contains the allow-top-navigation
keyword.
The sandboxed top-level navigation with user activation browsing context flag, unless
tokens contains either the allow-top-navigation-by-user-activation
keyword or the allow-top-navigation
keyword.
This means that if the allow-top-navigation
is present, the allow-top-navigation-by-user-activation
keyword will have no effect. For this reason, specifying both is a document conformance error.
The sandboxed origin browsing context flag, unless the tokens contains the allow-same-origin
keyword.
The allow-same-origin
keyword
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 pop-up windows, etc, without preventing the embedded page from communicating back to its originating site, using the database APIs to store data, etc.
The sandboxed forms browsing context flag, unless tokens contains the allow-forms
keyword.
The sandboxed pointer lock browsing context flag, unless tokens contains the allow-pointer-lock
keyword.
The sandboxed scripts browsing context flag, unless tokens contains the allow-scripts
keyword.
The sandboxed automatic features browsing context flag, unless tokens contains the allow-scripts
keyword (defined above).
This flag is relaxed by the same keyword 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.
The sandbox propagates to auxiliary browsing contexts flag, unless
tokens contains the allow-popups-to-escape-sandbox
keyword.
The sandboxed modals flag, unless tokens contains the allow-modals
keyword.
The sandboxed orientation lock browsing context flag, unless
tokens contains the allow-orientation-lock
keyword.
The sandboxed presentation browsing context flag, unless tokens
contains the allow-presentation
keyword.
Every top-level browsing context has a popup sandboxing flag set, which is a sandboxing flag set. When a browsing context is created, its popup sandboxing flag set must be empty. It is populated by the rules for choosing a browsing context.
Every browsing context that is a nested browsing context has an
iframe
sandboxing flag set, which is a sandboxing flag set.
Which flags in a nested browsing context's iframe
sandboxing flag
set are set at any particular time is determined by the iframe
element's sandbox
attribute.
Every Document
has an active sandboxing flag set, which is a
sandboxing flag set. When the Document
is created, its active
sandboxing flag set must be empty. It is populated by the navigation
algorithm.
Every resource that is obtained by the navigation algorithm has a forced sandboxing flag set, which is a sandboxing flag set. A resource by default has no flags set in its forced sandboxing flag set, but other specifications can define that certain flags are set.
In particular, the forced sandboxing flag set is used by Content Security Policy. [CSP]
To implement the sandboxing for a Document
object document,
populate document's active sandboxing flag set with the union of the flags
that are present in the following sandboxing flag
sets:
If document's browsing context is a top-level browsing context, then: the flags set on the browsing context's popup sandboxing flag set.
If document's browsing context is a
nested browsing context, then: the flags set on the browsing context's
iframe
sandboxing flag set.
If document's browsing context is a nested browsing context, then: the flags set on the browsing context's parent browsing context's active document's active sandboxing flag set.
The flags set on document's resource's forced sandboxing flag set, if it has one.