index.src.html

<h1>Referrer Policy</h1>
<pre class="metadata">
Status: ED
ED: https://w3c.github.io/webappsec-referrer-policy/
Shortname: REFERRER-POLICY
TR: http://www.w3.org/TR/referrer-policy/
Level: none
Editor: Jochen Eisinger 49402, Google Inc., eisinger@google.com
Editor: Emily Stark 76989, Google Inc., estark@google.com
Group: webappsec
Abstract: This document describes how an author can set a referrer policy for documents they create, and the impact of such a policy on the <code>Referer</code> HTTP header for outgoing requests and navigations.
Version History: https://github.com/w3c/webappsec-referrer-policy/commits/master/index.src.html
Indent: 2
Ignored Vars: requestURL
Repository: w3c/webappsec-referrer-policy
!Tests: <a href=https://github.com/web-platform-tests/wpt/tree/master/referrer-policy>web-platform-tests referrer-policy/</a> (<a href=https://github.com/web-platform-tests/wpt/labels/referrer-policy>ongoing work</a>)
</pre>

<pre class="anchors">
spec: CSSOM-1; urlPrefix: https://drafts.csswg.org/cssom-1/
  type: dfn
    text: CSS declaration block
    text: location; url: concept-css-style-sheet-location
    text: owner node; for: CSSStyleDeclaration; url: cssstyledeclaration-owner-node
    text: owner node; for: CSSStyleSheet; url: concept-css-style-sheet-owner-node
spec: HTML; urlPrefix: https://html.spec.whatwg.org/multipage/
  type: dfn
    urlPrefix: semantics.html
      text: pragma directives
      text: noreferrer; url: link-type-noreferrer
      text: referrer; url: meta-referrer; for: meta
    urlPrefix: embedded-content.html
      text: an iframe srcdoc document
      text: relevant mutation; url: relevant-mutations
    urlPrefix: browsers.html
      text: opaque origin; url: concept-origin-opaque
      text: active document
      text: associated Document; url: concept-document-window
      text: parse a sandboxing directive
      text: forced sandboxing flag set
      text: auxiliary browsing context
      text: parent browsing context
      text: ancestor browsing context
      text: browsing context container
      text: child browsing context
      text: creating a new Document object
      text: navigation; url: navigate
      text: nested browsing context
      text: nested through; url: browsing-context-nested-through
      text: opener browsing context
      text: plugin document
      text: sandboxed origin browsing context flag
      text: sandboxing flag set
      text: top-level browsing context
    urlPrefix: infrastructure.html
      text: ascii case-insensitive match; url: ascii-case-insensitive
      text: fragment; url: concept-url-fragment
      text: document base url
      text: plugin
      text: reflect
      text: securityerror
      text: mime type
      text: strictly split a string
      text: skip whitespace
      text: collect a sequence of characters
      text: space characters
      text: split a string on spaces
      text: strip leading and trailing whitespace
      text: firing; url: concept-event-fire
      text: reflect
      text: limited to only known values
      text: referrer policy attribute
    urlPrefix: webappapis.html
      text: queue a task
      text: task source
      text: tasks; url: concept-task
      text: environment settings object
      text: responsible browsing context
      text: global object; for: environment settings object; url: concept-settings-object-global
      text: creation URL
    urlPrefix: workers.html
      text: running a worker; url: run-a-worker
    urlPrefix: dom.html
      text: document referrer policy; url: concept-document-referrer-policy; for: Document
      text: style attribute; url: the-style-attribute
    urlPrefix: rendering.html
      text: presentational hints

  type: interface
    urlPrefix: dom.html
      text: Document
  type: element-attr
    urlPrefix: semantics.html
      text: name; for: meta; url: attr-meta-name
      text: referrerpolicy; for: a; url: attr-a-referrerpolicy
      text: referrerpolicy; for: link; url: attr-link-referrerpolicy
spec: SECURE-CONTEXTS; urlPrefix: https://w3c.github.io/webappsec-secure-contexts
  type: dfn
    text: potentially trustworthy URL url: is-url-trustworthy
spec: RFC5234; urlPrefix: https://tools.ietf.org/html/rfc5234
  type: grammar
    text: ALPHA; url: appendix-B.1
spec: RFC7231; urlPrefix: https://tools.ietf.org/html/rfc7231
  type: dfn
    text: referer; url: section-5.5.2
spec: RFC2616; urlPrefix: https://tools.ietf.org/html/rfc7231
  type: dfn
    text: redirection 3xx; url: section-6.4
</pre>

<pre class="link-defaults">
spec: html; type: element; text: link;
spec: html; type: element; text: a;
</pre>

<!--
████ ██    ██ ████████ ████████   ███████
 ██  ███   ██    ██    ██     ██ ██     ██
 ██  ████  ██    ██    ██     ██ ██     ██
 ██  ██ ██ ██    ██    ████████  ██     ██
 ██  ██  ████    ██    ██   ██   ██     ██
 ██  ██   ███    ██    ██    ██  ██     ██
