Encryption key rotation
During encryption key rotation, the database must be re-encrypted. While this operation is running, Passwork is switched to service mode: the web interface and automations become unavailable.
Before rotation, you must create a backup copy of the Passwork database and the encryption_key.
General information
During rotation, Passwork reads the current key from encryption_key or from the ENCRYPTION_KEY environment variable, checks that it matches the internal settings, and reads the new key from the new_encryption_key file.
After rotation is completed successfully, new_encryption_key replaces the current encryption_key. The old key is saved in the same directory with a timestamp.
Procedure
Enabling service mode
When service mode is enabled, access to the web interface and automations that use the API is closed. Enabling service mode is required:
- DEB
- RPM
- Docker
- PowerShell
sudo -u www-data bash -c 'cd /var/www && php bin/console app:service-mode enable'
sudo -u apache bash -c 'cd /var/www && php bin/console app:service-mode enable'
docker compose exec -T php-fpm sh -c 'cd /server/www && php bin/console app:service-mode enable'
cd "C:\inetpub\wwwroot\passwork"
php .\bin\console app:service-mode enable
Generating a new encryption key
To create a new encryption key and save it to the new_encryption_key file:
- DEB
- RPM
- Docker
- PowerShell
sudo -u www-data bash -c 'cd /var/www && php bin/console encryption-key:generate'
sudo -u apache bash -c 'cd /var/www && php bin/console encryption-key:generate'
docker compose exec -T php-fpm sh -c 'cd /server/www && php bin/console encryption-key:generate'
php .\bin\console encryption-key:generate
If the new_encryption_key file already exists, the command will fail.
Dry run
The encryption-key:update command without the --apply parameter runs in dry-run mode:
- DEB
- RPM
- Docker
- PowerShell
sudo -u www-data bash -c 'cd /var/www && php -d memory_limit=-1 bin/console encryption-key:update --ansi'
sudo -u apache bash -c 'cd /var/www && php -d memory_limit=-1 bin/console encryption-key:update --ansi'
docker compose exec -T php-fpm sh -c 'cd /server/www && php -d memory_limit=-1 bin/console encryption-key:update --ansi'
php -d "memory_limit=-1" .\bin\console encryption-key:update --ansi
Output explanation
| Column | Description |
|---|---|
Found | Number of records or values found that are suitable for checking at this stage. A value of 0 means there is no such data in the database. |
Processed | Number of values that the command successfully checked: decrypted with the old key and prepared for encryption with the new key. |
Skipped | Number of found records that do not require processing or do not contain values for re-encryption. For example, SMTP settings may be found, but the password may be absent. |
Restored | Number of values skipped during a repeated run after interruption because their state already differs from the saved intermediate state. In a normal dry run, this is 0. |
Conflicts | Number of conflicts while continuing an interrupted operation. For example, if a record saved earlier for continuation can no longer be found. In a normal dry run, this is 0. |
Seconds | Execution time of a specific stage in seconds. |
If the dry-run finishes with an error, re-encryption is not possible until the causes of the errors are resolved.
Applying re-encryption
The --apply parameter starts data modification. Before applying changes, the command displays a warning and asks for confirmation:
- DEB
- RPM
- Docker
- PowerShell
sudo -u www-data bash -c 'cd /var/www && php -d memory_limit=-1 bin/console encryption-key:update --apply'
sudo -u apache bash -c 'cd /var/www && php -d memory_limit=-1 bin/console encryption-key:update --apply'
docker compose exec -T php-fpm sh -c 'cd /server/www && php -d memory_limit=-1 bin/console encryption-key:update --apply'
php -d "memory_limit=-1" .\bin\console encryption-key:update --apply
After successful completion:
- Encrypted values in the database will be re-encrypted with the new key;
- The
new_encryption_keyfile will be renamed toencryption_key; - The old
encryption_keywill be renamed to the backup fileencryption_key.<date_and_time>.bak.
Disabling service mode
After re-encryption is completed successfully, service mode must be disabled to restore access to the Passwork web interface and automations:
- DEB
- RPM
- Docker
- PowerShell
sudo -u www-data bash -c 'cd /var/www && php bin/console app:service-mode disable'
sudo -u apache bash -c 'cd /var/www && php bin/console app:service-mode disable'
docker compose exec -T php-fpm sh -c 'cd /server/www && php bin/console app:service-mode disable'
php .\bin\console app:service-mode disable
Service mode should not be disabled before encryption-key:update --apply completes successfully.
If execution was interrupted
If command execution was interrupted, re-encryption can be started again. Passwork saves the operation state and continues processing from the point where the previous attempt stopped.
To continue, use the same new_encryption_key file:
- DEB
- RPM
- Docker
- PowerShell
sudo -u www-data bash -c 'cd /var/www && php -d memory_limit=-1 bin/console encryption-key:update --apply'
sudo -u apache bash -c 'cd /var/www && php -d memory_limit=-1 bin/console encryption-key:update --apply'
docker compose exec -T php-fpm sh -c 'cd /server/www && php -d memory_limit=-1 bin/console encryption-key:update --apply'
php -d "memory_limit=-1" .\bin\console encryption-key:update --apply
If an error occurs after the encryption_key file has been replaced, Passwork will try to restore the old key file from the backup file.
Checks and limitations
The encryption-key:update command will not start if:
- Service mode is disabled;
- The current encryption key does not match the hash in the database;
- The
new_encryption_keyfile is missing or damaged.
After successful rotation, check that Passwork works correctly and make sure users can open data. Delete the old key backup only after verifying functionality and confirming that the backup copy is correct.