Apply drafting changes to documentation.

Matthew Wilkes

2017-04-26 2ded2fc216b4caaf0d97813413943e0838b6eaaa

Apply drafting changes to documentation.

 CHANGES.txt

@@ -25,7 +25,7 @@
  appropriately. See https://github.com/Pylons/pyramid/pull/2989

- A new CSRF implementation, :class:`pyramid.csrf.SessionCSRF` has been added,
  which deleagates all CSRF generation to the current session, following the
  which delegates all CSRF generation to the current session, following the
  old API for this. A ``get_csrf_token()`` method is now available in template
  global scope, to make it easy for template developers to get the current CSRF
  token without adding it to Python code.

 docs/glossary.rst

@@ -891,6 +891,11 @@
      :meth:`pyramid.config.Configurator.set_session_factory` for more
      information.

   CSRF storage policy
      A utility that implements :class:`pyramid.interfaces.ICSRFStoragePolicy`
      which is responsible for allocating CSRF tokens to a user and verifying
      that a provided token is acceptable.

   Mako
     `Mako <http://www.makotemplates.org/>`_ is a template language
     which refines the familiar ideas of componentized layout and inheritance

 docs/narr/security.rst

@@ -766,6 +766,10 @@
zero. Keys should not be re-used across different contexts where an attacker
has the possibility of providing a chosen plaintext.

.. index::
   single: preventing cross-site request forgery attacks
   single: cross-site request forgery attacks, prevention

Preventing Cross-Site Request Forgery Attacks
---------------------------------------------


 docs/narr/sessions.rst

@@ -315,7 +315,3 @@
   ['info message']
   >>> request.session.peek_flash()
   []

.. index::
   single: preventing cross-site request forgery attacks
   single: cross-site request forgery attacks, prevention

 pyramid/config/security.py

@@ -232,7 +232,7 @@
    @action_method
    def set_csrf_storage_policy(self, policy):
        """
        Set the CSRF storage policy used by subsequent view registrations.
        Set the :term:`CSRF storage policy` used by subsequent view registrations.

        ``policy`` is a class that implements the
        :meth:`pyramid.interfaces.ICSRFStoragePolicy` interface that will be used for all

 pyramid/config/views.py

@@ -651,6 +651,12 @@

          .. versionadded:: 1.4a2

          .. versionchanged:: 1.9
            This feature requires either a :term:`session factory` to have been
            configured, or a :term:`CSRF storage policy` other than the default
            to be in use.


        physical_path

          If specified, this value should be a string or a tuple representing

 pyramid/csrf.py

@@ -31,7 +31,7 @@
    Note that using this CSRF implementation requires that
    a :term:`session factory` is configured.

    .. versionadded :: 1.8a1
    .. versionadded :: 1.9
    """
    def new_csrf_token(self, request):
        """ Sets a new CSRF token into the session and returns it. """
@@ -43,8 +43,8 @@
        return request.session.get_csrf_token()

    def check_csrf_token(self, request, supplied_token):
        """ Returns True if supplied_token is the same value as get_csrf_token
        returns for this request. """
        """ Returns ``True`` if ``supplied_token is`` the same value as
        ``get_csrf_token(request)``."""
        expected = self.get_csrf_token(request)
        return not strings_differ(
            bytes_(expected, 'ascii'),
@@ -55,11 +55,11 @@
class CookieCSRFStoragePolicy(object):
    """ An alternative CSRF implementation that stores its information in
    unauthenticated cookies, known as the 'Double Submit Cookie' method in the
    OWASP CSRF guidelines. This gives some additional flexibility with regards
    to scaling as the tokens can be generated and verified by a front-end
    server.
    `OWASP CSRF guidelines <https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_Prevention_Cheat_Sheet#Double_Submit_Cookie>`_.
    This gives some additional flexibility with regards to scaling as the tokens
    can be generated and verified by a front-end server.

    .. versionadded :: 1.8a1
    .. versionadded :: 1.9
    """

    def __init__(self, cookie_name='csrf_token', secure=False, httponly=False,
@@ -96,8 +96,8 @@
        return token

    def check_csrf_token(self, request, supplied_token):
        """ Returns True if supplied_token is the same value as get_csrf_token
        returns for this request. """
        """ Returns ``True`` if ``supplied_token is`` the same value as
        ``get_csrf_token(request)``."""
        expected = self.get_csrf_token(request)
        return not strings_differ(
            bytes_(expected, 'ascii'),
@@ -109,7 +109,7 @@
    a new one using ``new_csrf_token(request)`` if one does not exist. This
    calls the equivalent method in the chosen CSRF protection implementation.

    .. versionadded :: 1.8a1
    .. versionadded :: 1.9
    """
    registry = request.registry
    csrf = registry.getUtility(ICSRFStoragePolicy)
@@ -121,7 +121,7 @@
    implementation defined manner. This calls the equivalent method in the
    chosen CSRF protection implementation.

    .. versionadded :: 1.8a1
    .. versionadded :: 1.9
    """
    registry = request.registry
    csrf = registry.getUtility(ICSRFStoragePolicy)
@@ -159,8 +159,8 @@
       considered valid. It must be passed in either the request body or
       a header.

    .. versionchanged:: 1.8a1
       Moved from pyramid.session to pyramid.csrf
    .. versionchanged:: 1.9
       Moved from :mod:`pyramid.session` to :mod:`pyramid.csrf`
    """
    supplied_token = ""
    # We first check the headers for a csrf token, as that is significantly
@@ -192,27 +192,28 @@

def check_csrf_origin(request, trusted_origins=None, raises=True):
    """
    Check the Origin of the request to see if it is a cross site request or
    Check the ``Origin`` of the request to see if it is a cross site request or
    not.

    If the value supplied by the Origin or Referer header isn't one of the
    If the value supplied by the ``Origin`` or ``Referer`` header isn't one of the
    trusted origins and ``raises`` is ``True``, this function will raise a
    :exc:`pyramid.exceptions.BadCSRFOrigin` exception but if ``raises`` is
    ``False`` this function will return ``False`` instead. If the CSRF origin
    :exc:`pyramid.exceptions.BadCSRFOrigin` exception, but if ``raises`` is
    ``False``, this function will return ``False`` instead. If the CSRF origin
    checks are successful this function will return ``True`` unconditionally.

    Additional trusted origins may be added by passing a list of domain (and
    ports if nonstandard like `['example.com', 'dev.example.com:8080']`) in
    ports if nonstandard like ``['example.com', 'dev.example.com:8080']``) in
    with the ``trusted_origins`` parameter. If ``trusted_origins`` is ``None``
    (the default) this list of additional domains will be pulled from the
    ``pyramid.csrf_trusted_origins`` setting.

    Note that this function will do nothing if request.scheme is not https.
    Note that this function will do nothing if ``request.scheme`` is not
    ``https``.

    .. versionadded:: 1.7

    .. versionchanged:: 1.8a1
       Moved from pyramid.session to pyramid.csrf
    .. versionchanged:: 1.9
       Moved from :mod:`pyramid.session` to :mod:`pyramid.csrf`
    """
    def _fail(reason):
        if raises:

 pyramid/interfaces.py

@@ -999,8 +999,8 @@
        """

    def check_csrf_token(request, supplied_token):
        """ Returns a boolean that represents if supplied_token is a valid CSRF
        token for this request. Comparing strings for equality must be done
        """ Returns a boolean that represents if ``supplied_token`` is a valid
        CSRF token for this request. Comparing strings for equality must be done
        using :func:`pyramid.utils.strings_differ` to avoid timing attacks.
        """