Skip to content

Commit

Permalink
Various updates to the document.domain section
Browse files Browse the repository at this point in the history 
* Expand the previous warning, and make it more prominent. Closes whatwg#5128.

* Update the algorithm steps to modern Web IDL style.

* Update the domintro by incorporating the note on what it does, and
  describing failure cases in more detail.

* Move the helper algorithm below the getter/setter steps.
  • Loading branch information
@domenic @mfreed7
domenic authored and mfreed7 committed Sep 11, 2020
1 parent cda6473 commit 2473690
Showing 1 changed file with 70 additions and 61 deletions.
131 changes: 70 additions & 61 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79751,13 +79751,81 @@ interface <dfn>BarProp</dfn> {

<p>Can be set to a value that removes subdomains, to change the <span>origin</span>'s <span
data-x="concept-origin-domain">domain</span> 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
<code>iframe</code>s.)</p>
domain (if they do the same thing) to access each other. This enables pages on different hosts
of a domain to synchronously access each other's DOMs.</p>

<p>In sandboxed <code>iframe</code>s, <code>Document</code>s with <span
data-x="concept-origin-opaque">opaque origins</span>, <code>Document</code>s without a <span
data-x="concept-document-bc">browsing context</span>, and when the "<code
data-x="document-domain-feature">document-domain</code>" feature is disabled, the setter will
throw a <span>"<code>SecurityError</code>"</span> exception. In cases where <code
data-x="dom-crossOriginIsolated">crossOriginIsolated</code> returns true, the setter will do
nothing.</p>
</dd>
</dl>

<div class="critical">
<p>Avoid using the <code data-x="dom-document-domain">document.domain</code>
setter. It undermines the security protections provided by the same-origin policy. This is
especially acute when using shared hosting; for example, 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 <code
data-x="dom-document-domain">document.domain</code> setter has been used.</p>

<p>Because of these security pitfalls, this feature is in the process of being removed from the
Web platform. (This is a long process that takes many years.)</p>

<p>Instead, use <code data-x="dom-window-postMessage">postMessage()</code> or
<code>MessageChannel</code> objects to communicate across origins in a safe manner.</p>
</div>

<div w-nodev>

<p>The <dfn><code data-x="dom-document-domain">domain</code></dfn> getter steps are:</p>

<ol>
<li><p>Let <var>effectiveDomain</var> be <span>this</span>'s <span>origin</span>'s <span
data-x="concept-origin-effective-domain">effective domain</span>.

<li><p>If <var>effectiveDomain</var> is null, then return the empty string.</p></li>

<li><p>Return <var>effectiveDomain</var>, <span data-x="host
serializer">serialized</span>.</p></li>
</ol>

<p>The <code data-x="dom-document-domain">domain</code> setter steps are:</p>

<ol>
<li><p>If <span>this</span>'s <span data-x="concept-document-bc">browsing context</span> is null,
then throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>

<li><p>If <span>this</span>'s <span>active sandboxing flag set</span> has its <span>sandboxed
<code data-x="dom-document-domain">document.domain</code> browsing context flag</span> set, then
throw a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>

<li><p>If <span>this</span> is not <span>allowed to use</span> the "<code
data-x="document-domain-feature">document-domain</code>" feature, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>

<li><p>Let <var>effectiveDomain</var> be <span>this</span>'s <span>origin</span>'s <span
data-x="concept-origin-effective-domain">effective domain</span>.

<li><p>If <var>effectiveDomain</var> is null, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>

<li><p>If the given value <span data-x="is a registrable domain suffix of or is equal to">is not
a registrable domain suffix of and is not equal to</span> <var>effectiveDomain</var>, then throw
a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>

<li><p>If the <span>surrounding agent</span>'s <span>agent cluster</span>'s <span>cross-origin
isolated</span> is true, then return.</p></li>

<li><p>Set <var>this</var>'s <span>origin</span>'s <span
data-x="concept-origin-domain">domain</span> to the result of <span data-x="host
parser">parsing</span> the given value.</p></li>
</ol>

<p>To determine if a string <var>hostSuffixString</var> <dfn data-export="" data-lt="is a
registrable domain suffix of or is equal to|is not a registrable domain suffix of and is not equal
to">is a registrable domain suffix of or is equal to</dfn> a <span
Expand Down Expand Up @@ -79797,67 +79865,8 @@ interface <dfn>BarProp</dfn> {
<li><p>Return true.</p></li>
</ol>

<p>The <dfn><code data-x="dom-document-domain">domain</code></dfn> attribute's getter must run
these steps:</p>

<ol>
<li><p>Let <var>effectiveDomain</var> be this <code>Document</code> object's
<span>origin</span>'s <span data-x="concept-origin-effective-domain">effective domain</span>.

<li><p>If <var>effectiveDomain</var> is null, then return the empty string.</p></li>

<li><p>Return <var>effectiveDomain</var>, <span data-x="host
serializer">serialized</span>.</p></li>
</ol>

<p>The <code data-x="dom-document-domain">domain</code> attribute's setter must run these
steps:</p>

<ol>
<li><p>If this <code>Document</code> object's <span data-x="concept-document-bc">browsing
context</span> is null, then throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>.</p></li>

<li><p>If this <code>Document</code> object's <span>active sandboxing flag set</span> has its
<span>sandboxed <code data-x="dom-document-domain">document.domain</code> browsing context
flag</span> set, then throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code>.</p></li>

<li><p>If this <code>Document</code> object is not <span>allowed to use</span> the "<code
data-x="document-domain-feature">document-domain</code>" feature, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>

<li><p>Let <var>effectiveDomain</var> be this <code>Document</code> object's
<span>origin</span>'s <span data-x="concept-origin-effective-domain">effective domain</span>.

<li><p>If <var>effectiveDomain</var> is null, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>

<li><p>If the given value <span data-x="is a registrable domain suffix of or is equal to">is not
a registrable domain suffix of and is not equal to</span> <var>effectiveDomain</var>, then throw
a <span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p></li>

<li><p>If the <span>surrounding agent</span>'s <span>agent cluster</span>'s <span>cross-origin
isolated</span> is true, then return.</p></li>

<li><p>Set this <code>Document</code> object's <span>origin</span>'s <span
data-x="concept-origin-domain">domain</span> to the result of <span data-x="host
parser">parsing</span> the given value.</p></li>
</ol>

</div>

<p class="note">The <code data-x="dom-document-domain">document.domain</code> attribute is used to
enable pages on different hosts of a domain to access each other's DOMs.</p>

<p class="warning">Do not use the <code data-x="dom-document-domain">document.domain</code>
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 <code data-x="dom-document-domain">document.domain</code> attribute has been
used.</p>




<h3>Sandboxing</h3>
Expand Down

0 comments on commit 2473690

Please sign in to comment.