Skip to main content

Rotate your encryption key

Learn how to rotate Retool's encryption keys.

Retool supports encryption key rotation for organizations with self-hosted deployments. This encryption key is used to encrypt sensitive values in Retool's backend database. Encryption key rotation is a zero-downtime operation.

Organizations should rotate their encryption key if they suspect that their key was leaked or exposed to an unauthorized individual. Use the procedures below to add an encryption key to a deployment that previously did not have one. When using a deployment previously missing an encryption key, Retool generally does not encrypt values found to be in plaintext.

The minimum version required to complete an encryption key rotation is 3.148.

1. Take a snapshot of your deployment's database​

Before you begin, Retool recommends that you take a snapshot of your instance's database and store it somewhere safely with limited permissions. Retool's key rotation procedure is intended to have no downtime or data loss, but its status as an public beta feature means there is a higher risk of data loss.

2. Update your deployment's environment variables​

Start with generating a new encryption key. Retool recommends your keys to be at least 64 characters in length. Set the following environment variables:

USE_ENCRYPTION_V2=true
ENCRYPTION_KEY_OLD={old encryption key}
ENCRYPTION_KEY={new encryption key}

ENABLE_LOGS_FOR_DECRYPTION_WITH_OLD_KEY=true # optional, used for observability (more below)

After updating these environment variable:

  • Your database reads will be able to decrypt values encrypted with either the old or the new encryption key.
  • Your database writes will be encrypted with the new encryption key.
  • After adding a new key, it won't be safe to remove it until another database rotation is completed since it could be in use

If you are setting the encryption key for the first time, and therefore do not have an old encryption key, you can leave the ENCRYPTION_KEY_OLD environment variable blank in the encryption key rotation script.

3. Run the database rotation script​

To complete your encryption key rotation, encrypt all the values in your database to be encrypted with the new key using the following script:

./retool_backend --backfill-encrypt-secrets

Optional args:
--batch-size <number>
    > the number of rows to operate on in each batch (default 1000)
--resume-run-uuid <uuid>
    > the uuid of the backfill/key rotation run to resume, in case it previously failed/exited/etc

4. Monitor your deployment for completion​

Monitor the output of the above script for completion of the database rotation. After completion, you can monitor your instance for any usage of the old encryption key. With the ENABLE_LOGS_FOR_DECRYPTION_WITH_OLD_KEY environment variable, any usage of the old key for decryption will emit one of the following logs:

[decrypt] Decrypting a secret using the old encryption key AND old encryption schema!
[decrypt] Decrypting a secret using the old encryption key!
[decryptBuffer] Decrypting a secret using the old encryption key!

If you see these logs after completing the encryption key rotation script, please contact us immediately at support@retool.com.

5. Remove previous encryption key​

If you are rotating your encryption key because you suspect a data breach, Retool recommends that you remove all references to the previous key as soon as you are confident the encryption key rotation script is complete. To do so, you can remove the ENCRYPTION_KEY_OLD environment variable from your instance.