diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/internals/deprecation.txt | 2 | ||||
| -rw-r--r-- | docs/ref/checks.txt | 6 | ||||
| -rw-r--r-- | docs/ref/settings.txt | 21 | ||||
| -rw-r--r-- | docs/releases/3.1.txt | 23 | ||||
| -rw-r--r-- | docs/topics/signing.txt | 4 |
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 |