████ ██    ██    ██    ██     ██  ███████
-->
<section>
  <h2 id="intro">Introduction</h2>

  <em>This section is not normative.</em>

  Requests made from a document, and for navigations away from that document
  are associated with a <a><code>Referer</code></a> header. While the header
  can be suppressed for links with the <a><code>noreferrer</code></a> link
  type, authors might wish to control the <a><code>Referer</code></a> header
  more directly for a number of reasons:

  <h3 id="intro-privacy">Privacy</h3>

  A social networking site has a profile page for each of its users, and users
  add hyperlinks from their profile page to their favorite bands. The social
  networking site might not wish to leak the user's profile URL to the band web
  sites when other users follow those hyperlinks (because the profile URLs might
  reveal the identity of the owner of the profile).

  Some social networking sites, however, might wish to inform the band web sites
  that the links originated from the social networking site but not reveal which
  specific user's profile contained the links.

  <h3 id="intro-security">Security</h3>

  A web application uses HTTPS and a URL-based session identifier. The web
  application might wish to link to HTTPS resources on other web sites without
  leaking the user's session identifier in the URL.

  Alternatively, a web application may use URLs which themselves grant some
  capability. Controlling the referrer can help prevent these capability URLs
  from leaking via referrer headers. [[CAPABILITY-URLS]]

  Note that there are other ways for capability URLs to leak, and controlling
  the referrer is not enough to control all those potential leaks.

  <h3 id="intro-trackback">Trackback</h3>

  A blog hosted over HTTPS might wish to link to a blog hosted over HTTP and
  receive trackback links.

</section>

<!--
████████  ████████ ████████ ████ ██    ██ ████ ████████ ████  ███████  ██    ██  ██████
██     ██ ██       ██        ██  ███   ██  ██     ██     ██  ██     ██ ███   ██ ██    ██
██     ██ ██       ██        ██  ████  ██  ██     ██     ██  ██     ██ ████  ██ ██
██     ██ ██████   ██████    ██  ██ ██ ██  ██     ██     ██  ██     ██ ██ ██ ██  ██████
██     ██ ██       ██        ██  ██  ████  ██     ██     ██  ██     ██ ██  ████       ██
██     ██ ██       ██        ██  ██   ███  ██     ██     ██  ██     ██ ██   ███ ██    ██
████████  ████████ ██       ████ ██    ██ ████    ██    ████  ███████  ██    ██  ██████
-->
<section>
  <h2 id="terms">Key Concepts and Terminology</h2>

  <dl>
    <dt>
      <a for="/">referrer policy</a>
    </dt>
    <dd>
      A <a for="/">referrer policy</a> modifies the algorithm used to populate the
      <a><code>Referer</code></a> header when <a for=/ lt=fetch>fetching</a> subresources,
      prefetching, or performing navigations. This document defines the various
      behaviors for each <a for="/">referrer policy</a>.

      Every <a>environment settings object</a> has an algorithm for obtaining a
      <a for="/">referrer policy</a>, which is used by default for all <a for=/>requests</a>
      with that <a>environment settings object</a> as their <a for=request>client</a>.
    </dd>

    <dt><dfn>same-origin request</dfn></dt>
    <dd>
      A {{Request}} <var>request</var> is a <strong>same-origin request</strong>
      if <var>request</var>'s <a for=request>origin</a> and the <a for=url>origin</a> of
      <var>request</var>'s <a for=request>current url</a> are <a lt="same origin">the same</a>.
    </dd>

    <dt><dfn>cross-origin request</dfn></dt>
    <dd>
      A {{Request}} is a <strong>cross-origin request</strong> if it is
      <em>not</em> <a lt="same-origin request">same-origin</a>.
    </dd>
  </dl>
</section>

