[3.1.x] Fixed #31842 -- Added DEFAULT_HASHING_ALGORITHM transitional setting.

It's a transitional setting helpful in migrating multiple instance of
the same project to Django 3.1+.

Thanks Markus Holtermann for the report and review, Florian
Apolloner for the implementation idea and review, and Carlton Gibson
for the review.

Backport of d907371ef99a1e4ca6bc1660f57d81f265750984 from master.

5 files changed, 54 insertions, 2 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 14a2b41a4c..eddbcc3a1b 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -99,6 +99,8 @@ details on these changes.
 
 * The ``{% ifequal %}`` and ``{% ifnotequal %}`` template tags will be removed.
 
+* The ``DEFAULT_HASHING_ALGORITHM`` transitional setting will be removed.
+
 .. _deprecation-removed-in-3.1:
 
 3.1
diff --git a/docs/ref/checks.txt b/docs/ref/checks.txt
index d0cc4b163b..f4c8e8e213 100644
--- a/docs/ref/checks.txt
+++ b/docs/ref/checks.txt
@@ -474,6 +474,12 @@ The following checks are run if you use the :option:`check --deploy` option:
 * **security.E023**: You have set the :setting:`SECURE_REFERRER_POLICY` setting
   to an invalid value.
 
+The following checks verify that your security-related settings are correctly
+configured:
+
+* **security.E100**: :setting:`DEFAULT_HASHING_ALGORITHM` must be ``'sha1'`` or
+  ``'sha256'``.
+
 Signals
 -------
 
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 2306ed26fe..a4b4828a5a 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -1295,6 +1295,27 @@ Default email address to use for various automated correspondence from the
 site manager(s). This doesn't include error messages sent to :setting:`ADMINS`
 and :setting:`MANAGERS`; for that, see :setting:`SERVER_EMAIL`.
 
+.. setting:: DEFAULT_HASHING_ALGORITHM
+
+``DEFAULT_HASHING_ALGORITHM``
+-----------------------------
+
+.. versionadded:: 3.1
+
+Default: ``'sha256'``
+
+Default hashing algorithm to use for encoding cookies, password reset tokens in
+the admin site, user sessions, and signatures created by
+:class:`django.core.signing.Signer` and :meth:`django.core.signing.dumps`.
+Algorithm must be ``'sha1'`` or ``'sha256'``. See
+:ref:`release notes <default-hashing-algorithm-usage>` for usage details.
+
+.. deprecated:: 3.1
+
+    This transitional setting is deprecated. Support for it and tokens,
+    cookies, sessions, and signatures that use SHA-1 hashing algorithm will be
+    removed in Django 4.0.
+
 .. setting:: DEFAULT_INDEX_TABLESPACE
 
 ``DEFAULT_INDEX_TABLESPACE``
diff --git a/docs/releases/3.1.txt b/docs/releases/3.1.txt
index 59980ef310..3b0080b56f 100644
--- a/docs/releases/3.1.txt
+++ b/docs/releases/3.1.txt
@@ -96,6 +96,27 @@ and generate and apply a database migration. For now, the old fields and
 transforms are left as a reference to the new ones and are :ref:`deprecated as
 of this release <deprecated-jsonfield>`.
 
+.. _default-hashing-algorithm-usage:
+
+``DEFAULT_HASHING_ALGORITHM`` settings
+--------------------------------------
+
+The new :setting:`DEFAULT_HASHING_ALGORITHM` transitional setting allows
+specifying the default hashing algorithm to use for encoding cookies, password
+reset tokens in the admin site, user sessions, and signatures created by
+:class:`django.core.signing.Signer` and :meth:`django.core.signing.dumps`.
+
+Support for SHA-256 was added in Django 3.1. If you are upgrading multiple
+instances of the same project to Django 3.1, you should set
+:setting:`DEFAULT_HASHING_ALGORITHM` to ``'sha1'`` during the transition, in
+order to allow compatibility with the older versions of Django. Once the
+transition to 3.1 is complete you can stop overriding
+:setting:`DEFAULT_HASHING_ALGORITHM`.
+
+This setting is deprecated as of this release, because support for tokens,
+cookies, sessions, and signatures that use SHA-1 algorithm will be removed in
+Django 4.0.
+
 Minor features
 --------------
 
@@ -794,6 +815,8 @@ Miscellaneous
   <django.template.backends.django.DjangoTemplates>` option in
   :setting:`OPTIONS <TEMPLATES-OPTIONS>`.
 
+* ``DEFAULT_HASHING_ALGORITHM`` transitional setting is deprecated.
+
 .. _removed-features-3.1:
 
 Features removed in 3.1
diff --git a/docs/topics/signing.txt b/docs/topics/signing.txt
index b015f4bd87..d7d8f42728 100644
--- a/docs/topics/signing.txt
+++ b/docs/topics/signing.txt
@@ -81,13 +81,13 @@ generate signatures. You can use a different secret by passing it to the
     >>> value
     'My string:EkfQJafvGyiofrdGnuthdxImIJw'
 
-.. class:: Signer(key=None, sep=':', salt=None, algorithm='sha256')
+.. class:: Signer(key=None, sep=':', salt=None, algorithm=None)
 
     Returns a signer which uses ``key`` to generate signatures and ``sep`` to
     separate values. ``sep`` cannot be in the :rfc:`URL safe base64 alphabet
     <4648#section-5>`. This alphabet contains alphanumeric characters, hyphens,
     and underscores. ``algorithm`` must be an algorithm supported by
-    :py:mod:`hashlib`.
+    :py:mod:`hashlib`, it defaults to ``'sha256'``.
 
     .. versionchanged:: 3.1