reword docs

1 files changed, 37 insertions, 18 deletions

diff --git a/pyramid/authentication.py b/pyramid/authentication.py
index 0a406e370..08d283acc 100644
--- a/pyramid/authentication.py
+++ b/pyramid/authentication.py
@@ -510,23 +510,30 @@ class AuthTktAuthenticationPolicy(CallbackAuthenticationPolicy):
 
     ``hashalg``
 
-       Default: ``md5``. 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.
+       Default: ``md5`` (the literal string).
 
        Any hash algorithm supported by Python's ``hashlib.new()`` function
        can be used as the ``hashalg``.
 
-       This option is available as of :app:`Pyramid` 1.4. See the warning
-       above for reasons to change ``hashalg`` in your own apps.
+       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.
+
+       A warning is emitted at startup if an explicit ``hashalg`` is not
+       passed.  This is for backwards compatibility reasons.
+
+       This option is available as of :app:`Pyramid` 1.4.
 
        Optional.
 
        .. note::
 
-          ``sha512`` is recommended for improved security and to maintain
-          compatibility with Apache's ``mod_auth_tkt`` module.
+          ``md5`` is the default for backwards compatibility reasons. However,
+          if you don't specify ``md5`` as the hashalg explicitly, a warning is
+          issued at application startup time.  An explicit value of ``sha512``
+          is recommended for improved security, and ``sha512`` will become the
+          default in a future Pyramid version.
 
     ``debug``
 
@@ -556,16 +563,28 @@ class AuthTktAuthenticationPolicy(CallbackAuthenticationPolicy):
                  ):
         if hashalg is _marker:
             hashalg = 'md5'
-            warnings.warn('The MD5 hash function is known to have collisions. '
-                          'We recommend instead that you update your code to '
-                          'use the SHA512 algorithm by setting '
-                          'hashalg=\'sha512\'. If you accept these risks '
-                          'and want to continue using MD5, explicitly set '
-                          'the hashalg=\'md5\' in your authentication policy. '
-                          'The default algorithm used in this policy is '
-                          'likely to change in the future.',
-                          DeprecationWarning,
-                          stacklevel=2)
+            warnings.warn(
+                'The MD5 hash function used by default by the '
+                'AuthTktAuthenticationPolicy is known to be '
+                'susceptible to collision attacks.  It is the current default '
+                'for backwards compatibility reasons, but we recommend that '
+                'you use the SHA512 algorithm instead for improved security.  '
+                'Pass ``hashalg=\'sha512\'`` to the '
+                'AuthTktAuthenticationPolicy constructor to do so.\n\nNote '
+                'that a change to the hash algorithms will invalidate existing '
+                'auth tkt cookies set by your application.  If backwards '
+                'compatibility of existing auth tkt cookies is of greater '
+                'concern than the risk posed by the potential for a hash '
+                'collision, you\'ll want to continue using MD5 explicitly.  '
+                'To do so, pass ``hashalg=\'md5\'`` in your application to '
+                'the AuthTktAuthenticationPolicy constructor.   When you do so '
+                'this warning will not be emitted again.  The default '
+                'algorithm used in this policy will change in the future, so '
+                'setting an explicit hashalg will futureproof your '
+                'application.',
+                DeprecationWarning,
+                stacklevel=2
+                )
         self.cookie = AuthTktCookieHelper(
             secret,
             cookie_name=cookie_name,