<section>
  <h2 id="referrer-policies" oldids="referrer-policy-states">Referrer Policies</h2>

  A <dfn export>referrer policy</dfn>
  is the empty string, "<code>no-referrer</code>",
  "<code>no-referrer-when-downgrade</code>", "<code>same-origin</code>",
  "<code>origin</code>", "<code>strict-origin</code>",
  "<code>origin-when-cross-origin</code>",
  "<code>strict-origin-when-cross-origin</code>", or
  "<code>unsafe-url</code>".

  <pre class="idl">
    enum ReferrerPolicy {
      "",
      "no-referrer",
      "no-referrer-when-downgrade",
      "same-origin",
      "origin",
      "strict-origin",
      "origin-when-cross-origin",
      "strict-origin-when-cross-origin",
      "unsafe-url"
    };
  </pre>

  Each possible <a for="/">referrer policy</a> is explained below. A detailed
  algorithm for evaluating their effect is given in the
  <a section href="#integration-with-fetch"></a> and
  <a section href="#algorithms"></a> sections.

  Note: The referrer policy for an <a>environment settings object</a> provides a
  default baseline policy for requests when that <a>environment settings
  object</a> is used as a <a for=request lt=client>request client</a>. This policy may be tightened
  for specific requests via mechanisms like the <code><a>noreferrer</a></code>
  link type.

  <h3 dfn export id="referrer-policy-no-referrer" oldids="referrer-policy-state-no-referrer">"<code>no-referrer</code>"</h3>

  The simplest policy is <a>"<code>no-referrer</code>"</a>, which specifies
  that no referrer information is to be sent along with requests made from a
  particular <a for=request lt=client>request client</a> to any <a for=/>origin</a>. The header will be
  omitted entirely.

  <div class="example">
    If a document at <code>https://example.com/page.html</code> sets a policy of
    <a>"<code>no-referrer</code>"</a>, then navigations to
    <code>https://example.com/</code> (or any other URL) would send no
    <a><code>Referer</code></a> header.
  </div>

  <h3 dfn export id="referrer-policy-no-referrer-when-downgrade" oldids="referrer-policy-state-no-referrer-when-downgrade">"<code>no-referrer-when-downgrade</code>"</h3>

  The <a>"<code>no-referrer-when-downgrade</code>"</a> policy sends a full URL
  along with requests from <a>environment settings objects</a> whose <a for="environment settings object">HTTPS state</a>
  is "`modern`" to a <a>potentially trustworthy URL</a>, and requests from
  <a for=request>clients</a> whose <a for="environment settings object">HTTPS state</a> is not "`modern`"
  to any <a for=/>origin</a>.

  Requests from <a for=request>clients</a> whose <a for="environment settings object">HTTPS state</a> is "`modern`"
  to non-<a>potentially trustworthy URL</a>s, on the other hand, will contain no
  referrer information. A <code><a>Referer</a></code> HTTP header will not be
  sent.

  <div class="example">
    If a document at <code>https://example.com/page.html</code> sets a policy of
    <a>"<code>no-referrer-when-downgrade</code>"</a>, then navigations to
    <code>https://not.example.com/</code> would send a
    <code><a>Referer</a></code> HTTP header with a value of
    <code>https://example.com/page.html</code>, as neither resource's origin is a
    non-<a>potentially trustworthy URL</a>.

    Navigations from that same page to
    <code><strong>http</strong>://not.example.com/</code> would send no
    <a><code>Referer</code></a> header.
  </div>

  This is a user agent's default behavior, if no policy is otherwise specified.

  <h3 dfn export id="referrer-policy-same-origin">"<code>same-origin</code>"</h3>

  The <a>"<code>same-origin</code>"</a> policy specifies that a
  full URL, <a href="#strip-url">stripped for use as a referrer</a>, is sent as
  referrer information when making <a>same-origin requests</a> from a particular
  <a for=request>client</a>.

  <a>Cross-origin requests</a>, on the other hand, will contain no
  referrer information. A <code><a>Referer</a></code> HTTP header will not be
  sent.

  <div class="example">
    If a document at <code>https://example.com/page.html</code> sets a policy of
    <a>"<code>same-origin</code>"</a>, then navigations to
    <code>https://example.com/not-page.html</code> would send a
    <a><code>Referer</code></a> header with a value of
    <code>https://example.com/page.html</code>.

    Navigations from that same page to
    <code>https://<strong>not</strong>.example.com/</code> would send no
    <a><code>Referer</code></a> header.
  </div>

  <h3 dfn export id="referrer-policy-origin" oldids="referrer-policy-state-origin">"<code>origin</code>"</h3>

  The <a>"<code>origin</code>"</a> policy specifies that only the
  <a lt="ASCII serialization of an origin">ASCII serialization</a> of the
  <a for="environment settings object">origin</a> of the <a for=request lt=client>request client</a> is sent as referrer information
  when making both <a>same-origin requests</a> and <a>cross-origin requests</a>
  from a particular <a for=request>client</a>.

  Note: The serialization of an origin looks like
  <code>https://example.com</code>. To ensure that a valid URL is sent in the
  `<code>Referer</code>` header, user agents will append a U+002F SOLIDUS
  ("<code>/</code>") character to the origin (e.g.
  <code>https://example.com/</code>).

  Note: The <a>"<code>origin</code>"</a> policy causes the origin of HTTPS
  referrers to be sent over the network as part of unencrypted HTTP requests.
  The <a>"<code>strict-origin</code>"</a> policy addresses this concern.

  <div class="example">
    If a document at <code>https://example.com/page.html</code> sets a policy of
    <a>"<code>origin</code>"</a>, then navigations to any
    <a for=/>origin</a> would send a <a><code>Referer</code></a> header with a value
    of <code>https://example.com/</code>, even to URLs that are not
    <a>potentially trustworthy URL</a>.
  </div>

  <h3 dfn export id="referrer-policy-strict-origin">"<code>strict-origin</code>"</h3>

  The <a>"<code>strict-origin</code>"</a> policy sends the
  <a lt="ASCII serialization of an origin">ASCII serialization</a> of the
  <a for="environment settings object">origin</a> of the <a for=request lt=client>request client</a> when making requests:

  <ul>
      <li>from an <a>environment settings object</a> whose <a for="environment settings object">HTTPS state</a> is "`modern`" to a
          <a>potentially trustworthy URL</a>, and</li>
      <li>from <a>environment settings objects</a> whose <a for="environment settings object">HTTPS state</a> is not "`modern`" to
          any <a for=/>origin</a>.</li>
  </ul>

  Requests from <a for=request lt=client>request clients</a> whose <a for="environment settings object">HTTPS state</a> is "`modern`"
  to non-<a>potentially trustworthy URL</a>s, on the other hand, will contain no
  referrer information. A <code><a>Referer</a></code> HTTP header will not be
  sent.

  <div class="example">
    If a document at <code>https://example.com/page.html</code> sets a policy of
    <a>"<code>strict-origin</code>"</a>, then navigations to
    <code>https://<strong>not</strong>.example.com</code> would send a
    <a><code>Referer</code></a> header with a value of
    <code>https://example.com/</code>.

    Navigations from that same page to
    <code><strong>http://</strong>not.example.com</code> would send no
    <a><code>Referer</code></a> header.
  </div>

  <div class="example">
    If a document at <code>http://example.com/page.html</code> sets a policy of
    <a>"<code>strict-origin</code>"</a>, then navigations to
    <code>http://<strong>not</strong>.example.com</code> or
    <code><strong>https</strong>://example.com</code> would send a
    <a><code>Referer</code></a> header with a value of
    <code>http://example.com/</code>.
  </div>

  <h3 dfn export id="referrer-policy-origin-when-cross-origin" oldids="referrer-policy-state-origin-when-cross-origin">"<code>origin-when-cross-origin</code>"</h3>

  The <a>"<code>origin-when-cross-origin</code>"</a> policy specifies that a
  full URL, <a href="#strip-url">stripped for use as a referrer</a>, is sent as
  referrer information when making <a>same-origin requests</a> from a particular
  <a for=request lt=client>request client</a>, and only the
  <a lt="ASCII serialization of an origin">ASCII serialization</a> of the
  <a for="environment settings object">origin</a> of the <a for=request lt=client>request client</a> is sent as referrer information
  when making <a>cross-origin requests</a> from a particular <a for=request>client</a>.

  Note: For the <a>"<code>origin-when-cross-origin</code>"</a> policy, we also
  consider protocol upgrades, e.g. requests from
  <code>http://example.com/</code> to <code>https://example.com/</code>, to be
  <a>cross-origin requests</a>.

  Note: The <a>"<code>origin-when-cross-origin</code>"</a> policy causes the
  origin of HTTPS referrers to be sent over the network as part of unencrypted
  HTTP requests. The <a>"<code>strict-origin-when-cross-origin</code>"</a> policy
  addresses this concern.

  <div class="example">
    If a document at <code>https://example.com/page.html</code> sets a policy of
    <a>"<code>origin-when-cross-origin</code>"</a>, then navigations to
    <code>https://example.com/not-page.html</code> would send a
    <a><code>Referer</code></a> header with a value of
    <code>https://example.com/page.html</code>.

    Navigations from that same page to <code>https://not.example.com/</code>
    would send a <a><code>Referer</code></a> header with a value of
    <code>https://example.com/</code>, even to URLs that are not
    <a>potentially trustworthy URL</a>s.
  </div>

  <h3 dfn export id="referrer-policy-strict-origin-when-cross-origin">"<code>strict-origin-when-cross-origin</code>"</h3>

  The <a>"<code>strict-origin-when-cross-origin</code>"</a> policy specifies that a
  full URL, <a href="#strip-url">stripped for use as a referrer</a>, is sent as
  referrer information when making <a>same-origin requests</a> from a particular
  <a for=request lt=client>request client</a>, and only the
  <a lt="ASCII serialization of an origin">ASCII serialization</a> of the
  <a for="environment settings object">origin</a> of the <a for=request lt=client>request client</a> when making <a>cross-origin requests</a>:

  <ul>
      <li>from a <a>environment settings object</a> whose <a for="environment settings object">HTTPS state</a> is "`modern`" to a
          <a>potentially trustworthy URL</a>, and</li>
      <li>from <a>environment settings objects</a> whose <a for="environment settings object">HTTPS state</a> is not "`modern`" to
          any <a for=/>origin</a>.</li>
  </ul>

  Requests from <a for=request>clients</a> whose <a for="environment settings object">HTTPS state</a> is "`modern`" to non-
	<a>potentially trustworthy URL</a>s, on the other hand, will contain no
  referrer information. A <code><a>Referer</a></code> HTTP header will not be
  sent.

  <div class="example">
    If a document at <code>https://example.com/page.html</code> sets a policy of
    <a>"<code>strict-origin-when-cross-origin</code>"</a>, then navigations to
    <code>https://example.com/not-page.html</code> would send a
    <a><code>Referer</code></a> header with a value of
    <code>https://example.com/page.html</code>.

    Navigations from that same page to <code>https://not.example.com/</code>
    would send a <a><code>Referer</code></a> header with a value of
    <code>https://example.com/</code>.

    Navigations from that same page to
    <code><strong>http://</strong>not.example.com/</code> would send no
    <a><code>Referer</code></a> header.
  </div>

  <h3 dfn export id="referrer-policy-unsafe-url" oldids="referrer-policy-state-unsafe-url">"<code>unsafe-url</code>"</h3>

  The <a>"<code>unsafe-url</code>"</a> policy specifies that a full URL,
  <a href="#strip-url">stripped for use as a referrer</a>, is sent along with
  both <a>cross-origin requests</a> and <a>same-origin requests</a> made from
  a particular <a for=request>client</a>.

  <div class="example">
    If a document at <code>https://example.com/sekrit.html</code> sets a policy
    of <a>"<code>unsafe-url</code>"</a>, then navigations to
    <code>http://not.example.com/</code> (and every other origin) would send a
    <code><a>Referer</a></code> HTTP header with a value of
    <code>https://example.com/sekrit.html</code>.
  </div>

  Note: The policy's name doesn't lie; it is unsafe. This policy will leak
  origins and paths from secure resources to insecure origins.
  Carefully consider the impact of setting such a policy for potentially
  sensitive documents.

  <h3 dfn export id="referrer-policy-empty-string">The empty string</h3>

  The empty string "" corresponds to no <a for="/">referrer policy</a>, causing a
  fallback to a <a for="/">referrer policy</a> defined elsewhere, or in the case where
  no such higher-level policy is available, defaulting to
  <a>"<code>no-referrer-when-downgrade</code>"</a>. This defaulting happens in
  the [[#determine-requests-referrer]] algorithm.

  <div class="example">
    Given a HTML <{a}> element without any declared <{a/referrerpolicy}>
    attribute, its referrer policy is the empty string. Thus, navigation
    requests initiated by clicking on that <{a}> element will be sent
    <!-- The 'lt' below is a workaround for
    https://github.com/tabatkins/bikeshed/issues/786-->
    with the <a lt="document referrer policy" for="Document">referrer
    policy</a> of the <{a}> element's <a>node document</a>. If that
    {{Document}} has the empty string as its referrer policy, the
    [[#determine-requests-referrer]] algorithm will treat the empty
    string the same as
    <a>"<code>no-referrer-when-downgrade</code>"</a>.
  </div>

</section>

<section>
  <h2 id="referrer-policy-delivery">Referrer Policy Delivery</h2>

  A <a for=/>request</a>'s <a for=request>referrer policy</a>
  is delivered in one of five ways:

  <ul>
    <li>
      Via the <code>Referrer-Policy</code> HTTP header (defined
      in [[#referrer-policy-header]]).
    </li>
    <li>
      Via a <{meta}> element with a <{meta/name}> of
      <a for="meta"><code>referrer</code></a>.
    </li>
    <li>
      Via a <code>referrerpolicy</code> content attribute on an <{a}>,
      <{area}>, <{img}>, <{iframe}>, or <{link}> element.
    </li>
    <li>
      Via the <code><a>noreferrer</a></code> link relation on an <{a}>,
      <{area}>, or <{link}> element.
    </li>
    <li>
      Implicitly, via inheritance.
    </li>
  </ul>

  <h3 id="referrer-policy-header">Delivery via Referrer-Policy header</h3>

  The <code><dfn local-lt="referrer-policy header"
  id="referrer-policy-header-dfn">Referrer-Policy</dfn></code> HTTP header
  specifies the referrer policy that the user agent applies when determining
  what referrer information should be included with requests made, and with
  <a for=/>browsing contexts</a> created from the context of the protected
  resource.

  The syntax for the name and value of the header are described by the following
  ABNF grammar. ABNF is defined in [[!RFC5234]], and the <code>#rule</code> ABNF
  extension used below is defined in
  <a href="https://tools.ietf.org/html/rfc7230#section-7">Section 7</a> of
  [[!RFC7230]].

  <pre dfn-type="grammar" link-type="grammar">
    "Referrer-Policy:" 1#(<a>policy-token</a> / <a>extension-token</a>)
  </pre>
  <pre dfn-type="grammar" link-type="grammar">
    <dfn export>policy-token</dfn> = "no-referrer" / "no-referrer-when-downgrade" / "strict-origin" / "strict-origin-when-cross-origin" / "same-origin" / "origin" / "origin-when-cross-origin" / "unsafe-url"
    <dfn>extension-token</dfn> = 1*( <a>ALPHA</a> / "-" )
  </pre>

  Note: The header name does not share the HTTP Referer header's misspelling.

  Note: The purpose of <a link-type="grammar">extension-token</a> is so that
  browsers do not fail to parse the entire header field if it includes an
  unknown policy value.  [[#unknown-policy-values]] describes in greater detail
  how new policy values can be deployed.

  Note: The quotes in the ABNF above are used to indicate literal strings.
  Referrer-Policy header values should not be quoted.

  [[#integration-with-fetch]] and [[#integration-with-html]] describe
  how the <code>Referrer-Policy</code> header is processed.

  <section class="informative">
    <h4 id="referrer-usage">Usage</h4>

    <em>This section is not normative.</em>

    A protected resource can prevent referrer leakage by specifying
    <code>no-referrer</code> as the value of its
    <code>Referrer-Policy</code> header:

    <pre>
      Referrer-Policy: no-referrer
    </pre>

    This will cause all requests made from the protected resource's
    context to have an empty <code>Referer</code> [sic] header.
  </section>

  <section class="informative">
    <h3 id="referrer-policy-delivery-meta">Delivery via <{meta}></h3>

    <em>This section is not normative.</em>

    The HTML Standard defines the <a for="meta"><code>referrer</code></a>
    keyword for the <{meta}> element, which allows setting the <a for="/">referrer
    policy</a> via markup.
  </section>

  <section class="informative">
    <h3 id="referrer-policy-delivery-referrer-attribute">Delivery
    via a <code>referrerpolicy</code> content attribute</h3>

    <em>This section is not normative.</em>

    The HTML Standard defines the concept of <a>referrer policy
    attributes</a> which applies to several of its elements, for example:

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

  <section class="informative">
    <h3 id="referrer-policy-delivery-nested"
    oldids="referrer-policy-delivery-implicit">Nested browsing contexts</h3>

    <em>This section is not normative.</em>

    The HTML Standard and Fetch Standard define how nested browsing contexts
    that are not created from <a for="/">responses</a>, such as <{iframe}> elements with
    their <{iframe/srcdoc}> attribute set, or created from a blob URL, inherit
    their <a for="/">referrer policy</a> from the creator browsing context or blob URL.
  </section>
</section>

<section class="informative">
  <h2 id="integration-with-fetch">Integration with Fetch</h2>

  <em>This section is not normative.</em>

  The Fetch specification calls out to
  [[#set-requests-referrer-policy-on-redirect]]
  before <a href="https://fetch.spec.whatwg.org/#http-redirect-fetch">Step
  13 of the HTTP-redirect fetch</a>, so that a request's referrer policy
  can be updated before following a redirect.

  The Fetch specification calls out to [[#determine-requests-referrer]]
  as <a href="https://fetch.spec.whatwg.org/#main-fetch">Step 8 of the
  Main fetch algorithm</a>, and uses the result to set the <var>request</var>'s
  <code>referrer</code> property. Fetch is responsible for serializing the
  URL provided, and setting the `<code>Referer</code>` header on
  <var>request</var>.
</section>

<section class="informative">
  <h2 id="integration-with-html">Integration with HTML</h2>

  <em>This section is not normative.</em>

  The HTML Standard determines the <a for="/">referrer policy</a> of any response
  received during <a>navigation</a> or while <a>running a worker</a>, and uses
  the result to set the resulting {{Document}} or {{WorkerGlobalScope}}'s
  referrer policy. This is later used by the corresponding <a>environment
  settings object</a>, which serves as a <a for=request lt=client>request client</a> for <a
  for=/ lt="fetch">fetches</a> it initiates.

  Note: W3C HTML5 does not define the <code>referrerpolicy</code> content
  attributes, or <code>referrerPolicy</code> IDL attributes, or the
  <a for="meta"><code>referrer</code></a> keyword for <{meta}>, or the
  integration with navigation or running a worker. For this spec to make sense
  with W3C HTML5, those would need to be copied from [[HTML]].
</section>

<section>
  <h2 id="integration-with-css">Integration with CSS</h2>

  The CSS Standard does not specify how it fetches resources referenced from
  stylesheets. However, implementations should be sure to set the
  referrer-related properties of any <a for="/">requests</a> initiated by stylesheets
  as follows:

  <ol>
    <li>
       If a <a>CSS style sheet</a> is responsible for the request,
       and its <a>location</a> is non-null,
       set the <a for="request">referrer</a> to its
       <a>location</a>, and the <a for="request">referrer
       policy</a> to its <a for="CSSStyleSheet">referrer policy</a>.

       Issue: This requires that CSS style sheets process `Referrer-Policy`
       headers, and store a <dfn for="CSSStyleSheet">referrer policy</dfn>
       in the same way that <a for="Document" lt="referrer policy">Documents
       do</a>.
    </li>

    <li>
      If a <a>CSS style sheet</a> with a null <a>location</a> is responsible
      for the request, set the <a for="request">referrer</a> to its
      <a for="CSSStyleSheet">owner node</a>'s
      <a>node document</a>'s <a for="Document">URL</a>, and the
      <a for="request">referrer policy</a> to its
      <a for="CSSStyleSheet">owner node</a>'s
      <a>node document</a>'s <a for="Document">referrer policy</a>.
    </li>

    <li>
       Otherwise, a <a>CSS declaration block</a> that was created by the
       embedder is responsible for the request - either from parsing of an
       element's <a>style attribute</a>, or to implement an <a>presentational
       hint</a> for an element. We assume that in this case the <a>CSS
       declaration block</a>'s <a for="CSSStyleDeclaration">owner node</a>
       points to that element, and set the <a for="request">referrer</a> to the
       block's <a for="CSSStyleDeclaration">owner node</a>'s <a>node
       document</a>'s <a for="Document">URL</a>, and the
       <a for="request">referrer policy</a> to the block's
       <a for="CSSStyleDeclaration">owner node</a>'s <a>node document</a>'s
       <a for="Document">referrer policy</a>.
    </li>
  </ol>

  Note: Both the value of the <a for="/">request</a>'s <a for="request">referrer</a>
  and <a for="request">referrer policy</a> are set based on the values at the
  time a given <a for="/">request</a> is created. If a document's referrer policy
  changes during its lifetime, the policy associated with inline stylesheet
  requests will also change.
</section>

<section>
  <h2 id="algorithms">Algorithms</h2>

  <h3 id="parse-referrer-policy-from-header">
    Parse a referrer policy from a <a><code>Referrer-Policy</code></a> header
  </h3>

  Given a <a for=/>response</a> |response|, the following steps return a
  <a for="/">referrer policy</a> according to |response|'s
  `<code>Referrer-Policy</code>` header:

  <ol>
    <li>
      Let |policy-tokens| be the result of <a>extracting header list values</a> given
      `<code>Referrer-Policy</code>` and |response|'s <a for=response>header list</a>.
    </li>
    <li>
      Let |policy| be the empty string.
    </li>
    <li>
      For each |token| in |policy-tokens|, if |token| is a <a for="/">referrer
      policy</a> and |token| is not the empty string, then set |policy|
      to |token|.

	  Note: This algorithm loops over multiple policy values to allow
	  deployment of new policy values with fallbacks for older user
	  agents, as described in [[#unknown-policy-values]].
    </li>
    <li>
      Return |policy|.
    </li>
  </ol>

  <h3 id="set-requests-referrer-policy-on-redirect" dfn export>
    Set |request|'s referrer policy on redirect
  </h3>

  Given a <a for=/>request</a> |request| and a <a for=/>response</a> |actualResponse|,
  this algorithm updates |request|'s associated
  <a for=request>referrer policy</a>
  according to the Referrer-Policy header (if any) in |actualResponse|.

  <ol>
    <li>
      Let |policy| be the result of executing
      [[#parse-referrer-policy-from-header]] on |actualResponse|.
    </li>
    <li>If |policy| is not the empty string, then set |request|'s
    associated referrer policy to |policy|.</li>
  </ol>

  <h3 id="determine-requests-referrer" dfn export>
    Determine <var>request</var>'s Referrer
  </h3>

  Given a <a for=/>request</a> |request|, we can determine the correct
  referrer information to send by examining the
  <a for=request>referrer policy</a>
  associated with it, as detailed in the following steps, which return
  either <code>no referrer</code> or a URL:

  <ol>
    <li>
      Let <var>policy</var> be |request|'s associated <a for=request>referrer policy</a>.
    </li>
    <li>
      Let <var>environment</var> be <var>request</var>'s <a for=request>client</a>.
    </li>
    <li>
      Switch on |request|'s <a for=request>referrer</a>:

      <dl class="switch">
        <dt>"<code>client</code>"</dt>
        <dd>
          <ol>
            <li>
              If |environment|'s <a for="environment settings object">global
              object</a> is a {{Window}} object, then

              <ol>
                <li>Let |document| be
                the <a>associated <code>Document</code></a> of |environment|'s
                <a for="environment settings object">global object</a>.</li>

                <li>If |document|'s <a for=Document>origin</a> is an <a>opaque origin</a>,
                return <code>no referrer</code>.</li>

                <li>While |document| is <a>an <code>iframe srcdoc</code>
                document</a>, let |document| be |document|'s <a
                for="Document">browsing context</a>'s <a>browsing context
                container</a>'s <a>node document</a>.</li>

                <li>Let |referrerSource| be |document|'s <a
                for="Document">URL</a>.</li>
              </ol>
            </li>

            <li>Otherwise, let |referrerSource| be |environment|'s <a for=environment>creation
            URL</a>.</li>
          </ol>
        </dd>

        <dt>a <a for=/>URL</a></dt>
        <dd>Let |referrerSource| be |request|'s <a for=request>referrer</a>.</dd>
      </dl>

      Note: If <var>request</var>'s <a for=request>referrer</a> is
      "<code>no-referrer</code>", Fetch will not call into this algorithm.
    </li>

    <li>
      Let <var>referrerURL</var> be the result of <a href="#strip-url">stripping
      <var>referrerSource</var> for use as a referrer.</a>
    </li>
    <li>
      Let <var>referrerOrigin</var> be the result of
      <a href="#strip-url">stripping <var>referrerSource</var> for use as a
      referrer</a>, with the <code><a>origin-only flag</a></code> set to
      <code>true</code>.
    </li>

    <li>
      Execute the statements corresponding to the value of <var>policy</var>:

      <dl class="switch">
        <dt><a>"<code>no-referrer</code>"</a></dt>
        <dd>Return <code>no referrer</code></dd>

        <dt><a>"<code>origin</code>"</a></dt>
        <dd>Return <var>referrerOrigin</var></dd>

        <dt><a>"<code>unsafe-url</code>"</a></dt>
        <dd>Return <var>referrerURL</var>.</dd>

        <dt><a>"<code>strict-origin</code>"</a></dt>
        <dd>
          <ol>
            <li>
              If |environment| is not null:
              <ol>
                <li>
                  If |environment|'s <a for="environment settings object">HTTPS state</a> is "`modern`" <em>and</em>
                  <var>request</var>'s
                  <a href="https://fetch.spec.whatwg.org/#concept-request-current-url">current
                  URL</a> is not a <a>potentially trustworthy
                  URL</a>, then return <code>no referrer</code>.
                </li>
              </ol>
            </li>
            <li>Return |referrerOrigin|.
          </ol>
        </dd>

        <dt><a>"<code>strict-origin-when-cross-origin</code>"</a></dt>
        <dd>
          <ol>
            <li>
              If <var>request</var> is a <a>same-origin request</a>, then
              return <var>referrerURL</var>.
            </li>
            <li>
              If |environment| is not null:
              <ol>
                <li>
                  If |environment|'s <a for="environment settings object">HTTPS state</a> is "`modern`" <em>and</em>
                  <var>request</var>'s
                  <a href="https://fetch.spec.whatwg.org/#concept-request-current-url">current
                  URL</a> is not a <a>potentially trustworthy URL</a>
                  <ol>
                      <li>Return <code>no referrer</code>.
                  </ol>
                </li>
              </ol>
            </li>
            <li>Return |referrerOrigin|.
          </ol>
        </dd>

        <dt><a>"<code>same-origin</code>"</a></dt>
        <dd>
          <ol>
            <li>
              If <var>request</var> is a <a>same-origin request</a>, then
              return <var>referrerURL</var>.
            </li>
            <li>
              Otherwise, return <code>no referrer</code>.
            </li>
          </ol>
        </dd>

        <dt><a>"<code>origin-when-cross-origin</code>"</a></dt>
        <dd>
          <ol>
            <li>
              If <var>request</var> is a <a>cross-origin request</a>, then
              return <var>referrerOrigin</var>.
            </li>
            <li>
              Otherwise, return <var>referrerURL</var>.
            </li>
          </ol>
        </dd>

        <dt><a>"<code>no-referrer-when-downgrade</code>"</a></dt>
        <dd>
          <ol>
            <li>
              If |environment| is not null:
              <ol>
                <li>
                  If |environment|'s <a for="environment settings object">HTTPS state</a> is "`modern`" <em>and</em>
                  <var>request</var>'s
                  <a href="https://fetch.spec.whatwg.org/#concept-request-current-url">current
                  URL</a> is not a <a>potentially trustworthy
                  URL</a>, then return <code>no referrer</code>.
                </li>
              </ol>
            </li>
            <li>Return |referrerURL|.
          </ol>
        </dd>
      </dl>

      Note: Fetch will ensure |request|'s <a for="/">referrer policy</a> is not the
      empty string before calling this algorithm.
    </li>
  </ol>

  <h3 id="strip-url">
    Strip <var>url</var> for use as a referrer
  </h3>

  Certain portions of URLs must not be included when sending a URL as the value
  of a `<code>Referer</code>` header: a URLs fragment, username, and password
  components must be stripped from the URL before it's sent out. This
  algorithm accepts a <code><dfn>origin-only flag</dfn></code>, which defaults
  to <code>false</code>. If set to <code>true</code>, the algorithm will
  additionally remove the URL's path and query components, leaving only the
  scheme, host, and port.

  <ol>
    <li>
      If <var>url</var> is <code>null</code>, return <code>no referrer</code>.
    </li>
    <li>
      If <var>url</var>'s <a for=url>scheme</a> is a <a>local scheme</a>, then
      return <code>no referrer</code>.
    </li>
    <li>
      Set <var>url</var>'s <a>username</a> to the empty string.
    </li>
    <li>
      Set <var>url</var>'s <a>password</a> to <code>null</code>.
    </li>
    <li>
      Set <var>url</var>'s <a>fragment</a> to <code>null</code>.
    </li>
    <li>
      If the <code><a>origin-only flag</a></code> is <code>true</code>,
      then:

      <ol>
        <li>
          Set <var>url</var>'s <a for=url>path</a> to <code>null</code>.
        </li>
        <li>
          Set <var>url</var>'s <a for=url>query</a> to <code>null</code>.
        </li>
      </ol>
    </li>
    <li>
      Return <var>url</var>.
    </li>
  </ol>

</section>

<section>
  <h2 id="privacy">Privacy Considerations</h2>

  <h3 id="user-controls">User Controls</h3>

  Nothing in this specification should be interpreted as preventing user
  agents from offering options to users which would change the information
  sent out via a `<code>Referer</code>` header. For instance, user agents
  MAY allow users to suppress the referrer header entirely, regardless of the
  active <a for="/">referrer policy</a> on a page.
</section>

<section>
  <h2 id="security">Security Considerations</h2>

  <h3 id="information-leakage">Information Leakage</h3>

  The <a for="/">referrer policies</a> <a>"<code>origin</code>"</a>,
  <a>"<code>origin-when-cross-origin</code>"</a> and
  <a>"<code>unsafe-url</code>"</a> might leak the origin and the URL of
  a secure site respectively via insecure transport.

  Those three policies are included in the spec nevertheless to lower the friction
  of sites adopting secure transport.

  Authors wanting to ensure that they do not leak any more information than
  the default policy should instead use the policy states
  <a>"<code>same-origin</code>"</a>, <a>"<code>strict-origin</code>"</a>,
  <a>"<code>strict-origin-when-cross-origin</code>"</a> or
  <a>"<code>no-referrer</code>"</a>.

  <h3 id="downgrade">Downgrade to less strict policies</h3>

  The spec does not forbid downgrading to less strict policies, e.g., from
  <a>"<code>no-referrer</code>"</a> to <a>"<code>unsafe-url</code>"</a>.

  On the one hand, it is not clear which policy is more strict for all possible
  pairs of policies: While <a>"<code>no-referrer-when-downgrade</code>"</a> will
  not leak any information over insecure transport, and
  <a>"<code>origin</code>"</a> will, the latter reveals less information
  across cross-origin navigations.

  On the other hand, allowing for setting less strict policies enables authors
  to define safe fallbacks as described in [[#unknown-policy-values]].
</section>

<section>
  <h2 id="authoring">Authoring Considerations</h2>

  <h3 id="unknown-policy-values">Unknown Policy Values</h3>

  As described in [[#parse-referrer-policy-from-header]] and in the
  <{meta}> <a for="meta"><code>referrer</code></a> algorithm, unknown
  policy values will be ignored, and when multiple sources specify a
  referrer policy, the value of the latest one will be used. This makes
  it possible to deploy new policy values.

  <div class="example">
  	Suppose older user agents don't understand
    the <a>"<code>unsafe-url</code>"</a> policy. A site can specify
    an <a>"<code>origin</code>"</a> policy followed by an
    <a>"<code>unsafe-url</code>"</a> policy: older user agents will ignore the
    unknown <a>"<code>unsafe-url</code>"</a> value and use
    <a>"<code>origin</code>"</a>, while newer user agents will use
    <a>"<code>unsafe-url</code>"</a> because it is the last to be processed.
  </div>

  <div class="example">
    To specify multiple policy values in the Referrer-Policy header, a site can
    send multiple Referrer-Policy headers:
    <pre>
      Referrer-Policy: no-referrer
      Referrer-Policy: unsafe-url
    </pre>
    or, equivalently, multiple comma-separated header values:
    <pre>
      Referrer-Policy: no-referrer,unsafe-url
    </pre>
  </div>

  This behavior does not, however, apply to
  the <code>referrerpolicy</code> attribute. Authors may dynamically set
  and get the <code>referrerpolicy</code> attribute to detect whether a
  particular policy value is supported.

</section>

<!--
   ███     ██████  ██    ██ ██    ██  ███████  ██      ██ ██       ████████ ████████   ██████   ████████ ██     ██ ████████ ██    ██ ████████  ██████
  ██ ██   ██    ██ ██   ██  ███   ██ ██     ██ ██  ██  ██ ██       ██       ██     ██ ██    ██  ██       ███   ███ ██       ███   ██    ██    ██    ██
 ██   ██  ██       ██  ██   ████  ██ ██     ██ ██  ██  ██ ██       ██       ██     ██ ██        ██       ████ ████ ██       ████  ██    ██    ██
██     ██ ██       █████    ██ ██ ██ ██     ██ ██  ██  ██ ██       ██████   ██     ██ ██   ████ ██████   ██ ███ ██ ██████   ██ ██ ██    ██     ██████
█████████ ██       ██  ██   ██  ████ ██     ██ ██  ██  ██ ██       ██       ██     ██ ██    ██  ██       ██     ██ ██       ██  ████    ██          ██
██     ██ ██    ██ ██   ██  ██   ███ ██     ██ ██  ██  ██ ██       ██       ██     ██ ██    ██  ██       ██     ██ ██       ██   ███    ██    ██    ██
██     ██  ██████  ██    ██ ██    ██  ███████   ███  ███  ████████ ████████ ████████   ██████   ████████ ██     ██ ████████ ██    ██    ██     ██████
-->
<section>
  <h2 id="acknowledgements">Acknowledgements</h2>

  This specification is based in large part on Adam Barth and Jochen Eisinger's
  <a href="http://wiki.whatwg.org/wiki/Meta_referrer">Meta referrer</a>
  document.
</section>