W3C

Referrer Policy

W3C Working Draft,

This version:
http://www.w3.org/TR/2016/WD-referrer-policy-20160601/
Latest version:
http://www.w3.org/TR/referrer-policy/
Editor's Draft:
http://w3c.github.io/webappsec-referrer-policy/
Previous Versions:
http://www.w3.org/TR/2014/WD-referrer-policy-20140807/
Version History:
https://github.com/w3c/webappsec-referrer-policy/commits/gh-pages
Feedback:
public-webappsec@w3.org with subject line “[REFERRER] … message topic …” (archives)
Issue Tracking:
GitHub
Editors:
(Google Inc.)
(Google Inc.)

Copyright © 2016 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 section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was published by the Web Application Security Working Group as a Working Draft. This document is intended to become a W3C Recommendation.

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

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

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 September 2015 W3C Process Document.

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]

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

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 modifies the algorithm used to populate the Referer header when fetching subresources, prefetching, or performing navigations. This document defines the various behaviors for each referrer policy.

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

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 Policies

Each possible referrer policy, besides the empty string, is explained below. A detailed algorithm for evaluating their effect is given in the §5 Integration with Fetch and §7 Algorithms sections.

Note: The referrer policy for an environment settings object provides a default baseline policy for requests when that environment settings object is used as a request client. 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 request client 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 environment settings object to a a priori authenticated URL, and requests from request clients which are not TLS-protected to any origin.

Requests from TLS-protected request clients to non-a priori authenticated URLs, 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 non-a priori authenticated URL.

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. "same-origin"

The "same-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 request client.

Cross-origin requests, 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 "same-origin", then navigations to 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 no Referer header.

3.4. "origin"

The "origin" policy specifies that only the ASCII serialization of the origin of the request client is sent as referrer information when making both same-origin requests and cross-origin requests from a particular request client.

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" 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", then navigations to any origin would send a Referer header with a value of https://example.com/, even to URLs that are not a priori authenticated URLs.

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

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 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 URLs that are not a priori authenticated URLs.

3.6. "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 request client.

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.

3.7. The empty string

The empty string "" corresponds to no referrer policy, causing a fallback to a referrer policy defined elsewhere, or in the case where no such higher-level policy is available, defaulting to "no-referrer-when-downgrade". This defaulting happens in the §7.3 Determine request’s Referrer algorithm.

Given a HTML a element without any declared referrerpolicy attribute, its referrer policy is "". Thus, navigation requests initiated by clicking on that a element will be sent with the referrer policy of the a element’s node document. If that Document has "" as its referrer policy, the §7.3 Determine request’s Referrer algorithm will treat "" the same as "no-referrer-when-downgrade".

4. Referrer Policy Delivery

A request’s referrer policy is delivered in one of five ways:

4.1. Delivery via Referrer-Policy header

The Referrer-Policy HTTP header 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 header are described by the following ABNF grammar:

"Referrer-Policy:" 1#policy-token

policy-token   = "no-referrer" / "no-referrer-when-downgrade" / "same-origin" / "origin" / "origin-when-cross-origin" / "unsafe-url"

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

§5 Integration with Fetch and §6 Integration with HTML describe how the Referrer-Policy header is processed.

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 Referrer-Policy header:

Referrer-Policy: 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

This section is not normative.

The HTML Standard defines the referrer keyword for the meta element, which allows setting the referrer policy via markup.

4.3. Delivery via a referrerpolicy content attribute

This section is not normative.

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

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

4.4. Nested browsing contexts

This section is not normative.

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

5. Integration with Fetch

This section is not normative.

The Fetch specification calls out to §7.2 Set request’s referrer policy on redirect immediately before Step 15 of the HTTP-redirect fetch.

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

6. Integration with HTML

This section is not normative.

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

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 referrerpolicy content attributes, or referrerPolicy IDL attributes, or the referrer keyword for meta, or the integration with navigation or running a worker. For this spec to make sense with W3C HTML5, those would need to be copied from [HTML].

