[1.7.x] Fixed #22310 -- Documented exact usage of SECRET_KEY

Backport of 4ad57bbe31bc1813264824111de2f9f74dbda0d6 from master.

1 files changed, 23 insertions, 0 deletions

diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 8154ffd0d9..a306061afe 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -1899,6 +1899,29 @@ Django will refuse to start if :setting:`SECRET_KEY` is not set.
     security protections, and can lead to privilege escalation and remote code
     execution vulnerabilities.
 
+The secret key is used for:
+
+* All :doc:`sessions </topics/http/sessions>` if you are using
+  any other session backend than ``"django.contrib.sessions.backends.cache"``,
+  or if you use
+  :class:`~django.contrib.auth.middleware.SessionAuthenticationMiddleware`
+  and are using the default
+  :meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash()`.
+* All :doc:`messages </ref/contrib/messages>` if you are using
+  :class:`~django.contrib.messages.storage.cookie.CookieStorage` or
+  :class:`~django.contrib.messages.storage.fallback.FallbackStorage`.
+* :doc:`Form wizard </ref/contrib/formtools/form-wizard>` progress when using
+  cookie storage with
+  :class:`django.contrib.formtools.wizard.views.CookieWizardView`.
+* All :func:`~django.contrib.auth.views.password_reset` tokens.
+* All in progress :doc:`form previews </ref/contrib/formtools/form-preview>`.
+* Any usage of :doc:`cryptographic signing </topics/signing>`, unless a
+  different key is provided.
+
+If you rotate your secret key, all of the above will be invalidated.
+Secret keys are not used for passwords of users and key rotation will not
+affect them.
+
 .. setting:: SECURE_PROXY_SSL_HEADER
 
 SECURE_PROXY_SSL_HEADER