redocument relationship between get_csrf_token and new_csrf_token

Chris McDonough

2011-01-08 46d30f532edc7017b3dcc5233ef050aca5d7d586

redocument relationship between get_csrf_token and new_csrf_token

 docs/narr/sessions.rst

@@ -298,24 +298,6 @@
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

   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.get_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.get_csrf_token()`` (explained below) to
obtain 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.get_csrf_token`` Method
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

@@ -326,12 +308,20 @@

   token = request.session.get_csrf_token()

The ``get_csrf_token()`` method accepts no arguments.  It returns the "current"
*token* string generated by 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()``:
The ``session.get_csrf_token()`` method accepts no arguments.  It returns a
CSRF *token* string. If ``session.get_csrf_token()`` or
``session.new_csrf_token()`` was invoked previously for this session, the
existing token will be returned.  If no CSRF token previously existed for
this session, a new token will be will be set into the session and returned.
The newly created token will be opaque and randomized.

You can 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.get_csrf_token()`` *again* to obtain the
current CSRF token related to the user from the session, and compare it to
the value of the hidden form field.  For example, if your form rendering
included the CSRF token obtained via ``session.get_csrf_token()`` as a hidden
input field named ``csrf_token``:

.. code-block:: python
   :linenos:
@@ -340,3 +330,17 @@
   if token != request.POST['csrf_token']:
       raise ValueError('CSRF token did not match')

Using the ``session.new_csrf_token`` Method
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To explicitly add a new CSRF token to the session, 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()