Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

HTTP Referrer-Policy - new default value in spec #2792

Merged
merged 4 commits into from
Mar 2, 2021
Merged

HTTP Referrer-Policy - new default value in spec #2792

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
57c25dc
HTTP Referer-Policy - new default value in spec
hamishwillee Mar 2, 2021
8849170
HTTP Referer header - better links to policy
hamishwillee Mar 2, 2021
8f72f8a
Referer security concerns: minor subedit
hamishwillee Mar 2, 2021
20b9f55
Add release notes, improve directives
hamishwillee Mar 2, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 26 additions & 31 deletions files/en-us/web/http/headers/referrer-policy/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
---
<div>{{HTTPSidebar}}</div>

<p><span class="seoSummary">The <strong><code>Referrer-Policy</code></strong> {{glossary("HTTP header")}} controls how much <a href="/en-US/docs/Web/Security/Referer_header:_privacy_and_security_concerns">referrer information</a> (sent via the {{HTTPHeader("Referer")}} header) should be included with requests. Aside from the HTTP header, you can <a href="#Integration_with_HTML">set this policy in HTML</a>.</span></p>
<p><span class="seoSummary">The <strong><code>Referrer-Policy</code></strong> {{glossary("HTTP header")}} controls how much <a href="/en-US/docs/Web/Security/Referer_header:_privacy_and_security_concerns">referrer information</a> (sent via the {{HTTPHeader("Referer")}} header) should be included with requests. Aside from the HTTP header, you can <a href="#integration_with_html">set this policy in HTML</a>.</span></p>

<table class="properties">
<tbody>
Expand All @@ -30,10 +30,6 @@

<h2 id="Syntax">Syntax</h2>

<div class="notecard note">
<p>The original header name {{HTTPHeader("Referer")}} is a misspelling of the word "referrer". The <code>Referrer-Policy</code> header does not share this misspelling.</p>
</div>

<pre class="brush: html">Referrer-Policy: no-referrer
Referrer-Policy: no-referrer-when-downgrade
Referrer-Policy: origin
Expand All @@ -44,14 +40,18 @@ <h2 id="Syntax">Syntax</h2>
Referrer-Policy: unsafe-url
</pre>

<div class="notecard note">
<h4>Note</h4>
<p>The original header name {{HTTPHeader("Referer")}} is a misspelling of the word "referrer". The <code>Referrer-Policy</code> header does not share this misspelling.</p>
</div>

<h2 id="Directives">Directives</h2>

