diff --git a/docs/decisions/0008-secret-key-usage.rst b/docs/decisions/0008-secret-key-usage.rst new file mode 100644 index 0000000000..707a011112 --- /dev/null +++ b/docs/decisions/0008-secret-key-usage.rst @@ -0,0 +1,53 @@ +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.