From 0dcd549bbe36c060f536ec270d34d9e7d4b8e6c7 Mon Sep 17 00:00:00 2001 From: tschilling Date: Mon, 13 Dec 2021 21:47:03 -0600 Subject: Fixed #30360 -- Added support for secret key rotation. Thanks Florian Apolloner for the implementation idea. Co-authored-by: Andreas Pelme Co-authored-by: Carlton Gibson Co-authored-by: Vuyisile Ndlovu --- docs/ref/checks.txt | 10 ++++++++-- docs/ref/settings.txt | 39 ++++++++++++++++++++++++++++++++++++--- 2 files changed, 44 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/checks.txt b/docs/ref/checks.txt index 6c95b9376d..3228d71f08 100644 --- a/docs/ref/checks.txt +++ b/docs/ref/checks.txt @@ -457,8 +457,8 @@ The following checks are run if you use the :option:`check --deploy` option: * **security.W009**: Your :setting:`SECRET_KEY` has less than 50 characters, less than 5 unique characters, or it's prefixed with ``'django-insecure-'`` indicating that it was generated automatically by Django. Please generate a - long and random ``SECRET_KEY``, otherwise many of Django's security-critical - features will be vulnerable to attack. + long and random value, otherwise many of Django's security-critical features + will be vulnerable to attack. * **security.W010**: You have :mod:`django.contrib.sessions` in your :setting:`INSTALLED_APPS` but you have not set :setting:`SESSION_COOKIE_SECURE` to ``True``. Using a secure-only session @@ -511,6 +511,12 @@ The following checks are run if you use the :option:`check --deploy` option: to an invalid value. * **security.E024**: You have set the :setting:`SECURE_CROSS_ORIGIN_OPENER_POLICY` setting to an invalid value. +* **security.W025**: Your + :setting:`SECRET_KEY_FALLBACKS[n] ` has less than 50 + characters, less than 5 unique characters, or it's prefixed with + ``'django-insecure-'`` indicating that it was generated automatically by + Django. Please generate a long and random value, otherwise many of Django's + security-critical features will be vulnerable to attack. The following checks verify that your security-related settings are correctly configured: diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index e65f92b4ff..dac29755d0 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -2291,9 +2291,11 @@ The secret key is used for: * Any usage of :doc:`cryptographic 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. +When a secret key is no longer set as :setting:`SECRET_KEY` or contained within +:setting:`SECRET_KEY_FALLBACKS` all of the above will be invalidated. When +rotating your secret key, you should move the old key to +:setting:`SECRET_KEY_FALLBACKS` temporarily. Secret keys are not used for +passwords of users and key rotation will not affect them. .. note:: @@ -2301,6 +2303,36 @@ affect them. startproject ` creates a unique ``SECRET_KEY`` for convenience. +.. setting:: SECRET_KEY_FALLBACKS + +``SECRET_KEY_FALLBACKS`` +------------------------ + +.. versionadded:: 4.1 + +Default: ``[]`` + +A list of fallback secret keys for a particular Django installation. These are +used to allow rotation of the ``SECRET_KEY``. + +In order to rotate your secret keys, set a new ``SECRET_KEY`` and move the +previous value to the beginning of ``SECRET_KEY_FALLBACKS``. Then remove the +old values from the end of the ``SECRET_KEY_FALLBACKS`` when you are ready to +expire the sessions, password reset tokens, and so on, that make use of them. + +.. note:: + + Signing operations are computationally expensive. Having multiple old key + values in ``SECRET_KEY_FALLBACKS`` adds additional overhead to all checks + that don't match an earlier key. + + As such, fallback values should be removed after an appropriate period, + allowing for key rotation. + +Uses of the secret key values shouldn't assume that they are text or bytes. +Every use should go through :func:`~django.utils.encoding.force_str` or +:func:`~django.utils.encoding.force_bytes` to convert it to the desired type. + .. setting:: SECURE_CONTENT_TYPE_NOSNIFF ``SECURE_CONTENT_TYPE_NOSNIFF`` @@ -3725,6 +3757,7 @@ Security * :setting:`CSRF_USE_SESSIONS` * :setting:`SECRET_KEY` +* :setting:`SECRET_KEY_FALLBACKS` * :setting:`X_FRAME_OPTIONS` Serialization -- cgit v1.3