Rename TOMTOOLKIT_FIELD_ENCRYPTION_KEY to TOMTOOLKIT_DEK_ENCRYPTION_KEY

Naming Rationale:
The new name is more descriptive because in the "envelope encryption"
scheme, the TOMTOOLKIT_DEK_ENCRYPTION_KEY is the encryption key that
encrypts and decrypts the user's DEK (data encryption key). So it's
the user-DEK encryptiion key for TOM Toolkit.

Author: phycodurus

tom_base/settings.py

@@ -34,8 +34,8 @@
 # Encryption key for protecting sensitive user data (API keys, credentials) at rest.
 # This is a Fernet key — a 44-character URL-safe base64 string encoding 32 random bytes.
 # Treat this like SECRET_KEY. See the TOM Toolkit encryption documentation.
-TOMTOOLKIT_FIELD_ENCRYPTION_KEY = os.getenv(
-    'TOMTOOLKIT_FIELD_ENCRYPTION_KEY',
+TOMTOOLKIT_DEK_ENCRYPTION_KEY = os.getenv(
+    'TOMTOOLKIT_DEK_ENCRYPTION_KEY',
     'UlUYyKsGzQVwjpTbvhtgCihKaj07H1voc-V4pmb7NN4=')  # 44-char URL-safe base64 string
 
 ALLOWED_HOSTS = ['']

tom_common/management/commands/rotate_field_encryption_key.py

@@ -1,4 +1,4 @@
-"""Management command to rotate the TOMTOOLKIT_FIELD_ENCRYPTION_KEY.
+"""Management command to rotate the TOMTOOLKIT_DEK_ENCRYPTION_KEY.
 
 This is a thin CLI wrapper around ``session_utils.rotate_master_key()``.
 See that function for the actual rotation logic.
@@ -21,7 +21,7 @@
 class Command(BaseCommand):
     help = (
         'Re-encrypts all per-user Data Encryption Keys (DEKs) with a new master key. '
-        'Run this when rotating TOMTOOLKIT_FIELD_ENCRYPTION_KEY.'
+        'Run this when rotating TOMTOOLKIT_DEK_ENCRYPTION_KEY.'
     )
 
     def add_arguments(self, parser) -> None:
@@ -68,6 +68,6 @@ def handle(self, *args, **options) -> None:
 
         self.stdout.write("")
         self.stdout.write(self.style.WARNING(
-            "IMPORTANT: Update TOMTOOLKIT_FIELD_ENCRYPTION_KEY in your environment / "
+            "IMPORTANT: Update TOMTOOLKIT_DEK_ENCRYPTION_KEY in your environment / "
             "settings.py with the new key, then restart the server."
         ))

tom_common/models.py

@@ -5,7 +5,7 @@
 TOM Toolkit uses envelope encryption to protect sensitive user data (API keys,
 observatory credentials) at rest in the database. The scheme has two layers:
 
-1. A server-side **master key** (``TOMTOOLKIT_FIELD_ENCRYPTION_KEY``) is stored in the
+1. A server-side **master key** (``TOMTOOLKIT_DEK_ENCRYPTION_KEY``) is stored in the
    environment, never in the database. It is a Fernet key used to encrypt
    per-user keys.
 

tom_common/session_utils.py

@@ -5,7 +5,7 @@
 ``docs/design/encryption_architecture_redesign.md``; here is a brief summary
 of how the pieces fit together:
 
-**Master key** (``TOMTOOLKIT_FIELD_ENCRYPTION_KEY`` in settings / environment):
+**Master key** (``TOMTOOLKIT_DEK_ENCRYPTION_KEY`` in settings / environment):
     A Fernet key that never touches the database. It encrypts each user's
     Data Encryption Key so that database access alone cannot reveal user data.
 
@@ -54,19 +54,19 @@
 def _get_master_cipher() -> Fernet:
     """Return a Fernet cipher built from the server-side master key.
 
-    The master key (``TOMTOOLKIT_FIELD_ENCRYPTION_KEY``) lives in the server
+    The master key (``TOMTOOLKIT_DEK_ENCRYPTION_KEY``) lives in the server
     environment, not in the database. It is used only to encrypt and decrypt
     per-user DEKs — never to encrypt user data directly.
 
     Raises:
         django.core.exceptions.ImproperlyConfigured: If the setting is missing
             or empty.
     """
-    key = getattr(settings, 'TOMTOOLKIT_FIELD_ENCRYPTION_KEY', '')
+    key = getattr(settings, 'TOMTOOLKIT_DEK_ENCRYPTION_KEY', '')
     if not key:
         from django.core.exceptions import ImproperlyConfigured
         raise ImproperlyConfigured(
-            "TOMTOOLKIT_FIELD_ENCRYPTION_KEY is not set. This setting is required for "
+            "TOMTOOLKIT_DEK_ENCRYPTION_KEY is not set. This setting is required for "
             "encrypting sensitive user data at rest. Generate one with:\n"
             "  python -c \"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())\"\n"
             "Then add it to your environment or settings.py."
@@ -261,13 +261,13 @@ def rotate_master_key(new_key: str) -> RotationResult:
     """Re-encrypt all per-user DEKs with a new master key.
 
     Each Profile's ``encrypted_dek`` is decrypted with the current master key
-    (from ``TOMTOOLKIT_FIELD_ENCRYPTION_KEY``) and re-encrypted with
+    (from ``TOMTOOLKIT_DEK_ENCRYPTION_KEY``) and re-encrypted with
     ``new_key``. The user Profile's plaintext DEK is unchanged — only its
     encryption layer (i.e. `encrypted_dek`) is replaced. The actual encrypted
     data is not touched.
 
     After this function completes successfully, the server's
-    ``TOMTOOLKIT_FIELD_ENCRYPTION_KEY`` must be updated to ``new_key`` and the
+    ``TOMTOOLKIT_DEK_ENCRYPTION_KEY`` must be updated to ``new_key`` and the
     server restarted. Until that happens, the re-encrypted DEKs cannot be
     decrypted.
 

tom_common/tests.py

@@ -381,7 +381,7 @@ class TestEncryptionKeyManagement(TestCase):
     - Users get an encrypted DEK on creation (via signal)
     - The DEK can be decrypted and used to encrypt/decrypt data
     - Password changes do not affect the encryption key
-    - The master key (TOMTOOLKIT_FIELD_ENCRYPTION_KEY) is required for decryption
+    - The master key (TOMTOOLKIT_DEK_ENCRYPTION_KEY) is required for decryption
     """
     def setUp(self):
         self.user = User.objects.create_user(
@@ -476,7 +476,7 @@ def test_create_encrypted_dek_produces_valid_encrypted_key(self):
 
     def test_master_key_required_for_decryption(self):
         """Decrypting with a different master key should fail, proving
-        that the encrypted DEK is bound to TOMTOOLKIT_FIELD_ENCRYPTION_KEY."""
+        that the encrypted DEK is bound to TOMTOOLKIT_DEK_ENCRYPTION_KEY."""
         profile = Profile.objects.get(user=self.user)
         wrong_key = Fernet.generate_key()
         wrong_cipher = Fernet(wrong_key)

tom_setup/management/commands/tom_setup.py

@@ -216,7 +216,7 @@ def generate_secret_key(self):
 
     def generate_field_encryption_key(self):
         self.status('Generating field encryption key... ')
-        self.context['TOMTOOLKIT_FIELD_ENCRYPTION_KEY'] = Fernet.generate_key().decode()
+        self.context['TOMTOOLKIT_DEK_ENCRYPTION_KEY'] = Fernet.generate_key().decode()
         self.ok()
 
     def generate_config(self):

tom_setup/templates/tom_setup/settings.tmpl

@@ -28,9 +28,9 @@ SECRET_KEY = '{{ SECRET_KEY }}'
 # Encryption key for protecting sensitive user data (API keys, credentials) at rest.
 # This is a Fernet key — a 44-character URL-safe base64 string encoding 32 random bytes.
 # Treat this like SECRET_KEY. See the TOM Toolkit encryption documentation.
-TOMTOOLKIT_FIELD_ENCRYPTION_KEY = os.getenv(
-    'TOMTOOLKIT_FIELD_ENCRYPTION_KEY',
-    '{{ TOMTOOLKIT_FIELD_ENCRYPTION_KEY }}')  # 44-char URL-safe base64 string
+TOMTOOLKIT_DEK_ENCRYPTION_KEY = os.getenv(
+    'TOMTOOLKIT_DEK_ENCRYPTION_KEY',
+    '{{ TOMTOOLKIT_DEK_ENCRYPTION_KEY }}')  # 44-char URL-safe base64 string
 
 # SECURITY WARNING: don't run with debug turned on in production!
 DEBUG = True