Skip to content

Commit

Permalink
Explain CORS protocol and credentials interaction
Browse files Browse the repository at this point in the history 
WIP for #264.
  • Loading branch information
@annevk
annevk committed May 3, 2016
1 parent 3ac06c3 commit ac8bf61
Show file tree
Hide file tree
Showing 2 changed files with 166 additions and 5 deletions.
87 changes: 84 additions & 3 deletions Overview.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,8 @@ <h2 class="no-num no-toc" id="table-of-contents">Table of Contents</h2>
<li><a href="#general"><span class="secno">4.2.1 </span>General</a></li>
<li><a href="#http-requests"><span class="secno">4.2.2 </span>HTTP requests</a></li>
<li><a href="#http-responses"><span class="secno">4.2.3 </span>HTTP responses</a></li>
<li><a href="#http-new-header-syntax"><span class="secno">4.2.4 </span>HTTP new-header syntax</a></ol></li>
<li><a href="#http-new-header-syntax"><span class="secno">4.2.4 </span>HTTP new-header syntax</a></li>
<li><a href="#cors-protocol-and-credentials"><span class="secno">4.2.5 </span>CORS protocol and credentials</a></ol></li>
<li><a href="#x-content-type-options-header"><span class="secno">4.3 </span>`<code title="">X-Content-Type-Options</code>` header</a>
<ol>
<li><a href="#should-response-to-request-be-blocked-due-to-nosniff?"><span class="secno">4.3.1 </span>Should
Expand Down Expand Up @@ -225,6 +226,11 @@ <h2 id="infrastructure"><span class="secno">3 </span>Infrastructure</h2>

<hr>

<p><dfn id="credentials">Credentials</dfn> are HTTP cookies, TLS client certificates, and
<a href="#authentication-entry" title="authentication entry">authentication entries</a>.

<hr>

<p><a class="external" data-anolis-spec="html" href="https://html.spec.whatwg.org/multipage/webappapis.html#concept-task" title="concept-task">Tasks</a> that are
<a class="external" data-anolis-spec="html" href="https://html.spec.whatwg.org/multipage/webappapis.html#queue-a-task" title="queue a task">queued</a> by this standard are annotated as one
of:
Expand Down Expand Up @@ -941,8 +947,11 @@ <h4 id="requests"><span class="secno">3.1.5 </span>Requests</h4>
"<code title="">omit</code>", "<code title="">same-origin</code>", or
"<code title="">include</code>". Unless stated otherwise, it is "<code title="">omit</code>".

<p class="note no-backref">When <a href="#concept-request" title="concept-request">request</a>'s
<a href="#concept-request-mode" title="concept-request-mode">mode</a> is "<code title="">navigate</code>", its
<p class="note no-backref"><a href="#concept-request" title="concept-request">Request</a>'s
<a href="#concept-request-credentials-mode" title="concept-request-credentials-mode">credentials mode</a> controls the flow of
<a href="#credentials">credentials</a> during a <a href="#concept-fetch" title="concept-fetch">fetch</a>. When
<a href="#concept-request" title="concept-request">request</a>'s <a href="#concept-request-mode" title="concept-request-mode">mode</a> is
"<code title="">navigate</code>", its
<a href="#concept-request-credentials-mode" title="concept-request-credentials-mode">credentials mode</a> is assumed to be
"<code title="">include</code>" and <a href="#concept-fetch" title="concept-fetch">fetch</a> does not currently account
for other values. If <cite>HTML</cite> changes here, this standard will need corresponding changes.
Expand Down Expand Up @@ -1736,6 +1745,7 @@ <h3 id="http-cors-protocol"><span class="secno">4.2 </span>CORS protocol</h3>
Requirements for user agents are part of the <a href="#concept-fetch" title="concept-fetch">fetch</a>
algorithm.


<h4 id="general"><span class="secno">4.2.1 </span>General</h4>

<p>The <a href="#cors-protocol">CORS protocol</a> consists of a set of headers that indicates whether a
Expand Down Expand Up @@ -1848,6 +1858,76 @@ <h4 id="http-new-header-syntax"><span class="secno">4.2.4 </span>HTTP new-header
Access-Control-Allow-Headers = #<a class="external" data-anolis-spec="http" href="https://tools.ietf.org/html/rfc7230#section-3.2">field-name</a></pre>


<h4 id="cors-protocol-and-credentials"><span class="secno">4.2.5 </span>CORS protocol and credentials</h4>

