index.src.html

<h1>Referrer Policy</h1>
<pre class="metadata">
Status: ED
ED: https://w3c.github.io/webappsec-referrer-policy/
Shortname: REFERRER
TR: http://www.w3.org/TR/referrer-policy/
Level: 1
Editor: Jochen Eisinger, Google Inc., eisinger@google.com
Editor: Emily Stark, 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
</pre>

<pre class="anchors">
spec: FETCH; urlPrefix: https://fetch.spec.whatwg.org/
  type: dfn
    text: fetching
    text: request; url: concept-request
    text: response; url: concept-response
    text: referrer policy; url: concept-referrer-policy
    text: request client; url: concept-request-client
  type: interface
    text: Request
  type: interface
    text: Response
  type: attribute
    text: url; for: Request; url: concept-request-url
    text: origin; for: Request; url: concept-request-origin
    text: client; for: Request; url: concept-request-client
    text: context; for: Request; url: concept-request-context
    text: context-frame-type; for: Request; url: concept-request-context-frame-type
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: parse a sandboxing directive
      text: forced sandboxing flag set
      text: auxiliary browsing context
      text: 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: navigated
      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: incumbent settings object
      text: responsible browsing context
      text: API referrer source
      text: global object
    urlPrefix: workers.html
      text: run a worker
  type: interface
    urlPrefix: dom.html
      text: Document
  type: element
    text: a; url: the-a-element
  type: element-attr
    urlPrefix: semantics.html
      text: name; for: meta; url: attr-meta-name
spec: MIX; urlPrefix: https://w3c.github.io/webappsec/specs/mixedcontent/
  type: dfn
    text: a priori authenticated URL
spec: URL; urlPrefix: https://url.spec.whatwg.org
  type: dfn
    text: local scheme
  type: interface
    text: URL
spec: WSC-UI; urlPrefix: http://www.w3.org/TR/2010/REC-wsc-ui-20100812/
  type: dfn
    text: TLS-protected; url: typesoftls
