add docs and backward incompatibility notices for #2501

3 files changed, 35 insertions, 2 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 0cd2c0c9a..d316594bc 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -15,6 +15,10 @@ Backward Incompatibilities
 
   See https://github.com/Pylons/pyramid/pull/2496
 
+- The ``check_csrf_token`` function no longer validates a csrf token in the
+  query string of a request. Only headers and request bodies are supported.
+  See https://github.com/Pylons/pyramid/pull/2500
+
 Features
 --------
 
@@ -44,14 +48,18 @@ Features
   Additional allowed origins may be configured by setting
   ``pyramid.csrf_trusted_origins`` to a list of domain names (with ports if on
   a non standard port) to allow. Subdomains are not allowed unless the domain
-  name has been prefixed with a ``.``. See:
+  name has been prefixed with a ``.``. See
   https://github.com/Pylons/pyramid/pull/2501
 
+- Added a new ``pyramid.session.check_csrf_origin`` API for validating the
+  origin or referrer headers against the request's domain.
+  See https://github.com/Pylons/pyramid/pull/2501
+
 - Pyramid HTTPExceptions will now take into account the best match for the
   clients Accept header, and depending on what is requested will return
   text/html, application/json or text/plain. The default for */* is still
   text/html, but if application/json is explicitly mentioned it will now
-  receive a valid JSON response. See:
+  receive a valid JSON response. See
   https://github.com/Pylons/pyramid/pull/2489
 
 - A new event and interface (BeforeTraversal) has been introduced that will
diff --git a/docs/whatsnew-1.7.rst b/docs/whatsnew-1.7.rst
index a6d49673c..fd144a24a 100644
--- a/docs/whatsnew-1.7.rst
+++ b/docs/whatsnew-1.7.rst
@@ -28,6 +28,10 @@ Backwards Incompatibilities
   https://github.com/Pylons/pyramid/issues/2368 and
   https://github.com/Pylons/pyramid/pull/2256
 
+- The :func:`pyramid.session.check_csrf_token` function no longer validates a
+  csrf token in the query string of a request. Only headers and request bodies
+  are supported. See https://github.com/Pylons/pyramid/pull/2500
+
 Feature Additions
 -----------------
 
@@ -56,6 +60,22 @@ Feature Additions
   https://github.com/Pylons/pyramid/pull/2413 and
   https://github.com/Pylons/pyramid/pull/2500
 
+- Added an additional CSRF validation that checks the origin/referrer of a
+  request and makes sure it matches the current ``request.domain``. This
+  particular check is only active when accessing a site over HTTPS as otherwise
+  browsers don't always send the required information. If this additional CSRF
+  validation fails a ``BadCSRFOrigin`` exception will be raised and may be
+  caught by exception views (the default response is ``400 Bad Request``).
+  Additional allowed origins may be configured by setting
+  ``pyramid.csrf_trusted_origins`` to a list of domain names (with ports if on
+  a non standard port) to allow. Subdomains are not allowed unless the domain
+  name has been prefixed with a ``.``. See
+  https://github.com/Pylons/pyramid/pull/2501
+
+- Added a new :func:`pyramid.session.check_csrf_origin` API for validating the
+  origin or referrer headers against the request's domain.
+  See https://github.com/Pylons/pyramid/pull/2501
+
 - Subclasses of :class:`pyramid.httpexceptions.HTTPException` will now take
   into account the best match for the clients ``Accept`` header, and depending
   on what is requested will return ``text/html``, ``application/json`` or
diff --git a/pyramid/session.py b/pyramid/session.py
index a88d8a71c..2cc303558 100644
--- a/pyramid/session.py
+++ b/pyramid/session.py
@@ -227,6 +227,11 @@ def check_csrf_token(request,
     application automatically against CSRF attacks.
 
     .. versionadded:: 1.4a2
+
+    .. versionchanged:: 1.7a1
+       A CSRF token passed in the query string of the request is no longer
+       considered valid. It must be passed in either the request body or
+       a header.
     """
     # If this is a POST/PUT/etc request, then we'll check the body to see if it
     # has a token. We explicitly use request.POST here because CSRF tokens