<dl>
<dt><code>no-referrer</code></dt>
<dd>The {{HTTPHeader("Referer")}} header will be omitted entirely. No referrer information is sent along with requests.</dd>
<dt><code>no-referrer-when-downgrade</code> (default)</dt>
<dd>This is the default behavior if no policy is specified, or if the provided value is invalid. The {{glossary("origin")}}, path, and querystring of the URL are sent as a referrer when the protocol security level stays the same (HTTP→HTTP, HTTPS→HTTPS) or improves (HTTP→HTTPS), but isn't sent to less secure destinations (HTTPS→HTTP).
<div class="note">There is effort from browsers in moving to a stricter default value, namely <code>strict-origin-when-cross-origin</code> (see <a href="https://github.com/whatwg/fetch/pull/952">https://github.com/whatwg/fetch/pull/952</a>), consider using this value (or a stricter one), if possible, when changing the Referrer-Policy.</div>
<dt><code>no-referrer-when-downgrade</code></dt>
<dd>The {{glossary("origin")}}, path, and querystring of the URL are sent as a referrer when the protocol security level stays the same (HTTP→HTTP, HTTPS→HTTPS) or improves (HTTP→HTTPS), but isn't sent to less secure destinations (HTTPS→HTTP).
</dd>
<dt><code>origin</code></dt>
<dd>Only send the {{glossary("origin")}} of the document as the referrer.<br>
Expand All @@ -62,12 +62,19 @@ <h2 id="Directives">Directives</h2>
<dd>A referrer will be sent for <a href="/en-US/docs/Web/Security/Same-origin_policy">same-site origins</a>, but cross-origin requests will send no referrer information.</dd>
<dt><code>strict-origin</code></dt>
<dd>Only send the origin of the document as the referrer when the protocol security level stays the same (HTTPS→HTTPS), but don't send it to a less secure destination (HTTPS→HTTP).</dd>
<dt><code>strict-origin-when-cross-origin</code></dt>
<dd>Send the origin, path, and querystring when performing a same-origin request, only send the origin when the protocol security level stays the same while performing a cross-origin request (HTTPS→HTTPS), and send no header to any less-secure destinations (HTTPS→HTTP).</dd>
<dt><code>strict-origin-when-cross-origin</code> (default)</dt>
<dd>Send the origin, path, and querystring when performing a same-origin request, only send the origin when the protocol security level stays the same while performing a cross-origin request (HTTPS→HTTPS), and send no header to any less-secure destinations (HTTPS→HTTP).

<div class="notecard note">
<h4>Note</h4>
<p>This is the default policy if no policy is specified, or if the provided value is invalid (see spec revision <a href="https://github.com/whatwg/fetch/pull/1066">November 2020</a>). Previously the default was <code>no-referrer-when-downgrade</code>. </p>
</div>
</dd>
<dt><code>unsafe-url</code></dt>
<dd>Send the origin, path, and query string when performing any request, regardless of security.
<div class="notecard warning">
<p>This policy will leak potentially-private information from HTTPS resource URLs to insecure origins. Carefully consider the impact of this setting.</p>
<h4>Warning</h4>
<p>This policy will leak potentially-private information from HTTPS resource URLs to insecure origins. Carefully consider the impact of this setting.</p>
</div>
</dd>
</dl>
Expand All @@ -78,7 +85,7 @@ <h2 id="Integration_with_HTML">Integration with HTML</h2>

<pre class="brush: html">&lt;meta name="referrer" content="origin"&gt;</pre>

<p>Or set it for individual requests with <a href="https://developer.mozilla.org/en-US/search?q=referrerPolicy">the <code>referrerpolicy</code> attribute</a> on {{HTMLElement("a")}}, {{HTMLElement("area")}}, {{HTMLElement("img")}}, {{HTMLElement("iframe")}}, {{HTMLElement("script")}}, or {{HTMLElement("link")}} elements:</p>
<p>Or set it for individual requests with <a href="/en-US/search?q=referrerPolicy">the <code>referrerpolicy</code> attribute</a> on {{HTMLElement("a")}}, {{HTMLElement("area")}}, {{HTMLElement("img")}}, {{HTMLElement("iframe")}}, {{HTMLElement("script")}}, or {{HTMLElement("link")}} elements:</p>

<pre class="brush: html">&lt;a href="http://example.com" referrerpolicy="origin"&gt;</pre>

Expand All @@ -87,16 +94,17 @@ <h2 id="Integration_with_HTML">Integration with HTML</h2>
<pre class="brush: html">&lt;a href="http://example.com" rel="noreferrer"&gt;</pre>

<div class="notecard warning">
<p>As seen above, the <code>noreferrer</code> link relation is written without a dash — <code>noreferrer</code>. When the referrer policy is specified for the entire document with a {{HTMLElement("meta")}} element, it's written <em>with</em> a dash: <code>&lt;meta name="referrer" content="no-referrer"&gt;</code>.</p>
<h4>Warning</h4>
<p>As seen above, the <code>noreferrer</code> link relation is written without a dash — <code>noreferrer</code>. When the referrer policy is specified for the entire document with a {{HTMLElement("meta")}} element, it's written <em>with</em> a dash: <code>&lt;meta name="referrer" content="no-referrer"&gt;</code>.</p>
</div>

<h2 id="Integration_with_CSS">Integration with CSS</h2>

<p>CSS can fetch resources referenced from stylesheets. These resources follow a referrer policy as well:</p>

<ul>
<li>External CSS stylesheets use the default policy (<code>no-referrer-when-downgrade</code>), unless it's overwritten via a <code>Referrer-Policy</code> HTTP header on the CSS stylesheet’s response.</li>
<li>For {{HTMLElement("style")}} elements or <a href="/en-US/docs/Web/API/HTMLElement/style"><code>style</code> attributes</a>, the owner document's referrer policy is used.</li>
<li>External CSS stylesheets use the default policy (<code>strict-origin-when-cross-origin</code>), unless it's overwritten via a <code>Referrer-Policy</code> HTTP header on the CSS stylesheet’s response.</li>
<li>For {{HTMLElement("style")}} elements or <a href="/en-US/docs/Web/API/ElementCSSInlineStyle/style"><code>style</code> attributes</a>, the owner document's referrer policy is used.</li>
</ul>

<h2 id="Examples">Examples</h2>
Expand Down Expand Up @@ -232,25 +240,12 @@ <h2 id="Browser_compatibility">Browser compatibility</h2>

<p>{{Compat("http.headers.Referrer-Policy")}}</p>

<div class="note">
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed this note. Am attempting to move it into BCD - in discussion on precisely how here: mdn/browser-compat-data#9303

<ul>
<li>From version 53 onwards, Gecko has a pref available in <code>about:config</code> to allow users to set their default <code>Referrer-Policy</code> — <span class="quote"> <code>network.http.referer.userControlPolicy</code>.</span></li>
<li>From version 59 onwards (See <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=587523">#587523</a>), this has been replaced by <code>network.http.referer.defaultPolicy</code> and <code>network.http.referer.defaultPolicy.pbmode</code>.</li>
</ul>

<p>Possible values are:</p>

<ul>
<li>0 — <code>no-referrer</code></li>
<li>1 — <code>same-origin</code></li>
<li>2 — <code>strict-origin-when-cross-origin</code></li>
<li>3 — <code>no-referrer-when-downgrade</code> (the default)</li>
</ul>
</div>

<h2 id="See_also">See also</h2>

<ul>


<li><a href="/en-US/docs/Web/Security/Referer_header:_privacy_and_security_concerns">Web security > Referer header: privacy and security concerns</a></li>
<li>{{interwiki("wikipedia", "HTTP_referer", "HTTP referer on Wikipedia")}}</li>
<li>When using <a href="/en-US/docs/Web/API/Fetch_API">Fetch</a>: {{domxref("Request.referrerPolicy")}}</li>
<li>The obsolete <span style="white-space: nowrap;">{{HTTPHeader("Content-Security-Policy")}}</span> {{HTTPHeader("Content-Security-Policy/referrer", "referrer")}} {{Obsolete_Inline}} directive.</li>
Expand Down