index.src.html

<h1>Referrer Policy</h1>
<pre class="metadata">
Status: ED
ED: https://w3c.github.io/webappsec/specs/referrer-policy/
Shortname: REFERRER
Level: 1
Editor: Jochen Eisinger, Google Inc., eisinger@google.com
Editor: Mike West, Google Inc., mkwst@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.

Link Defaults: HTML5 (dfn) active document / plugin / browsing context / browsing context container / parent browsing context / nested browsing contexts / top-level browsing context / plugin document / frame / sandboxing flag set / ancestor / an iframe srcdoc document / noreferrer
Link Defaults: HTML5 (interface) document
Link Defaults: HTML5 (element) audio / iframe / video / source / track / script
Version History: https://github.com/w3c/webappsec/commits/master/specs/referrer-policy/index.src.html
</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> header</a>. 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> header</a>
  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]]

  <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>

  <h3 id="terms-defined-here">Terms defined by this specification</h3>
  <dl>
    <dt>
      <dfn export local-title="policy">referrer policy</dfn>
    </dt>
    <dd>
      A <strong>referrer policy</strong> is a property of a <a>JavaScript
      global environment</a> that defines the algorithm used to populate the
      <a><code>referer</code> header</a> when <a>fetching</a> subresources,
      prefetching, or performing navigations.

      If no referrer policy is explicitly set for a <a>global environment</a>,
      then the value of the property is <code>null</code>. Otherwise, the value
      is whatever has been explicitly set, as explained in the
      <a section href="#set-referrer-policy"></a> algorithm.
    </dd>
  </dl>

  <h3 id="terms-defined-by-reference">Terms defined by reference</h3>
  <dl>
    <dt><dfn local-title="Referer|Referer header">Referer HTTP header field</dfn></dt>
    <dd>
      The <strong>"Referer" [sic] HTTP header field</strong> is sent along with
      HTTP requests, and informs the server where the reference for the
      requested resource was found. It is specified in
      <a href="http://tools.ietf.org/html/rfc7231#section-5.5.2">Section 5.5.2</a>
      of HTTP/1.1 -- Semantics and Content [[!RFC7231]]
    </dd>

    <dt><dfn>origin</dfn></dt>
    <dd>
      An origin defines the scope of authority or privilege under which a
      resource operates. It is defined in detail in the Origin specification.
      [[!RFC6454]]
    </dd>

    <dt><dfn>ASCII serialization of an origin</dfn></dt>
    <dd>
      This algorithm is defined in
      <a href="http://tools.ietf.org/html/rfc6454#section-6.2">Section 6.2</a>
      of the Origin specification. [[!RFC6454]]
    </dd>

    <dt><dfn local-title="same-origin">same-origin request</dfn></dt>
    <dd>
      A <a>request</a> is a <strong>same-origin request</strong> if the
      request's <code>origin</code> and the <a>origin</a> of request's
      <code>url</code> are "the same", as defined by
      <a href="http://tools.ietf.org/html/rfc6454#section-5">Section 5</a>
      of the Origin specification. [[!RFC6454]]
    </dd>

    <dt><dfn local-title="cross-origin">cross-origin request</dfn></dt>
    <dd>
      A <a>request</a> is a <strong>cross-origin request</strong> if it is
      <em>not</em> <a>same-origin</a>.
    </dd>

    <dt><dfn>fetch</dfn></dt>
    <dd>
      "fetching" is the process by which a user agent requests resources, and
      delivers responses. It is defined in detail in the Fetch living standard.
      [[!FETCH]]
    </dd>

    <dt><dfn>request</dfn></dt>
    <dt><dfn title="request client|client">request client</dfn></dt>
    <dt><dfn title="request context|context">request context</dfn></dt>
    <dd>
      These terms are defined in
      <a href="http://fetch.spec.whatwg.org/#requests">Section 2.2</a> of the
      Fetch living standard. [[!FETCH]]
    </dd>

    <dt><dfn><em>a priori</em> insecure origin</dfn></dt>
    <dd>
      This term is defined in
      <a href="http://w3c.github.io/webappsec/specs/mixedcontent/#a-priori-insecure-origin">Section 2.1</a>
      of the Mixed Content specification. [[!MIX]].
    </dd>

    <dt><dfn title="JavaScript global environment|global environment">JavaScript global environment</dfn></dt>
    <dd>
      This term is defined in <a title="JavaScript global environment" spec="HTML5">Section
      2.2.2</a> of the HTML5 specification. [[!HTML5]]
    </dd>

    <dt><dfn>global object</dfn></dt>
    <dd>
      This term is defined in the ECMAScript specification. [[!ECMA-262]]
    </dd>

    <dt><dfn>document environment</dfn></dt>
    <dt><dfn>worker environment</dfn></dt>
    <dd>
      These terms are defined in
      <a title="document environment" spec="HTML5">Section 6.1.3.1</a> of the
      HTML5 specification. [[!!HTML5]]
    </dd>

    <dt><dfn>API referrer source</dfn></dt>
    <dd>
      This term is defined in
      <a title="API referrer source" spec="HTML5">Section 8.1.3.1</a> of the
      HTML5 specification. [[!HTML5]]
    </dd>

    <dt><dfn>Entry settings object</dfn></dt>
    <dd>
      This term is defined in
      <a title="entry settings object" spec="HTML5">Section 8.1.3.3</a> of the
      HTML5 specification. [[!HTML5]]
    </dd>

    <dt><dfn>TLS-protected</dfn></dt>
    <dd>
      This term is defined in
      <a href="http://www.w3.org/TR/2010/REC-wsc-ui-20100812/#typesoftls">Section
      5.2 of "Web Security Context: User Interface Guidelines"</a>. [[!WSC-UI]].
    </dd>

    <dt><dfn>relative scheme</dfn></dt>
    <dd>
      The set of <strong>relative schemes</strong> is defined in
      <a href="http://url.spec.whatwg.org/#relative-scheme">Section 5 of the
      URL specification</a>. [[!URL]]
    </dd>

    <dt><dfn>runs a worker</dfn> algorithm</dt>
    <dd>
      This algorithm is
      <a href="http://www.w3.org/TR/workers/#run-a-worker">defined in the Web
      Workers spec</a>. [[!WORKERS]]
    </dd>
  </dl>
