Referrer Policy

Editor’s Draft

This version:
https://w3c.github.io/webappsec/specs/referrer-policy/
Latest version:
http://www.w3.org/TR/referrer-policy/
Version History:
https://github.com/w3c/webappsec/commits/master/specs/referrer-policy/index.src.html
Feedback:
public-webappsec@w3.org with subject line “[REFERRER] … message topic …” (archives)
Issue Tracking:
Inline In Spec
Editors:
(Google Inc.)
(Google Inc.)

Copyright © 2015 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.

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 Referer HTTP header for outgoing requests and navigations.

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

Changes to this document may be tracked at https://github.com/w3c/webappsec.

The (archived) public mailing list public-webappsec@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “REFERRER” in the subject, preferably like this: “[REFERRER] …summary of comment…”

This document was produced by the Web Application Security Working Group.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 August 2014 W3C Process Document.

Table of Contents

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

referrer policy
A referrer policy is a property of a settings object 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 settings object, 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.

same-origin request
A Request request is a same-origin request if request’s origin and the origin of request’s url are the same.
cross-origin request
A Request is a cross-origin request if it is not same-origin.

3. Referrer Policy States

Every settings object 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: No Referrer, No Referrer 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 settings object provides a default baseline policy for requests. This policy may be tightened for specific requests via mechanisms like the noreferrer link type.

3.1. No Referrer

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

If a document at https://example.com/page.html sets a policy of No Referrer, then navigations to https://example.com/ (or any other URL) would send no Referer header.

3.2. No Referrer When Downgrade

The No Referrer When Downgrade policy sends a full URL along with requests from TLS-protected settings object to a non-a priori insecure origin, and requests from settings objects which are not TLS-protected to any origin.

Requests from TLS-protected settings objects to a priori insecure origins, on the other hand, will contain no referrer information. A Referer HTTP header will not be sent.

If a document at https://example.com/page.html sets a policy of No Referrer When Downgrade, then navigations to https://not.example.com/ would send a Referer HTTP header with a value of https://example.com/page.html, as neither resource’s origin is an a priori insecure origin.

Navigations from that same page to http://not.example.com/ would send no Referer header.

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 settings object from which a request is made is sent as referrer information when making both same-origin requests and cross-origin requests from a particular settings object.

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

Note: The Origin Only policy causes the origin of HTTPS referrers to be sent over the network as part of unencrypted HTTP requests.

If a document at https://example.com/page.html sets a policy of Origin Only, then navigations to any origin would send a Referer header with a value of https://example.com/, even to a priori insecure origins.

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 settings object, and only the ASCII serialization of the origin of the settings object from which a request is made is sent as referrer information when making cross-origin requests from a particular settings object.

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

Note: The Origin When Cross-Origin policy causes the origin of HTTPS referrers to be sent over the network as part of unencrypted HTTP requests.

If a document at https://example.com/page.html sets a policy of Origin When Cross-Origin, then navigations to any https://example.com/not-page.html would send a Referer header with a value of https://example.com/page.html.

Navigations from that same page to https://not.example.com/ would send a Referer header with a value of https://example.com/, even to a priori insecure origins.

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

If a document at https://example.com/sekrit.html sets a policy of Unsafe URL, then navigations to http://not.example.com/ (and every other origin) would send a Referer HTTP header with a value of https://example.com/sekrit.html.

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 settings object’s referrer policy is delivered in one of four ways:

4.1. Delivery via CSP

The referrer directive specifies the referrer policy that the user agent applies when determining what referrer information should be included with requests made, and with browsing contexts created from the context of the protected resource. The syntax for the name and value of the directive are described by the following ABNF grammar:

directive-name    = "referrer"
directive-value   = "no-referrer" / "no-referrer-when-downgrade" / "origin" / "origin-when-cross-origin" / "unsafe-url"

Note: The directive name does not share the HTTP header’s misspelling.

When enforcing the referrer directive, the user agent MUST execute §6.1 Set environment’s referrer policy to policy on the protected resource’s incumbent settings object, using the result of executing §6.4 Determine token’s Policy on the referrer directive’s value.

4.1.1. Usage

This section is not normative.

A protected resource can prevent referrer leakage by specifying no-referrer as the value of its policy’s referrer directive:

Content-Security-Policy: referrer no-referrer;

This will cause all requests made from the protected resource’s context to have an empty Referer [sic] header.

4.2. Delivery via meta

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

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

The following values for the content attribute are valid, and map to the listed referrer policy values:

no-referrer
No Referrer
origin
Origin
no-referrer-when-downgrade
No Referrer When Downgrade
origin-when-cross-origin
Origin When Cross-Origin
unsafe-url
Unsafe URL

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 then abort these steps.
  3. Let environment be the Document's incumbent settings object.
  4. Let meta-value be the value of the element’s content attribute, after stripping leading and trailing whitespace.
  5. If meta-value is the empty string, then abort these steps.
  6. Let policy be the result of executing the §6.4 Determine token’s Policy algorithm on meta-value.
  7. 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 no-referrer, no-referrer-when-downgrade, and unsafe-url respectively are preferred.

Note: Implementors are advised to also respect a referrer policy delivered via a meta element during speculative resource loads.

