Merge upstream master

1 files changed, 104 insertions, 39 deletions

diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index db554a93b..a1319e45f 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -260,19 +260,28 @@ added to the flash queue, and empties the queue.
 
 .. method:: pop_flash(queue='')
 
->>> request.session.flash('info message')
->>> request.session.pop_flash()
-['info message']
+.. testsetup::
+
+   from pyramid import testing
+   request = testing.DummyRequest()
+
+.. doctest::
+
+   >>> request.session.flash('info message')
+   >>> request.session.pop_flash()
+   ['info message']
 
 Calling ``session.pop_flash()`` again like above without a corresponding call
 to ``session.flash()`` will return an empty list, because the queue has already
 been popped.
 
->>> request.session.flash('info message')
->>> request.session.pop_flash()
-['info message']
->>> request.session.pop_flash()
-[]
+.. doctest::
+
+   >>> request.session.flash('info message')
+   >>> request.session.pop_flash()
+   ['info message']
+   >>> request.session.pop_flash()
+   []
 
 .. index::
    single: session.peek_flash
@@ -287,15 +296,17 @@ flash storage.
 
 .. method:: peek_flash(queue='')
 
->>> request.session.flash('info message')
->>> request.session.peek_flash()
-['info message']
->>> request.session.peek_flash()
-['info message']
->>> request.session.pop_flash()
-['info message']
->>> request.session.peek_flash()
-[]
+.. doctest::
+
+   >>> request.session.flash('info message')
+   >>> request.session.peek_flash()
+   ['info message']
+   >>> request.session.peek_flash()
+   ['info message']
+   >>> request.session.pop_flash()
+   ['info message']
+   >>> request.session.peek_flash()
+   []
 
 .. index::
    single: preventing cross-site request forgery attacks
@@ -305,7 +316,7 @@ Preventing Cross-Site Request Forgery Attacks
 ---------------------------------------------
 
 `Cross-site request forgery
-<http://en.wikipedia.org/wiki/Cross-site_request_forgery>`_ attacks are a
+<https://en.wikipedia.org/wiki/Cross-site_request_forgery>`_ attacks are a
 phenomenon whereby a user who is logged in to your website might inadvertantly
 load a URL because it is linked from, or embedded in, an attacker's website.
 If the URL is one that may modify or delete data, the consequences can be dire.
@@ -367,6 +378,21 @@ Or include it as a header in a jQuery AJAX request:
 The handler for the URL that receives the request should then require that the
 correct CSRF token is supplied.
 
+.. index::
+   single: session.new_csrf_token
+
+Using the ``session.new_csrf_token`` Method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To explicitly create a new CSRF token, use the ``session.new_csrf_token()``
+method.  This differs only from ``session.get_csrf_token()`` inasmuch as it
+clears any existing CSRF token, creates a new CSRF token, sets the token into
+the session, and returns the token.
+
+.. code-block:: python
+
+   token = request.session.new_csrf_token()
+
 Checking CSRF Tokens Manually
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -376,25 +402,76 @@ 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
 
-    from pyramid.session import check_csrf_token
+   from pyramid.session import check_csrf_token
 
-    def myview(request):
-        # Require CSRF Token
-        check_csrf_token(request)
+   def myview(request):
+       # Require CSRF Token
+       check_csrf_token(request)
 
-        # ...
+       # ...
 
-.. index::
-   single: session.new_csrf_token
+.. _auto_csrf_checking:
+
+Checking CSRF Tokens Automatically
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.7
+
+: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
+:meth:`pyramid.config.Configurator.set_default_csrf_options` directive.
+For example:
+
+.. code-block:: python
+
+   from pyramid.config import Configurator
+
+   config = Configurator()
+   config.set_default_csrf_options(require_csrf=True)
+
+CSRF checking may be explicitly enabled or disabled on a per-view basis using
+the ``require_csrf`` view option. A value of ``True`` or ``False`` will
+override the default set by ``set_default_csrf_options``. For example:
+
+.. code-block:: python
+
+   @view_config(route_name='hello', require_csrf=False)
+   def myview(request):
+       # ...
+
+When CSRF checking is active, the token and header used to find the
+supplied CSRF token will be ``csrf_token`` and ``X-CSRF-Token``, respectively,
+unless otherwise overridden by ``set_default_csrf_options``. The token is
+checked against the value in ``request.POST`` which is the submitted form body.
+If this value is not present, then the header will be checked.
+
+In addition to token based CSRF checks, if the request is using HTTPS then 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` or
+:class:`pyramid.exceptions.BadCSRFOrigin` 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`` response being sent to the
+client.
 
 Checking CSRF Tokens with a View Predicate
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. deprecated:: 1.7
+   Use the ``require_csrf`` option or read :ref:`auto_csrf_checking` instead
+   to have :class:`pyramid.exceptions.BadCSRFToken` exceptions raised.
+
 A convenient way to require a valid CSRF token for a particular view is to
 include ``check_csrf=True`` as a view predicate. See
 :meth:`pyramid.config.Configurator.add_view`.
@@ -410,15 +487,3 @@ include ``check_csrf=True`` as a view predicate. See
    predicate system, when it doesn't find a view, raises ``HTTPNotFound``
    instead of ``HTTPBadRequest``, so ``check_csrf=True`` behavior is different
    from calling :func:`pyramid.session.check_csrf_token`.
-
-Using the ``session.new_csrf_token`` Method
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To explicitly create a new CSRF token, use the ``session.new_csrf_token()``
-method.  This differs only from ``session.get_csrf_token()`` inasmuch as it
-clears any existing CSRF token, creates a new CSRF token, sets the token into
-the session, and returns the token.
-
-.. code-block:: python
-
-   token = request.session.new_csrf_token()