- Added CSRF token generation, as described in the narrative chapter entitled

  "Preventing Cross-Site Request Forgery Attacks".

5 files changed, 65 insertions, 38 deletions

diff --git a/docs/api.rst b/docs/api.rst
index 4808a08b3..b650c8ded 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -15,7 +15,6 @@ documentation is organized alphabetically by module name.
    api/config
    api/events
    api/exceptions
-   api/flash
    api/httpexceptions
    api/i18n
    api/interfaces
diff --git a/docs/api/flash.rst b/docs/api/flash.rst
deleted file mode 100644
index 94907958d..000000000
--- a/docs/api/flash.rst
+++ /dev/null
@@ -1,36 +0,0 @@
-.. _flash_module:
-
-:mod:`pyramid.flash`
---------------------
-
-Flash Category Constants
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following attributes represent constants for use as flash messaging
-category values (see :ref:`flash_chapter`).
-
-.. attribute:: DEBUG
-
-   An alternate spelling for the string ``debug``.  Represents development
-   debug messages.
-
-.. attribute:: INFO
-
-   An alternate spelling for the string ``info``.  Represents messages that
-   are informational for user consumption.
-
-.. attribute:: SUCCESS
-
-   An alternate spelling for the string ``success``.  Represents messages that
-   tell the user about a successful action.
-
-.. attribute:: WARNING
-
-   An alternate spelling for the string ``warning``.  Represents messages
-   that tell the user about a condition that is not a success, but is neither
-   an error.
-
-.. attribute:: ERROR
-
-   An alternate spelling for the string ``success``.  Represents messages
-   that tell the user about an unsuccessful action.
diff --git a/docs/index.rst b/docs/index.rst
index fbf9de810..343fb28ba 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -49,6 +49,7 @@ Narrative documentation in chapter form explaining how to use
    narr/webob
    narr/sessions
    narr/flash
+   narr/csrf
    narr/security
    narr/hybrid
    narr/i18n
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index 6a1992ba4..713c9841f 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -42,6 +42,7 @@ Narrative Documentation
    narr/webob
    narr/sessions
    narr/flash
+   narr/csrf
    narr/security
    narr/hybrid
    narr/i18n
@@ -89,7 +90,6 @@ API Reference
    api/config
    api/events
    api/exceptions
-   api/flash
    api/httpexceptions
    api/i18n
    api/interfaces
diff --git a/docs/narr/csrf.rst b/docs/narr/csrf.rst
new file mode 100644
index 000000000..7d1ee6fea
--- /dev/null
+++ b/docs/narr/csrf.rst
@@ -0,0 +1,63 @@
+.. _csrf_chapter:
+
+Preventing Cross-Site Request Forgery Attacks
+=============================================
+
+`Cross-site request forgery
+<http://en.wikipedia.org/wiki/Cross-site_request_forgery>`_ attacks are a
+phenomenon whereby a user with an identity on your website might click on a
+URL or button on another website which unwittingly redirects the user to your
+application to perform some command that requires elevated privileges.
+
+You can avoid most of these attacks by making sure that a the correct *CSRF
+token* has been set in an :app:`Pyramid` session object before performing any
+actions in code which requires elevated privileges and is invoked via a form
+post.  To use CSRF token support, you must enable a :term:`session factory`
+as described in :ref:`using_the_default_session_factory` or
+:ref:`using_alternate_session_factories`.
+
+Using the ``session.new_csrf_token`` Method
+-------------------------------------------
+
+To add a CSRF token to the session, use the ``session.new_csrf_token`` method.
+
+.. code-block:: python
+   :linenos:
+
+   token = request.session.new_csrf_token()
+
+The ``.new_csrf_token`` method accepts no arguments.  It returns a *token*
+string, which will be opaque and randomized.  This token will also be set
+into the session, awaiting pickup by the ``session.pop_csrf_token`` method.
+You can subsequently use the returned token as the value of a hidden field in
+a form that posts to a method that requires elevated privileges.  The handler
+for the form post should use ``session.pop_csrf_token`` (explained below) to
+pop the current CSRF token related to the user from the session, and compare
+it to the value of the hidden form field.
+
+Using the ``session.pop_csrf_token`` Method
+-------------------------------------------
+
+To pop the current CSRF token from the session, use the
+``session.pop_csrf_token`` method.
+
+.. code-block:: python
+   :linenos:
+
+   token = request.session.pop_csrf_token()
+
+The ``.pop_csrf_token`` method accepts no arguments.  It returns the
+"current" *token* string (as per the last call to
+``session.new_csrf_token``).  You can then use it to compare against the
+token provided within form post hidden value data.  For example, if your form
+rendering included the CSRF token obtained via ``session.new_csrf_token`` as
+a hidden input field named ``csrf_token``:
+
+.. code-block:: python
+   :linenos:
+
+   token = request.session.pop_csrf_token()
+   if token != request.POST['csrf_token']:
+       raise ValueError('CSRF token did not match')
+
+