From 406dba04e1482a308cad74e3d06c050c76ba2d16 Mon Sep 17 00:00:00 2001 From: Nick Pope Date: Thu, 21 Mar 2019 21:33:41 +0000 Subject: Fixed #29406 -- Added support for Referrer-Policy header. Thanks to James Bennett for the initial implementation. --- docs/ref/checks.txt | 8 +++- docs/ref/middleware.txt | 99 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/ref/settings.txt | 14 +++++++ 3 files changed, 120 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/checks.txt b/docs/ref/checks.txt index f147d9dc0b..1289ffe1ab 100644 --- a/docs/ref/checks.txt +++ b/docs/ref/checks.txt @@ -342,7 +342,8 @@ The following checks are run if you use the :option:`check --deploy` option: :class:`django.middleware.security.SecurityMiddleware` in your :setting:`MIDDLEWARE` so the :setting:`SECURE_HSTS_SECONDS`, :setting:`SECURE_CONTENT_TYPE_NOSNIFF`, :setting:`SECURE_BROWSER_XSS_FILTER`, - and :setting:`SECURE_SSL_REDIRECT` settings will have no effect. + :setting:`SECURE_REFERRER_POLICY`, and :setting:`SECURE_SSL_REDIRECT` + settings will have no effect. * **security.W002**: You do not have :class:`django.middleware.clickjacking.XFrameOptionsMiddleware` in your :setting:`MIDDLEWARE`, so your pages will not be served with an @@ -428,6 +429,11 @@ The following checks are run if you use the :option:`check --deploy` option: * **security.W021**: You have not set the :setting:`SECURE_HSTS_PRELOAD` setting to ``True``. Without this, your site cannot be submitted to the browser preload list. +* **security.W022**: You have not set the :setting:`SECURE_REFERRER_POLICY` + setting. Without this, your site will not send a Referrer-Policy header. You + should consider enabling this header to protect user privacy. +* **security.E023**: You have set the :setting:`SECURE_REFERRER_POLICY` setting + to an invalid value. Signals ------- diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index db70a7c14d..04b598625e 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -186,6 +186,7 @@ enabled or disabled with a setting. * :setting:`SECURE_HSTS_PRELOAD` * :setting:`SECURE_HSTS_SECONDS` * :setting:`SECURE_REDIRECT_EXEMPT` +* :setting:`SECURE_REFERRER_POLICY` * :setting:`SECURE_SSL_HOST` * :setting:`SECURE_SSL_REDIRECT` @@ -241,6 +242,104 @@ If you wish to submit your site to the `browser preload list`_, set the __ https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security .. _browser preload list: https://hstspreload.org/ +.. _referrer-policy: + +Referrer Policy +~~~~~~~~~~~~~~~ + +.. versionadded:: 3.0 + +Browsers use `the Referer header`__ as a way to send information to a site +about how users got there. When a user clicks a link, the browser will send the +full URL of the linking page as the referrer. While this can be useful for some +purposes -- like figuring out who's linking to your site -- it also can cause +privacy concerns by informing one site that a user was visiting another site. + +__ https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer + +Some browsers have the ability to accept hints about whether they should send +the HTTP ``Referer`` header when a user clicks a link; this hint is provided +via `the Referrer-Policy header`__. This header can suggest any of three +behaviors to browsers: + +__ https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy + +* Full URL: send the entire URL in the ``Referer`` header. For example, if the + user is visiting ``https://example.com/page.html``, the ``Referer`` header + would contain ``"https://example.com/page.html"``. + +* Origin only: send only the "origin" in the referrer. The origin consists of + the scheme, host and (optionally) port number. For example, if the user is + visiting ``https://example.com/page.html``, the origin would be + ``https://example.com/``. + +* No referrer: do not send a ``Referer`` header at all. + +There are two types of conditions this header can tell a browser to watch out +for: + +* Same-origin versus cross-origin: a link from ``https://example.com/1.html`` + to ``https://example.com/2.html`` is same-origin. A link from + ``https://example.com/page.html`` to ``https://not.example.com/page.html`` is + cross-origin. + +* Protocol downgrade: a downgrade occurs if the page containing the link is + served via HTTPS, but the page being linked to is not served via HTTPS. + +.. warning:: + When your site is served via HTTPS, :ref:`Django's CSRF protection system + ` requires the ``Referer`` header to be present, so completely + disabling the ``Referer`` header will interfere with CSRF protection. To + gain most of the benefits of disabling ``Referer`` headers while also + keeping CSRF protection, consider enabling only same-origin referrers. + +``SecurityMiddleware`` can set the ``Referrer-Policy`` header for you, based on +the the :setting:`SECURE_REFERRER_POLICY` setting (note spelling: browsers send +a ``Referer`` header when a user clicks a link, but the header instructing a +browser whether to do so is spelled ``Referrer-Policy``). The valid values for +this setting are: + +``no-referrer`` + Instructs the browser to send no referrer for links clicked on this site. + +``no-referrer-when-downgrade`` + Instructs the browser to send a full URL as the referrer, but only when no + protocol downgrade occurs. + +``origin`` + Instructs the browser to send only the origin, not the full URL, as the + referrer. + +``origin-when-cross-origin`` + Instructs the browser to send the full URL as the referrer for same-origin + links, and only the origin for cross-origin links. + +``same-origin`` + Instructs the browser to send a full URL, but only for same-origin links. No + referrer will be sent for cross-origin links. + +``strict-origin`` + Instructs the browser to send only the origin, not the full URL, and to send + no referrer when a protocol downgrade occurs. + +``strict-origin-when-cross-origin`` + Instructs the browser to send the full URL when the link is same-origin and + no protocol downgrade occurs; send only the origin when the link is + cross-origin and no protocol downgrade occurs; and no referrer when a + protocol downgrade occurs. + +``unsafe-url`` + Instructs the browser to always send the full URL as the referrer. + +.. admonition:: Unknown Policy Values + + Where a policy value is `unknown`__ by a user agent, it is possible to + specify multiple policy values to provide a fallback. The last specified + value that is understood takes precedence. To support this, an iterable or + comma-separated string can be used with :setting:`SECURE_REFERRER_POLICY`. + + __ https://w3c.github.io/webappsec-referrer-policy/#unknown-policy-values + .. _x-content-type-options: ``X-Content-Type-Options: nosniff`` diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index aa9bc1ddb8..1ec8e9d94c 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -2319,6 +2319,19 @@ If a URL path matches a regular expression in this list, the request will not be redirected to HTTPS. If :setting:`SECURE_SSL_REDIRECT` is ``False``, this setting has no effect. +.. setting:: SECURE_REFERRER_POLICY + +``SECURE_REFERRER_POLICY`` +-------------------------- + +.. versionadded:: 3.0 + +Default: ``None`` + +If configured, the :class:`~django.middleware.security.SecurityMiddleware` sets +the :ref:`referrer-policy` header on all responses that do not already have it +to the value provided. + .. setting:: SECURE_SSL_HOST ``SECURE_SSL_HOST`` @@ -3500,6 +3513,7 @@ HTTP * :setting:`SECURE_HSTS_SECONDS` * :setting:`SECURE_PROXY_SSL_HEADER` * :setting:`SECURE_REDIRECT_EXEMPT` + * :setting:`SECURE_REFERRER_POLICY` * :setting:`SECURE_SSL_HOST` * :setting:`SECURE_SSL_REDIRECT` * :setting:`SIGNING_BACKEND` -- cgit v1.3