7. Algorithms

7.1. Parse a referrer policy from a Referrer-Policy header

Given a Response response, the following steps return a referrer policy according to response’s `Referrer-Policy` header:

  1. Let policy-tokens be the result of parsing `Referrer-Policy` in response’s header list.
  2. Let policy be the empty string.
  3. For each token in policy-tokens, execute §7.5 Determine token’s Policy on token and set policy to the result if it is not the empty string.
  4. Return policy.

7.2. Set request’s referrer policy on redirect

Given a request request and a response actualResponse, this algorithm updates request’s associated referrer policy according to the Referrer-Policy header (if any) in actualResponse.

  1. Let policy be the result of executing §7.1 Parse a referrer policy from a Referrer-Policy header on actualResponse.
  2. If policy is not the empty string, then set request’s associated referrer policy to policy.

7.3. Determine request’s Referrer

Given a Request request, we can determine the correct referrer information to send by examining the referrer policy associated with it, 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.

  1. Let policy be request’s associated referrer policy.
  2. Let environment be request’s client.
  3. If request’s referrer is a URL, then let referrerSource be request’s referrer. Otherwise:
    1. If environment’s global object is a Window object:
      1. Let document be the Document object of the active document of the browsing context of environment’s responsible browsing context.
    2. Otherwise, environment’s global object is a WorkerGlobalScope:
      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 an opaque origin (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:
    "no-referrer"
    Return no referrer
    "origin"
    Return referrerOrigin
    "unsafe-url"
    Return referrerURL.
    "same-origin"
    1. If request is a same-origin request, then return referrerURL.
    2. Otherwise, return no referrer.
    "origin-when-cross-origin"
    1. If request is a cross-origin request, then return referrerOrigin.
    2. Otherwise, return referrerURL.
    "no-referrer-when-downgrade"
    the empty string
    1. If environment is not null:
      1. If environment is TLS-protected and the origin of request’s current URL is not an a priori authenticated URL, then return no referrer.
    2. Return referrerURL.

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

7.5. Determine token’s Policy

Given a string token (for example, the value of a Referrer-Policy header), 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 ASCII case-insensitive match for the string "default" or "no-referrer-when-downgrade", return "no-referrer-when-downgrade".
  3. If token is an ASCII case-insensitive match for the string "origin", return "origin".
  4. If token is an ASCII case-insensitive match for the string "same-origin", return "same-origin".
  5. If token is ASCII case-insensitive match for the string "origin-when-cross-origin", return "origin-when-cross-origin".
  6. If token is ASCII case-insensitive match for the strings "always" or "unsafe-url", return "unsafe-url".
  7. If token is empty, return "no-referrer".
  8. Return the empty string.

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.

8. Privacy Considerations

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

9. Security Considerations

9.1. Information Leakage

The referrer policies "origin" and "unsafe-url" 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.

9.2. Downgrade to less strict policies

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

On the one hand, it is not clear which policy is more strict for all possible pairs of policies: While "no-referrer-when-downgrade" will not leak any information over insecure transport, and "origin" 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 §10.1 Unknown Policy Values.

10. Authoring Considerations

10.1. Unknown Policy Values

As described in §7.5 Determine token’s 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.

Suppose older user agents don’t understand the "unsafe-url" policy. A site can specify an "origin" policy followed by an "unsafe-url" policy: older user agents will ignore the unknown "unsafe-url" value and use "origin", while newer user agents will use "unsafe-url" because it is the last to be processed.

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

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[FETCH]
Anne van Kesteren. Fetch. Living Standard. URL: http://fetch.spec.whatwg.org/
[HTML]
Ian Hickson. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[MIX]
Mike West. Mixed Content. ED. URL: https://w3c.github.io/webappsec-mixed-content/
[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
[DOM-LS]
Document Object Model URL: https://dom.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[URL]
Anne van Kesteren; Sam Ruby. URL. 9 December 2014. WD. URL: http://www.w3.org/TR/url-1/
[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

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