c5913a58d5
Add an ADR about secret key usage. Don't use secret keys for use cases which would result in breakage upon rotation and which might slow down the act of rotation.
54 lines
1.8 KiB
ReStructuredText
54 lines
1.8 KiB
ReStructuredText
Django Secret Key Usage
|
|
-----------------------
|
|
|
|
Status
|
|
======
|
|
|
|
Pending
|
|
|
|
Context
|
|
=======
|
|
|
|
Django's Secret key is used by Django to cryptographically sign various
|
|
capabilities in Django. It is also used by the edx-platform in various cases
|
|
as a `pepper`_ when hashing data to anonymize it while keeping it consistent.
|
|
Some of the uses of the ``SECRET_KEY`` in edx-platform were not resilient to
|
|
the key being rotated. As a part of ARCHBOM-1646 those code paths are being
|
|
updated so that regular rotation of the ``SECRET_KEY`` will cause temporary
|
|
issues but will not fully break things. ie. Sessions might get invalidated or
|
|
data might not be correlatable over the change boundary but the change is
|
|
otherwise safe.
|
|
|
|
.. _pepper: https://en.wikipedia.org/wiki/Pepper_(cryptography)
|
|
|
|
Decisions
|
|
=========
|
|
|
|
1. Any uses of ``SECRET_KEY`` should be resilient to that key being rotated.
|
|
|
|
2. Wherever the ``SECRET_KEY`` is used, it should also document the impact of
|
|
rotating the key.
|
|
|
|
For example:
|
|
|
|
Rotation is a one-time discontinuity in tracking metrics and should be
|
|
accompanied by a heads-up to data researchers
|
|
|
|
3. Whenever the ``SECRET_KEY`` is used, it should also document the
|
|
consequences of the key being exposed.
|
|
|
|
For example:
|
|
|
|
Exposure of secret could result in identifying the tracking data for users
|
|
if their actual session keys are also known
|
|
|
|
Consequences
|
|
============
|
|
|
|
- The ``SECRET_KEY`` should only be used in cases where rotation can be done
|
|
quickly. Because the secret is shared, not changing it quickly can expose
|
|
multiple features to attack if any one usage is more expensive to rotate than others.
|
|
If you are considering using the ``SECRET_KEY`` in a situation where the act
|
|
of rotation will be expensive (time, coordination, preparation) you should
|
|
instead consider using a new unique secret specific to your use case.
|