</section>

<section>
  <h2 id="referrer-policy-states">Referrer Policy States</h2>

  Every <a>global environment</a> has a <a>referrer policy</a> which governs
  the referrer information sent along with requests made for subresources, and
  for navigations. The <a>policy</a> will be <code>null</code> if no policy has
  been set, otherwise it will be one of the following five values:
  <code><a>No Referrer</a></code>, <code><a>No Referrer When
  Downgrade</a></code>, <code><a>Origin Only</a></code>, <code><a>Origin When
  Cross-origin</a></code>, and <code><a>Unsafe URL</a></code>. Each is explained
  below, and 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 a <a>global environment</a> provides a default
  baseline policy for requests. This policy may be tightened for specific
  requests via mechanisms like the <code><a>noreferrer</a></code> link type.

  <h3 id="referrer-policy-state-no-referrer">No Referrer</h3>

  The simplest policy is <dfn>No Referrer</dfn>, which specifies that no
  referrer information is to be sent along with requests made from a particular
  <a>global environment</a> to any <a>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
    <code>No Referrer</code>, then navigations to
    <code>https://example.com/</code> (or any other URL) would send no
    <a><code>referer</code> header</a>.
  </div>

  <h3 id="referrer-policy-state-no-referrer-when-downgrade">No Referrer When Downgrade</h3>

  The <dfn>No Referrer When Downgrade</dfn> policy sends a full URL along with
  requests from <a>TLS-protected</a> <a>global environments</a> to a
  non-<a><em>a priori</em> insecure origin</a>, and requests from <a>global
  environments</a> which are <em>not</em> <a>TLS-protected</a> to any
  <a>origin</a>.

  Requests from <a>TLS-protected</a> <a>global environments</a> to <a><em>a
  priori</em> insecure origins</a>, on the other hand, will contain no referrer
  information. A <code><a>referer</a></code> will not be sent.

  <div class="example">
    If a document at <code>https://example.com/page.html</code> sets a policy of
    <code>No Referrer When Downgrade</code>, 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 an
    <a><em>a priori</em> insecure origin</a>.

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

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

  <h3 id="referrer-policy-state-origin">Origin Only</h3>

  The <dfn>Origin Only</dfn> policy specifies that only the
  <a title="ASCII serialization of an origin">ASCII serialization</a> of the
  <a>origin</a> of the <a>global environment</a> from which a request is
  made is sent as referrer information when making both <a>same-origin
  requests</a> and <a>cross-origin requests</a> from a particular
  <a>global environment</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 <code>Origin Only</code> policy causes the origin of HTTPS referrers
  to be sent over the network as part of unencrypted HTTP requests.

  <div class="example">
    If a document at <code>https://example.com/page.html</code> sets a policy of
    <code>Origin Only</code>, then navigations to any <a>origin</a> would send a
    <a><code>referer</code> header</a> with a value of
    <code>https://example.com/</code>, even to <a><em>a priori</em> insecure
    origins</a>.
  </div>

  <h3 id="referrer-policy-state-origin-when-cross-origin">Origin When Cross-Origin</h3>

  The <dfn>Origin When Cross-Origin</dfn> 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>global environment</a>, and only the
  <a title="ASCII serialization of an origin">ASCII serialization</a> of the
  <a>origin</a> of the <a>global environment</a> from which a request is
  made is sent as referrer information when making <a>cross-origin requests</a>
  from a particular <a>global environment</a>.

  Note: For the <code>Origin When Cross-Origin</code> 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 <code>Origin When Cross-Origin</code> policy causes the origin of
  HTTPS referrers to be sent over the network as part of unencrypted HTTP
  requests.

  <div class="example">
    If a document at <code>https://example.com/page.html</code> sets a policy of
    <code>Origin When Cross-Origin</code>, then navigations to any
    <code>https://example.com/not-page.html</code> would send a
    <a><code>referer</code> header</a> 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> header</a> with a value of
    <code>https://example.com/</code>, even to <a><em>a priori</em> insecure
    origins</a>.
  </div>

  <h3 id="referrer-policy-state-unsafe-url">Unsafe URL</h3>

  The <dfn>Unsafe URL</dfn> 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>global environment</a>.

  <div class="example">
    If a document at <code>https://example.com/sekrit.html</code> sets a policy
    of <code>Unsafe URL</code>, 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 <a>TLS-protected</a> resources to insecure origins.
  Carefully consider the impact of setting such a policy for potentially
  sensitive documents.
