From 15c45d58e1a60bd3809e70c47e0ccd0a69d5fa2b Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Wed, 5 Jan 2011 22:21:56 -0700 Subject: slight reword for better flow --- docs/narr/sessions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index de9add3b7..3e3ad9288 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -32,7 +32,7 @@ limitation: representation of the session is fewer than 4000. This is suitable only for very small data sets. -It is, however, digitally signed, and thus its data cannot easily be +It is digitally signed, however, and thus its data cannot easily be tampered with. You can configure this session factory in your :app:`Pyramid` -- cgit v1.2.3 From 4614826b25f692ff431a110d371242a470ef0681 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Wed, 5 Jan 2011 22:35:50 -0700 Subject: reduce strength of assertion --- docs/narr/sessions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 3e3ad9288..cb3545a06 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -113,7 +113,7 @@ documentation. Some gotchas: - Keys and values of session data must be *pickleable*. This means, - typically, that they must be instances of basic types of objects, + typically, that they are instances of basic types of objects, such as strings, lists, dictionaries, tuples, integers, etc. If you place an object in a session data key or value that is not pickleable, an error will be raised when the session is serialized. -- cgit v1.2.3 From b0b9f70b16aeb36b8588efde13b7b2475a46278b Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Wed, 5 Jan 2011 23:21:12 -0700 Subject: combine flash and csrf into sessions chapt --- docs/narr/sessions.rst | 183 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 181 insertions(+), 2 deletions(-) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index cb3545a06..a4e30520f 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -3,8 +3,8 @@ .. _sessions_chapter: -Session Objects -=============== +Sessions +======== A :term:`session` is a namespace which is valid for some period of continual activity that can be used to represent a user's interaction @@ -162,3 +162,182 @@ both types are available in :class:`pyramid.interfaces.ISession`. You might use the cookie implementation in the :mod:`pyramid.session` module as inspiration. +.. index:: + single: flash messages + +Flash Messages +-------------- + +"Flash messages" are simply a queue of message strings stored in the +:term:`session`. To use flash messaging, you must enable a :term:`session +factory` as described in :ref:`using_the_default_session_factory` or +:ref:`using_alternate_session_factories`. + +Flash messaging has two main uses: to display a status message only once to +the user after performing an internal redirect, and to allow generic code to +log messages for single-time display without having direct access to an HTML +template. The user interface consists of a number of methods of the +:term:`session` object. + +Using the ``session.flash`` Method +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To add a message to a flash message queue, use a session object's ``flash`` +method: + +.. code-block:: python + :linenos: + + request.session.flash('mymessage') + +The ``.flash`` method appends a message to a flash queue, creating the queue +if necessary. + +``.flash`` accepts three arguments: + +.. method:: flash(message, queue='', allow_duplicate=True) + +The ``message`` argument is required. It represents a message you wish to +later display to a user. It is usually a string but the ``message`` you +provide is not modified in any way. + +The ``queue`` argument allows you to choose a queue to which to append the +message you provide. This can be used to push different kinds of messages +into flash storage for later display in different places on a page. You can +pass any name for your queue, but it must be a string. The default value is +the empty string, which chooses the default queue. Each queue is independent, +and can be popped by ``pop_flash`` or examined via ``peek_flash`` separately. +``queue`` defaults to the empty string. The empty string represents the +default flash message queue. + +.. code-block:: python + + request.session.flash(msg, 'myappsqueue') + +The ``allow_duplicate`` argument defaults to ``True``. If this is +``False``, if you attempt to add a message to a queue which is already +present in the queue, it will not be added. + +Using the ``session.pop_flash`` Method +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once one or more messages have been added to a flash queue by the +``session.flash`` API, the ``session.pop_flash`` API can be used to pop that +queue and return it for use. + +To pop a particular queue of messages from the flash object, use the session +object's ``pop_flash`` method. + +.. method:: pop_flash(queue='') + +.. code-block:: python + :linenos: + + >>> 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. + +.. code-block:: python + :linenos: + + >>> request.session.flash('info message') + >>> request.session.pop_flash() + ['info message'] + >>> request.session.pop_flash() + [] + +The object returned from ``pop_flash`` is a list. + +Using the ``session.peek_flash`` Method +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once one or more messages has been added to a flash queue by the +``session.flash`` API, the ``session.peek_flash`` API can be used to "peek" +at that queue. Unlike ``session.pop_flash``, the queue is not popped from +flash storage. + +.. method:: peek_flash(queue='') + +.. code-block:: python + :linenos: + + >>> 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 + single: cross-site request forgery attacks, prevention + +Preventing Cross-Site Request Forgery Attacks +--------------------------------------------- + +`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 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.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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To get the current CSRF token from the session, use the +``session.get_csrf_token`` method. + +.. code-block:: python + :linenos: + + token = request.session.get_csrf_token() + +The ``get_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.get_csrf_token() + if token != request.POST['csrf_token']: + raise ValueError('CSRF token did not match') + + + -- cgit v1.2.3 From 7aaeb5b93f894c57efb99985180fb893b0634a55 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Wed, 5 Jan 2011 23:21:38 -0700 Subject: don't need linenos for one line --- docs/narr/sessions.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index a4e30520f..def70aa6f 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -186,7 +186,6 @@ To add a message to a flash message queue, use a session object's ``flash`` method: .. code-block:: python - :linenos: request.session.flash('mymessage') -- cgit v1.2.3 From fd3988fa3f97e217ac69abec2117bb72c2f5f262 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Wed, 5 Jan 2011 23:26:07 -0700 Subject: add parens to method references --- docs/narr/sessions.rst | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index def70aa6f..0c50a996a 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -182,17 +182,17 @@ template. The user interface consists of a number of methods of the Using the ``session.flash`` Method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To add a message to a flash message queue, use a session object's ``flash`` +To add a message to a flash message queue, use a session object's ``flash()`` method: .. code-block:: python request.session.flash('mymessage') -The ``.flash`` method appends a message to a flash queue, creating the queue +The ``flash()`` method appends a message to a flash queue, creating the queue if necessary. -``.flash`` accepts three arguments: +``flash()`` accepts three arguments: .. method:: flash(message, queue='', allow_duplicate=True) @@ -200,14 +200,15 @@ The ``message`` argument is required. It represents a message you wish to later display to a user. It is usually a string but the ``message`` you provide is not modified in any way. -The ``queue`` argument allows you to choose a queue to which to append the -message you provide. This can be used to push different kinds of messages -into flash storage for later display in different places on a page. You can -pass any name for your queue, but it must be a string. The default value is -the empty string, which chooses the default queue. Each queue is independent, -and can be popped by ``pop_flash`` or examined via ``peek_flash`` separately. -``queue`` defaults to the empty string. The empty string represents the -default flash message queue. +The ``queue`` argument allows you to choose a queue to which to append +the message you provide. This can be used to push different kinds of +messages into flash storage for later display in different places on a +page. You can pass any name for your queue, but it must be a string. +The default value is the empty string, which chooses the default queue. +Each queue is independent, and can be popped by ``pop_flash()`` or +examined via ``peek_flash()`` separately. ``queue`` defaults to the +empty string. The empty string represents the default flash message +queue. .. code-block:: python @@ -221,11 +222,11 @@ Using the ``session.pop_flash`` Method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Once one or more messages have been added to a flash queue by the -``session.flash`` API, the ``session.pop_flash`` API can be used to pop that -queue and return it for use. +``session.flash()`` API, the ``session.pop_flash()`` API can be used to +pop that queue and return it for use. To pop a particular queue of messages from the flash object, use the session -object's ``pop_flash`` method. +object's ``pop_flash()`` method. .. method:: pop_flash(queue='') @@ -237,7 +238,7 @@ object's ``pop_flash`` method. ['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 +to ``session.flash()`` will return an empty list, because the queue has already been popped. .. code-block:: python @@ -249,15 +250,15 @@ been popped. >>> request.session.pop_flash() [] -The object returned from ``pop_flash`` is a list. +The object returned from ``pop_flash()`` is a list. Using the ``session.peek_flash`` Method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Once one or more messages has been added to a flash queue by the -``session.flash`` API, the ``session.peek_flash`` API can be used to "peek" -at that queue. Unlike ``session.pop_flash``, the queue is not popped from -flash storage. +``session.flash()`` API, the ``session.peek_flash()`` API can be used to +"peek" at that queue. Unlike ``session.pop_flash()``, the queue is not +popped from flash storage. .. method:: peek_flash(queue='') -- cgit v1.2.3 From 3a6919fe80d0ba6501b52b013800832549d09d63 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Wed, 5 Jan 2011 23:31:58 -0700 Subject: remove redundant sentence --- docs/narr/sessions.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 0c50a996a..acc7bdd80 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -204,7 +204,6 @@ The ``queue`` argument allows you to choose a queue to which to append the message you provide. This can be used to push different kinds of messages into flash storage for later display in different places on a page. You can pass any name for your queue, but it must be a string. -The default value is the empty string, which chooses the default queue. Each queue is independent, and can be popped by ``pop_flash()`` or examined via ``peek_flash()`` separately. ``queue`` defaults to the empty string. The empty string represents the default flash message -- cgit v1.2.3 From 2eefe0dd57f578cc11edbf8c98bf58ab86d6025c Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Wed, 5 Jan 2011 23:36:18 -0700 Subject: clarify behavior of allow_duplicate --- docs/narr/sessions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index acc7bdd80..6a538766c 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -214,7 +214,7 @@ queue. request.session.flash(msg, 'myappsqueue') The ``allow_duplicate`` argument defaults to ``True``. If this is -``False``, if you attempt to add a message to a queue which is already +``False``, and you attempt to add a message value which is already present in the queue, it will not be added. Using the ``session.pop_flash`` Method -- cgit v1.2.3 From abedea975768affa778e433ebb75697998075cc9 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Wed, 5 Jan 2011 23:44:54 -0700 Subject: incorporate return type and queue semantics into same paragraph --- docs/narr/sessions.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 6a538766c..958ede7d6 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -222,10 +222,11 @@ Using the ``session.pop_flash`` Method Once one or more messages have been added to a flash queue by the ``session.flash()`` API, the ``session.pop_flash()`` API can be used to -pop that queue and return it for use. +pop an entire queue and return it for use. To pop a particular queue of messages from the flash object, use the session -object's ``pop_flash()`` method. +object's ``pop_flash()`` method. This returns a list of the messages +that were added to the flash queue, and empties the queue. .. method:: pop_flash(queue='') @@ -249,8 +250,6 @@ been popped. >>> request.session.pop_flash() [] -The object returned from ``pop_flash()`` is a list. - Using the ``session.peek_flash`` Method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 089c63c9bd0a2bf666cbfa17868f67802fe1d502 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Wed, 5 Jan 2011 23:53:25 -0700 Subject: add summary paragraph to tie things together better --- docs/narr/sessions.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 958ede7d6..d46685c08 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -10,6 +10,11 @@ A :term:`session` is a namespace which is valid for some period of continual activity that can be used to represent a user's interaction with a web application. +This chapter describes how to configure sessions, what session +implementations :app:`Pyramid` provides out of the box, and two +session-specific features: flash messages, and cross-site request +forgery attack prevention. + .. _using_the_default_session_factory: Using The Default Session Factory -- cgit v1.2.3 From 826fd7b11d190dafe9571e10eb7c2cf96ed97732 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Wed, 5 Jan 2011 23:54:50 -0700 Subject: forgot an important session feature in summary --- docs/narr/sessions.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index d46685c08..6a6de2639 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -11,9 +11,9 @@ continual activity that can be used to represent a user's interaction with a web application. This chapter describes how to configure sessions, what session -implementations :app:`Pyramid` provides out of the box, and two -session-specific features: flash messages, and cross-site request -forgery attack prevention. +implementations :app:`Pyramid` provides out of the box, how to store and +retrieve data from sessions, and two session-specific features: flash +messages, and cross-site request forgery attack prevention. .. _using_the_default_session_factory: -- cgit v1.2.3 From e5f66f8e839ee5d7eeaebb118c9d03f11578dd14 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Wed, 5 Jan 2011 23:58:24 -0700 Subject: add parens to method references --- docs/narr/sessions.rst | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 6a6de2639..edd24d839 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -301,19 +301,18 @@ as described in :ref:`using_the_default_session_factory` or Using the ``session.new_csrf_token`` Method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To add a CSRF token to the session, use 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* +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. +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 +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. @@ -321,19 +320,18 @@ Using the ``session.get_csrf_token`` Method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To get the current CSRF token from the session, use the -``session.get_csrf_token`` method. +``session.get_csrf_token()`` method. .. code-block:: python - :linenos: token = request.session.get_csrf_token() -The ``get_csrf_token`` method accepts no arguments. It returns the "current" -*token* string (as per the last call to ``session.new_csrf_token``). You can +The ``get_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``: +obtained via ``session.new_csrf_token()`` as a hidden input field named +``csrf_token()``: .. code-block:: python :linenos: @@ -342,5 +340,3 @@ obtained via ``session.new_csrf_token`` as a hidden input field named if token != request.POST['csrf_token']: raise ValueError('CSRF token did not match') - - -- cgit v1.2.3 From f8f2fa32bcbec2334e02b9f16ee72d40e2fa857b Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Thu, 6 Jan 2011 00:00:34 -0700 Subject: clarify --- docs/narr/sessions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index edd24d839..cce77ca5b 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -293,7 +293,7 @@ application to perform some command that requires elevated privileges. You can avoid most of these attacks by making sure that 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 +actions in code which requires elevated privileges that 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`. -- cgit v1.2.3 From edd530c7bf07ff902585b57a136c0ab8fafc9254 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Thu, 6 Jan 2011 00:06:31 -0700 Subject: clarify by promoting parenthetical, add comment requesting some advice --- docs/narr/sessions.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index cce77ca5b..bd0fe69bf 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -327,7 +327,7 @@ To get the current CSRF token from the session, use the token = request.session.get_csrf_token() The ``get_csrf_token()`` method accepts no arguments. It returns the "current" -*token* string (as per the last call to ``session.new_csrf_token()``). You can +*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 @@ -340,3 +340,6 @@ obtained via ``session.new_csrf_token()`` as a hidden input field named if token != request.POST['csrf_token']: raise ValueError('CSRF token did not match') +.. comment:: + XXX Some advice on when a new csrf token should be generated would be + useful. At login time? When the form is generated? -- cgit v1.2.3 From 3fe316cb75b4311fbc4c7610f140e423b30d9ff6 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Thu, 6 Jan 2011 00:11:22 -0700 Subject: remove comment, it's more or less answered --- docs/narr/sessions.rst | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index bd0fe69bf..842b838cd 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -340,6 +340,3 @@ obtained via ``session.new_csrf_token()`` as a hidden input field named if token != request.POST['csrf_token']: raise ValueError('CSRF token did not match') -.. comment:: - XXX Some advice on when a new csrf token should be generated would be - useful. At login time? When the form is generated? -- cgit v1.2.3 From 46d30f532edc7017b3dcc5233ef050aca5d7d586 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 8 Jan 2011 00:28:45 -0500 Subject: redocument relationship between get_csrf_token and new_csrf_token --- docs/narr/sessions.rst | 52 +++++++++++++++++++++++++++----------------------- 1 file changed, 28 insertions(+), 24 deletions(-) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 842b838cd..0ed52b563 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -298,24 +298,6 @@ 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 - - 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 @@ To get the current CSRF token from the session, use the 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 @@ obtained via ``session.new_csrf_token()`` as a hidden input field named 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() + + -- cgit v1.2.3 From 70acd25f40f32fc6cbb3b5d38a695b8982b52a31 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 27 Jan 2011 23:06:55 -0500 Subject: module name contractions --- docs/narr/sessions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/sessions.rst') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 0ed52b563..97e3ebc55 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -42,7 +42,7 @@ tampered with. You can configure this session factory in your :app:`Pyramid` application by using the ``session_factory`` argument to the -:class:`pyramid.config.Configurator` class: +:class:`~pyramid.config.Configurator` class: .. code-block:: python :linenos: -- cgit v1.2.3