Improving the Web Platform’s Referrer Policy

Overview of the Proposal

Let’s improve the way browsers handle the HTTP Referer header:

Old Policy New Policy
Subresources & Navigation Subresources Navigation
Same-origin Entire URL Entire URL Entire URL
Cross-origin Mixed Content None None None
HTTPS→HTTPS Entire URL Origin None (originreferrer can be used to opt into sending the origin.)
Other Entire URL Origin None

Motivation

See Facebook’s “Protecting Privacy with Referrers” note and DropBox’s “Web vulnerability affecting shared links” blog post for real-world large-scale motivating examples of the need to prevent leaking sensitive information in the Referer header, and the difficulty of doing so. The primary goal of this proposal is to provide such protection by default in a way that minimizes breakage to existing web pages. Improved performance (including better interaction with prefetching), additional intra-origin protection for capability URLs, the removal of disincentives to HTTPS adoption, and the ability for websites to opt into more comprehensive privacy protection are secondary goals of this proposal.

Design Constraints

Additional Design Considerations

The author of this document considers the Referer header field to be a well-intended experiment that has become a misfeature, time sink, and footgun. There are a lot of more interesting things to build than referrer controls, and there are other channels (e.g. sendBeacon and postMessage) to explicitly share information across domains. Accordingly, this proposal focuses on minimizing the risks caused by the Referer header, rather than adding elaborate mechanisms to elevate the Referer header into a first-class feature of the web platform.

The noreferrer link relation is currently defined in the HTML specification. For maximum consistency, let’s change the HTML specification to define it as equivalent to a CSP policy of navigation-referrer 'none' that applies just to the link that has the relation.

The originreferrer link relation applies a CSP policy of navigation-referrer 'origin' to the link. Additionally, for HTTPS→HTTPS navigations only, the originreferrer link relation changes the default referrer policy for the link from 'none' to 'origin'. This is the only circumstance where the page can expand the amount of information leaked from the default. Note that a CSP policy of navigation-referrer 'none' overrides originreferrer.

The navigation-referrer and subresource-referrer CSP directives

The navigation-referrer CSP directive restricts the value of the Referer request header field in navigation requests (TODO: precisely define “navigation request”). The subresource-referrer CSP directive restricts the value of the Referer request header field in subresource requests (TODO: precisely define “subresource request”). Both directives share the same syntactic structure: 

directive-value = "'none'" | "'origin'"

The value 'none' means that the Referer header field MUST NOT be sent in the request. The value 'origin' means that any URL in the Referer header field MUST be truncated to the first / in the path. To get the default behavior, omit the directive.

These directives apply to prefetches and/or fetches done for resources linked to with the Link HTTP header field, but only when the policy is specified in the Content-Security-Policy HTTP header field. Browsers SHOULD warn when these directives are used in a CSP policy specified using <meta http-equiv=Content-Security-Policy> when the document has any Link HTTP response header fields or when there are any <link> elements preceding the policy, since the policy will not affect fetches for the linked-to resources. (TODO: This should happen for any CSP policy, not just ones containing these directives.)

Note that these directives are defined as truncations of the values calculated using the HTML “Determine request’s Referrer” algorithm so no value of these directives will increase the amount of information included in the Referer header field. Also note that when there are multiple CSP policies with these directives, all of the policies are applied, just as is the case for all other CSP directives (TODO: except reflected-xss). Thus, the value 'none' in one policy overrides the value 'origin' in another policy, and the value 'origin' overrides the default value.

TODO: Define forward compatibility stuff.

Some pages already try to limit information leakage via the Referer header field. See the StackOverflow discussion “How can I detect rel=‘noreferrer’ support?” and Facebook’s “Protecting Privacy with Referrers” note to see how pages are detecting browsers’ support for the noreferrer link relation. These techniques are tedious, error-prone, and (TODO: probably) expensive. To improve this, we define a new dictionary: 

window.navigator.linkRelations = {
    noreferrer: 1,
    originreferrer: 1
};

A non-zero value indicates support for the given link relation. Future revisions to this document may define additional semantics for these link relations, and the intent is to increment the value each time additional semantics are added.

These would be used like so: 

<script type="text/javascript">
    if (!window.navigator.linkRelations.originreferrer) {
        window.onclick = function(e) {
           [simulate originreferrer using data: and <meta refresh>]
        }
    }
</script>

TODO: Define feature detection for the CSP directives. It is unclear whether this should be done as part of CSP or as part of this document.

Prefetching and Prerendering

Browsers that don't have support for referrer control MUST NOT do prefetching or prerendering for navigations unless specifically requested by the page, because they cannot account for any polyfills for noreferrer or originreferrer.

Capability URLS

Resources addressed using capability URLs should use the navigation-referrer and subresource-referrer CSP directives to ensure that the secrets in the URLs are removed from the Referer header value even in same-origin requests. Either 'none' or 'origin' may be used for this purpose.

Deprecating <meta name=referrer>

The <meta name=referrer> mechanism was part of an earlier proposal for controlling the Referer header field. The model for <meta name=referrer> did not differentiate between subresource requests and navigation requests and was based on the premise that browsers would, by default, leak the entire referrer URL in requests. Also, <meta name=referrer> does not interact well with prefetching or other uses of the Link HTTP header. With the new default behaviors and new mechanisms defined in this document, the <meta name=referrer> mechanism is no longer needed. Browsers SHOULD print a warning in the console when <meta name=referrer> is encountered and MUST otherwise ignore it.

