Ротация ключа шифрования
В процессе ротации ключа шифрования необходимо перешифровать базу данных. На время выполнения этой операции, Пассворк переводится в сервисный режим: веб-интерфейс и автоматизации становятся недоступны.
Перед ротацией обязательно должна быть создана резервная копия базы данных Пассворка (MongoDB и ли PostgreSQL) и ключа шифрования encryption_key.
Общие сведения
При ротации Пассворк получает текущий ключ из encryption_key или из переменной окружения ENCRYPTION_KEY, проверяет его соответствие внутренним настройкам и читает новый ключ из файла new_encryption_key.
После успешного завершения ротации, new_encryption_key заменяет текущий encryption_key. Старый ключ сохраняется в этой же директории с временной меткой.
Порядок выполнения
Включение сервисного режима
При включении сервисного режима, закрывается доступ к веб-интерфейсу и автоматизациям использущим API. Его включение является обязательным условием:
- 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
Генерация нового ключа шифрования
Для создания нового ключа шифрования и его последующего сохранения в файл new_encryption_key:
- 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
Если файл new_encryption_key уже существует, команда завершится с ошибкой.
Проверочный запуск
Команда encryption-key:update без параметра --apply работает в режиме dry-run:
- 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
Разбор вывода
| Колонка | Описание |
|---|---|
Found | Количество найденных записей или значений, которые подходят для проверки на этом этапе. Значение 0 означает, что таких данных в базе нет. |
Processed | Количество значений, которые команда смогла успешно проверить: расшифровать старым ключом и подготовить к шифрованию новым ключом. |
Skipped | Количество найденных записей, которые не требуют обработки или не содержат значения для перешифровки. Например, SMTP-настройки могут быть найдены, но пароль может отсутствовать. |
Restored | Количество значений, которые были пропущены при повторном запуске после прерывания, потому что их состояние уже отличается от сохранённого промежуточного состояния. В обычном dry-run равно 0. |
Conflicts | Количество конфликтов при продолжении прерванной операции. Например, если ранее сохранённая для продолжения запись больше не найдена. В обычном dry-run равно 0. |
Seconds | Время выполнения конкретного этапа в секундах. |
Если dry-run завершился с ошибкой, то перешифрование невозможно до устранения причин ошибок.
Применение перешифровки
Параметр --apply запускает изменение данных. Перед началом применения команда выводит предупреждение и запрашивает подтверждение:
- 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
После успешного завершения:
- Зашифрованные значения в базе данных будут перешифрованы новым ключом;
- Файл
new_encryption_keyбудет переименован вencryption_key; - Старый
encryption_keyбудет переименован в backup-файлencryption_key.<дата_и_время>.bak.
Отключение сервисного режима
После успешного завершения перешифровки сервисный режим необходимо отключить, чтобы вернуть доступ к веб-интерфейсу и автоматизациям Пассворка:
- 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
Сервисный режим не следует отключать до успешного завершения — encryption-key:update --apply.
Если выполнение было прервано
Если выполнение команды было прервано, перешифрование можно запустить повторно. Пассворк сохраняет состояние операции и продолжает обработку с места, на котором остановилась предыдущая попытка.
Для продолжения необходимо использовать тот же файл new_encryption_key:
- 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
Если ошибка произошла после замены файла encryption_key, будет выполнена попытка восстановить старый файл ключа из backup-файла.
Проверки и ограничения
Команда encryption-key:update не начнёт выполнение, если:
- Сервисный режим выключен;
- Текущий ключ шифрования не соответствует хэшу в базе данных;
- Файл
new_encryption_keyотсутствует или повреждён.
После успешной ротации необходимо проверить работу Пассворка и убедиться, что пользователи могут открыть данные. Удалять backup старого ключа рекомендуется только после проверки работоспособности и подтверждения корректности резервной копии.