</section>

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

  A <a>JavaScript global environment</a>'s <a>referrer policy</a> is delivered
  in one of four ways:

  <ul>
    <li>
      Via the
      <a href="https://w3c.github.io/webappsec/specs/content-security-policy/#directive-referrer"><code>referrer</code>
      Content Security Policy directive</a>, delivered via the
      <a href="https://w3c.github.io/webappsec/specs/content-security-policy/#content-security-policy-header-field"><code>Content-Security-Policy</code></a>
      HTTP header. [[!CSP]]
    </li>
    <li>
      Via the
      <a href="https://w3c.github.io/webappsec/specs/content-security-policy/#directive-referrer"><code>referrer</code>
      Content Security Policy directive</a>, delivered via a
      <a href="https://w3c.github.io/webappsec/specs/content-security-policy/#delivery-html-meta-element"><code>&lt;meta&gt;</code> element</a>
      [[!CSP]]
    </li>
    <li>
      Via a <a element>meta</a> element with a <a element-attr>name</a> of
      <code>referrer</code>.
    </li>
    <li>
      Implicitly, via inheritance.
    </li>
  </ul>

  The CSP-based delivery mechanisms are defined in the Content Security Policy
  specification. [[!CSP]] The <a element>meta</a> and implicit mechanisms are
  defined below.

  <h3 id="referrer-policy-delivery-meta">Delivery via <a element>meta</a></h3>

  A referrer policy may be set when an HTML <code><a element>meta</a></code>
  element with a name attribute that is a case-insensitive match for the string
  "<code>Referrer</code>" is inserted into a document, for example:

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

  The following values for the <code>content</code> attribute are valid, and map
  to the listed <a>referrer policy</a> values:

  <dl>
    <dt>no-referrer</dt>
    <dd><a><code>No Referrer</code></a></dd>
    <dt>origin</dt>
    <dd><a><code>Origin</code></a></dd>
    <dt>no-referrer-when-downgrade</dt>
    <dd><a><code>No Referrer When Downgrade</code></a></dd>
    <dt>origin-when-crossorigin</dt>
    <dd><a><code>Origin When Cross-Origin</code></a></dd>
    <dt>unsafe-url</dt>
    <dd><a><code>Unsafe URL</code></a></dd>
  </dl>

  Add the following entry to the
  <a href="http://www.w3.org/TR/html5/document-metadata.html#pragma-directives">pragma directives</a>
  for the <code><a element>meta</a></code> element:

  <dl>
    <dt>
      Referrer policy
      (<code>name="Referrer"</code>)
    </dt>
    <dd>
      <ol>
        <li>If the Document's <code><a element>head</a></code> element is
        not an ancestor of the <code><a element>meta</a></code> element, abort
        these steps.</li>

        <li>
          If the <code><a element>meta</a></code> element lacks a
          <code><a element-attr>content</a></code> attribute then abort these
          steps.
        </li>

        <li>
          Let <var>environment</var> be the <a>global environment</a> associated
          with the Document.
        </li>

        <li>
          Let <var>meta-value</var> be the value of the element's
          <code><a element-attr>content</a></code> attribute, after
          <a title="strip leading and trailing whitespace" spec="HTML5">stripping
          leading and trailing whitespace</a>.
        </li>

        <li>
          If <var>meta-value</var> is the empty string, then abort these steps.
        </li>

        <li>
          Let <var>policy</var> be the result of executing the
          [[#determine-policy-for-token]] algorithm on <var>meta-value</var>.
        </li>

        <li>
          Execute the <a section href="#set-referrer-policy"></a> algorithm on
          <var>environment</var> using <var>policy</var>, if <var>policy</var>
          is not <code>null</code>.
        </li>
      </ol>

      Note: Authors are encouraged to avoid the legacy keywords
      <code>never</code>, <code>default</code>, and <code>always</code>. The
      keywords <code>no-referrer</code>,
      <code>no-referrer-when-downgrade</code>, and <code>unsafe-url</code>
      respectively are preferred.

      Note: Implementors are advised to also respect a <a>referrer policy</a>
      delivered via a <code><a element>meta</a></code> element during
      speculative resource loads.
    </dd>
  </dl>

  <h3 id="referrer-policy-delivery-implicit">Implicit Delivery</h3>

  A <a>global environment</a> inherits the <a>referrer policy</a> of another
  environment in several circumstances:

  <h4 id="referrer-policy-delivery-implicit-nested">
     Nested Browsing Contexts
  </h4>

  Whenever a user agent creates a <a>nested browsing context</a> containing
  <a>an iframe srcdoc document</a> or a resource whose <a>origin</a>'s scheme
  is not a <a>relative scheme</a> (for instance, a <code>blob</code> or
  <code>data</code> resource):

  <ol>
    <li>
      Let <var>environment</var> be the <a>nested browsing context</a>'s
      <a>JavaScript global environment</a>.
    </li>
    <li>
      Let <var>policy</var> be the <a>parent browsing context</a>'s
      <a>JavaScript global environment</a>'s <a>referrer policy</a>.
    </li>
    <li>
      Execute the <a section href="#set-referrer-policy"></a> algorithm on
      <var>environment</var> using <var>policy</var>, if <var>policy</var>
      is not <code>null</code>.
    </li>
  </ol>

  <h4 id="referrer-policy-delivery-implicit-workers">
    Workers
  </h4>

  Whenever a user agent <a>runs a worker</a>:
  scheme is not a <a>relative scheme</a>:

  Issue: What about service workers?

  <ol>
    <li>
      Let <var>environment</var> be the Worker's <a>JavaScript global
      environment</a>.
    </li>
    <li>
      Let <var>policy</var> be <code>No Referrer When Downgrade</code>.
    </li>
    <li>
      Execute the <a section href="#set-referrer-policy"></a> algorithm on
      <var>environment</var> using <var>policy</var>.
    </li>
  </ol>
</section>

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

  The Fetch specification calls out to the
  <a href="#determine-requests-referrer">Determine <var>request</var>'s
  referrer</a> algorithm as
  <a href="http://fetch.spec.whatwg.org/#concept-fetch">Step 2 of the
  Fetching algorithm</a>, and uses the response 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>
  <h2 id="algorithms">Algorithms</h2>

  <h3 id="set-referrer-policy">
    Set <var>environment</var>'s referrer policy to <var>policy</var>.
  </h3>

  If no referrer policy has been set for a <a>global environment</a>, then
  setting its value is straightforward. If a policy has previously been set,
  however, then we need to deal with potential conflict. We handle conflict
  in a draconian fashion: conflicts resolve to <code>No Referrer</code>, as
  described below.

  <ol>
    <li>If <var>policy</var> is not one of <code><a>No Referrer</a></code>,
    <code><a>No Referrer When Downgrade</a></code>, <code><a>Origin
    Only</a></code>, <code><a>Origin when cross-origin</a></code>, or
    <code><a>Unsafe URL</a></code>, then set <var>policy</var> to
    <code><a>No Referrer</a></code>.</li>

    <li>
      Let <var>currentPolicy</var> be the value of <var>environment</var>'s
      <a>referrer policy</a>.
    </li>

    <li>
      If <var>currentPolicy</var> is <code>null</code> (that is, if no policy has
      been explicitly set), then:

      <ol>
        <li>
          Set <var>environment</var>'s <a>referrer policy</a> to
          <var>policy</var>.
        </li>
        <li>
          Skip the remaining steps.
        </li>
      </ol>
    </li>

    <li>
      If <var>currentPolicy</var> is not <var>policy</var>, then set
      <var>environment</var>'s <a>referrer policy</a> to <code>Never</code>.
    </li>
  </ol>

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

  Given a <a>Request</a> <var>request</var>, we can determine the correct
  referrer information to send by examining the <a>policy</a> associated with
  its <code>client</code>'s <a>global environment</a>, as detailed in the
  following steps, which returns either <code>no referrer</code> or a URL:

  Note: If Fetch is performing a navigation in response to a link of type
  <code><a>noreferrer</a></code>, then <var>request</var>'s
  <code>referrer</code> will be <code>no referrer</code>, and Fetch won't call
  into this algorithm.

  <ol>
    <li>
      Let <var>environment</var> be <var>request</var>'s <code>client</code>.
    </li>
    <li>
      Let <var>policy</var> be the value of <var>environment</var>'s
      <a>referrer policy</a>.
    </li>
    <li>
      If <var>request</var>'s <code>referrer</code> is a URL, then let
      <var>referrerSource</var> be <var>request</var>'s
      <code>referrer</code>. Otherwise:

      <ol>
        <li>
          If <var>environment</var> is a <a>document environment</a>:
          
          <ol>
            <li>
              Let <var>document</var> be the {{Document}} object of the
              <a>active document</a> of the <a>browsing context</a> of
              <var>environment</var>'s <a>global object</a>.
            </li>
          </ol>
        </li>
        <li>
          Otherwise, <var>environment</var> is a <a>worker environment</a>:

          <ol>
            <li>
              Let <var>source</var> be the <a>API referrer source</a>
              specified by the <a>entry settings object</a>.
            </li>
            <li>
              If <var>source</var> is a URL, let <var>referrerSource</var>
              be <var>source</var>, otherwise let <var>document</var> be
              <var>source</var>.
            </li>
          </ol>
        </li>
        <li>
          If <var>document</var> is set, execute the following steps:
        
          <ol>
            <li>
              If <var>document</var>'s <a>origin</a> is not a scheme/host/port
              tuple (because, for example, it has been sandboxed into a unique
              origin), return <code>no referrer</code> and abort these steps.
            </li>
            <li>
              While <var>document</var> corresponds to <a>an iframe srcdoc Document</a>,
              let <var>document</var> be that Document's <a>browsing context</a>'s
              <a>browsing context container</a>'s {{Document}}.
            </li>
            <li>
              Let <var>referrerSource</var> be <var>document</var>'s URL.
            </li>
          </ol>
        </li>
      </ol>
    </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>
        <dt><var>policy</var> is <code><a>No Referrer</a></code></dt>
        <dd>Return <code>no referrer</code></dd>

        <dt><var>policy</var> is <code><a>Origin Only</a></code></dt>
        <dd>Return <var>referrerOrigin</var></dd>

        <dt><var>policy</var> is <code><a>Unsafe URL</a></code></dt>
        <dd>Return <var>referrerURL</var>.</dd>

        <dt>
          <var>policy</var> is <code><a>Origin When Cross-Origin</a></code>
        </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>
          <var>policy</var> is <code><a>No Referrer When Downgrade</a></code>
        </dt>
        <dt>
          <var>policy</var> is <code>null</code>
        </dt>
        <dd>
          <ol>
            <li>
              If <var>environment</var> is <a>TLS-protected</a> <em>and</em> the
              <a>origin</a> of <var>request</var>'s <code>URL</code> is
              an <a><em>a priori</em> insecure origin</a>, then return
              <code>no referrer</code>.
            </li>
            <li>
              Otherwise, return <var>requestURL</var>.
            </li>
          </ol>
        </dd>
      </dl>
    </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 should 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 <code>scheme</code> is <em>not</em> a <a>relative
      scheme</a>, then return <code>no referrer</code>.
    </li>
    <li>
      Set <var>url</var>'s <code>username</code> to the empty string.
    </li>
    <li>
      Set <var>url</var>'s <code>password</code> to <code>null</code>.
    </li>
    <li>
      Set <var>url</var>'s <code>fragment</code> 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 <code>path</code> to <code>null</code>.
        </li>
        <li>
          Set <var>url</var>'s <code>query</code> to <code>null</code>.
        </li>
      </ol>
    </li>
    <li>
      Return <var>url</var>.
    </li>
  </ol>

  <h3 id="determine-policy-for-token">
    Determine <var>token</var>'s Policy.
  </h3>

  Given a token (for example, the value of a
  <a href="https://w3c.github.io/webappsec/specs/content-security-policy/#directive-referrer"><code>referrer</code>
  Content Security Policy directive</a>), this algorithm will return the
  <a>referrer policy</a> it refers to:

  <ol>
    <li>
      If <var>token</var> is <code>never</code> or <code>no-referrer</code>,
      return <a><code>No Referrer</code></a>.
    </li>
    <li>
      If <var>token</var> is <code>origin</code>, return
      <a><code>Origin</code></a>.
    </li>
    <li>
      If <var>token</var> is <code>default</code> or
      <code>no-referrer-when-downgrade</code>, return
      <a><code>No Referrer When Downgrade</code></a>.
    </li>
    <li>
      If <var>token</var> is <code>origin-when-crossorigin</code>, return
      <a><code>Origin When Cross-Origin</code></a>.
    </li>
    <li>
      If <var>token</var> is <code>always</code> or <code>unsafe-url</code>,
      return <a><code>Unsafe URL</code></a>.
    </li>
    <li>
      Return <a><code>No Referrer</code></a>.
    </li>
  </ol>

  Note: Authors are encouraged to avoid the legacy keywords
  <code>never</code>, <code>default</code>, and <code>always</code>. The
  keywords <code>no-referrer</code>,
  <code>no-referrer-when-downgrade</code>, and <code>unsafe-url</code>
  respectively are preferred.
</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>referrer policy</a> on a page.
</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>