LabKey Server uses AES128 symmetric encryption to encrypt some sensitive information in the database such as stored credentials, certificates, etc. Administrators must provide an
EncryptionKey that the server uses to encrypt and decrypt this content.
This topic describes how an administrator can change this key, useful if they originally provided a weak key, or need to change it to comply with institutional requirements.
Provide an Encryption Key
Beginning with version 24.3, the encryption key is provided in your application.properties file:
context.encryptionKey=<encryptionKey>
The key can be randomly generated, or a strong password or passphrase, for example, a string of 32 random ASCII characters or 64 random hexadecimal digits. Your organization may provide strong password guidance and/or requirements.
Learn more about the application.properties file here:
If you are using a database with a key previously set, such as from a backup from another server, the matching key will need to be provided.
Developers building locally will need to run 'gradlew pickPg' after adding an encryption key to <LK_ENLISTMENT>/server/configs/application.properties to 'merge' it (with pg.properties) into the working version in <LK_ENLISTMENT>/build/deploy/embedded/config/application.properties.
Learn more here.
Change an Encryption Key
If you need to change to a new key, follow these steps.
Stop the server, then temporarily uncomment the "oldEncryptionKey" line in application.properties, providing the old key and setting a new one:
context.encryptionKey=<newEncryptionKey>
context.oldEncryptionKey=<oldEncryptionKey>
Restart the server. During startup all the components that use encryption will decrypt their content using the old key, re-encrypt using the new key, and save the result.
Once migrated, the admin must again stop the server, and comment out or completely delete the oldEncryptionKey. If commenting out, it might look like:
context.encryptionKey=<betterEncryptionKey>
#context.oldEncryptionKey=
Troubleshooting
If you simply change the context.encryptionKey property without providing the context.oldEncryptionKey, your server will start, but you will not be able to access any resources that required credentials. LabKey can't decrypt these saved secrets without the old encryption key. Any failed decryptions (which are likely due to a changed key) will be reported to admins via a yellow warning banner.
You can delete and reestablish all such connections individually, or stop the server and follow the above process, assuming you recall the original encryption key that was used.
Methods for Previous Releases
Prior to version 24.3, the encryption key was specified and/or changed in your configuration file (usually either labkey.xml or ROOT.xml). The procedures were the same, but the syntax for defining a key was the following, where @@origEncryptionKey@@ is replaced with the actual key:
<Parameter name="EncryptionKey" value="@@oldEncryptionKey@@" />
And for changing a key:
<Parameter name="OldEncryptionKey" value="@@oldEncryptionKey@@" />
<Parameter name="EncryptionKey" value="@@newEncryptionKey@@" />
Make sure to remove the "OldEncryptionKey" line after making this change.
Related Topics
