Open
Conversation
TOMTOOKIT_FIELD_ENCRYPTION_KEY is used as the master encryption key to encrypt/decrypt each User's encrypted_data_encryption_key, which is saved in the Profile model.
This is the user-specific, envelope-encrypted (by the master cipher), Data Encryption Field (DEK). It is created with the user's Profile and encrypted with the master cipher (created with the master TOMTOOLKIT_FIELD_ENCRYPTION_KEY). If that master key changes, then each user's Profile.encrypted_dek must be re-encrypted, but that user's encrypted-data itself doesn't have to change.
the (way better) envelope encryption scheme doesn't save anything to the session
(I gather that) the term of art in envelope encryption is to wrap(encrypt) and unwrap(decrypt) the secret encryption keys (with the TOMTOOLKIT_FIELD_ENCRYPTION_KEY-created cipher in our case). This commit removes that conceptual jargon in favor of what's literally going on: encrypting and decrypting.
Shorten the comment and add a note explaining that BinaryField is excluded by Django's model_to_dict(), which is why encrypted_dek intentionally does not appear on the user Profile card.
This warning isn't needed with the new ecryption scheme.
Add a check in TomCommonConfig.ready() that raises ImproperlyConfigured if the encryption key is missing. This prevents the TOM from starting in a half-configured state where logins would crash when the signal tries to generate a DEK. The error message includes step-by-step instructions for generating and configuring the 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.
Fingel
approved these changes
Apr 1, 2026
There were some straggling references to the "field" encryption key that are now changed to "DEK" encryption key (including the name of the key rotation management command).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
resolves login issue by reworking the encryption scheme
Removes old encryption scheme and implements envelope encryption where one master encryption key (
TOMTOOLKIT_DEK_ENCRYPTION_KEY) encrypts a user-specific data encryption key (DEK),Profile.encrypted_dek, which is used to encrypt that user's sensitive data.TOMTOOLKIT_DEK_ENCRYPTION_KEYshould be treated like Django's SECRET_KEY and is documented (in the code) as such. If the TOM admin wants to rotate theTOMTOOLKIT_DEK_ENCRYPTION_KEY(there's a management command for that), the user data is not touched, only the user's (new)Profile.encrypted_dekis decrypted and re-encrypted. When the user's sensitive data is accessed, thisencrypted_dekis decrypted with theTOMTOOLKIT_DEK_ENCRYPTION_KEYand then used to create the cipher that is used to access (i.e. decrypt/encrypt) the sensitive data.Unchanged:
EncryptableModelMixin_cipherto access the encrypted FieldEncryptedPropertysession_utils:{get,set}_encrypted_field()_cipherand attach it temporarily to theEncryptedPropertydescriptor to access the data.Changes:
tom_base/settings.pytom_setupsettings.tomlencrypted_dekBinaryFieldto every userProfilemodelencrypted_dek(intentionally does not appear in the Profile card).UserSessionmodel and associated logicmodels.reencrypt_model_fieldsgoes awaymodels.clear_encrypt_fieldsgoes awaysession_utils.reencrypt_data(user)goes awaysession_utilsas "service layer" keeping business logic out of the management command (which is a Django thing that should remain pure Django (i.e. no business logic).UserUpdateViewdoesn't care about password changes (warning removed).closes #1459