<!-- non-normative -->

<p>When <a href="#concept-request" title="concept-request">request</a>'s
<a href="#concept-request-credentials-mode" title="concept-request-credentials-mode">credentials mode</a> is "<code>include</code>" it
has an impact on the functioning of <a href="#cors-protocol">CORS protocol</a> other than including
<a href="#credentials">credentials</a> in the <a href="#concept-fetch" title="concept-fetch">fetch</a>.

<div class="example">
<p>In the old days, <a href="https://xhr.spec.whatwg.org/#xmlhttprequest"><code class="external" data-anolis-spec="xhr">XMLHttpRequest</code></a> could be used to set
<a href="#concept-request" title="concept-request">request</a>'s
<a href="#concept-request-credentials-mode" title="concept-request-credentials-mode">credentials mode</a> to "<code>include</code>":

<pre>var client = new XMLHttpRequest()
client.open("GET", "./")
client.withCredentials = true
/* … */</pre>

<p>Nowadays, <code title="">fetch("./", { credentials:"include" }).then(/* … */)</code>
suffices.
</div>

<p><a href="#concept-request" title="concept-request">Request</a>'s
<a href="#concept-request-credentials-mode" title="concept-request-credentials-mode">credentials mode</a> is not necessarily observable
on the server, only when <a href="#credentials">credentials</a> exist for
<a href="#concept-request" title="concept-request">request</a> can it be observed. In such a scenario the
<a href="#cors-request">CORS request</a> would include <a href="#credentials">credentials</a>, but the
<a href="#cors-preflight-request">CORS-preflight request</a> would not. It never does.

<p>The server developer therefore needs to decide whether or not resources "tainted" with
<a href="#credentials">credentials</a> can be shared. Generally speaking, this is rather unsafe and extreme care
has to be taken to avoid the confused deputy problem.

<p>To share resources with <a href="#credentials">credentials</a>, the
`<a href="#http-access-control-allow-origin"><code title="http-access-control-allow-origin">Access-Control-Allow-Origin</code></a>` and
`<a href="#http-access-control-allow-credentials"><code title="http-access-control-allow-credentials">Access-Control-Allow-Credentials</code></a>`
<a href="#concept-header" title="concept-header">headers</a> are important. The following table serves to illustrate
the various legal and illegal combinations for a request to <code>https://rabbit.invalid/</code>:

<table>
<tr>
<th>Request's credentials mode
<th>`<code title="">Access-Control-Allow-Origin</code>`
<th>`<code title="">Access-Control-Allow-Credentials</code>`
<th>Shared?
<th>Notes
<tr>
<td>"<code>omit</code>"
<td>`<code>*</code>`
<td>Omitted
<td>✅
<td>—
<tr>
<td>"<code>omit</code>"
<td>`<code>*</code>`
<td>`<code>true</code>`
<td>✅
<td>If credentials mode is not "<code>include</code>", then
`<a href="#http-access-control-allow-credentials"><code title="http-access-control-allow-credentials">Access-Control-Allow-Credentials</code></a>` is
ignored.
<tr>
<td>"<code>omit</code>"
<td>`<code>https://rabbit.invalid/`</code></td>
<td>Omitted
<td>❌
<td>A serialized origin has no trailing slash.
</table>


<h3 id="x-content-type-options-header"><span class="secno">4.3 </span>`<code title="">X-Content-Type-Options</code>` header</h3>

<p>The
Expand Down Expand Up @@ -5393,6 +5473,7 @@ <h2 class="no-num" id="acknowledgments">Acknowledgments</h2>
Philip Jägenstedt,
R. Auburn,
Ryan Sleevi,
Rory Hewitt,
Sébastien Cevey,
Shao-xuan Kang,
Sharath Udupa,
Expand Down
84 changes: 82 additions & 2 deletions Overview.src.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,11 @@ <h2>Infrastructure</h2>

<hr>

<p><dfn>Credentials</dfn> are HTTP cookies, TLS client certificates, and
<span title="authentication entry">authentication entries</span>.

<hr>

<p><span data-anolis-spec=html title=concept-task>Tasks</span> that are
<span data-anolis-spec=html title="queue a task">queued</span> by this standard are annotated as one
of:
Expand Down Expand Up @@ -871,8 +876,11 @@ <h4>Requests</h4>
"<code title>omit</code>", "<code title>same-origin</code>", or
"<code title>include</code>". Unless stated otherwise, it is "<code title>omit</code>".

