Effects of changing Django's SECRET_KEY

Edit: This answer is based on django 1.5

SECRET_KEY is used in a lot of various places, I'll point out what is impacted by it first and then try to go over that list and give precise explanation of the impact.

The list of things using SECRET_KEY directly or indirectly:

  • JSON object signing
  • crypto functions for salted hmacs or seeding the random engine which impacts:
    • password reset token
    • comment form security to protect against forged POST requests
    • form security
    • protect against message tampering as the message framework may use cookies to pass messages between views.
    • protect session data and create random session keys to avoid tampering as well.
    • create random salt for most password hashers
    • create random passwords if necessary
    • create itself when using startproject
    • create CSRF key

In reality a lot of the items listed here use SECRET_KEY through django.utils.crypt.get_random_string() which uses it to seed the random engine. This won't be impacted by a change in value of SECRET_KEY.

User experience directly impacted by a change of value are:

  • sessions, the data decode will break, that is valid for any session backend (cookies, database, file based or cache).
  • password reset token already sent won't work, users will have to ask a new one.
  • comments form (if using django.contrib.comments) will not validate if it was requested before the value change and submitted after the value change. I think this is very minor but might be confusing for the user.
  • messages (from django.contrib.messages) won't validate server-side in the same timing conditions as for comments form.

UPDATE: now working on django 1.9.5, a quick look at the source gives me pretty much the same answers. Might do a thorough inspection later.


Since this question was asked, the Django documentation has changed to include an answer.

The secret key is used for:

  • All sessions if you are using any other session backend than django.contrib.sessions.backends.cache, or are using the default get_session_auth_hash().
  • All messages if you are using CookieStorage or FallbackStorage.
  • All PasswordResetView tokens.
  • Any usage of 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.

It wasn't clear to me exactly how I should rotate the secret key. I found a discussion of how Django generates a key for a new project, as well as a Gist that discusses other options. I finally decided to just get Django to create a new project, copy the new secret key into my old project, and then erase the new project.

cd ~/junk # Go to some safe directory to create a new project.
django-admin startproject django_scratch
grep SECRET_KEY django_scratch/django_scratch/settings.py # copy to old project
rm -R django_scratch

Update

It looks like Django added the get_random_secret_key() function in version 1.10. You could use that to generate a new secret key.

$ ./manage.py shell -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
s!)5@5s79sp=92a+!f4v!1g0d0+64ln3d$xm1f_7=749ht&-zi
$ ./manage.py shell -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
_)+%kymd=f^8o_fea1*yro7atz3w+5(t2/lm2cz70*e$2mn\g3
$

According to this page https://docs.djangoproject.com/en/dev/topics/signing/, the SECRET_KEY is mostly used for transitory stuff -- signing data sent over the wire so you can detect tampering, for example. It looks like the things that COULD break are:

  • Signed cookies, e.g. "remember my auth on this computer" type values. In this case, the cookie will be invalidated, the signature will fail to verify and the user will have to re-authenticate.
  • For any users that have requested links for a password reset or a custom file download, those links will no longer be valid. The users would simply have to re-request those links.

Someone with more recent and/or salient Django experience than me might chime in otherwise, but I suspect that unless you are explicitly doing something with the signing API, this should only create a mild inconvenience for your users.

Tags:

Django

Recent Posts