Opened 10 years ago

Closed 9 years ago

Last modified 9 years ago

#22310 closed Cleanup/optimization (fixed)

Document exact usage of and consequences of rotating SECRET_KEY

Reported by: Sasha Romijn Owned by: Sasha Romijn
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

Occasionally, people have accidents with their secret keys. It is somehow leaked, or they discover that they haven't stored it as securely as they should have. The trivial fix is to rotate your secret key. However, the secret key is used in various places, and this may invalidate existing tokens, sessions, etc. For example, if I remember correctly, secret keys form part of signed cookies and password reset tokens - but not password hashes.

We should document where exactly secret keys are being used, and therefore which data will be invalidated as soon as you rotate your secret key. This helps people understand what's going to happen, and will make sure nobody keeps an unsafe secret key because they are afraid of rotating it.

This requires some digging: there are of course many direct references to settings.SECRET_KEY, but also some more generic utilities, like cookie signing, that use the secret key, but that various other parts of Django then depend upon.

Attachments (1)

secret_key_import_scheme.txt (3.5 KB ) - added by Zulu 10 years ago.
Draft of settings.SECRET_KEY importing

Download all attachments as: .zip

Change History (14)

comment:1 by Claude Paroz, 10 years ago

Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

comment:2 by Russell Keith-Magee, 10 years ago

Agreed this is a good idea.

A related issue is #20081, which would minimise the risk of a "leak to version control" of the SECRET_KEY.

comment:3 by Zulu, 10 years ago

Owner: changed from nobody to Zulu
Status: newassigned

by Zulu, 10 years ago

Draft of settings.SECRET_KEY importing

comment:4 by Zulu, 10 years ago

Where does this doc should be included ?

comment:5 by Sasha Romijn, 10 years ago

I think https://docs.djangoproject.com/en/dev/topics/signing/ might be the best place, as that's what SECRET_KEY is already described as being used for from the settings documentation.

comment:6 by Zulu, 10 years ago

Hello erikr,
My work is available at https://github.com/ZuluPro/django/commit/5f8e017c6d2378251d3a68a346b01b19a4293cf7

Tell if you want me to go more in depth.
Thanks

comment:7 by Sasha Romijn, 10 years ago

Has patch: set
Patch needs improvement: set

Thanks for the patch, but I had something a bit more practical in mind. More like (contents all fictional):

The secret key is used for:

* Password reset tokens
* Session using the FooBarBackend
* Signed cookies you may have set yourself using .....
* ...

If you rotate your secret key, all of the above will be invalidated.

Secret keys are not used, and rotation therefore will not affect:

* Password stored for users
* Sessions using other backends than FooBarBackend
* ...

The second list would not be exhaustive, just some items where confusion is more likely.

comment:8 by Sasha Romijn, 10 years ago

Owner: changed from Zulu to Sasha Romijn

I am currently working on this, but it'll have to wait on #22638.

comment:9 by Tim Graham, 10 years ago

Easy pickings: unset

comment:10 by Sasha Romijn, 10 years ago

Patch needs improvement: unset

comment:11 by Tim Graham, 9 years ago

Triage Stage: AcceptedReady for checkin

comment:12 by Erik Romijn <eromijn@…>, 9 years ago

Resolution: fixed
Status: assignedclosed

In 4ad57bbe31bc1813264824111de2f9f74dbda0d6:

Fixed #22310 -- Documented exact usage of SECRET_KEY

Thanks to Tim Graham for the review.

comment:13 by Erik Romijn <eromijn@…>, 9 years ago

In ab8afafcc06b4d1f306459756a74eee3392b782d:

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

Backport of 4ad57bbe31bc1813264824111de2f9f74dbda0d6 from master.

Note: See TracTickets for help on using tickets.
Back to Top