<p class="note no-backref">When <span title=concept-request>request</span>'s
<span title=concept-request-mode>mode</span> is "<code title>navigate</code>", its
<p class="note no-backref"><span title=concept-request>Request</span>'s
<span title=concept-request-credentials-mode>credentials mode</span> controls the flow of
<span>credentials</span> during a <span title=concept-fetch>fetch</span>. When
<span title=concept-request>request</span>'s <span title=concept-request-mode>mode</span> is
"<code title>navigate</code>", its
<span title=concept-request-credentials-mode>credentials mode</span> is assumed to be
"<code title>include</code>" and <span title=concept-fetch>fetch</span> does not currently account
for other values. If <cite>HTML</cite> changes here, this standard will need corresponding changes.
Expand Down Expand Up @@ -1666,6 +1674,7 @@ <h3 id=http-cors-protocol>CORS protocol</h3>
Requirements for user agents are part of the <span title=concept-fetch>fetch</span>
algorithm.


<h4>General</h4>

<p>The <span>CORS protocol</span> consists of a set of headers that indicates whether a
Expand Down Expand Up @@ -1778,6 +1787,76 @@ <h4>HTTP new-header syntax</h4>
Access-Control-Allow-Headers = #<span data-anolis-spec=http>field-name</span></pre>


<h4>CORS protocol and credentials</h4>

<!-- non-normative -->

<p>When <span title=concept-request>request</span>'s
<span title=concept-request-credentials-mode>credentials mode</span> is "<code>include</code>" it
has an impact on the functioning of <span>CORS protocol</span> other than including
<span>credentials</span> in the <span title=concept-fetch>fetch</span>.

<div class="example">
<p>In the old days, <code data-anolis-spec=xhr>XMLHttpRequest</code> could be used to set
<span title=concept-request>request</span>'s
<span title=concept-request-credentials-mode>credentials mode</span> to "<code>include</code>":

<pre>var client = new XMLHttpRequest()
client.open("GET", "./")
client.withCredentials = true
/* &hellip; */</pre>

<p>Nowadays, <code title>fetch("./", { credentials:"include" }).then(/* &hellip; */)</code>
suffices.
</div>

<p><span title=concept-request>Request</span>'s
<span title=concept-request-credentials-mode>credentials mode</span> is not necessarily observable
on the server, only when <span>credentials</span> exist for
<span title=concept-request>request</span> can it be observed. In such a scenario the
<span>CORS request</span> would include <span>credentials</span>, but the
<span>CORS-preflight request</span> would not. It never does.

<p>The server developer therefore needs to decide whether or not resources "tainted" with
<span>credentials</span> can be shared. Generally speaking, this is rather unsafe and extreme care
has to be taken to avoid the confused deputy problem.

<p>To share resources with <span>credentials</span>, the
`<code title=http-access-control-allow-origin>Access-Control-Allow-Origin</code>` and
`<code title=http-access-control-allow-credentials>Access-Control-Allow-Credentials</code>`
<span title=concept-header>headers</span> are important. The following table serves to illustrate
the various legal and illegal combinations for a request to <code>https://rabbit.invalid/</code>:

<table>
<tr>
<th>Request's credentials mode
<th>`<code title>Access-Control-Allow-Origin</code>`
<th>`<code title>Access-Control-Allow-Credentials</code>`
<th>Shared?
<th>Notes
<tr>
<td>"<code>omit</code>"
<td>`<code>*</code>`
<td>Omitted
<td>✅
<td>&mdash;
<tr>
<td>"<code>omit</code>"
<td>`<code>*</code>`
<td>`<code>true</code>`
<td>✅
<td>If credentials mode is not "<code>include</code>", then
`<code title=http-access-control-allow-credentials>Access-Control-Allow-Credentials</code>` is
ignored.
<tr>
<td>"<code>omit</code>"
<td>`<code>https://rabbit.invalid/`</td>
<td>Omitted
<td>❌
<td>A serialized origin has no trailing slash.
</table>


<h3>`<code title>X-Content-Type-Options</code>` header</h3>

<p>The
Expand Down Expand Up @@ -5231,6 +5310,7 @@ <h2 class=no-num>Acknowledgments</h2>
Philip Jägenstedt,
R. Auburn,
Ryan Sleevi,
Rory Hewitt,
Sébastien Cevey,
Shao-xuan Kang,
Sharath Udupa,
Expand Down

0 comments on commit ac8bf61

Please sign in to comment.