Comparison to the W3C WebAppSec Draft Referrer Policy

Let’s compare how this proposal compares to the W3C WebAppSec Draft Referrer Policy as of 2014-08-07 with respect to the design constraints mentioned above, where there are significant differences in how the constraint is addressed.

HTML Design Principle 2.1: Support Existing Content
The WebAppSec draft referrer policy likely has an edge in terms of compatibility because it does not attempt to change the default behavior of browsers. This proposal does consider compatibility to be a top concern, and serious effort has been put into minimizing any negative compatibility impact. It will not be clear how much compatibility will be affected by this document’s proposed policy until experiments are done.
HTML Design Principle 2.2: Degrade Gracefully
The current proposal seems better because it defines an easy-to-use feature detection mechanism that allows web pages to degrade gracefully to handle browsers that do not support it. The current WebAppSec draft does not specify such a mechanism. TODO: The current document does not specify feature detection for the CSP features.
HTML Design Principle 3.2: Priority of Constituencies
The most controversial difference between this proposal and the current W3C WebAppSec draft is that this proposal omits the 'unsafe-url' mechanism in the WebAppSec draft. Omitting the 'unsafe-url' mechanism is more in line with the Priority of Constituencies. End users generally do not understand how websites share information about their browsing through the Referer header field. Also, the few users that have something to say about the Referer header field generally want to minimize the information shared through it.
HTML Design Principle 3.3: Secure by Design

This proposal’s better default policy means that most web pages will not have to use explicit referrer control mechanisms at all to avoid leaking sensitive information in Referer headers; that is, this proposal is secure by default. In contrast, the current WebAppSec draft requires all web pages to add markup to get equivalent protection; that is, it is not secure by default.

The WebAppSec draft allows all the protections to be disabled, even for mixed content (using unsafe-url or always). This proposal works in conjunction with browsers’ mixed content blocking policies to prevent leaking information from secure origins to non-secure origins through the Referer header field.

This proposal integrates with CSP in a more secure way, because its CSP directives cannot be overridden by content within the page (consistently with all other CSP directives, except the proposed refected-xss), so a site’s system administrator can easily specify site-wide protection against leaking secrets through the Referer header field. In contrast, the current WebAppSec draft does not allow this, because its CSP directive can be overridden within the page.

HTML Design Principle 4.1: Well-defined Behavior
The WebAppSec draft is currently more precisely specified. This draft of this proposal is intended more as an introduction to the new policy instead of a complete specification. The changes to HTML algorithms are the same as the ones specified in the WebAppSec draft, for the intersection of features in the two proposals.
HTML Design Principle 4.2: Avoid Needless Complexity
This proposal’s better default referrer handling simplifies all other aspects of referrer handling. For example, this proposal’s CSP directives requires fewer options than the draft WebAppSec referrer CSP directive. Also, the way that referrer control mechanisms interact are more consistent with existing CSP and HTML mechanisms, compared to the the WebAppSec draft. This proposal also avoids all the redundancy and complexity of the <meta name=referrer> mechanism.
HTTP specification RFC 7320 Section 5.5
This proposal is compatible with the HTTP specification’s requirement that “A user agent MUST NOT send a Referer header field in an unsecured HTTP request if the referring page was received with a secure protocol.“ The draft WebAppSec mechanism specifies mechanisms to violate this requirement.
Removing Disincentives to HTTPS Adoption

Currently, a website can get credit for being the referrer of an HTTP→HTTP navigation, but a website cannot get credit for being the referrer of an HTTPS→HTTP navigation. This has lead some major websites that typically act as the referring site to avoid completely adopting HTTPS. On the other hand, some websites that are usually the referred-to website have recognized that switching to HTTPS will make the Referer header work better for them; see the New York Times’s “Embracing HTTPS” blog post for an example of this.

The WebAppSec draft attempts to improve this by allowing HTTPS pages to opt into leaking the referring origin or the full referring URL in HTTPS→HTTP navigations. That removes the disincentive for the referring website to adopt HTTPS, but it does not provide any incentive for the referred-to website to adopt HTTP. In fact, the availability of such options is a disincentive for the referred-to website to adopt HTTPS.

This proposal attempts to eliminate any Referer-related disincentive to adopting HTTPS by never sending a Referer header field in any navigation from or to a non-secure origin, and by allowing the referring page to opt into sending its origin (only) in the Referer header for HTTPS→HTTPS navigations only. Thus, both the referring site and the referred-to site are actively discouraged from using non-secure origins, and both are actively encouraged to use HTTPS origins.

Hotlink Prevention
This proposal allows the referring page to omit referrer information in all navigation requests, while still allowing the site to send its origin in subresource requests so that hotlink protection works as well as it has historically. In fact, this is the default behavior. The current WebAppSec draft does not offer this flexibility.

Additional References

The definition of the Referer header field in the 1992 edition of the HTTP specification.
The earliest reference (1992/1994) to the Referer header field the author of this proposal could find.
Mozilla’s Shortened HTTP Referer Project
The outline of Mozilla’s project to reduce the amount of information leaked in the Referer header.
Shortened HTTP Referer Header Project Email Thread
A discussion about Mozilla’s Shortened HTTP Referer Project, which formed the basis for this document.