Merge remote-tracking branch 'upstream/master'

2 files changed, 25 insertions, 13 deletions

diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index d66e86258..7cf96ac7d 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -391,8 +391,8 @@ will return ``True``, otherwise it will raise ``HTTPBadRequest``. Optionally,
 you can specify ``raises=False`` to have the check return ``False`` instead of
 raising an exception.
 
-By default, it checks for a GET or POST parameter named ``csrf_token`` or a
-header named ``X-CSRF-Token``.
+By default, it checks for a POST parameter named ``csrf_token`` or a header
+named ``X-CSRF-Token``.
 
 .. code-block:: python
 
@@ -411,15 +411,16 @@ Checking CSRF Tokens Automatically
 
 .. versionadded:: 1.7
 
-:app:`Pyramid` supports automatically checking CSRF tokens on POST requests.
-Any other request may be checked manually. This feature can be turned on
-globally for an application using the ``pyramid.require_default_csrf`` setting.
+:app:`Pyramid` supports automatically checking CSRF tokens on requests with an
+unsafe method as defined by RFC2616. Any other request may be checked manually.
+This feature can be turned on globally for an application using the
+``pyramid.require_default_csrf`` setting.
 
 If the ``pyramid.required_default_csrf`` setting is a :term:`truthy string` or
 ``True`` then the default CSRF token parameter will be ``csrf_token``. If a
 different token is desired, it may be passed as the value. Finally, a
 :term:`falsey string` or ``False`` will turn off automatic CSRF checking
-globally on every POST request.
+globally on every request.
 
 No matter what, CSRF checking may be explicitly enabled or disabled on a
 per-view basis using the ``require_csrf`` view option. This option is of the
@@ -430,13 +431,20 @@ If ``require_csrf`` is ``True`` but does not explicitly define a token to
 check, then the token name is pulled from whatever was set in the
 ``pyramid.require_default_csrf`` setting. Finally, if that setting does not
 explicitly define a token, then ``csrf_token`` is the token required. This token
-name will be required in ``request.params`` which is a combination of the
-query string and a submitted form body.
+name will be required in ``request.POST`` which is the submitted form body.
 
 It is always possible to pass the token in the ``X-CSRF-Token`` header as well.
 There is currently no way to define an alternate name for this header without
 performing CSRF checking manually.
 
+In addition to token based CSRF checks, the automatic CSRF checking will also
+check the referrer of the request to ensure that it matches one of the trusted
+origins. By default the only trusted origin is the current host, however
+additional origins may be configured by setting
+``pyramid.csrf_trusted_origins`` to a list of domain names (and ports if they
+are non standard). If a host in the list of domains starts with a ``.`` then
+that will allow all subdomains as well as the domain without the ``.``.
+
 If CSRF checks fail then a :class:`pyramid.exceptions.BadCSRFToken` exception
 will be raised. This exception may be caught and handled by an
 :term:`exception view` but, by default, will result in a ``400 Bad Request``
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index e645185f5..cd5b8feb0 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -195,10 +195,11 @@ Non-Predicate Arguments
 
 ``require_csrf``
 
-  CSRF checks only affect POST requests. Any other request methods will pass
-  untouched. This option is used in combination with the
-  ``pyramid.require_default_csrf`` setting to control which request parameters
-  are checked for CSRF tokens.
+  CSRF checks will affect any request method that is not defined as a "safe"
+  method by RFC2616. In pratice this means that GET, HEAD, OPTIONS, and TRACE
+  methods will pass untouched and all others methods will require CSRF. This
+  option is used in combination with the ``pyramid.require_default_csrf``
+  setting to control which request parameters are checked for CSRF tokens.
 
   This feature requires a configured :term:`session factory`.
 
@@ -214,6 +215,9 @@ Non-Predicate Arguments
   If this option is set to ``False`` then CSRF checks will be disabled
   regardless of the ``pyramid.require_default_csrf`` setting.
 
+  In addition, if this option is set to ``True`` or a string then CSRF origin
+  checking will be enabled.
+
   See :ref:`auto_csrf_checking` for more information.
 
   .. versionadded:: 1.7
@@ -459,7 +463,7 @@ configured view.
   check name.
 
   If CSRF checking is performed, the checked value will be the value of
-  ``request.params[check_name]``.  This value will be compared against the
+  ``request.POST[check_name]``.  This value will be compared against the
   value of ``request.session.get_csrf_token()``, and the check will pass if
   these two values are the same.  If the check passes, the associated view will
   be permitted to execute.  If the check fails, the associated view will not be