spec: RFC6454; urlPrefix: https://tools.ietf.org/html/rfc6454
  type: dfn
    text: origin; url: section-3.2
    text: ASCII serialization of an origin; url: section-6.2
    text: the same; url: section-5
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
</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>referrer policy</a>
    </dt>
    <dd>
      A <a>referrer policy</a> modifies the algorithm used to populate the
      <a><code>Referer</code></a> header when <a>fetching</a> subresources,
      prefetching, or performing navigations. This document defines the various
      behaviors for each <a>referrer policy</a>.

      The empty string corresponds to no <a>referrer policy</a>, causing a
      fallback to a <a>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>.

      Every <a>environment settings object</a> has a <a>referrer policy</a>. If
      no <a>referrer policy</a> is explicitly set for an <a>environment settings
      object</a>, then the <a>referrer policy</a> is the empty string. Otherwise,
      the value is whatever has been explicitly set, as explained in the <a
      section href="#set-referrer-policy"></a> algorithm.
    </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 {{Request/origin}} and the <a>origin</a> of
      <var>request</var>'s {{Request/url}} are <a><code>the same</code></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>

  Each possible <a>referrer policy</a>, besides the empty string, 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>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>request client</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
    <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>TLS-protected</a> <a>environment settings
  object</a> to a <a><em>a priori</em> authenticated URL</a>, and requests from
  <a>request clients</a> which are <em>not</em> <a>TLS-protected</a> to any
  <a>origin</a>.

  Requests from <a>TLS-protected</a> <a>request clients</a> to non-<a><em>a
  priori</em> authenticated URLs</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>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 an
    non-<a><em>a priori</em> authenticated 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-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>origin</a> of the <a>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>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.

  <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>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><em>a
    priori</em> authenticated URLs</a>.
  </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>request client</a>, and only the
  <a lt="ASCII serialization of an origin">ASCII serialization</a> of the
  <a>origin</a> of the <a>request client</a> is sent as referrer information
  when making <a>cross-origin requests</a> from a particular <a>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.

  <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 any
    <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><em>a
    priori</em> authenticated URLs</a>.
  </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>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 <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>request</a>'s <a>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>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:

  <pre>
    "Referrer-Policy:" 1#<a>policy-token</a>
  </pre>
  <pre>
    <dfn export>policy-token</dfn>   = "no-referrer" / "no-referrer-when-downgrade" / "origin" / "origin-when-cross-origin" / "unsafe-url"
  </pre>

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

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

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

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

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

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

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

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

  An <a>environment settings object</a> inherits the <a>referrer
  policy</a> of another object 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 a <a>local 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>incumbent settings object</a>.
    </li>
    <li>
      Let <var>policy</var> be the <a>parent browsing context</a>'s
      <a>incumbent settings object</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>.
    </li>
  </ol>

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

  Whenever a user agent <a lt="run a worker">runs a worker</a> for a
  script with {{URL}} <var>url</var> and <var>url</var>'s scheme is a
  <a>local scheme</a>:

  <ol>
    <li>
      Let <var>environment</var> be the Worker's <a>incumbent settings
      object</a>.
    </li>
    <li>
      Let <var>policy</var> be <a>"<code>no-referrer-when-downgrade</code>"</a>.
    </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
  [[#set-requests-referrer-policy-on-redirect]] immediately
  before <a href="https://fetch.spec.whatwg.org/#http-redirect-fetch">Step
  15 of the HTTP-redirect fetch</a>.

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

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

  When a {{Document}} or {{WorkerGlobalScope}} is created after fetching
  a {{Request}} |request| with a {{Response}} |response|, then the HTML
  specification should call out to
  [[#parse-referrer-policy-from-header]] on |response| and use the
  resulting |policy| to execute [[#set-referrer-policy]] on |request|'s
  |environment|.

  Issue: TODO: define content attribute integrations. For example, for
  img elements, HTML should set the request's associated referrer policy
  before fetching.

  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}>. For this spec to
  make sense with W3C HTML5, those would need to be copied from [[HTML]].
</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 {{Response}} |response|, the following steps return a <a>referrer policy</a> according to |response|'s `<code>Referrer-Policy</code>` header:

  <ol>
    <li>
      Let |policy-tokens| be the result of
      parsing `<code>Referrer-Policy</code>` in |response|'s header list.
    </li>
    <li>
      Let |policy| be the empty string.
    </li>
    <li>
      For each <var>token</var> in <var>policy-tokens</var>, execute
      [[#determine-policy-for-token]] on <var>token</var> and
      set <var>policy</var> to the result if it is not the empty string.
    </li>
    <li>
      Return |policy|.
    </li>
  </ol>

  <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 an <a>environment settings
  object</a>, then setting its value is straightforward. If a policy has
  previously been set, then we overwrite it with the new value if the
  new value is not the empty string.

  <ol>
    <li>
      If <var>policy</var> is the empty string, abort these steps.
    </li>

    <li>
      If <var>policy</var> is not one of
      <a>"<code>no-referrer</code>"</a>,
      <a>"<code>no-referrer-when-downgrade</code>"</a>,
      <a>"<code>origin</code>"</a>,
      <a>"<code>origin-when-cross-origin</code>"</a>, or
      <a>"<code>unsafe-url</code>"</a>,
      abort these steps.
    </li>

    <li>
      Set <var>environment</var>'s <a>referrer policy</a> to
      <var>policy</var>.
    </li>
  </ol>

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

  Given a <a>request</a> |request| and a <a>response</a> |actualResponse|,
  this algorithm updates |request|'s associated <a>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">
    Determine <var>request</var>'s Referrer
  </h3>

  Given a {{Request}} <var>request</var>, we can determine the correct
  referrer information to send by examining the <a>referrer policy</a>
  associated with it, as detailed in the following steps, which return
  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>policy</var> be |request|'s associated <a>referrer policy</a>.
    </li>
    <li>
      Let <var>environment</var> be <var>request</var>'s <code>client</code>.
    </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>'s <a>global object</a> is a {{Window}}
          object:

          <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>responsible browsing context</a>.
            </li>
          </ol>
        </li>
        <li>
          Otherwise, <var>environment</var>'s <a>global object</a> is a
          {{WorkerGlobalScope}}:

          <ol>
            <li>
              Let <var>source</var> be the <a>API referrer source</a>
              specified by the <a>incumbent 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 an <a>opaque
              origin</a> (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 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>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>
        <dt>the empty string</dt>
        <dd>
          <ol>
            <li>
              If |environment| is not null:
              <ol>
                <li>
                  If |environment| is <a>TLS-protected</a> <em>and</em>
                  the <a>origin</a>
                  of <var>request</var>'s <a href="https://fetch.spec.whatwg.org/#concept-request-current-url">current
                  URL</a> is not an <a><em>a priori</em> authenticated
                  URL</a>, then return <code>no referrer</code>.
                </li>
              </ol>
            </li>
            <li>Return |referrerURL|.
          </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 <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>

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

  Given a string <var>token</var> (for example, the value of a
  <a><code>Referrer-Policy</code></a> header), this algorithm will return the
  <a>referrer policy</a> it refers to:

  <ol>
    <li>
      If <var>token</var> is an <a>ASCII case-insensitive match</a> for the
      strings "<code>never</code>" or "<code>no-referrer</code>", return
      <a>"<code>no-referrer</code>"</a>.
    </li>
    <li>
      If <var>token</var> is <a>ASCII case-insensitive match</a> for the string
      "<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 an <a>ASCII case-insensitive match</a> for the
      string "<code>origin</code>", return <a>"<code>origin</code>"</a>.
    </li>
    <li>
      If <var>token</var> is <a>ASCII case-insensitive match</a> for the string
      "<code>origin-when-cross-origin</code>", return
      <a>"<code>origin-when-cross-origin</code>"</a>.
    </li>
    <li>
      If <var>token</var> is <a>ASCII case-insensitive match</a> for the strings
      "<code>always</code>" or "<code>unsafe-url</code>",
      return <a>"<code>unsafe-url</code>"</a>.
    </li>
    <li>
      If <var>token</var> is empty, return <a>"<code>no-referrer</code>"</a>.
    </li>
    <li>
      Return the empty string.
    </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="security">Security Considerations</h2>

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

  The <a>referrer policies</a> <a>"<code>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 two policies are include in the spec nevertheless to lower the friction
  of sites adopting secure transport.

  <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 [[#determine-policy-for-token]] and
  [[#set-referrer-policy]], 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>
</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>