Referrer Policy

1 Introduction

This section is not normative.

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

1.1 Privacy

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.

1.2 Security

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]

1.3 Trackback

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

2 Key Concepts and Terminology

2.1 Terms defined by this specification

referrer policy

A referrer policy is a property of a JavaScript global environment that defines the algorithm used to populate the referer header when fetching subresources, prefetching, or performing navigations.

If no referrer policy is explicitly set for a global environment, then the value of the property is null. Otherwise, the value is whatever has been explicitly set, as explained in the §6.1 Set environment’s referrer policy to policy. algorithm.

2.2 Terms defined by reference

Referer HTTP header field

The "Referer" [sic] HTTP header field is sent along with HTTP requests, and informs the server where the reference for the requested resource was found. It is specified in Section 5.5.2 of HTTP/1.1 -- Semantics and Content [RFC7231]

origin

An origin defines the scope of authority or privilege under which a resource operates. It is defined in detail in the Origin specification. [RFC6454]

ASCII serialization of an origin

This algorithm is defined in Section 6.2 of the Origin specification. [RFC6454]

same-origin request

A request is a same-origin request if the request’s origin and the origin of request’s url are "the same", as defined by Section 5 of the Origin specification. [RFC6454]

cross-origin request

A request is a cross-origin request if it is not same-origin.

fetch

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

request

request client

request context

These terms are defined in Section 2.2 of the Fetch living standard. [FETCH]

a priori insecure origin

This term is defined in Section 2.1 of the Mixed Content specification. [MIX].

JavaScript global environment

This term is defined in Section 2.2.2 of the HTML5 specification. [HTML5]

global object

This term is defined in the ECMAScript specification. [ECMA-262]

document environment

worker environment

These terms are defined in Section 6.1.3.1 of the HTML5 specification. [[!!HTML5]]

API referrer source

This term is defined in Section 8.1.3.1 of the HTML5 specification. [HTML5]

Entry settings object

This term is defined in Section 8.1.3.3 of the HTML5 specification. [HTML5]

TLS-protected

This term is defined in Section 5.2 of "Web Security Context: User Interface Guidelines". [WSC-UI].

relative scheme

The set of relative schemes is defined in Section 5 of the URL specification. [URL]

runs a worker algorithm

This algorithm is defined in the Web Workers spec. [WORKERS]

3 Referrer Policy States

Every global environment has a referrer policy which governs the referrer information sent along with requests made for subresources, and for navigations. The policy will be null if no policy has been set, otherwise it will be one of the following five values: None, None when downgrade, Origin Only, Origin when cross-origin, and Unsafe URL. Each is explained below, and a detailed algorithm for evaluating their effect is given in the §5 Integration with Fetch and §6 Algorithms sections:

Note: The referrer policy for a global environment provides a default baseline policy for requests. This policy may be tightened for specific requests via mechanisms like the noreferrer link type.

3.1 None

The simplest policy is None, which specifies that no referrer information is to be sent along with requests made from a particular global environment to any origin. The header will be omitted entirely.

3.2 None When Downgrade

The None When Downgrade policy sends a full URL along with requests from TLS-protected global environments to a non-a priori insecure origin, and requests from global environments which are not TLS-protected to any origin.

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

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

3.3 Origin Only

The Origin Only policy specifies that only the ASCII serialization of the origin of the global environment from which a request is made is sent as referrer information when making both same-origin requests and cross-origin requests from a particular global environment.

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

3.4 Origin When Cross-Origin

The Origin When Cross-Origin policy specifies that a full URL, stripped for use as a referrer, is sent as referrer information when making same-origin requests from a particular global environment, and only the ASCII serialization of the origin of the global environment from which a request is made is sent at referrer information when making cross-origin requests from a particular global environment.

Note: For the Origin When Cross-Origin policy, we also consider protocol upgrades, e.g. requests from http://exmaple.com/ to https://example.com/ to be cross-origin requests.

3.5 Unsafe URL

The Unsafe URL policy specifies that a full URL, stripped for use as a referrer, is sent along with both cross-origin requests and same-origin requests made from a particular global environment.

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

4 Referrer Policy Delivery

A JavaScript global environment’s referrer policy is delivered in one of four ways:

• Via the referrer Content Security Policy directive, delivered via the Content-Security-Policy HTTP header. [CSP]
• Via the referrer Content Security Policy directive, delivered via a <meta> element [CSP]
• Via a meta element with a name of referrer.
• Implicitly, via inheritance.

The CSP-based delivery mechanisms are defined in the Content Security Policy specification. [CSP] The meta and implicit mechanisms are defined below.

4.1 Delivery via meta

When an HTML meta element with a name attribute that is a case-insensitive match for the string "Referrer" is inserted into a document, for example:

<meta name="referrer" content="origin">

Add the following entry to the pragma directives for the meta element:

Referrer policy (name="Referrer")