4.3. Delivery via a referrer attribute

A referrer policy may be set when a referrer attribute is added to an a, area, img or iframe element, for example:

<a href="http://example.com" referrer="origin">

The following values for the referrer attribute are valid, and map to the listed referrer policy values:

no-referrer
No Referrer
origin
Origin
unsafe-url
Unsafe URL

A policy delivered via a referrer attribute on an element takes precedence over the policy defined for the whole document via CSP or a meta element.

If an a or area element includes both a referrer attribute as well as a noreferrer link type, should the policy of the referrer attribute take precedence over the link type, as suggested by Martin Thomson, or should we take the more conservative approach as suggested by Brian Smith and honor the noreferrer link type?

4.4. Implicit Delivery

A settings object inherits the referrer policy of another object in several circumstances:

4.4.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 a local scheme (for instance, a blob or data resource):

  1. Let environment be the nested browsing context’s incumbent settings object.
  2. Let policy be the parent browsing context’s incumbent settings object’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.4.2. Workers

Whenever a user agent runs a worker for a script with URL url and url’s scheme is a local scheme:

  1. Let environment be the Worker’s incumbent settings object.
  2. Let policy be No Referrer 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 settings object, then setting its value is straightforward. If a policy has previously been set, then we overwrite it with the new value.

  1. If policy is not one of No Referrer, No Referrer When Downgrade, Origin Only, Origin when cross-origin, or Unsafe URL, then return without setting environment’s referrer policy.
  2. Set environment’s referrer policy to policy.

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, as detailed in the following steps, which return either no referrer or a URL:

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

This algorithm needs to be modifed to take into account any local overrides via the referrer attribute on elements.

  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 responsible browsing context.
    2. Otherwise, environment is a worker environment:
      1. Let source be the API referrer source specified by the incumbent 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 no referrer 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 No Referrer
    Return no referrer
    policy is Origin Only
    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 No Referrer 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 no referrer.
    2. Otherwise, return requestURL.

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 no referrer.
  2. If url’s scheme is a local scheme, then return no referrer.
  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.

6.4. Determine token’s Policy

Given a string token (for example, the value of a referrer directive), this algorithm will return the referrer policy it refers to:

  1. If token is an ASCII case-insensitive match for the strings "never" or "no-referrer", return No Referrer.
  2. If token is an ASCII case-insensitive match for the string "origin", return Origin.
  3. If token is ASCII case-insensitive match for the string "default" or "no-referrer-when-downgrade", return No Referrer When Downgrade.
  4. If token is ASCII case-insensitive match for the string "origin-when-cross-origin", return Origin When Cross-Origin.
  5. If token is ASCII case-insensitive match for the strings "always" or "unsafe-url", return Unsafe URL.
  6. Return No Referrer.

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

7. Privacy Considerations

7.1. User Controls

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 `Referer` header. For instance, user agents MAY allow users to suppress the referrer header entirely, regardless of the active referrer policy on a page.

8. Acknowledgements

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

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words "for example" or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word "Note" and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

Conformance Classes

A conformant user agent must implement all the requirements listed in this specification that are applicable to user agents.

A conformant server must implement all the requirements listed in this specification that are applicable to servers.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSP2]
Mike West; Adam Barth; Dan Veditz. Content Security Policy Level 2. CR. URL: https://w3c.github.io/webappsec/specs/content-security-policy/
[FETCH]
Anne van Kesteren. Fetch. Living Standard. URL: https://fetch.spec.whatwg.org/
[MIX]
Mike West. Mixed Content. LCWD. URL: https://w3c.github.io/webappsec/specs/mixedcontent/
[RFC6454]
Adam Barth. The Web Origin Concept. RFC. URL: http://www.ietf.org/rfc/rfc6454.txt
[RFC7231]
Roy T. Fielding; Julian F. Reschke. HTTP/1.1 Semantics and Content. RFC. URL: http://www.ietf.org/rfc/rfc7231.txt
[URL]
Anne van Kesteren. URL. Living Standard. URL: https://url.spec.whatwg.org/
[DOM]
Anne van Kesteren; et al. W3C DOM4. 10 July 2014. LCWD. URL: http://www.w3.org/TR/dom/
[HTML5]
Robin Berjon; et al. HTML5. 28 October 2014. REC. URL: http://www.w3.org/TR/html5/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: http://www.ietf.org/rfc/rfc2119.txt
[WORKERS]
Ian Hickson. Web Workers. 1 May 2012. CR. URL: http://www.w3.org/TR/workers/
[WSC-UI]
Thomas Roessler; Anil Saldhana. Web Security Context: User Interface Guidelines. 12 August 2010. REC. URL: http://www.w3.org/TR/wsc-ui/

Informative References

[CAPABILITY-URLS]
Jenni Tennison. Capability URLs. WD. URL: http://www.w3.org/TR/capability-urls/

Issues Index

If an a or area element includes both a referrer attribute as well as a noreferrer link type, should the policy of the referrer attribute take precedence over the link type, as suggested by Martin Thomson, or should we take the more conservative approach as suggested by Brian Smith and honor the noreferrer link type? ↵
This algorithm needs to be modifed to take into account any local overrides via the referrer attribute on elements. ↵