Merge branch 'master' into move-acl-security-to-authorization

5 files changed, 159 insertions, 24 deletions

diff --git a/src/pyramid/authentication.py b/src/pyramid/authentication.py
index 95c01bbea..3bfab78ee 100644
--- a/src/pyramid/authentication.py
+++ b/src/pyramid/authentication.py
@@ -430,9 +430,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
 
@@ -696,14 +835,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
@@ -821,12 +952,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``.
 
     """
 
@@ -860,7 +995,7 @@ class AuthTktCookieHelper(object):
         http_only=False,
         path="/",
         wild_domain=True,
-        hashalg='md5',
+        hashalg='sha512',
         parent_domain=False,
         domain=None,
         samesite='Lax',
diff --git a/src/pyramid/config/testing.py b/src/pyramid/config/testing.py
index db1aefb24..ea3f92d17 100644
--- a/src/pyramid/config/testing.py
+++ b/src/pyramid/config/testing.py
@@ -32,8 +32,8 @@ class TestingConfiguratorMixin(object):
             :attr:`pyramid.request.Request.authenticated_userid` will have this
             value as well.
         :type userid:  str
-        :param identity:  If provided, the policy's ``identify`` method will
-            return this value.  As a result,
+        :param identity:  If provided, the policy's ``authenticated_identity``
+            method will return this value.  As a result,
             :attr:`pyramid.request.Request.authenticated_identity`` will have
             this value.
         :type identity:  object
diff --git a/src/pyramid/interfaces.py b/src/pyramid/interfaces.py
index 433ac0c9d..e92662f11 100644
--- a/src/pyramid/interfaces.py
+++ b/src/pyramid/interfaces.py
@@ -483,16 +483,16 @@ class IViewMapperFactory(Interface):
 
 
 class ISecurityPolicy(Interface):
+    def authenticated_identity(request):
+        """ Return the :term:`identity` of the current user.  The object can be
+        of any shape, such as a simple ID string or an ORM object.
+        """
+
     def authenticated_userid(request):
         """ Return a :term:`userid` string identifying the trusted and
         verified user, or ``None`` if unauthenticated.
         """
 
-    def identify(request):
-        """ Return the :term:`identity` of the current user.  The object can be
-        of any shape, such as a simple ID string or an ORM object.
-        """
-
     def permits(request, context, permission):
         """ Return an instance of :class:`pyramid.security.Allowed` if a user
         of the given identity is allowed the ``permission`` in the current
diff --git a/src/pyramid/security.py b/src/pyramid/security.py
index a5b4ce442..657af045a 100644
--- a/src/pyramid/security.py
+++ b/src/pyramid/security.py
@@ -224,7 +224,7 @@ class SecurityAPIMixin:
         policy = _get_security_policy(self)
         if policy is None:
             return None
-        return policy.identify(self)
+        return policy.authenticated_identity(self)
 
     @property
     def authenticated_userid(self):
@@ -357,7 +357,7 @@ class LegacySecurityPolicy:
     def _get_authz_policy(self, request):
         return request.registry.getUtility(IAuthorizationPolicy)
 
-    def identify(self, request):
+    def authenticated_identity(self, request):
         return self.authenticated_userid(request)
 
     def authenticated_userid(self, request):
diff --git a/src/pyramid/testing.py b/src/pyramid/testing.py
index a03f2678e..af02872dd 100644
--- a/src/pyramid/testing.py
+++ b/src/pyramid/testing.py
@@ -51,7 +51,7 @@ class DummySecurityPolicy(object):
         self.remember_result = remember_result
         self.forget_result = forget_result
 
-    def identify(self, request):
+    def authenticated_identity(self, request):
         return self.identity
 
     def authenticated_userid(self, request):