1. If the Document’s head element is not an ancestor of the meta element, abort these steps.
2. If the meta element lacks a content attribute, or if that attribute’s value is the empty string, then abort these steps.
3. Let environment be the global environment associated with the Document.
4. Let meta-value be the value of the element’s content attribute, after stripping leading and trailing whitespace.
5. Let policy be the value associated with the first of the following keywords which is a case-insensitive match for meta-value:

   never

   none

   None

   origin

   Origin

   default

   none-when-downgrade

   None When Downgrade

   origin-when-crossorigin

   Origin When Cross-Origin

   always

   unsafe-url

   Unsafe URL

6. Execute the §6.1 Set environment’s referrer policy to policy. algorithm on environment using policy, if policy is not null.

Note: Authors are encouraged to avoid the legacy keywords never, default, and always. The keywords none, none-when-downgrade, and unsafe-url respectively are preferred.

What is the interaction with the preload scanner?

4.2 Implicit Delivery

A global environment inherits the referrer policy of another environment in several circumstances:

4.2.1 Nested Browsing Contexts

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

1. Let environment be the nested browsing context’s JavaScript global environment.
2. Let policy be the parent browsing context’s JavaScript global environment’s referrer policy.
3. Execute the §6.1 Set environment’s referrer policy to policy. algorithm on environment using policy, if policy is not null.

4.2.2 Workers

Whenever a user agent runs a worker: scheme is not a relative scheme:

What about service workers?

1. Let environment be the Worker’s JavaScript global environment.
2. Let policy be the None when downgrade
3. Execute the §6.1 Set environment’s referrer policy to policy. algorithm on environment using policy.

5 Integration with Fetch

The Fetch specification calls out to the Determine request’s referrer algorithm as Step 2 of the Fetching algorithm, and uses the response to set the request’s referrer property. Fetch is responsible for serializing the URL provided, and setting the `Referer` header on request.

6 Algorithms

6.1 Set environment’s referrer policy to policy.

If no referrer policy has been set for a global environment, 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 None, as described below.

1. If policy is not one of None, None when downgrade, Origin Only, Origin when cross-origin, or Unsafe URL, then set policy to None.
2. Let currentPolicy be the value of environment’s referrer policy.
3. If currentPolicy is null (that is, if no policy has been explicitly set), then:
   1. Set environment’s referrer policy to policy.
   2. Skip the remaining steps.
4. If currentPolicy is not policy, then set environment’s referrer policy to Never.

6.2 Determine request’s Referrer.

Given a Request request, we can determine the correct referrer information to send by examining the policy associated with its client’s global environment, as detailed in the following steps, which returns either none or a URL:

Note: If Fetch is performing a navigation in response to a link of type noreferrer, then request’s referrer will be none, and Fetch won’t call into this algorithm.

1. Let environment be request’s client.
2. Let policy be the value of environment’s referrer policy.
3. If request’s referrer is a URL, then let referrerSource be request’s referrer. Otherwise:
   1. If environment is a document environment:
      1. Let document be the Document object of the active document of the browsing context of environment’s global object.
   2. Otherwise, environment is a worker environment:
      1. Let source be the API referrer source specified by the entry settings object.
      2. If source is a URL, let referrerSource be source, otherwise let document be source.
   3. If document is set, execute the following steps:
      1. If document’s origin is not a scheme/host/port tuple (because, for example, it has been sandboxed into a unique origin), return none and abort these steps.
      2. While document corresponds to an iframe srcdoc Document, let document be that Document’s browsing context’s browsing context container’s Document.
      3. Let referrerSource be document’s URL.
4. Let referrerURL be the result of stripping referrerSource for use as a referrer.
5. Let referrerOrigin be the result of stripping referrerSource for use as a referrer, with the origin-only flag set to true.
6. Execute the statements corresponding to the value of policy:

   policy is None

   Return none

   policy is Origin

   Return referrerOrigin

   policy is Unsafe URL

   Return referrerURL.

   policy is Origin When Cross-Origin

   1. If request is a cross-origin request, then return referrerOrigin.
   2. Otherwise, return referrerURL.

   policy is None When Downgrade

   policy is null

   1. If environment is TLS-protected and the origin of request’s URL is an a priori insecure origin, then return none.
   2. Otherwise, return requestURL.

Note: Nothing here should be interpreted as preventing user agents from offering options to users which would reduce the information sent out via a `Referer` header. For instance, user agents MAY allow users to suppress the referrer header entirely, regardless of the referrer policy.

6.3 Strip url for use as a referrer.

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

1. If url is null, return none.
2. If url’s scheme is not a relative scheme, then return none.
3. Set url’s username to the empty string.
4. Set url’s password to null.
5. Set url’s fragment to null.
6. If the origin-only flag is true, then:
   1. Set url’s path to null.
   2. Set url’s query to null.
7. Return url.

7 Acknowledgements

This specification is based in large part on Adam Barth and Jochen Eisinger’s Meta referrer document.