change hashalg on AuthTktCookieHelper to sha512.

5 files changed, 156 insertions, 23 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index 383906e00..650e7a34f 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -156,6 +156,10 @@ Backward Incompatibilities
   ``require_csrf`` view option to enable automatic CSRF checking.
   See https://github.com/Pylons/pyramid/pull/3521
 
+- Changed the ``hashalg`` on ``pyramid.authentication.AuthTktCookieHelper`` to
+  ``sha512``.
+  See https://github.com/Pylons/pyramid/pull/3557
+
 Documentation Changes
 ---------------------
 
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index e3820ce19..72c2721f6 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -698,7 +698,7 @@ A "secret" is required by various components of Pyramid.  For example, the
 helper below might be used for a security policy and uses a secret value
 ``seekrit``::
 
-  helper = AuthTktCookieHelper('seekrit', hashalg='sha512')
+  helper = AuthTktCookieHelper('seekrit')
 
 A :term:`session factory` also requires a secret::
 
diff --git a/docs/quick_tutorial/authentication/tutorial/security.py b/docs/quick_tutorial/authentication/tutorial/security.py
index e8d323ea7..8324000ed 100644
--- a/docs/quick_tutorial/authentication/tutorial/security.py
+++ b/docs/quick_tutorial/authentication/tutorial/security.py
@@ -17,10 +17,7 @@ USERS = {'editor': hash_password('editor'),
 
 class SecurityPolicy:
     def __init__(self, secret):
-        self.authtkt = AuthTktCookieHelper(
-            secret=secret,
-            hashalg='sha512',
-        )
+        self.authtkt = AuthTktCookieHelper(secret=secret)
 
     def authenticated_identity(self, request):
         identity = self.authtkt.identify(request)
diff --git a/docs/quick_tutorial/authorization/tutorial/security.py b/docs/quick_tutorial/authorization/tutorial/security.py
index a004a20f2..5b3e04a5f 100644
--- a/docs/quick_tutorial/authorization/tutorial/security.py
+++ b/docs/quick_tutorial/authorization/tutorial/security.py
@@ -20,10 +20,7 @@ GROUPS = {'editor': ['group:editors']}
 
 class SecurityPolicy:
     def __init__(self, secret):
-        self.authtkt = AuthTktCookieHelper(
-            secret=secret,
-            hashalg='sha512',
-        )
+        self.authtkt = AuthTktCookieHelper(secret=secret)
         self.acl = ACLHelper()
 
     def authenticated_identity(self, request):
diff --git a/src/pyramid/authentication.py b/src/pyramid/authentication.py
index 500a84646..14a4ad210 100644
--- a/src/pyramid/authentication.py
+++ b/src/pyramid/authentication.py
@@ -428,9 +428,148 @@ class RemoteUserAuthenticationPolicy(CallbackAuthenticationPolicy):
 @implementer(IAuthenticationPolicy)
 class AuthTktAuthenticationPolicy(CallbackAuthenticationPolicy):
     """A :app:`Pyramid` :term:`authentication policy` which
-    obtains data from a Pyramid "auth ticket" cookie.  See
-    :class:`.AuthTktCookieHelper` for documentation of the constructor
-    arguments.
+    obtains data from a Pyramid "auth ticket" cookie.
+
+    Constructor Arguments
+
+    ``secret``
+
+       The secret (a string) used for auth_tkt cookie signing.  This value
+       should be unique across all values provided to Pyramid for various
+       subsystem secrets (see :ref:`admonishment_against_secret_sharing`).
+       Required.
+
+    ``callback``
+
+       Default: ``None``.  A callback passed the userid and the
+       request, expected to return ``None`` if the userid doesn't
+       exist or a sequence of principal identifiers (possibly empty) if
+       the user does exist.  If ``callback`` is ``None``, the userid
+       will be assumed to exist with no principals.  Optional.
+
+    ``cookie_name``
+
+       Default: ``auth_tkt``.  The cookie name used
+       (string).  Optional.
+
+    ``secure``
+
+       Default: ``False``.  Only send the cookie back over a secure
+       conn.  Optional.
+
+    ``include_ip``
+
+       Default: ``False``.  Make the requesting IP address part of
+       the authentication data in the cookie.  Optional.
+
+       For IPv6 this option is not recommended. The ``mod_auth_tkt``
+       specification does not specify how to handle IPv6 addresses, so using
+       this option in combination with IPv6 addresses may cause an
+       incompatible cookie. It ties the authentication ticket to that
+       individual's IPv6 address.
+
+    ``timeout``
+
+       Default: ``None``.  Maximum number of seconds which a newly
+       issued ticket will be considered valid.  After this amount of
+       time, the ticket will expire (effectively logging the user
+       out).  If this value is ``None``, the ticket never expires.
+       Optional.
+
+    ``reissue_time``
+
+       Default: ``None``.  If this parameter is set, it represents the number
+       of seconds that must pass before an authentication token cookie is
+       automatically reissued as the result of a request which requires
+       authentication.  The duration is measured as the number of seconds
+       since the last auth_tkt cookie was issued and 'now'.  If this value is
+       ``0``, a new ticket cookie will be reissued on every request which
+       requires authentication.
+
+       A good rule of thumb: if you want auto-expired cookies based on
+       inactivity: set the ``timeout`` value to 1200 (20 mins) and set the
+       ``reissue_time`` value to perhaps a tenth of the ``timeout`` value
+       (120 or 2 mins).  It's nonsensical to set the ``timeout`` value lower
+       than the ``reissue_time`` value, as the ticket will never be reissued
+       if so.  However, such a configuration is not explicitly prevented.
+
+       Optional.
+
+    ``max_age``
+
+       Default: ``None``.  The max age of the auth_tkt cookie, in
+       seconds.  This differs from ``timeout`` inasmuch as ``timeout``
+       represents the lifetime of the ticket contained in the cookie,
+       while this value represents the lifetime of the cookie itself.
+       When this value is set, the cookie's ``Max-Age`` and
+       ``Expires`` settings will be set, allowing the auth_tkt cookie
+       to last between browser sessions.  It is typically nonsensical
+       to set this to a value that is lower than ``timeout`` or
+       ``reissue_time``, although it is not explicitly prevented.
+       Optional.
+
+    ``path``
+
+       Default: ``/``. The path for which the auth_tkt cookie is valid.
+       May be desirable if the application only serves part of a domain.
+       Optional.
+
+    ``http_only``
+
+       Default: ``False``. Hide cookie from JavaScript by setting the
+       HttpOnly flag. Not honored by all browsers.
+       Optional.
+
+    ``wild_domain``
+
+       Default: ``True``. An auth_tkt cookie will be generated for the
+       wildcard domain. If your site is hosted as ``example.com`` this
+       will make the cookie available for sites underneath ``example.com``
+       such as ``www.example.com``.
+       Optional.
+
+    ``parent_domain``
+
+       Default: ``False``. An auth_tkt cookie will be generated for the
+       parent domain of the current site. For example if your site is
+       hosted under ``www.example.com`` a cookie will be generated for
+       ``.example.com``. This can be useful if you have multiple sites
+       sharing the same domain. This option supercedes the ``wild_domain``
+       option.
+       Optional.
+
+    ``domain``
+
+       Default: ``None``. If provided the auth_tkt cookie will only be
+       set for this domain. This option is not compatible with ``wild_domain``
+       and ``parent_domain``.
+       Optional.
+
+    ``hashalg``
+
+       Default: ``sha512`` (the literal string).
+
+       Any hash algorithm supported by Python's ``hashlib.new()`` function
+       can be used as the ``hashalg``.
+
+       Cookies generated by different instances of AuthTktAuthenticationPolicy
+       using different ``hashalg`` options are not compatible. Switching the
+       ``hashalg`` will imply that all existing users with a valid cookie will
+       be required to re-login.
+
+       Optional.
+
+    ``debug``
+
+        Default: ``False``.  If ``debug`` is ``True``, log messages to the
+        Pyramid debug logger about the results of various authentication
+        steps.  The output from debugging is useful for reporting to maillist
+        or IRC channels when asking for support.
+
+    ``samesite``
+
+        Default: ``'Lax'``.  The 'samesite' option of the session cookie. Set
+        the value to ``None`` to turn off the samesite option.
 
     .. versionchanged:: 1.4
 
@@ -694,14 +833,6 @@ class AuthTktCookieHelper(object):
        subsystem secrets (see :ref:`admonishment_against_secret_sharing`).
        Required.
 
-    ``callback``
-
-       Default: ``None``.  A callback passed the userid and the
-       request, expected to return ``None`` if the userid doesn't
-       exist or a sequence of principal identifiers (possibly empty) if
-       the user does exist.  If ``callback`` is ``None``, the userid
-       will be assumed to exist with no principals.  Optional.
-
     ``cookie_name``
 
        Default: ``auth_tkt``.  The cookie name used
@@ -819,12 +950,16 @@ class AuthTktCookieHelper(object):
         Default: ``False``.  If ``debug`` is ``True``, log messages to the
         Pyramid debug logger about the results of various authentication
         steps.  The output from debugging is useful for reporting to maillist
-        or IRC channels when asking for support.
+        or IRC channels when asking for support. Optional.
 
     ``samesite``
 
         Default: ``'Lax'``.  The 'samesite' option of the session cookie. Set
-        the value to ``None`` to turn off the samesite option.
+        the value to ``None`` to turn off the samesite option. Optional.
+
+    .. versionchanged:: 2.0
+
+        The default ``hashalg`` was changed from ``md5`` to ``sha512``.
 
     """
 
@@ -858,7 +993,7 @@ class AuthTktCookieHelper(object):
         http_only=False,
         path="/",
         wild_domain=True,
-        hashalg='md5',
+        hashalg='sha512',
         parent_domain=False,
         domain=None,
         samesite='Lax',